CALL (Call Program)
Purpose
The Call (CALL) command calls a program named on the command, and passes control to it. Optionally, the program or user issuing the CALL command can pass parameters to the called program. The CALL command can be used in batch jobs, in interactive jobs, and in both compiled and interpreted control language (CL). When the called program finishes processing, it can return control to the calling program using the RETURN command.
If the CALL command is issued by a CL program, each parameter value passed to the called program can be a character string constant, a numeric constant, a logical constant, a floating-point constant, or a CL program variable. If a floating-point constant is specified, the value is converted to double-precision format and passed to the called program. If parameters are passed, the value of the constant or variable is available to the program that is called. Parameters cannot be passed in any of the following forms: lists of values, qualified names, expressions, null parameters (that is, a parameter whose value is null, specified by *N), or keyword parameters. Up to 99 parameters can be passed to the called program.>
If parameters are passed to a program using the CALL command, the values of the parameters are passed in the order in which they appear on the CALL command; this order must match the order in which they appear in the parameter list in the calling program.
Parameters in a called program can be used in place of its variables. However, no storage in the called program is associated with the variables it receives. Instead, if a variable is passed, the storage for the variable is in the program in which it was originally declared. If a constant is passed, a copy of the constant is made in the calling program and that copy is passed to the called program.
The result is that if a variable is passed, the called program can change its value and the change is reflected in the calling program. If a constant is passed, and its value is changed by the called program, the changed value is not known to the calling program. Therefore, if the calling program calls the same program again, the values of constants are set to their original values, but the variables do not change.
Information on passing variable parameters using the CALL command within a Submit Job (SBMJOB) command is in the Work Management book.
Restriction: The user must have object operational authority to the program being called. The user must also have a data authority.
Required Parameters
- PGM
- Specifies the qualified name of the program being called.
The name of the program can be qualified by one of the following library values:
-
*LIBL: All libraries in the job's library list are searched until the first match is found.
-
*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.
-
library-name: Specify the name of the library to be searched.
program-name: Specify the name of the program being called.
-
Optional Parameters
- PARM
- Specifies one or more parameter values that are passed to the called
program. Each of the values can be specified in only one of the following
forms: a character string constant, a numeric constant, logical constant,
double-precision floating point constant, or program variable.
The type and length of each parameter must be the same in both the calling and receiving programs. The number of parameters and the order in which they are sent and received must also be the same. If the CALL command is entered interactively or in a noncompiled batch environment, the type and length expected by the called program must match that of each parameter being passed on the command.
Parameters can be passed and received as follows:
- Character string constants of 32 bytes or less are always passed
with a length of 32 bytes (padded on the right with blanks). If a
character constant is longer than 32 bytes, the whole length of the constant is
passed. If the parameter is defined to contain more than 32 bytes, the calling
program must pass a constant that contains exactly that number of bytes.
Constants longer than 32 characters are not padded to the length
expected by the receiving program.
The receiving program can receive less than the number of bytes passed (in this case, no message is sent). For example, if a program specifies that 4 characters are to be received and ABCDEF is passed (padded with blanks in 26 positions), only ABCD is accepted and used by the program. Quoted character strings can also be passed.
- Decimal constants are passed in packed form and with a length of (15 5),
where the value is 15 digits long, of which 5 digits are decimal positions. If
a parameter of 12345 is passed, the receiving program must declare the decimal
field as (15 5); the parameter is received as 1234500000 (which is
12,345.00000).
- Logical constants are passed as 1 byte with a logical value of '1' or '0'.
- Floating-point literals and floating-point special values (*NAN, *INF, and
*NEGINF) are passed as double-precision floating-point numbers, which occupy 8
bytes and are specified in the form
n.n E n;
for example, 2.47E3). A single-precision floating-point number cannot be passed to a called program.
- A program variable can be passed if the call is made from a CL program, in
which case the receiving program must declare the field to match the variable
defined in the calling CL program. For example, if a CL program defines a
decimal variable named &CHKNUM as (5 0), the receiving program must declare
the field as packed with 5 digits total, with no decimal positions.
If either a decimal constant or a program variable can be passed to the called program, the parameter should be defined as (15 5), and any calling program must adhere to that definition. If the type, number, order, and length of the parameters do not match between the calling and receiving programs (other than the length exception noted previously for character constants), unpredictable results will occur.
The value *N cannot be used to specify a null value because a null value cannot be passed to another program.
- Character string constants of 32 bytes or less are always passed
with a length of 32 bytes (padded on the right with blanks). If a
character constant is longer than 32 bytes, the whole length of the constant is
passed. If the parameter is defined to contain more than 32 bytes, the calling
program must pass a constant that contains exactly that number of bytes.
Constants longer than 32 characters are not padded to the length
expected by the receiving program.
Examples for CALL
Example 1: Calling a Program
CALL PGM(PAYROLL)
The program named PAYROLL is called with no parameters being passed to it. The library list is used to locate the called program.
Example 2: Defining a Character Constant
CALL PAYROLL '1'
The program named PAYROLL is called with a character constant passed as a quoted string. The program must declare a field of up to 32 characters to receive the constant. The library list is used to locate the called program.
Example 3: Passing Parameters
CALL LIB1/PAYROLL (CHICAGO 1234 &VAR1)
The program named PAYROLL located in library LIB1 is called. The calling program passes three parameters: a character string (CHICAGO), a decimal value (1234.00000), and the contents of the CL variable &VAR1. The attributes of the variable determine the attributes of the third parameter.
Example 4: Calling Program with Floating-Point Values
CALL PGM1 (1.5E3 *INF)
The program named PGM1 is called with two double-precision floating-point values being passed to it.
Error messages for CALL
*ESCAPE Messages
- CPD0783
- Variable &3 for parameter &2 must be TYPE(*DEC), LEN(&4,&5).
- CPF0005
- Returned command string exceeds variable provided length.
- CPF0006
- Errors occurred in command.
- CPF0805
- Error found when program &1 in &2 started.
- CPF0806
- Error found when procedure started.