We've discussed UCL comments in a few previous articles (primarily 59, 62 and 66) as part of looking at other code, however due to a bug, they didn't function properly before now. Since we never formally discussed comments, here is the user documentation:

Indicates that the remainder of the line is a comment and should be ignored by UCL. You cannot use command continuation on a line that has a comment since the dash is interpreted as part of the comment itself.

Labels are a means of indicating a specific location in a command file that can be later used as a target for the GOTO command. Use of labels are only allowed in files, so if tried with a terminal, an error occurs. The way that DCL/UCL works is that whenever a label is encountered, the line of the file containing the label is saved along with the label name. If encountered again, the line number is updated. Thus, although not recommended, the same label can be used multiple times in a script. When referenced with GOTO, the last encountered label is the one that execution transfers to. Thus, our job of processing labels in UCL is quite simple.

                if( S = ':' ) then // A label
                begin
                    if( Interactive ) then
                    begin
                        Exception( UCL_NOLBLS, Sym + ':' ) ;
//NEW------>
                    end else
                    begin
                        Add_Label( Sym ) ;
//<------NEW
                    end ;
                    continue ;
                end ;

procedure Add_Label( Sym : string ) ;

var I : integer ;

begin
    Sym := lowercase( Sym ) ;
    I := This_UCL_Context.Labels.IndexOf( Sym ) ;
    if( I = -1 ) then // Not encountered before
    begin
        This_UCL_Context.Labels.AddObject( Sym, pointer( This_UCL_Context.syscommand_line ) ) ;
    end else
    begin
        This_UCL_Context.Labels.Objects[ I ] :=
            pointer( This_UCL_Context.syscommand_line ) ;
    end ;
end ;

The GOTO command is used to redirect execution of the script at a different location. It is only allowed in files, so use of it in interactive mode does nothing. My first inclination would be to show an error if used, but DCL just ignores it. In the case of an interrupted command file, we might allow it to operate (although DCL does not). But, that is something for a future article. Here is the documentation for the command.

                    if( Sym = 'goto' )
                    begin
                        Process_Goto ;
                        exit ; // Fetch next command
                    end else

procedure Process_Goto ;

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 ) ;
    Goto_Line( integer( This_UCL_Context.Labels.Objects[ I ] ) ) ;
end ; // Process_Goto

function Find_Target_Label : string ;

var Code : int64 ;
    E, I, Position : integer ;
    Lab, S, S1, Sym : string ;

begin
    Lab := lowercase( Get_Prompted_Parameter( '_Label: ' ) ) ;
    if( Lab = '' ) then
    begin
        Result := '' ;
        exit ; // Aborted
    end ;
    Position := This_UCL_Context.syscommand_line ; // Save our position
    I := This_UCL_Context.Labels.Indexof( Lab ) ;

    if( I = -1 ) then // Not already found
    begin
        LIB_Seek_File( RH_sysCommand, 0 ) ;
        while( true ) do
        begin
            S := Edit( Get_Command_Line( '' ), 4 or 128, 0 ) ; // Remove CRLF, trailing spaces, etc.
            E := LIB_Get_Exception( 0 ) ;
            if( E <> 0 ) then
            begin
                Goto_Line( Position + 1 ) ;
                LIB_Get_Exception_Info( 0, 0, int64( @Code ), 0 ) ;
                if( Code = UOSErr_Read_Past_End ) then // EOF
                begin
                    Exception( UCL_USGOTO, '' ) ;
                    exit ;
                end ;
                Set_Exception( LIB_Get_Exception_Text( 0, E ) ) ;
                Handle_Exception ;
                exit ;
            end ;
            if( copy( S, 1, 1 ) = '$' ) then
            begin
                S := trim( copy( S, 2, length( S ) ) ) ;
                if( Parser <> nil ) then
                begin
                    Parser.Free ;
                end ;
                Parser := TParser.Create ;
                Parser.Command := S ;
                Parser.Add_Special_Token( '==' ) ;
                Parser.Add_Special_Token( ':==' ) ;
                Parser.Add_Special_Token( '::' ) ;
                Parser.Add_Special_Token( ':=' ) ;
                Parser.Set_Quotes( '"' ) ;
                Sym := Get_Token ;
                S1 := Get_Token ;
                if( S1 = ':' ) then
                begin
                    if( lowercase( Sym ) = Lab ) then
                    begin
                        Add_Label( Sym ) ;
                        break ;
                    end ;
                end ;
            end ; // if( copy( S, 1, 1 ) = '$' )
        end ; // while( true )
    end ; // if( I = -1 )
    Result := Lab ;
end ;

procedure Goto_Line( L : integer ) ;

begin
    if( L < This_UCL_Context.syscommand_line ) then
    begin
        LIB_Seek_File( RH_sysCommand, 0 ) ;
        This_UCL_Context.syscommand_line := 0 ;
    end ;

    // Read up to the target line...
    while( This_UCL_Context.syscommand_line < L - 1 ) do
    begin
        Get_Line( '' ) ;
    end ;
end ;

function Get_Prompted_Parameter( Prompt : string ) : string ;

begin
    Result := Edit( Get_Token, 512, 0 ) ;
    if( Interactive ) then
    begin
        exit ;
    end ;
    Waiting_For_Label := True ;
    while( Result = '' ) do
    begin
        Result := Get_Line( Prompt ) ;
        if( not Waiting_For_Label ) then // Aborted
        begin
            exit ;
        end ;
    end ;
end ;

procedure Exception( Err : integer ; const Context : string = '' ) ;

begin
    Set_Exception( UCL_ERT( Err ), Context ) ;
end ;

function LIB_Seek_File( Handle, Position : int64 ) : int64 ;

var Status : int64 ;
    SysRequest : TFile_Request ;

begin
    Status := 0 ;
    fillchar( SysRequest, sizeof( SysRequest ), 0 ) ;
    SysRequest.Request.Subsystem :=  UOS_Subsystem_FIP ;
    SysRequest.Request.Request := UOS_FIP_Position ;
    SysRequest.Request.Length := sizeof( SysRequest.FRB ) ;
    SysRequest.Request.Status := integer( @Status ) ;
    SysRequest.FRB.Length := Position ;
    SysRequest.FRB.Handle := Handle ;
    Call_To_Ring0( integer( @SysRequest ) ) ;
end ;

function SYS_REWIND( _RAB, Err, Success : int64 ) : int64 ;

var RAB : TRAB ;

begin
    if( _RAB = 0 ) then
    begin
        Result := RMS_RAB ;
        exit ;
    end ;
    Result := LIB_Seek_File( PRAB( _RAB ).RAB_W_ISI, 0 ) ;
end ;

        UOS_FIP_Position:
            begin
                if( not Enter_Standard_FRB_Call( False ) ) then
                begin
                    exit ;
                end ;
                try
                    Position_File( SysReqFRB.FRB.Handle, SysReqFRB.FRB.Length, SysReqFRB.FRB.Flags ) ;
                finally
                    Exit_Standard_FRB_Call ;
                end ;
            end ;

function TUOS_FiP.Position_File( Handle : THandle ; Pos, Flags : int64 ) : TUnified_Exception ;

var Len : TStore_Size64 ;
    Resource : TResource ;
    Written : cardinal ;

begin
    Set_Last_Error( nil ) ;
    Handle := USC.Translate_Handle( Kernel.PID, Handle ) ;
    if( not USC.Valid_Handle( Kernel.PID, Handle ) ) then
    begin
        Result := Set_Last_Error( Create_Error( UOSErr_Invalid_Handle ) ) ;
        exit ;
    end ;
    Resource := TResource( Handle ) ;
    if( Resource._File.Is_Store ) then // Only affects stores and streams
    begin
        if( Pos > Resource._File.Get_File_Size ) then
        begin
            Pos := Resource._File.Get_File_Size ; // Cannot position beyond EOF
        end ;
        Resource.Position := Pos ;
    end ;
end ; // TUOS_FiP.Position_File