The @ command is used to start execution of another UCL script (command file). There are other means of executing UCL scripts, but this command is the typical means of executing a script from inside UCL - whether interactively or from another script file.

So, let's talk about what this means. DCL/UCL creates a new script context when @ is used. That context has its own local symbols, open files, and command stream from the script file (due to having a different SYS$COMMAND assignment). Now there are several mechanisms that we could use to implement this behavior. Because DCL uses its own internal symbol table, a single instance of DCL can handle nested levels of command files (up to 16). We can take the same approach, but since UCL uses system symbol tables, to keep the scopes (nested levels) separate, we'd have to either save the symbol table contents when starting the new scope and restore it after, or we'd have to create another separate symbol table and switch between them as appropriate.

Beyond that, we have to keep the open files somehow separate between levels since things like SYS$COMMAND would be associated with different files at each level. We could keep track of this and reopen the appropriate file and read up to the saved location each time we exit a scope - but therein lies another problem. If the previous scope's command file is deleted prior to exiting a scope, there is nothing to reopen and reposition to. If we can keep the file open, then even if it was marked for deletion, we'd still have access to it.

One possible approach would be to create a subprocess for each level. That would easily take care of symbols since a new symbol table is created for each process, and the files associated with SYS$INPUT would be independent with each subprocess (level). Unfortunately, as simple as this solution is, there are problems with the approach. The main issue is that any changes made in the subprocess, such as to enabled privileges for example, would only affect the subprocess and not the one that invoked the script. This is probably not the expected (non)behavior of running a script. Also, this would create a lot of additional processes, which would impact system resources. Finally, while we don't expect UCL scripts to execute as fast as compiled programs, creating a subprocess is a somewhat costly operation.

So, which approach is the best one for this situation? Doubtless there are other approaches we could take. Just as doubtless, there is no "right" choice between the options. This is typical of most design decisions and we must choose the one that has the most benefit and/or the least trouble for our problem domain. While I like the conceptual simplicity of the subprocess approach, I think that the best overall approach is to handle the nesting within a single UCL instance. This is the approach used by DCL for new levels.

Given that choice, what are the considerations? I'm not aware of how DCL handles keeping context for each nested scope, but this is how we'll do it. First, we have to keep track of which files are associated with SYS$INPUT, SYS$ERROR, SYS$COMMAND, and SYS$OUTPUT, where we are within the input and command files, and various other contextual issues which we will be addressing in future articles. Thus, we will have a UCL context class to maintain this information for us. Yes, this may cause a problem if the input file is deleted while in a sub-scope, but it seems a reasonable expectation that this not happen - and the user will get an error if it does. Second, we have to create a new symbol table for the new scope's symbols, and then delete it when we exit the scope.

type TUCL_Context = class
                        public // Instance data...
                            sysoutput_name : string ;
                            sysinput_name : string ;
                            syserror_name : string ;
                            syscommand_name : string ;
                            sysinput_line : integer ;
                            syscommand_line : integer ;
                    end ;

var _Contexts : TList = nil ;
    _This_UCL_Context : TUCL_Context = nil ;

function Contexts : TList ;

begin
    if( _Contexts = nil ) then
    begin
        _Contexts := TList.Create ;
        _This_UCL_Context := TUCL_Context.Create ;
        _Contexts.Add( _This_UCL_Context ) ;
    end ;
    Result := _Contexts ;
end ;


function This_UCL_Context : TUCL_Context ;

begin
    if( _This_UCL_Context = nil ) then
    begin
        Contexts ;
    end ;
    Result := _This_UCL_Context ;
end ;

To support keeping track of what line we are at, we add the following line to the Get_Command function:

    while( True ) do
    begin
        S := Edit( Get_Command( '' ), 4 or 128, 0 ) ; // Remove CRLF, trailing spaces, etc.
//NEW--->
        E := LIB_Get_Exception( 0 ) ;
        if( E <> 0 ) then
        begin
            LIB_Get_Exception_Info( 0, 0, int64( @Code ), 0 ) ;
            if( ( Code = UOSErr_Read_Past_End ) and ( Contexts.Count > 1 ) ) then
            begin
                Process_Exit ;
                continue ;
            end ;
            Set_Exception( LIB_Get_Exception_Text( 0, E ) ) ;
            Handle_Exception ;
            continue ;
        end ;
//<-----NEW
        while(
               ( copy( S, length( S ) - 1, 2 ) = ' -' )
               or
               ( copy( S, length( S ) - 1, 2 ) = HT + '-' )
             ) do // Line continuation
        begin
            if( not End_Within_Quotes( S ) ) then
            begin
                setlength( S, length( S ) - 2 ) ;
                S1 := Edit( Get_Command( '_' ), 4 or 128, 0 ) ;
//NEW--->
                E := LIB_Get_Exception( 0 ) ;
                if( E <> 0 ) then
                begin
                    LIB_Get_Exception_Info( 0, 0, int64( @Code ), 0 ) ;
                    if(
                        ( Code <> UOSErr_Read_Past_End )
                        or
                        ( Contexts.Count <= 1 )
                      ) then
                    begin // Not an EOF condition
                        Set_Exception( LIB_Get_Exception_Text( 0, E ) ) ;
                        Handle_Exception ;
                        S := '' ;
                    end ;
                    break ;
                end ;
//<-----NEW
                if( CC_Interrupt or CY_Interrupt ) then
                begin
                    S := '' ;
                    S1 := '' ;
                end ;
                S := S + S1 ;
            end ;
        end ;
        if( Check_Interrupt ) then
        begin
            continue ; // Skip to next command
        end ;
        S := trim( S ) ;
//NEW--->
        if( copy( S, 1, 1 ) = '$' ) then
        begin
            S := copy( S, 2, length( S ) ) ;
        end ;
//<-----NEW
        S := Parse( S ) ;
        if( Check_Interrupt ) then
        begin
            continue ; // Skip to next command
        end ;
        if( Edit( S, 8 or 128, 0 ) <> '' ) then
        begin
            Process( S ) ;
        end ;
    end ; // while( True )

Note that there are three sections of new code above. The second one differs from the first in that it is for handling the end of the command file during a line continuation situation. In that case, we want to terminate the continuation and execute the amount of the command we've read in so far. When that finishes, we will come back to this procedure to get the next command. Since that will still result in an end of file exception, we will enter the first section of new code which will then go to the Process_Exit code.

The final section of new code is simply checking to see if the command starts with "$". If it does, the dollar sign prefix is removed. Command files must always prefix UCL commands with the dollar sign (it is optional for interactive mode) and this code handles it.

            if( Sym = '@' ) then
            begin
                Sym := Parser.Grab_Line ;
                if( Sym = '' ) then
                begin
                    Output_Line( RH_SysError, UCL_ERT( UCL_NULFIL ) ) ;
                    exit ;
                end ;
                if( Process_At( Sym ) ) then
                begin
                    exit ;
                end ;
            end else

function Process_At( S : string ) : boolean ; // @

var Output, Sym, X : string ;
    E, Err, I : int64 ;
    Loop : integer ;
    Previous : TUCL_Context ;
    Resname : string ;
    SL : TStringList ;
    Node, Access, Secondary_Node, Device, Path, Name, Extension, Version : string ;

begin
    // Setup...
    Result := False ;
    Sym := Parse_Parameter( ' ', S ) ;
    Parse_Filename( sym, Node, Access, Secondary_Node, Device, Path, Name, Extension, Version ) ;
    if( Extension = '' ) then
    begin
        Extension := '.com' ;
    end ;
    Sym := Node + Access + Device + Path + Name + Extension + Version ;

    // Process output switch...
    Output := '' ;
    if( Parse_Switch( 'OUTPUT', '', S, Output ) = 1 ) then
    begin
        if( Output = '' ) then
        begin
            Result := True ;
            Output_Line( RH_SysError, UCL_ERT( UCL_NULFIL ) ) ;
            exit ;
        end ;
    end ;
    if( Switch_Present( S ) > 0 ) then
    begin
        Result := True ;
        Output_Line( RH_SysError, UCL_ERT( UCL_IVQUAL ) ) ;
        exit ;
    end ;
    if( pos( '*', Sym ) + pos( '?', Sym ) > 0 ) then
    begin
        Result := True ;
        Output_Line( RH_SysError, UCL_ERT( UCL_WLD ) ) ;
        exit ;
    end ;
    if( not Directory_Exists( Sym ) ) then // Referenced file not found
    begin
        Result := True ;
        Output_Line( RH_SysError, UCL_ERT( UCL_FNF ) ) ;
        exit ;
    end ;

    try
        // Save special files...
        This_UCL_Context.sysoutput_name := LIB_Get_Symbol( 'sys$output' ) ;
        This_UCL_Context.sysinput_name := LIB_Get_Symbol( 'sys$input' ) ;
        This_UCL_Context.syscommand_name := LIB_Get_Symbol( 'sys$command' ) ;
        This_UCL_Context.syserror_name := LIB_Get_Symbol( 'sys$error' ) ;

        // Create new symbol table...
        I := CRELNT( LNM_M_MAKE_DEFAULT, Resname, 0,
            PROTECTION_OWNER_READ or PROTECTION_OWNER_WRITE or PROTECTION_OWNER_CONTROL,
            'lnm$ucl$' + inttostr( Contexts.Count - 1 ), 'lnm$process_directory', 3 ) ;
        if( ( I and Error_Mask ) > Error_Warning ) then
        begin
            E := LIB_Get_Exception( 0 ) ; // Get handle
            Set_Exception( LIB_Get_Exception_Text( 0, E ) ) ;
            Result := True ;
            exit ;
        end ;

        // Process parameters...
        SL := TStringList.Create ;
        while( S <> '' ) do
        begin
            X := Parse_Parameter( ' ', S ) ;
            if( X <> '' ) then
            begin
                if( copy( X, 1, 1 ) = '"' ) then
                begin
                    // Trim leading/trailing quotes...
                    X := copy( X, 2, length( X ) ) ;
                    if( copy( X, length( X ), 1 ) = '"' ) then
                    begin
                        setlength( X, length( X ) - 1 ) ;
                    end ;
                end ; // if( copy( X, 1, 1 ) = '"' )

                // Handle double-quotes
                I := 1 ;
                while( I < length( X ) ) do
                begin
                    if( copy( X, I, 2 ) = '""' ) then
                    begin
                        delete( X, I + 1, 1 ) ;
                    end ;
                    inc( I ) ;
                end ;
                X := Edit( X, 32 or 256 ) ; // Uppercase except within quotes
                SL.Add( X ) ;
            end ; // if( X <> '' )
        end ;
        for Loop := 0 to SL.Count - 1 do
        begin
            if( LIB_Set_Symbol( 'P' + inttostr( Loop + 1 ), SL[ Loop ], LNM_PROCESS ) <> 0 ) then
            begin
                // Delete the new table and make previous table the default...
                if( Contexts.Count = 1 ) then
                begin
                    DELLNT( 'lnm$ucl$' + inttostr( Contexts.Count - 1 ), '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 ;

                E := LIB_Get_Exception( 0 ) ; // Get handle
                Set_Exception( LIB_Get_Exception_Text( 0, E ) ) ;
                Result := True ;
                exit ;
            end ;
        end ;

For compatibility with DCL, each parameter is processed this way: if the entire parameter is surrounded by a double quote, we trim the leading and trailing (if present) quotes. We then iterate through the parameter, converting double quotes to single quotes. Finally, we convert everything not within quotes to uppercase. Note that DCL allows a maximum of 8 parameters. UCL essentially has no limit to the number of parameters allowed.

Now, there are some cases where the user (or a program or command file) could possibly shoot himself in the foot. Of greatest concern would be if the user manually deleted the symbol table being used by the current scope. That would likely result in the scope's symbols reverting to the outermost scope - or simply deleting all the symbols in the current scope (this would happen if the user tried to delete the lnm$process table, which cannot be deleted until the process itself is deleted). Likewise it is possible that the sys$command symbol could be changed in a way that pointed to the wrong place. And we talked about the situation when the command file being used by one scope is deleted by another scope. But, these are almost all scenarios where there is a bug in the script that is running in a given scope. Scripts are programs and bugs can always cause odd behavior with any program. Worst case scenario will be that the user is returned to the outermost scope with an error. Well, okay, there are worse cases for errant or malicious scripts, but that is whole 'nother discussion.

        // Create new context...
        Previous := This_UCL_Context ;
        _This_UCL_Context := TUCL_Context.Create ;
        Contexts.Add( This_UCL_Context ) ;
        Err := LIB_Set_Symbol( 'sys$command', Sym, LNM_PROCESS ) ;
        if( Err <> 0 ) then
        begin
            Process_Exit ;
            E := LIB_Get_Exception( 0 ) ; // Get handle
            Set_Exception( LIB_Get_Exception_Text( 0, E ) ) ;
            Result := True ;
            exit ;
        end ;

        if( This_UCL_Context.sysinput_name = '' ) then
        begin
            This_UCL_Context.sysinput_name := Previous.sysinput_name ;
        end ;
        if( This_UCL_Context.syserror_name = '' ) then
        begin
            This_UCL_Context.syserror_name := Previous.syserror_name ;
        end ;

        // Save current line on input/command
        if( This_UCL_Context.sysinput_name = Previous.sysinput_name ) then // Same input
        begin
            This_UCL_Context.sysinput_line := Previous.sysinput_line ;
        end ;
        This_UCL_Context.syscommand_name := Sym ;

        // Handle output
        if( Output <> '' ) then
        begin
            Err := LIB_Set_Symbol( 'sys$output', Output, LNM_PROCESS ) ;
            if( Err <> 0 ) then
            begin
                Process_Exit ;
                E := LIB_Get_Exception( 0 ) ; // Get handle
                Set_Exception( LIB_Get_Exception_Text( 0, E ) ) ;
                Result := True ;
                Process_Exit ;
                exit ;
            end ;
            This_UCL_Context.sysoutput_name := Output ;
        end ;
        if( This_UCL_Context.sysoutput_name = '' ) then
        begin
            This_UCL_Context.sysoutput_name := Previous.sysoutput_name ;
        end ;
    finally
        SL.Free ;
    end ;
    Set_Status( 0 ) ; // Clear $STATUS
end ; // Process_At

One more change needs to be made in the executive. When the QIO service is called to read a command line, if the command input was being pulled from a file rather than a terminal, it read 256 bytes. But, if a line is less than 256 bytes (and most of them probably are), the service will read in multiple lines when it should only read in one.

    if( Resource._File.Is_Store ) then
    begin
//NEW ----->
        I := pos( CR, B ) ;
        I1 := pos( LF, B ) ;
        if( ( I1 < I ) and ( I1 > 0 ) ) then
        begin
            I := I1 ;
        end ;
        if( I > 0 ) then
        begin
            if(
                ( ( copy( B, I, 1 ) = CR ) and ( copy( B, I + 1, 1 ) = LF ) )
                or
                ( ( copy( B, I, 1 ) = LF ) and ( copy( B, I + 1, 1 ) = CR ) )
              ) then
            begin
                inc( I ) ; // Include second delimiter (CRLF or LFCR)
            end ;
            setlength( B, I ) ; // Trim anything after the line delimiter
        end ;
//NEW <-----
        Resource.Position := Resource.Position + Length( B ) ;
    end ;

In the next article, we will look at the user documentation for both the @ and exit commands, and then look at the code for handling EXIT.