PATH / GEN - ECL Development Tools
Two utilities to facilitate the use of ECL in demand.
Often a demand user will need to invoke repeatedly a locally written processor, program, @ADD stream, or SSG skeleton. It would be useful to have a shorter way of doing this than by always typing in the file and element name. The PATH utility provides two ways for doing this.
The first way assumes that all paths will reside in TPF$ for the duration of the run or until otherwise deleted. Up to 4096 paths may be so defined. PATH creates them by inserting the self-contained auxiliary absolute PATHX into the user's TPF$ and changing its name to a specified call name. A temporary file, $PATH$$INFO$, contains the data for each defined path, including the type of path and the name of the source file and element. When the path name is invoked, its copy of PATHX generates an @ADD stream (or an ER QECL$ call) that will invoke, @XQT, @ADD, or @SSG the source element from its original file. If there are several paths you expect to use every time you sign on, you could put their @PATH definition calls in an @ADD runstream, possibly using the N option. This first method may not be suitable if you frequently @FREE or @ERS your TPF$.
The second way allows the creation of a standalone absolute that can be saved in a file for later use, including a system file like SYS$LIB$*ALTLIB$.
@PATH[,opts] [pathname/type(n),sourcefile.elt,ADD-opts/XQT-opts,Spec1,...]
none - Define or replace path. If no arguments, show all currently defined paths by reading the $PATH$$INFO$ file. If pathname only, display that path. If type only, display all paths of that type.
B - Sort paths in reverse order of being defined when displaying all path definitions. If used with S or T, sort in reverse name order.
C - Edit elt cycle field with / vs. () when editing INFOR items.
D - Delete the given pathname.
E - When editing an unformatted processor call's spec fields, replace all normal punctuation marks (* / . etc.), except commas, with spaces. Even with this option it may not be possible to generate all variations of unformatted call parameters.
F - Assign the FUSION$NOINF file, provided the call to the path (as opposed to the internally generated PATHX call) is not @ADDed. This will prevent programs using FUSION from checking their INFOR$ to see if the call to them was @ADDed, assuming their 'INF' parameter was set. Otherwise, such programs could not use FUSION on their first output.
HELP - Display a 3-page Help screen about PATH.
I - Ignore user's call options for a PROC, XQT, or SSG path.
The I, J, and R options define how a PROC, XQT, or SSG path treats the execute options a path is called with, as opposed to the ones it was defined with.
If none of the I, J, or R options is used, the default will be R if no execute options were defined, I if they were. If you want to force an execution with no options, you must use I.
J - Join the user's call options to any predefined ones for a PROC, XQT, or SSG path. The two sets of options will be OR'ed.
L - List the generated ECL before submitting it, as opposed to the L @ADD option. In the case of an unformatted processor call, this will result in the listing of all specs as well as the program name, which would ordinarily not happen with an @ADD,L.
N - Do not display messages when defining or deleting paths. This is intended for multiple consecutive calls, such as might be found in an @ADD stream.
If used when displaying all paths or with HELP options, prevents the use of FUSION full screen mode.
P - If a PROC type path contains hard-coded processor call fields (Spec1, etc.), allow the caller to include additional fields, which will be edited after them. See also V.
Q - If the processor call generated by invoking a PROC type path would require only a single image (i.e., no continuation), submit it using ER QECL$ instead of an @ADD. Do the same for an XQT path call that has no specs, meaning it won't need data images following the @XQT. This option can be useful if a program executed via a path call makes a decision based on whether it is currently in an @ADD stream.
If a Q-option path does not meet the above conditions (by having continuation images or @XQT specs), it will revert to being @ADDed. If you anticipate this might happen for a path call to a FUSION program, use the F option along with Q. Q is ignored for unformatted calls.
R - Replace any predefined options on a PROC/XQT/SSG path with the user's. At least one user option must be present.
S - Sort entries by pathname when displaying all path definitions. The default is to list the paths in the order they were defined. If a type without a pathname is given ("@PATH,S /type"), sort and list only paths of that type.
T - Sort entries by type, then name.
U - Update a path to replace its @ADD, execute, or I/J/R options; its @ADD file digit; or to toggle its C, E, F, L, P, or Q options. If updating execute options, you may also need to update to the I, J, or R option depending on how the path was initially defined. If the @ADD or @XQT options, or @ADD file digit, are to be blank, code a '-' for that item. The path type and source cannot be updated; instead, replace the path.
V - If used with P, allow user-coded specs to fill any consecutive void fields that occur before the first hard-coded spec.
X - Delete all paths in TPF$. Will solicit confirmation in demand.
pathname: 1-12-character name to use when invoking this path. Must not duplicate any name in the standard search path (SYS$*LIB$, SYS$LIB$ or ALTLIB files, TPF$), any FURPUR commands, or any ECL statements. May be preceded by "filename." to denote a standalone absolute.
type: Type of path -- PROC - Processor Call (default)
XQT - Program @XQT
ADD - @ADD runstream
SSG - @SSG skeleton
UNF - Unformatted Processor Call. The path itself is called normally, but it will generate a call beginning with @'. See E option regarding fields.
n: If this path is calling another path, the pathname field may include an elt cycle field with a single digit that will be added to the path's @ADD file name to make it different from the default, in order to avoid @ADD conflicts: pathname/type(n).
sourcefile.elt: Absolute element to call (PROC/XQT/UNF), runstream to @ADD, or skeleton to input to SSG. If a standalone absolute is being created (filename.pathname) and sourcefile is 'CSINTNAME$', then this path will always assume that its target absolute, runstream, or skeleton is in the same file as itself, allowing them both to be copied to different files without modification.
ADD-opts: E, L, P, or R, for @ADD of program call, @ADD stream, or @SSG call. Note that SSG paths must have the E @ADD option for the skeleton to begin executing. Otherwise, SSG will be expecting file input (SGS, etc.) followed by an @EOF. The R option may be needed for PATH calls submitted through ER QECL$. Using the L option for a Q-option PATH will set the equivalent bit in the QECL$ packet. If the path generates an unformatted processor call, the P option will list only the processor name, not any spec fields.
XQT-opts: any letters, for processor, @XQT, or @SSG call options.
Spec1,...: Hard-coded processor call fields to include on a PROC type PATH call. If a field is to be left void, code '--' for it. The complete processor call will not be allowed to exceed 80 characters.
PATH assigns these temporary files to contain the following:
$PATH$$INFO$ - display information about each path. If this file should be inadvertently @FREEd (such as by a utility like FREEM or FREEALL), paths may still execute but cannot be displayed; or the @PATH display may contain garbage. To remedy this, do a '@PATH,X' and recreate all paths.
$PATH$$ADDF$ - @ADD file created when a path is called. If it should become necessary to define a path which calls another path, a conflict between @ADD files may be avoided by coding a digit in the pathname's elt cycle field which will be used to make this path's @ADD file unique. Example:
@PATH CALL2(0),file.CALL1
- will use $PATH$$ADDF0.
PATH$SGS - processor call and/or option field SGSs for SSG or ADD paths.
Below are examples of PATH usage. Each path setup inserts the small, internally contained absolute PATHX into TPF$, changing its name to "pathname" and version to PATH$-msadr.
@<file>.PATH,Q PATH,<file>.PATH . Sets up call to PATH
-----------------------------------------------------------------------
@PATH TST,MYFILE.MYPROG . Sets up PROC call path
Usage: @TST,FKV TEST1,A.B . Call the path with any options or specs
Generates: @MYFILE.MYPROG,FKV TEST1,A.B
OR: @XQT,FKV MYFILE.MYPROG . if XQT path(@PATH TST/XQT,MYFILE.MYPROG)
then: TEST1 ...etc. . (One data image generated for each spec)
@PATH,D TST . Delete the path definition for TST
-----------------------------------------------------------------------
@PATH UPD,MYFILE.MYPROG,,MYFILE.ELT1,.ELT2 . Call with fields
Usage: @UPD
Generates: @MYFILE.MYPROG MYFILE.ELT1,.ELT2
-----------------------------------------------------------------------
@PATH CPL/ADD,PROGS.COMPILE/RUNSTREAM,L . @ADD runstream call
Usage: @CPL[,options] [spec1,spec2,...]
Generates: @ADD,L PROGS.COMPILE/RUNSTREAM
@PATH,U CPL,,PL . Updates CPL path to change @ADD options
-----------------------------------------------------------------------
@PATH SKL/SSG,MYFILE.COMPILE/SKEL,E/MNL . @SSG skeleton call
Usage: @SKL,ABC ELT1,,FILE.ELT2 . Call path with any options or specs
Generates: @SSG,MNL MYFILE.COMPILE/SKEL,PATH$SGS.
PATH$SGS contains: PATH$OPT ''ABC'','',ABC'' A,B,C
[ If no options: PATH$OPT '''','''' ]
PATH$MOD nn [ If @SKL(nn) ]
PATH$ ''ELT1''
PATH$ ''''
PATH$ ''FILE.ELT2''
@PATH,U SKL,,-/BK . Cancel @ADD options, replace @SSG options.
-----------------------------------------------------------------------
@PATH MYFILE.MSDISP/SSG,MYFILE.MSDISP/SKEL,E/MN
. This generates a standalone absolute that can be
. used as a utility processor to invoke a skeleton.
Usage: @MYFILE.MSDISP[,options]
-----------------------------------------------------------------------
@PATH EADD/ADD . '@EADD file.elt' will exit @ED update before @ADDing.
-----------------------------------------------------------------------
@PATH UDSMON,UDS$$SRC*UTIL$.UDSMON . Easier call to UDSMON.
-----------------------------------------------------------------------
@PATH MSD,PROGFILE.MSD . Define call for mass storage display.
@PATH,I MF, PROGFILE.MSD,/F . MSD call for fixed drives.
@PATH MR, PROGFILE.MSD,/R PAK/ABC$$$ . MSD call for selected drives.
-----------------------------------------------------------------------
@PATH,LE SPUTIL/UNF,ABC*ABS.SPUTIL . Unformatted processor call
Usage: @SPUTIL PARAM1*PARAM2.PARAM3
Generates: @'ABC*ABS.SPUTIL PARAM1 PARAM2 PARAM3
2. GEN -- SSG Path for Generating Multiple ECL Images [Top][Contents]
The SSG skeleton GENSKEL is included as part of the PATH package to provide still more development shortcuts. Its purpose is to generate and @ADD multiple ECL statements, or to save them and define a PATH to them.
Before using GENSKEL, the following PATH definition will be required:
@PATH GEN/SSG,<file>.GENSKEL,E/MNL
@GEN[,options] SPEC1,SPEC2,...
Options:
A - Used with P to denote that a standalone PATH absolute will be generated (requires filename.SPEC1). If omitted, the call will still work, but you will get a warning message that SPEC1 is not a simple pathname.
B - Replace all special characters in $images with a blank.
C - Replace all special characters in $images with a comma.
E - Generate @EOF as last ECL. Assumed if last processor call is ELT, MAP, MASM, FTN, or ACOB. (These are defined on the NEEDEOF SGS at the beginning of the skeleton.)
G - Assume S option, and also define SPEC1 as an @SSG path.
I - If used with S, do not @ADD the saved ECL. Assumed with P.
HELP - Display a 2-page Help screen about GEN.
L - Always list the generated ECL.
N - Do not list the saved ECL (S/P options) or @PATH calls (P option).
P - Assume S option, and also define SPEC1 as an @ADD path.
S - Save the generated ECL in the file or element named in SPEC1. If no filename is given, temp file "TPG$" will be assigned and used.
V - Leave void fields (--) as they are.
W - For a regular @GEN (no P or S), ask whether to @ADD the generated ECL.
Starting with SPEC1 (SPEC2 if S or P option), the @GEN processor call fields are used to describe one or more ECL statements, according to these rules:
1. The first item is the ECL statement or processor call. This is put in the element name field; any options go in the version name field.
2. Any consecutive specs after that are specs for the ECL or processor.
3. One ECL image is ended, and separated from the next, by a blank spec.
4. A new ECL image beginning with '$' is generated as a data image. The '$' is dropped and special characters replaced: *=Sp (=sp )=sp /=sp .=. These are defined by the CHSUB1 & CHSUB2 SGSs, but may be overridden by the B or C options.
5. A void spec field may be generated by coding '--'.
6. If defining a G-option @SSG path, the character string '--n--' may be used when the path is called to insert SPEC n of the path call statement into the generated ECL.
@GEN MASM/E,FILE.PROG,REL,,MAP,FILE.PROG/MAP,.ABS
Generates: @MASM,E FILE.PROG,REL @MAP FILE.PROG/MAP,.ABS @EOF
and @ADDs the ECL. ----------------------------------------------------------------------- @GEN,S FILE.TESTADD,XQT/ABC,FILE.PROG,,$3,4,,$TEST/1
Generates: @XQT,ABC FILE.PROG 3,4 TEST 1
and saves the ECL in FILE.TESTADD, then @ADDs it. ----------------------------------------------------------------------- @GEN,P MYFILE.TSTCMP,UC/E,F1.PROG
Generates: @UC,E F1.PROG into runstream MYFILE.TSTCMP and a standalone path call into absolute MYFILE.TSTCMP
To call: @MYFILE.TSTCMP ----------------------------------------------------------------------- @GEN,P CMP,FTN/E,F.SUB1,SUB1,,MAP,--,ABS,,$IN/MAIN,SUB1
Generates: @FTN,E F.SUB1,SUB1 @MAP ,ABS IN MAIN,SUB1 @EOF
saves the ECL in TPG$.CMP (but does not @ADD it) then generates and @ADDs: @PATH CMP/ADD,TPG$.CMP,L
If not saved, generated ECL will always go into the temporary file GENADD. ----------------------------------------------------------------------- @GEN,G CPL,FTN/E,F.--1--,REL.,,PREP,REL,,MAP,F.MAP,.ABS
Generates: #FTN,E F.[PATH$,1,1,1],REL. #PREP REL #MAP F.MAP,.ABS #EOF
saves the skeleton in TPG$.CPL then generates and @ADDs: @PATH CPL/SSG,TPG$.CPL,E/LMN
If path called later with: @CPL INITSUB will generate and @ADD: @FTN,E F.INITSUB,REL. @PREP REL @MAP F.MAP,.ABS @EOF
3. Utility SSG Skeletons for PATH [Top][Contents]
These skeletons are included to further demonstrate the usefulness of PATH.
BDISKEL provides a call, @BDI, for listing all or selected BDIs of installed products. There are options for sorting, verifying, and basing the BDIs.
To define: @PATH BDI/SSG,<file>.BDISKEL,E/MN
For B or V options, requires absolute BDIBASE in same file as BDISKEL.
For user guide: @BDI,HELP
FSORTSKEL provides a call, @FSORT, that can be used to invoke the @SORT processor against most types of SDF input, and to create and optionally view the output. FSORTSKEL sets up the call to @SORT, as well as any required parameters.
To define: @PATH FSORT/SSG,<file>.FSORTSKEL,E/LMN
For user guide: @FSORT,HELP
The *DEFINE proc EDCALL in the skeleton may be altered to reflect the user's choice for the different editor calls.
OMLISTSKEL and the companion absolute, OMLIST, provide a way to list the definitions in an MSD omnibus element if the source is not available. Both the absolute and the skeleton must reside in the same file. The absolute was defined by:
@PATH OMLIST/SSG,CSINTNAME$.OMLISTSKEL,LE/MN
Call example: @<file.>OMLIST 48R8*ASM$PF.AAPCT
For user guide: @OMLIST,H
TABLESKEL provides a call, @TABLE, for viewing and querying different UDS structures, whether reporting on a schema or querying a table.
To define: @PATH TABLE/SSG,<file>.TABLESKEL,E/KLMN
For user guide: @TABLE,HELP
The *DEFINE procs BK1 and BK2 may be altered to reflect the user's desired methods of breakpointing into and out of a print file, and later examining it.