Call Subroutine (CALLSUBR)
Where allowed to run:
|
Parameters Examples Error messages |
The Call Subroutine (CALLSUBR) command is used in a CL program or ILE CL procedure for passing control to a subroutine. The subroutine name on the CALLSUBR command must match the subroutine name of a SUBR (Subroutine) command. The CALLSUBR command may be placed anywhere within the procedure, including other subroutines, with the exception of a program-level MONMSG command. If the called subroutine returns a value, such as an error code, the returned value can be stored into a 4-byte integer CL variable by specifying the CL variable name for the CL variable for returned value (RTNVAL) parameter.
Each CALLSUBR command which is run places a return address on the subroutine stack. A return address is removed from the subroutine stack when a RTNSUBR (Return from Subroutine) or ENDSUBR (End Subroutine) command is run. The default depth of the subroutine stack is 99. The subroutine stack depth can be set for a CL program or ILE CL procedure by using the the DCLPRCOPT (Declare Processing Options) command, and specifying a value for the Subroutine stack depth (SUBRSTACK) parameter. If a CALLSUBR command would cause the subroutine stack depth limit to be exceeded, message CPF0822 is issued and the subroutine stack is not changed.
Restrictions: This command is valid only within a CL program or ILE CL procedure.
| Top |
Parameters
| Keyword | Description | Choices | Notes |
|---|---|---|---|
| SUBR | Subroutine | Simple name | Required, Positional 1 |
| RTNVAL | CL variable for returned value | CL variable name, *NONE | Optional |
| Top |
Subroutine (SUBR)
Specifies the subroutine to which control is to be transferred when the Call Subroutine (CALLSUBR) command is processed. The subroutine must be defined within the same procedure as the CALLSUBR command.
This is a required parameter.
- simple-name
- Specify the name of the subroutine to which control will be passed. A CL variable name cannot be used to specify the subroutine name.
| Top |
CL variable for returned value (RTNVAL)
Specifies the variable to receive the return value from the called subroutine.
- *NONE
- The value returned by the subroutine is ignored.
- CL-variable-name
- Specify the name of the CL variable to receive the return value from the called subroutine. The return value will either be the default of zero, or the value specified for the Return value (RTNVAL) parameter on the Return from Subroutine (RTNSUBR) or End Subroutine (ENDSUBR) command. The variable must be a 4-byte signed integer CL variable.
| Top |
Examples
Example 1: CALLSUBR with RTNVAL
DCL &INT4VAR TYPE(*INT) LEN(4) : CALLSUBR SUBR(SUBR1) RTNVAL(&INT4VAR)
The subroutine named SUBR1 is called, and the return value is stored in the variable &INT4VAR
Example 2: CALLSUBR as command parameter on IF command
IF (&A *LT 30) THEN(CALLSUBR LT30)
The subroutine named LT30 is called if &A is less than 30.
| Top |
| Top |