Begin procedure file and define procedure parameters
Component : | SYSFILE |
Functional area: | Procedures |
Domain: | PROCEDURE |
Privileges: | STD-PROCESSING |
Function
This command can only be used for non-S procedures.
The BEGIN-PROCEDURE command is required as the first record in a non-S procedure. It defines symbolic parameters that are used in the subsequent commands in the procedure file. Symbolic parameters are variables which are given actual values while the procedure is executing. These values may be defined as follows:
when the procedure is called: in the CALL-PROCEDURE command,
when the procedure is created: in the BEGIN-PROCEDURE command (so-called predefinition: these values are used only if no values are specified in the CALL-PROCEDURE command),
while the procedure is executing (prompting): The user is requested to enter a value during the dialog if no values were defined for the corresponding symbolic operands either in the CALL-PROCEDURE command or in the BEGIN-PROCEDURE command.
The BEGIN-PROCEDURE command may be used only in procedure files. In interactive mode it is rejected, and is therefore not offered as a menu option.
Format
BEGIN-PROCEDURE | ||||||||||||||||||||||||
| ||||||||||||||||||||||||
Operands
LOGGING =
Type of logging used for the procedure run. SDF statements are treated like commands for the purpose of logging.
LOGGING = *NO
No log of the procedure run is written to SYSOUT.
LOGGING = *ALL
Commands and input data for the procedure file are logged on SYSOUT when the procedure is executed.
LOGGING = *DATA
The input data for the procedure file is logged on SYSOUT when the procedure is executed.
LOGGING = *CMD
Commands and SDF statements of the procedure file are logged on SYSOUT when the procedure is executed.
PARAMETERS = *NO / *YES(...)
Specifies whether the procedure contains symbolic parameters.
PARAMETERS = *YES(...)
PROCEDURE-PARAMETERS = <text 0..1800 with-low>
Names of the symbolic parameters to be used in the procedure file. They form the so called parameter list for the procedure.
Permissible characters for symbolic parameters:
first character: | & |
second character: | letter |
subsequent characters: | letters and digits |
minimum length: | 2 characters |
maximum length: | 255 characters |
The individual symbolic parameters must be separated by commas; the entire expression must be enclosed in parentheses.
Symbolic parameters may be defined as positional parameters or as keyword parameters.
Positional parameters consist of only the name, e.g. &A.
Keyword parameters consist of the name followed by an equals sign, e.g. &A=. In addition, the name may be assigned a value, e.g. &A=VALUE. This value is used if the operand concerned is omitted when the procedure is called (CALL-PROCEDURE). The value must not exceed 254 characters in length.
Strings enclosed in apostrophes are also permitted as a value. 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.
If values are entered during procedure execution (prompting), lowercase letters will be converted into uppercase characters also within strings. The slash preceding a command cannot be replaced by parameters. Keyword parameters and positional parameters may appear in any order in the parameter list. If a symbolic parameter is followed in the procedure file by a period or an alphanumeric character, the parameter must be separated from it by a period.
ESCAPE-CHARACTER = *NONE / <c-string 1..1>
Character (&, @, #, $ or *) identifying symbolic parameters in input data. If no character is specified (= presetting NONE) symbolic parameters in input data are not replaced. SDF statements are treated as commands, i.e. symbolic parameters must begin with & there and are always replaced. Symbolic parameters in input data must begin with the specified character. If the character is duplicated, it is replaced by a single character preventing parameter replacement.
INTERRUPTION-ALLOWED =
Defines whether the procedure can be interrupted with the K2 key for command input. Commands within the procedure which result in an interrupt are executed nonetheless.
INTERRUPTION-ALLOWED = *YES
Interrupting the procedure with the K2 key is possible.
The user may enter commands.
The specification is ignored if the procedure is called from a noninterruptible procedure.
INTERRUPTION-ALLOWED = *NO
Interruption of the procedure via the K2 key is not possible. Nested procedures for subsequent procedure levels are also noninterruptible (regardless of the setting in INTERRUPTION-ALLOWED). If a program in which the event class ESCPBRK has been defined is called in a procedure, this STXIT routine is always activated by means of the K2 key.
Return codes
The BEGIN-PROCEDURE command is not interpreted by SDF. It can only result in an error if used in an incorrect context. In such a case the following command return code is issued.
(SC2) | SC1 | Maincode | Meaning |
|---|---|---|---|
64 | SSM2057 | Command not the first command of a non-S procedure |
Notes
The BEGIN-PROCEDURE command must always be the first record in a procedure file. This file must not contain any further BEGIN-PROCEDURE commands or LOGON or RESTART-PROGRAM commands.
The description of the CALL-PROCEDURE command explains how a procedure file is called and how the symbolic parameters are replaced with current values.
The description of the END-PROCEDURE command explains how a procedure file is terminated.
Examples
Example 1
The procedure file MJ.PROC begins with the following record:
/BEG-PROC LOG=*ALL,PAR=*YES(PROC-PAR=(&A,&B),ESC-CHAR=C'#')
By means of the procedure call:
/CALL-PROC FROM-FILE=MJ.PROC,PROC-PAR=(MODULE,LISTE)
the symbolic parameters are given values and the procedure is executed.
With the call:
/CALL-PROC FROM-FILE=MJ.PROC
the values are not defined until during the procedure run (prompting).
Example 2
The procedure file MJ.PROC contains the following records:
/BEG-PROC LOG=*ALL,PAR=*YES(PROC-PAR=(&A,&B),ESC-CHAR=C'#') /MODIFY-JOB-SWITCHES ON=(1,4,5) /ASS-SYSDTA TO=*SYSCMD /START-EXE FROM-FILE=$LMS LIB MJ.BIBLIO.#A,BOTH,NEW ADDJ #B END /SHOW-FILE-ATTR F-NAME=MJ.BIBLIO.&A,INF=*ALL-ATTR /MODIFY-JOB-SWITCHES OFF=(1,4,5) /END-PROC
By means of the procedure call:
/CALL-PROC FROM-FILE=MJ.PROC,PROC-PAR=(MODULE,LISTE)
the following commands and LMS statements are executed:
... /ASS-SYSDTA TO=*SYSCMD /START-EXE FROM-FILE=$LMS LIB MJ.BIBLIO.MODULE,BOTH,NEW ADDJ LISTE END /SHOW-FILE-ATTR F-NAME=MJ.BIBLIO.MODULE,INF=*ALL-ATTR ...
Example 3
The procedure file MJ.PROC1 contains the following records:
/BEG-PROC LOG=*ALL,PAR=*YES(PROC-PAR=(&IN,&OUT=MJ.OUT),ESC-CHAR=C'&') /ASS-SYSDTA TO=*SYSCMD /MOD-JOB-SW ON=(4,5) /START-EDT @READ'&IN' ... @WRITE'&OUT' @HALT /MOD-JOB-SW OFF=(4,5) /END-PROC
When called with:
/CALL-PROC FROM-FILE=MJ.PROC1
the following output appears on the screen:
%/BEG-PROC LOG=*ALL,PAR=*YES(PROC-PAR=(&IN,&OUT=MJ.OUT),ESC-CHAR=C'&') %/ASS-SYSDTA TO=*SYSCMD %/MOD-JOB-SW ON=(4,5) %/START-EDT %@READ'&IN' &IN= mj.inputfile %@READ'MJ.INPUTFILE' ... %@WRITE'MJ.OUT' %@HALT %/MOD-JOB-SW OFF=(4,5) %/END-PROC
Thus, the symbolic parameter &OUT is already preset by the procedure declaration; only &IN remains to be specified during the procedure run.