Call Subroutine (CALLSUBR)

Where allowed to run:
  • Batch program (*BPGM)
  • Interactive program (*IPGM)
Threadsafe: Yes 		Parameters
Examples
Error messages

The Call Subroutine (CALLSUBR) command is used in CL procedures 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 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 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

Error messages

*ESCAPE Messages

CPF0822
Subroutine stack overflow at statement &1.
Top