Go to Subroutine (GOSUBR)

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

The Go to Subroutine (GOSUBR) command is used in CL procedures for passing control to a subroutine. The subroutine name on the GOSUBR command must match the subroutine name of a SUBR command. The GOSUBR 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 GOSUBR command which is run places a return address on the subroutine stack. A return address is removed from the subroutine stack when a RTNSUBR or ENDSUBR command is run. The depth of the subroutine stack is 99. If a GOSUBR command would cause the subroutine stack depth to exceed 99, message CPF0822 is issued and the subroutine stack is not changed. Recursive calls (subroutines that call themselves) are included in the 99 limit.

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 Go to Subroutine (GOSUBR) command is processed. The subroutine must be defined within the same procedure as the GOSUBR 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: GOSUBR with RTNVAL

DCL &INT4VAR TYPE(*INT) LEN(4)
:
GOSUBR SUBR(SUBR1) RTNVAL(&INT4VAR)


The subroutine named SUBR1 is called, and the return value is stored in the variable &INT4VAR

Example 2: GOSUBR as command parameter on IF command

IF  (&A *LT 30)  THEN(GOSUBR 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