On the Pam files the authors indicate the data type of the material contained in each patch or deck. The data type gives a generic handle to specify in the cradle what to do with the material of each type.
"Diversion" is primarily an instrument to separate routines which have to be compiled with down-graded optimisation from the main-stream routines. "Extra diversion" can be used to further split the material, for example into the routines of a program and the routines for testing the program.
The combination of data type plus diversion results in what is called a
"logical (output) stream". With the c/l +ASM given in the blank
deck of the cradle one can overrule Nypatchy's default assumption on
what to to with the material of each logical stream.
T= parameter;
defaults: for a deck: type of its patch;
for a patch: Fortran.
There are 7 standard data types:
T=FORT for Fortran
T=CC for C
T=INCL for C include files
T=AS for assembler
T=DATA for data with no implied special actions
T=SHELL for shell scripts
T=CRAD for cradles
(The old keys words CO[mpile], X[cc], AS[...], D[ata] are
supported for back compatibility. The square brackets indicate
optional additional characters.)
There may be any reasonable number of user data types on the Pam file(s). For each type the user chooses a name and sticks to it (no abbreviations), For example:
+PATCH, DOC, T=LATEX.The standard data types are reserved names, and also
J[oin],
R[epeat],
CO[mpile], X[cc], AS[...], D[ata].
To use the new data types on Pam files which may still have to be read with Patchy 4, one may declare an old data type followed by a new one, for example:
+DECK, COUM, T=DATA, SHELL.Patchy 4 will see
"DATA", whilst Patchy 5 will see "SHELL".
Or:
+DECK, AQUA, T=XCC, INCL.Patchy 4 will see
XCC, Patchy 5 will see an include file and therefor
add the extension ".h" by default.
Careful: do not use a user data type starting with any of the letters A, C, D, J, R, X if you want to be back-compatible.
Material may be diverted or extra-diverted with the control lines
+DIVERT, pname[, D=dname].
+XDIV, pname[, D=dname].
The logical streams are identified by the name of the data type
and a suffix, for example:
LATEX:1 normal/normal
LATEX:2 normal/diverted
LATEX:3 extra/normal
LATEX:4 extra/diverted stream of data type LATEX
The generic logical stream LATEX (or LATEX:0) designates all
logical streams of the this data type.
A logical stream may be made physical by giving output instructions for it, a file name in the simplest case. Several logical streams may be bound to a physical stream.
To establish a physical stream one may give in the cradle one of the
4 forms of the control-line +ASM (using FORT:0 as example):
+ASM, FORT, T=ATTACH .fname or +ASM, FORT, T=SPLIT. or +ASM, FORT, T=MODIFY. or +ASM, FORT, T=BYPASS.These examples each establish the physical stream
FORT. In the
first case the file name is given on the control-line, in the second
and third case each deck is written to a separate file (see later),
in the last case all material coming to this stream is flushed.
The generic logical streams of any of FORT, CC, AS,
or DATA and the
diverted streams FORT:2, CC:2, AS:2, and DATA:2,
can also be made
physical by giving the file-name in the corresponding positional
parameter of the program call statement for Nypatchy. Unless instructed
otherwise with a +ASM line in the cradle, T=ATTACH is then assumed
for such a stream.
For any other physical stream a +ASM line has to be used, for example:
+ASM, LATEX, T=ATTACH .fname (all)
+ASM, LATEX:1, T=ATTACH .fname (normal)
+ASM, FORT:3, T=ATTACH .fname (extra)
If several logical streams are to be bound to one physical stream this
can be done as with this example:
+ASM, TEX, LATEX, T=ATTACH .fnameThis sends all logical streams of
LATEX and TEX together
through the physical stream TEX (or TEX:0, which is the
same thing) onto the single file fname.
"Binding" of a given logical stream means that the output of this stream goes to the same file as the output from the stream it is bound to.
Default binding is initialized such that the wanted set-up can be specified with minimal instructions. This default is:
CC, AS, SHELL, CRAD,
DATA are bound to the generic stream FORT;
INCL is bound to
the generic stream CC;
DATA;
X:i of type X are bound
to the generic stream X:0;
if this is itself bound to the generic stream Y:0, then the logical
streams X:i are bound to the corresponding streams Y:i;
X:0 or X:1 are made physical all logical
streams X:i are bound to it, provided they have not been bound
explicitly to somewhere else; similarly if the logical stream X:3
is made physical, the logical stream X:4 is bound to X:3.
+ASM, FORT, T=ATTACH .finorm
+ASM, FORT:2, T=ATTACH .fidiv
collects the output of the logical streams "divert" of all data types
and sends it to file fidiv; the output from all other streams goes
to file finorm.
+ASM, DATA, T=BYPASS.
+ASM, FORT, T=ATTACH .finorm
+ASM, FORT:2, T=ATTACH .fidiv
does the same as the previous example, but all non-compilable material
is by-passed.
Explicite binding can be done by giving several logical streams, for example:
+ASM, TEX:2, LATEX:2, T=ATTACH .fnamewhich establishes the physical stream
TEX:2 and binds the logical
stream LATEX:2 to it.
To specify binding without at the same time establishing a physical stream
one has to give the parameter T=BIND; thus to achieve the binding-only
of the previous example:
+ASM, TEX:2, LATEX:2, T=BIND.By giving 2 (or more) generic logical streams one can map all logical streams of one data type onto the logical streams of another data type, for example:
+ASM, TEX, LATEX, T=BIND.binds the data type
LATEX to the data type TEX, such that
the logical streams LATEX:i are bound to TEX:i.
"Aliasing" is similar to binding, for example
+ASM, TEX, LATEX, T=ALIAS.signals that
LATEX is just another name for TEX.
Only generic stream names may be aliased.
The difference between binding and aliasing is
further explained below and in sect. 10.
Again, several names may be given, as for example:
+ASM, FORT, FORT77, FORT99, T=ALIAS.which tells Nypatchy that
FORT77 and FORT99 are just other
names for the data type FORT.
T=SPLIT
One may request that Nypatchy writes each deck coming to a given physical stream to a separate file, whose name is derived from the deck-name with an extension added. For example:
+ASM, FORT, T=SPLIT. (or T=MODIFY, see later)requests splitting of all decks arriving on the physical stream
FORT,
that is the decks of all logical streams bound to this physical stream.
It will create in the current working directory a number of files,
one for each non-empty deck, with extensions like
.f, or .c, or .s, or .h, added
according to the data type of each deck.
Nypatchy knows the extensions needed for the standard data types
FORT, CC,
INCL, and AS, on the machine one is running on.
For data type CRAD the
extension used is .cra; for SHELL .sh is used on UNIX, .com on VAX.
For data type DATA .dat is used on the VAX, and nothing on UNIX.
One may want to change the extensions used, or for the user data types or
for type DATA one may want to set the extension; this can be done with,
for example:
+ASM, FORT, T=EXT ..ftnThe directory into which the files are written is the current working directory by default; this can be changed by adding a common prefix to all file names, with for example:
+ASM, FORT, T=SPLIT, PREFIX .work/One may request that a record of the files created be written to a file to be digested by Nyshell, a child of Fcasplit, with for example:
+ASM, FORT, T=SPLIT, LOG .fnameThe last two examples can be combined if the prefix is a pure directory, for example:
+ASM, FORT, T=SPLIT, PREFIX, LOG .work/fnameThe resulting log file will contain one line for each deck written, giving its logical stream name and its file name, as for example:
fort:1 chdirf.f
cc:1 chdiri.c
fort:1 getenvf.f
cc:1 geteni.c
cc:1 getpidf.c
fort:2 getwdf.f
cc:2 getwdi.c
Note the difference between binding and aliasing in this context:
if there is a deck M432 of type LATEX on the Pam file, which is
processed with
+ASM, TEX, LATEX, T=SPLIT, LOG ...there will be an entry
"latex:1 m432" on the log file, but
if the processing is done with
+ASM, TEX, T=SPLIT, LOG ...
+ASM, TEX, LATEX, T=ALIAS.
the entry will be "tex:1 m432".
T=MODIFY
Giving T=MODIFY instead of T=SPLIT will cause Nypatchy to
compare the text of each deck against the corresponding file,
if it pre-exists, and to suppress the output if the two are identical.
Thus the date of the existing and unchanged file is not disturbed.
As for T=SPLIT, one may give, for example:
+ASM, FORT, T=MODIFY, PREFIX .work/
+ASM, FORT, T=MODIFY, LOG .fname
+ASM, FORT, T=MODIFY, PREFIX, LOG .work/fname
The resulting log file will contain one line for each deck, unchanged decks
are marked with the "same" flag, giving something like:
fort:1 chdirf.f
cc:1 chdiri.c
fort:1 getenvf.f same
cc:1 geteni.c same
cc:1 getpidf.c
fort:2 getwdf.f
cc:2 getwdi.c same
Arbitrary routine header lines can be defined for a given data type either for all logical streams, or for a particular stream with, for example:
+ASM, AS, T=RH .@|DECK ID>, @ . (all) or +ASM, AS:1, T=RH .@|DECK ID>, @ . (normal only) or +ASM, AS:2, T=RH .@|DECK ID>, @ . (diverted only)In the comment field of the control line one gives the mask for generating the routine header line; the very first character is the escape character used to indicate the place where the routine name has to be inserted.
On the machines where this useful, routine header lines are pre-initialized as needed by Fcasplit on the machine where one is running on to something like:
+ASM, FORT, T=RH .@CDECK ID>, @ .
+ASM, CC, T=RH .@/*DECK ID>, @ . */
+ASM, AS, T=RH .@|DECK ID>, @ .
This can be switched off, for example with:
+ASM, AS, T=RH.with an empty comment field.
Routine header lines are not generated for processing in T=SPLIT mode.
Note that +ASM, T=RH... lines merely modify the information for
the logical stream, quite independent from and without disturbing
its binding to some physical stream.
In a similiar manner, control-character substitution can be requested with, for example:
+ASM, DATA, T=CCHSUB .&+!+This example changes the control-character
& or ! on any line
of the output written to the ASM file for all logical streams of type
DATA into a + if
the key of the line is that of a Patchy control line.
The data types SHELL and CRAD are initialized with
T=CCHSUB .&+ which can be over-ridden with a +ASM line.
Again, this could be switched off
with +ASM, SHELL, T=CCHSUB. for example.
Primarily to help in the phase of transition from Patchy 4 to 5, a facility is provided to change the data type of all decks of a particular logical stream, for example:
+ASM, DATA:2, T=REASSIGN, S=INCL.This tells Patchy that material driven to the logical stream
DATA:2,
"diverted DATA", consists really of include files for C. This material
should have had a T=INCL declaration on the Pam file and it will be
treated as if it had: it will be sent to output through the logical
stream INCL:2, with the right properties, like file extension or
routine-header lines.
This also works:
+ASM, CC:2, T=REASSIGN, S=INCL."Diverted CC" will be re-assigned to "diverted INCL", which logical stream is bound be default to
CC:2, and if this latter is made
physical the output will appear there, but with the properties
corrected.
Note that "reassignment" has nothing to do with "binding" and does not interfer with it.
All user data types whose material is USEd should have been declared on
some +ASM line in the blank deck of the cradle.
If no +ASM line for such a user data type is needed for any of the above
purposes, a line like
+ASM, LATEX, T=USED.should be given, for example; it does nothing but open the generic logical stream
LATEX.
Several data types may be given on one line as with
+ASM, LATEX, TEX, SCRIPT, T=USED.which does not imply any binding.
If Nypatchy finds a non-declared data type when processing USE-selected
material on the Pam file, it prints a warning and opens a generic stream
for this data type, which it then binds to the stream DATA.
The general format is:
+ASM, (D=)str1,str2,..., T=action, S=dtyp, IF=... .comment-fieldEstablishing a physical stream, with binding:
+ASM, phys, log1, log2, ..., T=ATTACH .fname
+ASM, phys, log1, log2, ..., T=SPLIT.
+ASM, phys, log1, log2, ..., T=MODIFY.
+ASM, phys, log1, log2, ..., T=BYPASS.
Binding only:
+ASM, here, log1, log2, ..., T=BIND.Aliasing:
+ASM, here, generic1, generic2, ..., T=ALIAS.Specify file-name prefix for
SPLIT or MODIFY mode:
+ASM, phys, T=PREFIX .prefixSpecify log file for
SPLIT or MODIFY mode:
+ASM, phys, T=LOG .fnameSpecify default extension:
+ASM, log1, log2, ..., T=EXT. extensionSpecify routine header lines
+ASM, log1, log2, ..., T=RH .maskSpecify control character substitution:
+ASM, log1, log2, ..., T=CCHSUB .maskData-type reassignment
+ASM, log, T=REASSIGN, S=true.User type declaration:
+ASM, log1, log2, ..., T=USED.
To allow a period of transition where one may want to use the same cradles both with versions 4 and 5 of Patchy, the following is available in back-compatible mode (the default for the time being):
If Nypatchy is presented with a +ASM line for the old Ypatchy
it will do the following:
a) translate 21 -> FORT:1, 22 -> AS:1, 23 -> DATA:1, 24 -> CC:1
31 FORT:2, 32 AS:2, 33 DATA:2, 34 CC:2
b) a parameter LUN=n is ignored.
c) if no T= parameter is given T=BIND is assumed.
d) the presence of a parameter like R=! will cause an error.
e) the presence of any of T=EOF, HOLD, MIX, RESUME will cause
an error (rather unlikely to happen).
Thus the following cradle is alright as it stands, provided one
does not want to use the new features of Patchy, such as Nyshell:
+USE, ${PLINAME}.
+ASM, 23, T=ATT .=${CERN_ROOT}/bin/wylbur.help
+ASM, 24.
+EXE.
+USE, *WYLBUR.
+PAM, 11, T=C,ATT .${CERN_ROOT}/src/car/wylbur
+QUIT.
The line +ASM,23,T=ATT ... is translated into +ASM,DATA,T=ATTACH ...
The line +ASM,24. is translated to +ASM,CC,T=BIND. and has hence
no effect: with Patchy 4 this line establishes stream 24 with the
file-name taken from the command line. With Patchy 5 the presence
of the command line parameter for stream CC is sufficient; but be
careful:
the order of the file-names on the program-call statement has changed:
asm= 21 22 23 31 32 33 24 34
ypatchy pam fort cradle print as data fort:2 as:2 data:2 cc cc:2
nypatchy pam fort cradle print cc as data fort:2 cc:2 as:2 data:2
asm= 21 24 22 23 31 34 32 33
p= 1 2 3 4 5 6 7 8 9 10 11
Remember also the default stream binding rules:
With Patchy 4 all streams are initially bound to stream 21; to establish
a physical stream "n" a control-line +ASM,n has to be given as well
as the file-name in the correct position on the program-call statement.
With Patchy 5 generic streams
CC, AS, SHELL, CRAD, DATA are intially bound to stream FORT,
stream INCL is initially bound to CC,
all user data types are bound to DATA,
logical streams X:i are initially bound to X:0, but if X:0
is itself bound to Y:0 all X:i are bound to Y:i.
Giving a file-name for a particular stream on the program-call
command establishes this stream as physical.
For the following Cernlib cradle:
+USE, ${PLINAME}.
+ASM, 23, T=ATT .:flibD.dat
+ASM, 24.
+ASM, 34, R=! ./*DECK ID>, !.h */
+EXE.
+DIVERT, FMH.
+USE, *FATLIB.
...
+PAM, 11, T=C,ATT .${CERN_ROOT}/src/car/fatmen
+QUIT.
being used with:
21=FORT:1 22 24=CC:1 34=CC:2
1 2 3 4 5 10 11
ypatchy - flibf.fca $CRAD $PR ----- flibc.fca flibc.inc .go
fcasplit flibf.fca
fcasplit flibc.fca
fcasplit flibc.inc
we have to do something; let us change it into:
+USE, ${PLINAME}.
+ASM, 23, T=ATT .:flibD.dat
+ASM, 24.
+ASM, 34, R=!, IF=-PY_VS5 ./*DECK ID>, !.h */
+ASM, 34, T=REASSIGN, S=INCL, IF=PY_VS5.
+EXE.
+DIVERT, FMH.
+USE, *FATLIB.
...
+PAM, 11, T=C,ATT .${CERN_ROOT}/src/car/fatmen
+QUIT.
This cradle can be used with Patchy 4 as before, provided that
P=PY_VS5 is not USE selected.
It can be used with Patchy 5 in the same context:
21=FORT:1 24=CC:1 22 34=CC:2 32
1 2 3 4 5 6 9 10
nypatchy - flibf.fca $CRAD $PR flibc.fca --- flibc.inc .go
fcasplit flibf.fca
fcasplit flibc.fca
fcasplit flibc.inc
P=PY_VS5 is internally pre-selected as USEd if Patchy 5 is running.