@ and EXIT

As described in the previous article, the @ command is used to start execution of a UCL script. The EXIT command is used to leave the current scope and return to the last scope. Here is the documentation:

This executes a UCL script.

Format
@ filespec {/OUTPUT=outfilespec} {parameter{ parameter...}}

Parameters
filespec

File specification of the script to execute. Wildcards (* and ?) are not permitted in the file name. The default file type is ".com".

parameter

Specifies one or more optional parameters. The symbols (P1, P2, etc.) are assigned these values during the execution of the specified script. Each parameter is delimited by one or more spaces. A null parameter can be provided by two consecutive quotes (""). Each parameter can contain any characters desired, consistent with the following rules.

If the first parameter starts with a slash, the entire parameter must be surrounded by quotes.

If the parameter includes embedded spaces, the parameter must be enclosed in quotes.

All alphabetic characters are converted to uppercase. If you wish to preserve lowercase characters, the parameter must be enclosed in quotes.

You can enclose quotes within the parameter by using double quotes for each quote.

For instance, the following parameters:
Hello there
will be converted to two parameters as if the following were executed:
P1="HELLO" P2="THERE" The following:
"Hello there"
will be converted to a single parameter as if:
P1="Hello there" The following:
"Hello ""there"""
the value assigned to P1 in this case would be:
Hello "there"

Description

The @ command is used to execute a UCL script. It can be used within a UCL script to execute another script. Each use of @ creates a new scope with local symbols. The maximum number of levels allowed depends upon system quotas.

Qualifiers
/OUTPUT=filespec

Specifies the name of the file to which the script output is written. By default, the output goes to the current SYS$OUTPUT specification. The /OUTPUT qualifier must immediately follow the file specification or else it will be interpreted as a parameter.

Example

$ @MAKE MYAPP

EXIT

Terminates processing of a UCL script and returns control to the calling command level.

Format
EXIT {code}

Parameters
code

An optional numeric code that the reserved global symbol $STATUS is set to. The lower 3 bits of the value are assigned to the $SEVERITY symbol. If no code is specified, the current value of $STATUS is returned.

Description

The EXIT command is used to terminate the execution of a procedure.

Example

$ EXIT

procedure Process_Exit( Code : int64 = -1 ) ;

var E, Saved : int64 ;
    Err, I : integer ;
    Context, S : string ;

begin
    if( Parser <> nil ) then
    begin
        S := trim( Parser.Grab_Line ) ;
        if( S <> '' ) then
        begin
            Parser.Put_Token( S ) ;
            Code := Get_Numeric_Parameter( Err, Context ) ;
        end ;
    end ;
    if( Code <> -1 ) then
    begin
        Set_Status( Code ) ;
    end ;

This routine takes an optional parameter, which is the exit code. This routine can be called in two different circumstances: from within normal command processing and from the Run procedure. In the first case, we have a parser and the exit code may optionally follow, so we grab the line so see if there is anything there. If so, we push the value back and use Get_Next_Parameter to get the exit code, overwriting whatever code was passed to the routine. In any case, if the code is not -1 (indicating no code), we set the $STATUS symbol via the Set_Status routine (covered later in this article).

    if( Contexts.Count > 1 ) then // Nested
    begin
        // Delete the current scope table and make previous table the default...
        if( Contexts.Count = 2 ) then
        begin
            DELLNT( 'lnm$ucl$0', 'lnm$process_directory', 'lnm$process' ) ;
        end else
        begin
            DELLNT( 'lnm$ucl$' + inttostr( Contexts.Count - 1 ), 'lnm$process_directory', 
                'lnm$ucl$' + inttostr( Contexts.Count - 2 ) ) ;
        end ;

        // Delete the context...
        Contexts.Delete( Contexts.Count - 1 ) ;
        _This_UCL_Context.Free ;
        _This_UCL_Context := TUCL_Context( Contexts[ Contexts.Count - 1 ] ) ;

If there is more than one item in the Contexts list, we are currently nested. Thus, we delete the table for the current scope. The name of the table we delete is constructed according to our nesting level, and we change the default table to the previous scope's table. Then we remove the UCL context from the list and free it. Finally, we set the current context to the previous (more outer) context.

        // Restore sys$ states...
        Err := LIB_Set_Symbol( 'sys$command', This_UCL_Context.syscommand_name ) ;
        if( Err <> 0 ) then
        begin
            E := LIB_Get_Exception( 0 ) ; // Get handle
            Set_Exception( LIB_Get_Exception_Text( 0, E ) ) ;
        end ;
        Err := LIB_Set_Symbol( 'sys$output', This_UCL_Context.sysoutput_name ) ;
        if( Err <> 0 ) then
        begin
            E := LIB_Get_Exception( 0 ) ; // Get handle
            Set_Exception( LIB_Get_Exception_Text( 0, E ) ) ;
        end ;
        Err := LIB_Set_Symbol( 'sys$input', This_UCL_Context.sysinput_name ) ;
        if( Err <> 0 ) then
        begin
            E := LIB_Get_Exception( 0 ) ; // Get handle
            Set_Exception( LIB_Get_Exception_Text( 0, E ) ) ;
        end ;
        Err := LIB_Set_Symbol( 'sys$error', This_UCL_Context.syserror_name ) ;
        if( Err <> 0 ) then
        begin
            E := LIB_Get_Exception( 0 ) ; // Get handle
            Set_Exception( LIB_Get_Exception_Text( 0, E ) ) ;
        end ;

Now we restore the state of the various SYS$ symbols. If setting any of the symbols causes an error, we set the error. Notice we don't exit if there was a problem - we need to do our best to restore the scope.

        if( pos( '\', This_UCL_Context.sysinput_name ) > 0 ) then // file
        begin
            Saved := This_UCL_Context.sysinput_line ;
            for I := 1 to This_UCL_Context.sysinput_line do
            begin
                Get_Input( '' ) ; // Include Get_Input in next article
            end ;
            This_UCL_Context.sysinput_line := Saved ;
        end ;
        if( pos( '\', This_UCL_Context.syscommand_name ) > 0 ) then // file
        begin
            Saved := This_UCL_Context.syscommand_line ;
            for I := 1 to This_UCL_Context.syscommand_line do
            begin
                Get_Command( '' ) ;
            end ;
            This_UCL_Context.syscommand_line := Saved ;
        end ;
    end ; // if( Contexts.Count > 1 )

At this point, we have the previous scope mostly restored. But if the sys$input value is a file, we need to reposition the file to the line after the last line that we processed. We repeat the same process for sys$output.

    S := Get_Symbol_Value( 'lnm$job', '$STATUS' ) ;
    if( S = '' ) then
    begin
        Code := 0 ;
    end else
    begin
        Code := strtoint( S ) ;
    end ;
    Set_Exception( Code ) ;
    Handle_Exception ;
end ; // Process_Exit

Finally, we get the current value of $STATUS. If it is defined, non-blank, and non-zero, we set the exception code and handle any exceptions. This essentially passes any exceptions that happened in the called scope to be propogated to the current scope.

function Get_Input( const Prefix : string ) : string ;

var IOSB : TIOSB ;

begin
    SYS_QIOW( 0, RH_SysCommand, IO_SETMODE or IOM_CLI_CTRLCAST, integer( @IOSB ), integer( @CC_AST ), 
        0, 0, 0, 0, 0,  0, 0 ) ;
    SYS_QIOW( 0, RH_SysCommand, IO_SETMODE or IOM_CLI_CTRLYAST, integer( @IOSB ), integer( @CY_AST ), 
        0, 0, 0, 0, 0, 0, 0 ) ;
    Result := PasStarlet.LIB_Get_Input( Prefix ) ;
    inc( This_UCL_Context.sysinput_line ) ;
end ;

This mirrors the Get_Command procedure that we've covered in the past. We will discuss its use in the future. Essentially it is what is used when we want user data input rather than user command input.

function Set_Status( I : int64 ) : int64 ;

begin
    Result := LIB_Set_Symbol( '$STATUS', inttostr( I ), LNM_JOB ) ;
    if( Result = 0 ) then
    begin
        Result := LIB_Set_Symbol( '$SEVERITY', inttostr( I and 3 ), LNM_JOB ) ;
    end ;
end ;

This routine is used to set the $STATUS symbol. The low 3 bits of each UOS/VMS error code indicates the severity of the error, so we set the severity from the lowest three bits.

We've made one other change to support the EXIT command in the SSC's Set_Symbol method.

    // Handle special symbols...
    if( PID <> 0 ) then
    begin
        N := lowercase( N ) ;
        if( N = 'sys$command' ) then
        begin
            UE := FiP.Assign( PID, 'sys$command:', RH_SysCommand, 0, '', 0 ) ;
            if( UE <> nil ) then
            begin
                Set_Exception( UE ) ;
                exit ;
            end ;
        end ;
        if( N = 'sys$error' ) then
        begin
            UE := FiP.Assign( PID, 'sys$error:', RH_SysError, 0, '', 0 ) ;
            if( UE <> nil ) then
            begin
                Set_Exception( UE ) ;
                exit ;
            end ;
        end ;
        if( N = 'sys$input' ) then
        begin
            UE := FiP.Assign( PID, 'sys$input:', RH_SysInput, 0, '', 0 ) ;
            if( UE <> nil ) then
            begin
                Set_Exception( UE ) ;
                exit ;
            end ;
        end ;
        if( N = 'sys$output' ) then
        begin
            UE := FiP.Assign( PID, 'sys$output:', RH_SysOutput, 0, '', 0 ) ;
            if( UE <> nil ) then
            begin
                Set_Exception( UE ) ;
                exit ;
            end ;
        end ;
    end ; // if( PID <> 0 )

If called by a process (PID is non-zero), we handle special symbols. If any of these four special symbols is being set, we call the FiP's Assign method to associate the symbol value with the corresponding redirection handle. If the assignment results in an error, we exit - the symbol value will have changed, but the redirection handle will still refer to the previously assigned target.

In the next article, we will look at the CRELNT system service.