ON, SET {NO}ON, and error handling

The ON command is used to catch error and abort conditions that occur while running a UCL script. The SET ON command is used to enable error handling and SET NOON ("no on") disables it. Here is the user documentation:

Performs an action when a command or program executed by a command procedure encounters an error condition or is interrupted.

Format

ON condition THEN {$} command

Parameters

condition
Specifies a condition. It must be one of the following keywords, which may be abbreviated to as few as one character:

WARNING Execute command if a warning occurs.

ERROR Execute command if an error occurs.

SEVERE_ERROR Execute command if a severe error occurs.

CONTROL_Y Control-Y was typed on SYS$INPUT.

The default condition is: ON ERROR THEN EXIT.

command
Specifies the UCL command to execute. The dollar sign ($) is optional. When an error level is specified, the command executes if an error occurs which is greater than or equal to the specified level of errors.

Description

After each command is executed, UCL checks the current error status and if an error occurs that is equal to or greater than the specified error level, the command specified with ON is executed. Unless the command is GOTO or EXIT, control returns to the next command in the command file after the one that resulted in an error.
For instance if ON WARNING is used, then the specified command will be executed when a warning, error, or severe error occurs. If ON SEVERE_ERROR is used, then the specified command is executed only if a severe error occurs. In that case, the script will continue if a warning or error occurs.
The global symbol $SEVERITY indicates the error level.
An active ON condition only applies to the command procedure in which it executes. Therefore, if ON is used in a script which then calls another script with @, it will not apply to the called file. Likewise, if ON is used in the called script file, that ON will not apply once the script file has exited to the calling script.
Separate from catching errors is the ability to catch control-Y.
It is highly recommended that ON CONTROL_Y not be used in command scripts since this disables the normal processing of control-Y. Any infinite loops cannot be interrupted in this case.

Example:


$ ON ERROR THEN GOTO Next
$ WRITE FILE "This is Test2"
$ EXIT
$Next:
$ ON ERROR THEN EXIT
.
.
.

The code first requests that any error will result in the code after the "Next" label be executed. If no error occurs on the WRITE, the script exits after the operation. If an error occurs, UCL begins execution at the "Next" label, which requests that any error will result in exiting the script, and then proceeds to execute any following commands.

SET {NO}ON

Turns the error handling on and off.

Format

SET {NO}ON

Parameters

None.

Description

Use SET NOON to enable normal error handling, which is to report the error and exit the script (if not interactive). Use SET ON to disable normal error handling and allow the use of customer error handling set via the ON command.

Example:


$ SET NOON
$ @Custom.com
$ SET ON

Note that we covered Control_Y response in article 64. In the code below we cover how the response can be defined via UCL commands.

                    if( Sym = 'on' ) then
                    begin
                        Process_On ;
                    end else
                    if(
                        ( Sym = 'set' )
                        and
                        (
                          ( Edit( Parser.Peek, 512, 0 ) = 'on' )
                          or
                          ( Edit( Parser.Peek, 512, 0 ) = 'noon' )
                        )
                      ) then
                    begin
                        Process_Set ;
                    end else

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

    Error : string ; // Command to execute on errors
    Error_Level : integer ; // Error level
    Control_Y : string ; // Command to execute on Control-Y
    
const EL_WARNING = 1 ;
const EL_ERROR = 2 ;
const EL_SEVERE_ERROR = 3 ;

When I started writing UCL code, I had some ideas for expansions to the DCL - specifically for separate error handlers for each level of error, unlike DCL which has a single error handler. However, this is what we call "spec creep" (specification creep). Spec creep can take a well-defined project onto a road of endless changes. So, I changed the code to work more like DCL. Thus, there may be some changes to some of the code that was shared early in these articles, in regard to error handling. But, at least, the project will have an end instead of going on forever. Enhancements to DCL can occur after we finish the basic UOS feature set, according to the VMS documentation/specification. Yes, there are some specific planned changes from VMS, but we must be disciplined and not go beyond that.

The above code has been added to support error handling.

procedure Handle_Exception ;

var I, L : integer ;

begin
    if( Current_Exception = '' ) then
    begin
        exit ; // No current exception
    end ;
    I := pos( '-', Current_Exception ) ;
    if( copy( Current_Exception, I + 1, 1 ) = 'F' ) then
    begin
        L := EL_SEVERE_ERROR ;
    end ;
    if( copy( Current_Exception, I + 1, 1 ) = 'E' ) then
    begin
        L := EL_ERROR ;
    end ;
    if( copy( Current_Exception, I + 1, 1 ) = 'W' ) then
    begin
        L := EL_WARNING ;
    end ;
    if( Errors_On ) then
    begin
        if( L >= Error_Level ) then
        begin
            Parser.Command := Error ;
            Current_Exception := '' ;
            exit ;
        end ;
    end else
    if( L >= EL_ERROR ) then
    begin
        Parser.Command := 'EXIT' ;
        Current_Exception := '' ;
    end ;
    Output_Line( RH_SysError, Current_Exception ) ;
    if( Current_Context <> '' ) then
    begin
        Output_Line( RH_SysError, '    \' + Current_Context + '\' ) ;
    end ;
    Current_Exception := '' ;
end ; // Handle_Exception

We've altered this routine to handle the new error handling. This is called each time we complete a command. We check for an error, then check against the defined error level. Finally, we place the specified command into the parser and exit. Thus, the next command to be executed will be the specified command.

function Process_On : boolean ;

var S : string ;

begin
    Result := False ;
    if( Interactive ) then
    begin
        Exception( UCL_ONLEVL, '' ) ;
        Result := True ;
        exit ;
    end ;
    S := uppercase( Get_Token ) ;
    if( Name_Match( S, 'WARNING', 1 ) ) then
    begin
        if( Check_Then ) then
        begin
            exit ;
        end ;
        Error := trim( Parser.Grab_Line ) ;
        Error_Level := EL_WARNING ;
    end else
    if( Name_Match( S, 'ERROR', 1 ) ) then
    begin
        if( Check_Then ) then
        begin
            exit ;
        end ;
        Error := trim( Parser.Grab_Line ) ;
        Error_Level := EL_ERROR ;
    end else
    if( Name_Match( S, 'SEVERE_ERROR', 1 ) ) then
    begin
        if( Check_Then ) then
        begin
            exit ;
        end ;
        Error := trim( Parser.Grab_Line ) ;
        Error_Level := EL_SEVERE_ERROR ;
    end else
    if( Name_Match( S, 'CONTROL_Y', 1 ) ) then
    begin
        if( Check_Then ) then
        begin
            exit ;
        end ;
        Control_Y := trim( Parser.Grab_Line ) ;
    end else
    begin
        Exception( UCL_ONERR, '' ) ;
        Result := True ;
    end ;
end ; // Process_On

This routine handles the processing of the ON command. First we validate that the user isn't interactive. Then we set the appropriate values, exiting with an error if the ON condition is unrecognized. We also exit with an error if the THEN keyword isn't present in the appropriate position.

function Check_Then : boolean ;

var S : string ;

begin
    Result := False ;
    S := Get_Token ;
    if( lowercase( S ) <> 'then' ) then
    begin
        Exception( UCL_NOTHEN, S ) ;
        Result := True ;
    end ;
    if( Parser.Peek = '$' ) then
    begin
        Get_Token ; // Eat dollar sign
    end ;
end ;

This new function checks for the presence of a required THEN keyword, exiting if not found. If found, it also removes the optional dollar sign from the parser.

procedure Process_Set ;

var S : string ;

begin
    S := Edit( Get_Token, 512, 0 ) ;
    if( S = 'on' ) then
    begin
        Errors_On := True ;
    end else
    if( S = 'noon' ) then
    begin
        Errors_On := False ;
    end ;
end ; // Process_Set

The procedure handles the SET {NO}ON command, setting the Errors_On flag appropriately.

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