GOSUB and RETURN

In the previous article, we discussed the GOTO command. In this article, we will examine the GOSUB command. This is one of the three ways to execute a subroutine in UCL. The first is the @ command, and we will discuss the third in a future article. GOSUB differs from @ in a couple of ways. First, it calls code within the current script scope (file). Second, it doesn't create a nested scope. This means that all of the symbols available at the current scope remain available to the subroutine. Finally, GOSUB doesn't pass parameters (which means that the current scope's symbols can serve the same purpose). The RETURN command is used to return control to the line after the GOSUB. Here is the user documentation:

GOSUB

Transfers control to a labeled subroutine in the current script file without creating a new procedure nesting level.

Format

GOSUB label

Parameter

label
Specifies a label that must appear within the command file. The label may follow or preceed the GOSUB command. If there are duplicate labels, the last one encountered is used. If it hasn't been encountered yet, the entire script is searched from the beginning and the first instance found is used. If still not found, an error occurs.

Description

If the command procedure is not coming from a random-access device, GOSUB does nothing. Otherwise, control of the script is transferred to the command immediately following the specified label. The RETURN command will end the subroutine and return control to the command immediately following the GOSUB.
GOSUB does not create a new script scope and so all labels and local symbols defined in the current scope are available to the subroutine called with GOSUB.

Example:


$ A = 1
$Test1:
$ GOSUB Test2
$ IF A.LE.10 THEN GOTO Test1
$ EXIT
$Test2:
$ WRITE SYS$OUTPUT "This is Test2"
$ GOSUB Test3
$ A = A + 1
$ RETURN
$Test3:
$ WRITE SYS$OUTPUT "This is Test3"
$ RETURN

This sample script shows how to use GOSUB and RETURN. A is set to 1 and the lines between Test1 and EXIT will loop 10 times. Each time through the loop, control is transferred to the line after Test2, which writes "This is Test2" and then uses GOSUB to transfer control to the line after Test3, which write "This is Test3". When RETURN is executed, control is returned to the line after the GOSUB Test3, which adds 1 to A and then executes RETURN, which returns to the line after GOSUB Test2. The output from this will be:

This is Test2
This is Test3
This is Test2
This is Test3
This is Test2
This is Test3
This is Test2
This is Test3
This is Test2
This is Test3
This is Test2
This is Test3
This is Test2
This is Test3
This is Test2
This is Test3
This is Test2
This is Test3
This is Test2
This is Test3
This is Test2
This is Test3

RETURN

Terminates a subroutine and returns control to the command following the calling GOSUB command.

Format

RETURN {code}

Parameter

code
An optional code that can be used to set the global $STATUS and $SEVERITY symbols. If not provided, $STATUS and $SEVERITY are unchanged by the RETURN command.

Description

RETURN terminates a subroutine called via the GOSUB command and returns control to the line immediately following the GOSUB that initiated the subroutine. If RETURN is encountered without a previous GOSUB command execution, an error occurs. RETURN is ignored if encountered in a command stream that is not on a random access device.

Example:


$ GOSUB Test
$ EXIT
$Test:
$ WRITE SYS$OUTPUT "This is Test"
$ RETURN

In order to implement GOSUB/RETURN, we need to keep track of a call stack. Each GOSUB will add the return location to the stack and each RETURN will remove the last item from the stack. This will be stored, of course, in the UCL context. Note that this is a completely different mechanism from the @ processing, which creates a new scope. A command procedure invoked with @ can be called from within a subroutine and can, itself, contain subroutines. However, a RETURN from a new command scope cannot return from a subroutine called by a GOSUB in the previous scope since each scope has its own separate call stack. Thus, GOSUB and RETURN must be matched (in terms of execution) within a given script file.

                            Stack : TInteger_List ;

This line is added to the TUCL_Context class. This is be our gosub/return stack.

    Stack := TInteger_List.Create ;

This line is added to the TUCL_Context constructor to create the empty stack.

    Stack.Free ;
    Stack := nil ;

And these lines are added to the TUCL_Context destructor to clean up the stack when we exit a scope.

                    if( Sym = 'gosub' ) then
                    begin
                        Process_Gosub ;
                    end else
                    if( Sym = 'return' ) then
                    begin
                        Process_Return ;
                    end else

This code is added to the Process routine to handle the two new commands.

procedure Process_Gosub ;

var I, Position : integer ;
    S : string ;

begin
    Position := This_UCL_Context.syscommand_line ; // Save our position
    S := Find_Target_Label ;
    if( S = '' ) then
    begin
        exit ; // Aborted
    end ;

    I := This_UCL_Context.Labels.Indexof( S ) ;
    This_UCL_Context.Stack.Add( Position + 1 ) ;
    Goto_Line( integer( This_UCL_Context.Labels.Objects[ I ] ) ) ;
end ;

The code for processing GOSUB is exactly the same as the code for processing GOTO, with the one addition of adding the position + 1 to the Stack. The +1 is so that the RETURN will return to the line following the line with the GOSUB. Otherwise, RETURN would return to the line with the GOSUB, which would call the routine again, most likely causing an infinite loop.

procedure Process_Return ;

var Err, Position : integer ;
    Context, S : string ;
    Have_Code : boolean ;

begin
    if( Interactive ) then
    begin
        Parser.Grab_Line ;
        exit ; // Do nothing if interactive
    end ;
    if( This_UCL_Context.Stack.Count = 0 ) then // Nothing to return to
    begin
        Parser.Grab_Line ;
        Exception( UCL_BADRETURN, '' ) ;
        exit ;
    end ;
    Have_Code := Parser.Peek <> '' ;
    if( Have_Code ) then
    begin
        S := Get_Expression( err, context ) ;
        if( Err <> 0 ) then
        begin
            Exception( Err, Context ) ;
            exit ;
        end ;
    end ;

This new routine handles the RETURN command. If we are in interactive mode, we simply exit because RETURN is ignored in this case. We also throw away any remainder of the line in case there was the optional code following the RETURN.
If we're not interactive, we check that there is someting on the stack. If not, that indicates that we encountered a RETURN without having been called via GOSUB. So we again throw away the rest of the line and then exit with an error.
Otherwise, we check to see if there is anything following the RETURN command and, if so, we get the expression. If there is an expression error, we exit with that error.

    // Pop the return location from the stack and go there...
    Position := This_UCL_Context.Stack[ This_UCL_Context.Stack.Count - 1 ] ;
    This_UCL_Context.Stack.Count := This_UCL_Context.Stack.Count - 1 ;
    Goto_Line( Position ) ;
    if( Have_Code ) then
    begin
        Set_Status( strtoint( UCL_Strtoint( S ) ) ) ;
    end ;
end ;

Now we are ready to pop the return line number off of the stack which is what the first two lines accomplish. Then we position to that target line. Finally, if a status code was specified, we set the global status to that.

In the next article, we will look at the next UCL command.