Where allowed to run:
|
Parameters Examples Error messages |
The Program (PGM) command is used in a CL source file to identify the start of a CL procedure that is to be compiled and to specify the parameters that are to be received by the procedure after it is compiled. If a PGM command is used, it must be the first command in the source file; if a PGM command is not used, a PGM command without parameters is assumed. The name of the CL procedure is specified on the CL command used to compile the CL source file.
The PGM command also specifies the parameters to be passed to the CL procedure, if any, when it is called for processing by another program. For information about how constants are passed, see the PARM parameter description for the Call (CALL) command.
If the CL procedure source file is compiled to create a program (*PGM) object, the program can be called by a Call (CALL) or Transfer Control (TFRCTL) command, or by a routing entry in a subsystem description. When the program is called by a CALL or TFRCTL command, the specified parameters can be passed to it.
Parameters defined in this command must be passed when the procedure is called. The parameters passed must be of the type, length, and order specified in this command. Each of the parameter values can be a character string, a numeric value, or a CL variable. When received, each value is given a different CL variable name. Each CL variable name must be defined in the CL source file by a separate DCL (Declare) command before the procedure is compiled. Up to 255 parameters can be passed.
ILE programs and procedures will not detect parameter mismatches between the calling program or procedure and the called program or procedure. If the calling procedure passes more parameters than the called procedure expects, the called procedure will ignore the extra parameters. If the calling procedure passes fewer parameters than are specified on the called procedures PGM command, the results may be unpredictable.
Restrictions: This command is valid only in a CL procedure.
| Top |
| Keyword | Description | Choices | Notes |
|---|---|---|---|
| PARM | Parameter CL variable names | Values (up to 255 repetitions): CL variable name | Optional, Positional 1 |
| Top |
Specifies one or more CL variables that are to receive the parameter values passed to this procedure. Specify a CL variable name for each of the values to be received; the name must start with an ampersand (&).
Null values, *N, cannot be specified for any parameter. The parameter values are associated with the variables in the PARM parameter in the order in which they were specified on the CALL or TFRCTL commands. The type and length of each value passed must have matching attributes in the calling and receiving programs. However, for character constants, the receiving program can specify a shorter length; when this is done, the character string passed is truncated to the length declared in the receiving program. For information on how each data type is passed, see the description of the PARM parameter in the CALL command.
Note: If a parameter value is to be changed by a CL procedure or specified as a variable on a CL command, it must be in writeable storage. For example, in C or C++, strings may be read only. If a read-only string is passed as a parameter to a CL procedure, and the CL procedure attempts to change the value of the variable or uses the variable on a CL command, the CL procedure will fail.
| Top |
Example 1: CL Procedure Containing No Parameters
PGM : ENDPGM
This PGM command is the first command in a CL source file for a CL procedure that contains no parameters.
Example 2: CL Procedure Containing Two Parameters
PGM PARM(&X &Y)
This is the first command in a CL source file for a CL procedure that contains two parameters, &X and &Y, that have values passed to them from the calling program or procedure.
Example 3: CL Procedure Containing Two Parameters in Positional Form
PGM (&PARM1 &PARM2)
This is the first command in a CL source file for a CL procedure that specifies two parameters in positional form, &PARM1 and &PARM2. When this procedure is called, the calling program or procedure passes the parameter values to be used for &PARM1 and &PARM2.
| Top |
None
| Top |