|
External routines can be called under CFS as:
a) User Options for evaluating the catalog entries according to special characteristics.
b) Variable Actions to perform special processing tasks on files, library elements or Job variables.
c) Action Codes to perform special processing tasks on files, library elements or Job variables as a customised Action Code.
d) Commands to perform special processing tasks for files, library elements or Job variables.
The CFS user can call an external User Option or a command routine as follows:
(module [,lib]) [ params]
Calling an external routine as a Variable Action is done as follows:
ONX(module [, lib]) [ params] | ON&(module [, lib]) [ params]
module Name of the module to be called (Module/CSECT Name).
lib Library in which the module is located.
Standard: CFSLIB
params optional parameters to be passed to the module when it is called, and which will control the execution of the routine.
Calling an external Action Code routine is done by entering the required Code in the Action Field.
This Action Code must first have been entered in a CFS-internal Action Code table before it will be correctly executed. Further information can be found in the source code of CFSMAIN, located in CFS.S.LMSLIB.
Calling conventions for external routines:
R1 Address of the parameter list
R13 Address of a 72 byte Save Area
R14 Return address in CFS
R15 Start address of the routine
Saving the registers should be achieved by following the standard conventions:
STM 14,12,12(13) (Start)
...
LM 14,12,12(13) (Return)
THe source code of the following routines is included in CFS.S.LMSLIB as examples of each of the different types of external routines:
a) FREE as an example of a User Option routine (Free Space).
b) CONV as an example of a user-specific Variable Action.
c) PREMOTE as an example of a user-specific Action Code (PD).
d) VSNSP as an example of a user-spcific CFS command.
VSNSP will display all VSNs occupied by a specified file, as well as the number of PAM pages occupied on each VSN by the file. The syntax is: (VSNSP) file.
Notes:
The expected parameter input for the above examples is documented in each sorce code.
To be recognised as such, user-defined Action Codes must be defined within the CFS system, in an Action Code table. The structure of the table element for the PD Action Code is described in the source code of CFSMAIN, located in CFS.S.LMSLIB.
User-specific message handling by the Connection handler can also be achieved. For further information, please contact our company, OPG.
CFS as SubprogramCFS can be called by any user program, without this program needing to be unloaded. The subprogram CFS can be linked directly into the user program, or loaded afterwards by a link macro. The following link macro statement should be issued to load CFS:
LINK ENTRY=CFSMAIN,LIBNAM=$TSOS.CFSLIB,INHIBIT=YES
When loading CFSMAIN, other modules will be called automatically by the autolink function. From there, a large module may be loaded that already contains the necessary submodules CFSUP and GDATE. This CFS2 module can be created by the procedure /DO CFS.S.LMSLIB(CFSLNK2).
The CFSMAIN and CFS2 modules must be loaded on page boundaries in the lower address area.
The source of the CFSMAIN module is located in the CFS.S.LMSLIB library, and may be adapted to computer center- or user-specific purposes.
CFS activates Stxit's internally for INTR, ABEND, K2 (ESCPBRK) and SVC conditions.
The main program can pass selection parameters, commands, Action Codes, as well as data to modify files, to CFS. It is therefore possible when calling CFS from a main program to perform an array of actions, such as selecting files or elements from a library, opening Connections, loading P-keys, setting particular CFS modes, loading files into EDT, displaying files under the CFS Editor, etc.
The various possibilities of using CFS as a subprogram is best explained by describing the calling parameter list.
Calling conventions and parameter lists: Main program --> CFS
Register assignment
R1 Address of the parameter list for CFSUP.
R13 Address of an 18 word Save Area in the calling program.
R14 Main program return address.
R15 Start address: start of the CFS2 or CFSMAIN modules.
Parameter list
P1 DC A(RECTABLE) | A(0)
P2 DC A(IND)
P1 DC A(RECTABLE)
List of input records in RDATA format.
CFS behaves as in a dialog procedure (see page 19-). In particular, the selection defined by a *002 record will be executed.
RECTABLE List of input records in V format. RECTABLE has the same function as SYSDTA, except that the data records exist in virtual memory, and not in a file. The end of RECTABLE should be marked with X'80'. After reaching the end of RECTABLE, or upon reading a *DIA record (see page 19-), CFS will expect all further input from the screen.
P1 DC A(0)
CFS expects no input from the calling program.
After being started by the user program, CFS will display the Selection mask on the screen, as though started normally with an EXEC command. Returning to the main program is achieved by the CFS commands END, * or MAIN.
P2 DC A(IND)
IND DC C'N'
New CFS begins with a new transaction, i.e. a record specifying the selection criteria (*001 or *002 record) is expected first.
IND DC C'C'
Continue Continue call. CFS continues at the point at which it was last interrupted by an END, * or MAIN command.
Example:
A simple example can be found in the CFS.S.LMSLIB library. The sample program TEST calls CFS multiply as a subprogram. The program can be assembled with /DO CFS.S.LMSLIB(ASSEMB),TEST and executed with /EXEC (TEST, CFSLIB).
The following example contains a parameter list from the main program for CFS.
P1 DC A(RECTABLE)
P2 DC A(IND)
IND DC C'N'
RECTABLE DS 0A
REC1 DC AL2(REC1L,0)
DC C'*002 FILE=NO'
REC1L EQU *-REC1
REC2 DC AL2(REC2L,0)
DC C'OC1/LOGON user-id,acct,C''passw'''
REC2L EQU *-REC2
REC3 DC AL2(REC3L,0)
DC C'LOAD programm'
REC3L EQU *-REC3
REC4 DC AL2(REC4L,0)
DC C'^'
REC4L EQU *-REC4
REC5 DC AL2(REC5L,0)
DC C'PL plus-module,maplib'
REC5L EQU *-REC5
REC6 DC AL2(REC6L,0)
DC C'EDT,file'
REC6L EQU *-REC6
REC7 DC AL2(REC7L,0)
DC C'@RET'
REC7L EQU *-REC7
REC8 DC AL2(REC8L,0)
DC C'NP'
REC8L EQU *-REC8
DC X'80'
Note:
Before passing a RECTABLE, the user should set task switches 1 and 4.