HP OpenVMS Systems Documentation

Transfers control to a labeled subroutine in a command procedure without creating a new procedure level.

Format

GOSUB label

Parameter

label

Specifies a label of 1 to 255 alphanumeric characters that appears as the first item on a command line. A label may not contain embedded blanks. When the GOSUB command is executed, control passes to the command following the specified label.

The label can precede or follow the GOSUB statement in the current command procedure. When you use a label in a command procedure, it must be terminated with a colon (:). If you use duplicate labels, control is always given to the label most recently read by DCL.

Description

Use the GOSUB command in command procedures to transfer control to a subroutine specified by the label. If the command stream is not being read from a random-access device (that is, a disk device), the GOSUB command performs no operation.

The RETURN command terminates the GOSUB subroutine procedure, returning control to the command following the calling GOSUB statement. The RETURN command accepts an optional status value.

The GOSUB command does not cause the creation of a new procedure level. Therefore, it is referred to as a "local" subroutine call. Any labels and local symbols defined in the current command procedure level are available to a subroutine invoked with a GOSUB command. The GOSUB command can be nested up to a maximum of 16 levels per procedure level.

When the command interpreter encounters a label, it enters the label in a label table. This table is allocated from space available in the local symbol table. If the command interpreter encounters a label that already exists in the table, the new definition replaces the existing one. Therefore, if you use duplicate labels, control is always given to the label most recently read by DCL. The following rules apply:

• If duplicate labels precede and follow the GOSUB command, control is given to the label preceding the command.
• If duplicate labels all precede the GOSUB command, control is given to the most recent label, that is, the one nearest the GOSUB command.
• If duplicate labels all follow the GOSUB command, control is given to the one nearest the GOSUB command.

If a label does not exist in the current command procedure, the procedure cannot continue and is forced to exit.

Note that the amount of space available for labels is limited. If a command procedure uses many symbols and contains many labels, the command interpreter may run out of table space and issue an error message.

Example

$! 
$! GOSUB.COM 
$! 
$ SHOW TIME 
$ GOSUB TEST1 
$ WRITE SYS$OUTPUT "success completion" 
$ EXIT 
$! 
$! TEST1 GOSUB definition 
$! 
$ TEST1: 
$     WRITE SYS$OUTPUT "This is GOSUB level 1." 
$     GOSUB TEST2 
$     RETURN %X1 
$! 
$! TEST2 GOSUB definition 
$! 
$ TEST2: 
$     WRITE SYS$OUTPUT "This is GOSUB level 2." 
$     GOSUB TEST3 
$     RETURN 
$! 
$! TEST3 GOSUB definition 
$! 
$ TEST3: 
$     WRITE SYS$OUTPUT "This is GOSUB level 3." 
$     RETURN 
 
      

This sample command procedure shows how to use the GOSUB command to transfer control to labeled subroutines. The GOSUB command transfers control to the subroutine labeled TEST1. The procedure executes the commands in subroutine TEST1, branching to the subroutine labeled TEST2. The procedure then executes the commands in subroutine TEST2, branching to the subroutine labeled TEST3. Each subroutine is terminated by the RETURN command. After TEST3 is executed, the RETURN command returns control back to the command line following each calling GOSUB statement. At this point, the procedure has been successfully executed.