&GOSUB

Branches to a sub-routine within the procedure.

&GOSUB .label [ .limlabel [ EQ | NE | GT | LT | GE | LE ] ]

The &GOSUB verb lets you structure a procedure to take advantage of common processing routines, called sub-routines. &GOSUB changes the current processing location within a procedure. Control transfers to the statement beginning with the specified target label. On completion of the sub-routine an &RETSUB statement resumes processing at the statement following the &GOSUB statement.

The label, after variable substitution, must begin with a period and is from 1 to 12 characters long (not including the period).

The target label can precede or follow the statement containing the &GOSUB.

Operands:

.label

A label within the procedure.

.limlabel

A label in the procedure that delimits the extent of the search for .label. If .limlabel is found before the required label .label is located, the search terminates with a 'label not found' condition. Use .limlabel to improve the performance of procedures where a large number of unexpected labels normally discarded by the &CONTROL NOLABEL are received. When used with the search scope (see next operand), .limlabel can assist with table processing.

EQ | NE | GT | LT | GE | LE

An optional search scope used to qualify the selection of a target label that satisfies the search for .label up to the range set by .limlabel. If this operand is required, then .limlabel must be specified. In cases where .limlabel is not required, enter it with the same value as .label.

If this operand is omitted, .limlabel must exactly equal a procedure label to terminate the search.

EQ: Specifies that the first label generically equal to .label will satisfy the search.
NE: Specifies that the first label generically not equal to .label will satisfy the search.
GT: Specifies that the first label greater than .label will satisfy the search.
LT: Specifies that the first label less than .label will satisfy the search.
GE: Specifies that the first label greater than or equal to .label will satisfy the search.
LE: Specifies that the first label less than or equal to .label will satisfy the search.

Examples: &GOSUB

.MAINLINE
   &GOSUB .INITIALIZE
   &DOUNTIL &RETCODE NE 0
   &GOSUB .PROCESS
   &DOEND
   .

.INITIALIZE
   -* 
   -* Initialization logic
   -*
   &RETSUB

.PROCESS
   -* 
   -* Processing logic
   -*
   &IF &REQUEST = EXIT &THEN +
   &RETSUB 4
   &RETSUB 0
   &PANEL CMDENTRY
   &GOSUB .P$&COMMAND .PEND
   &RETSUB

.P$DISPLAY
   -* 
   -* Display logic
   -*  
   &RETSUB

.P$LIST
   -* 
   -* List logic
   -* 
   &RETSUB
.PEND

Notes:

Using the &CONTROL NODUPCHK option can improve the processing of &GOSUB statements. This option eliminates duplicate label checking and lets you use a faster search algorithm. It should only be used in procedures that have been thoroughly tested, as its use in a procedure containing duplicate labels can lead to unpredictable results.
The target label on an &GOSUB statement is a variable. Substitution is performed before attempting to transfer control to the target label.
Missing labels result in an error unless &CONTROL NOLABEL is used. This returns control to the statement after the &GOSUB statement, if the label does not exist.
Using label variables with &CONTROL NOLABEL is an easy and efficient way to isolate a target processing routine, instead of sifting data using multiple &IF statements.
The system maintains a loop control counter to stop inadvertent runaway loops within a procedure. This counter (&LOOPCTL) is set to 1000 for each nesting level entered. It is decremented by 1 for each &GOTO or &GOSUB executed. If the counter reaches 0 the procedure terminates with an error message. (You can reset the loop control counter using the &LOOPCTL statement if a larger value is required.)

More information: