Run command sequence from procedure file or list variable
Component: | SYSFILE |
Functional area: | Procedures |
Domain: | PROCEDURE |
Privileges: | STD-PROCESSING |
Function
The CALL-PROCEDURE command starts a stored command sequence (procedure). During processing, symbolic parameters contained in the sequence are replaced by the values specified in the command call (PROCEDURE-PARAMETERS operand). A procedure may contain the following components:
commands (starting with a slash)
SDF statements, i.e. statements for a program which are defined in a syntax file (starting with a double slash)
input data, i.e. data, parameters and statements read by a program
During invocation, the procedure is assigned to the system file SYSCMD as the input source for commands. If the procedure includes SDF statements and/or input data, the SYSDTA system file must be assigned to the SYSCMD system file (see ASSIGN-SYSDTA, or SET-PROCEDURE-OPTIONS for S procedures).
Procedures can be stored as:
a cataloged SAM or ISAM file (even a temporary one) with records of variable length
a type J or SYSJ element in a PLAM library
an S variable of the “list” type
There are two types of procedure, which differ in formal structure and operational sequence:
non-S procedure
S procedure
Restrictions
Users with SECURITY-ADMINISTRATION, SAT-FILE-EVALUATION or SAT-FILE-MANAGEMENT privilege can use the command in procedures only.
A procedure cannot be started from an S variable by specifying FROM=*VARIABLE(...) unless the chargeable SDF-P subsystem is loaded.
Non-S procedure
The first data record in the non-S procedure must be the command BEGIN-PROCEDURE. The symbolic parameters, logging, and interruptibility of the procedure can be specified. Next come the commands, SDF statements and input data to be processed. Processing ends with the command END-, CANCEL- or EXIT-PROCEDURE or the last data record. If an error occurs, spin-off is activated. Error handling is described under the SET-JOB-STEP command.
S procedure
The first record in an S procedure must be a command. The commands BEGIN-PROCEDURE, or PROCEDURE (ISP command), and SET-LOGON-PARAMETERS, or LOGON (ISP command), are not allowed. Procedure attributes can be explicitly specified via SET-PROCEDURE-OPTIONS as the first command. If no explicit specification is made, the SDF-P presettings apply implicitly (see SET-PROCEDURE-OPTIONS). Once the procedure attributes have been defined, the DECLARE-PARAMETER command can be used to define symbolic parameters, which are replaced by the values of the like-named S variables during execution. S procedures can only execute if S variables are available, i.e. if at least the SDFPBASY subsystem (see section "SDF-P-BASYS" and the “SDF-P” manual [34]) is loaded.
Processing of commands, SDF statements and input data ends with the CANCEL- or EXIT-PROCEDURE command or with the final record. If an error occurs, SDF-P error recovery is activated. Error recovery is described under the command IF-BLOCK-ERROR.
Two different procedure formats are supported:
text procedure. The S procedure is in its original text format. The full range of SDF-P functions is available only if the chargeable subsystem SDF-P is loaded when the procedure is called. In libraries, element type J should be used for text procedures.
object procedure. An S procedure in text format has been translated to object format with the COMPILE-PROCEDURE command. The COMPILE-PROCEDURE command is part of the chargeable SDF-P subsystem. The object procedure can utilize the full functionality of SDF-P (apart from the COMPILE-PROCEDURE command) irrespective of whether the SDF-P subsystem is currently available or not. In libraries, element type SYSJ (the default for COMPILE-PROCEDURE) should be used for object procedures.
Automatic procedure start
LOGON procedure
After LOGON processing, SDF automatically starts the system LOGON procedure followed by the user LOGON procedure. A system LOGON procedure is started when system administration makes one available. A user LOGON procedure is started as a call procedure if it is cataloged in the relevant user identification under the name SYS.SDF.LOGON.USERPROC (if it is under SYS.SDF.LOGON.USERINCL it is called as an include procedure). LOGON procedures are ignored in the following cases and no warning is issued:
The procedure file is simply cataloged but does not occupy any storage space.
The task is an RFA task.
The task does not possess any privileges apart from HARDWARE-MAINTENANCE, SECURITY-ADMINISTRATION, SAT-FILE-MANAGEMENT, and SAT-FILE-EVALUATION.
Input is not possible until the LOGON procedures have been executed.
LOGOFF procedure
During LOGOFF processing, SDF automatically starts the user LOGOFF procedure and then the system LOGOFF procedure. A user LOGOFF procedure is started as a call procedure if it is cataloged under the name SYS.SDF.LOGOFF.USERPROC in the associated user logon (under SYS.SDF.LOGOFF.USERINCL the call takes the form of a call procedure). A system LOGOFF procedure is started if one has been made available by systems support (entry in the SDF parameter file).
LOGOFF procedures are ignored in the following cases and no warning is issued:
The procedure file is simply cataloged but does not occupy any storage space.
The task was canceled with CANCEL-JOB or FORCE-JOB-CANCEL.
The task is an RFA task.
The task does not possess any privileges apart from HARDWARE-MAINTENANCE, SECURITY-ADMINISTRATION, SAT-FILE-MANAGEMENT, and SAT-FILE-EVALUATION.
Implemented procedure
If commands implemented as procedures occur in an active syntax file (see the “SDF-A” manual [33]), the specified procedure is started when such a command is called.
Nesting of procedures
Procedures may be nested to any depth: If the command sequence of a procedure file contains a CALL-PROCEDURE command, the sequence is interrupted and the next procedure is started, etc.
At the end of a procedure (END-PROCEDURE, EXIT-PROCEDURE or EOF condition), control branches back to the interrupt point of the procedure last exited. The figure below provides an illustration of procedure nesting with CALL-PROCEDURE for a non-S procedure.
Format
CALL-PROCEDURE | Alias: CL/CLP | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Operands
FROM-FILE = <filename 1..54 without-gen> / *LIBRARY-ELEMENT(...) / *VARIABLE(...)
Name of the procedure file.
FROM-FILE = *LIBRARY-ELEMENT(...)
The procedure is stored in a PLAM library element.
LIBRARY = <filename 1..54 without-gen>
Name of the PLAM library containing the procedure as an element (type J or SYSJ: see TYPE operand).
ELEMENT = <composed-name 1..64>(...)
Name of the element.
VERSION = *HIGHEST-EXISTING / <composed-name 1..24>
Version of the library element. The default value is HIGHEST-EXISTING, i.e. the procedure is taken from the element with the highest version.
TYPE = *STD / *BY-LATEST-MODIFICATION / <alphanum-name 1..8>
Designates the element type the procedure is stored under in the PLAM library.
TYPE = *STD
The procedure can be stored as an element of type SYSJ or J. The specified element is first searched for among the type SYSJ elements. If it is not found there, the search proceeds to the type J elements.
A non-S procedure can only be a type J element. An S procedure may be either a text procedure (original text format) or an object procedure (compiled object format). To simplify maintenance of the two formats in a library, text procedures should be stored as type J elements, object procedures as type SYSJ elements. The COMPILE-PROCEDURE command (part of the chargeable SDF-P subsystem) by default generates an object procedure of type SJ from a text procedure of type J. If this convention is followed, specifying TYPE=*STD (the default value) ensures that object procedures will be given precedence over text procedures.
TYPE = *BY-LATEST-MODIFICATION
The procedure can be stored as an element of type SYSJ or J. If the specified element exists both as type SYSJ and as type J, the element most recently modified will be called. If the time stamp is identical, the type SYSJ element will be called. Specifying TYPE=*BY-LATEST-MODIFICATION ensures that the most up-to-date element will be called, typically during the debugging phase when a procedure is being written or modified.
TYPE = <alphanum-name 1..8>
The procedure will be searched among elements of the specified type only.
FROM-FILE = *VARIABLE(...)
Only possible if the chargeable software product SDF-P is loaded. The procedure is stored in an S variable of the “list” type.
VARIABLE-NAME = <composed-name 1..255>
Name of the S variable.
PROCEDURE-PARAMETERS = *NO / <text 0..1800 with-low>
Parameter values to be used in place of the corresponding symbolic parameters in the procedure file. For “text”, the following format applies:
( { sympar= / paramvalue / sympar=paramvalue }[,...] )
sympar is the name of a symbolic keyword parameter declared either in the BEGIN-PROCEDURE command (without the initial “&”) in the non-S procedure file, or in the DECLARE-PARAMETER command of the S procedure file.
paramval is the current value either of a keyword or positional parameter declared in the BEGIN-PROCEDURE command (maximum length 254 characters), or of a procedure parameter defined in the DECLARE-PARAMETER command. Character strings enclosed in apostrophes are also allowed as actual parameter values. The value must be enclosed in apostrophes if it contains blanks or special characters. Apostrophes within strings must be doubled. Lowercase letters within strings are retained.
The null string is interpreted as missing parameter value and, in interactive mode, leads to a request for a value during procedure execution. Values input during procedure execution (prompting) are converted to uppercase letters also within strings. If the current value of a parameter is requested during procedure execution and the user presses the K2 key, the system issues message SSM2060 asking if the user wants to terminate the procedure. If the procedure is continued, the value is queried again.
The current “paramval” parameter values from the CALL-PROCEDURE command replace the symbolic parameters as follows:
In the case of S procedures, parameters can be transferred as keyword or positional parameters since no specification in this regard is made in the DECLARE-PARAMETER command. However, a positional parameter must not follow a keyword parameter. Prompting is only possible if it has been defined (INITIAL-VALUE=*PROMPT).
In the case of non-S procedures, parameters can only be transferred as defined in the BEGIN-PROCEDURE command, i.e. positional parameters if defined as such and keyword parameters if defined as such.
Keyword parameters receive their current values from the parameter list of the CALL-PROCEDURE command. If a value is not specified, the value defined in the procedure is used. If no value was defined there either, the value is requested, in interactive mode, when the procedure is executed. This is called “prompting”.
The following table provides an overview of related parameter specifications in the BEGIN-PROCEDURE and CALL-PROCEDURE commands:
Specification in BEGIN- PROCEDURE &X=ABC
&X=
Specification in CALL-PROCEDURE
X=
Prompting
Prompting
X=DEF
DEF
DEF
without
ABC
Prompting
Positional parameters are assigned, in sequence, those current parameter values from the CALL-PROCEDURE command that are specified without the keyword “sympar=”. If the current value of a positional parameter is not specified in the CALL-PROCEDURE command (a comma stands for the value), it will be requested in interactive mode (prompting) when the procedure is executed (if the value is required at all).
LOGGING = *PARAMETERS(...) / *YES / *NO
This controls logging of procedure execution.
The LOGGING operand is ignored when non-S procedures are called since in this case logging can only be declared in the procedure head (see the LOGGING operand in the BEGIN-PROCEDURE command). When an S procedure is logged, every procedure line that is processed is output with the line number and procedure level prefixed to it.
LOGGING = *PARAMETERS(...)
Logging can be set separately for command/statement lines and for data lines.
CMD = *BY-PROC-TEST-OPTION / *YES / *NO
This specifies whether commands are to be logged. The default value is BY-PROC-TEST-OPTION, i.e. no logging (equivalent to *NO) or the value selected as the default by the user with the MODIFY-PROC-TEST-OPTIONS command (component of the chargeable SDF-P subsystem).
DATA = *BY-PROC-TEST-OPTION / *YES / *NO
This specifies whether data lines are to be logged. The default value is BY-PROC-TEST-OPTION, i.e. no logging (equivalent to *NO) or the value selected as the default by the user with the MODIFY-PROC-TEST-OPTIONS command (component of the chargeable SDF-P subsystem).
UNLOAD-ALLOWED = *YES / *NO
This specifies whether a program that was loaded when the procedure was called may be unloaded. Protection against unloading is guaranteed only for unloading by means of the commands START-(EXECUTABLE-)PROGRAM, LOAD-(EXECUTABLE-)PROGRAM, and CANCEL-PROGRAM.
The specification YES is ignored if the procedure is called from a procedure for which UNLOAD-ALLOWED=*NO was declared.
EXECUTION = *YES / *NO
This specifies whether the procedure is merely to be analyzed for test purposes or whether it is also to be executed. Only EXECUTION=*YES may be specified for non-S procedures. Testing is possible via the MODE operand of the MODIFY-SDF-OPTIONS command.
Return codes
The following command return codes can only be returned if the called procedure does not supply any command return code itself (e.g. EXIT-PROCEDURE not executed). Command return codes whose maincode begins with “SSM” can only be returned when a non-S procedure is called. Command return codes whose maincode begins with “SDP” can only be returned when an S procedure is called.
(SC2) | SC1 | Maincode | Meaning |
|---|---|---|---|
0 | CMD0001 | No error | |
2 | 0 | SSM2058 | Protocol type error |
2 | 0 | SSM2065 | EOF on procedure file, /END-PROC simulated |
1 | SSM2036 | Incomplete operand | |
1 | SSM2054 | Symbolic operand error | |
1 | SSM2055 | Symbolic operand error in /BEGIN-PROC | |
1 | SDP0138 | Error during pre-analysis of the text procedure or object procedure faulty | |
1 | CMD0202 | Syntax error | |
3 | CMD2203 | Incorrect syntax file | |
32 | CMD0221 | System error (internal error) | |
64 | SDP0093 | Non-S procedure can only be type J element. | |
64 | SDP0144 | Error during parameter transfer | |
64 | SSM2052 | DMS error (OPEN error) | |
64 | SSM2053 | Not a SAM/ISAM file or file does not begin with /BEGIN-PROC or /PROC | |
64 | SSM2056 | Parameters of /CALL-PROC and /BEGIN-PROC incompatible | |
64 | SSM2061 | Error on accessing library element | |
64 | SSM2064 | Procedure file cannot be fetched from remote system | |
130 | SDP0099 | No more address space available | |
xx | xx | xxxxxxx | Other return codes of the called procedure |
Notes
Symbolic operands may be used anywhere in any command in the procedure file. However, they cannot replace the initial slash preceding a command.
When the procedure records processed are logged to SYSOUT, symbolic operands are replaced with the current operand values.
Procedure files may be protected with passwords against reading, overwriting and execution, e.g. using the MODIFY-FILE-ATTRIBUTES command. The execute password or a higher-ranking password must be given in an ADD-PASSWORD command before a CALL-PROCEDURE command is issued.
When a library element is used, a temporary SAM file named S.IN.library.element.tsn.hhmmss.nnnn is created (only for non-S procedures), which contains the element. where:
library
Library name (up to 20 characters are printed)
tsn
Task sequence number
hhmmss
Time in hours-minutes-seconds
nnnn
Sequence number
This temporary file is automatically deleted when the following commands are encountered:
EXIT-JOB or LOGOFF in the ENTER file
END-PROCEDURE in the procedure
If the CALL-PROCEDURE command is called via the CMD macro, the calling program is unloaded. Any ABEND-STXIT routine defined in the program is not activated. For details of the CMD macro, ABEND-STXIT routine, refer to the “Executive Macros” manual [22].
If a non-S procedure file contains statement or data records in addition to command records, the following command record must be written in the procedure file prior to the statement or data records:
/ASSIGN-SYSDTA TO=*SYSCMDThis assignment need not be repeated in the event of nesting. In S procedures, this depends on the setting in the SET-PROCEDURE-OPTIONS command.