Condition handling

When a Rexx program is executed, normally the flow of execution is determined by the program's instructions. However, during the course of processing, various exceptional conditions can arise.

An exception is handled in one of three ways (earlier in the program):

1. establish a SIGNAL ON handler. This establishes a trap label that receives control when the condition occurs. The label is activated as though a signal instruction had transferred control to the label.

2. establish a CALL ON handler. This establishes a trap label that receives control when the condition occurs. The label is activated as though a call instruction had transferred control to the label as a subroutine.

3. Allow default actions to handle the condition.

The Rexx language defines the following condition categories.

ERROR

A command completed with an error condition.
For example: renaming a non-existent file

FAILURE

A command completed with a failure condition.
For example: a command could not be found

HALT

The user performed an external action to stop the processing of the Rexx program.
For example: a special key was pressed on the console

NOTREADY

A stream was in an inappropriate state for a requested operation.
For example: an attempt was made to read from a non-existent file

NOVALUE

A symbol was referenced which does not currently have an assigned value. This condition is only raised when SIGNAL ON NOVALUE or CALL ON NOVALUE traps have been activated.

SYNTAX

An error condition was encountered in the syntax, or operation, of an instruction.

Default condition handling

If a condition handler (CALL ON or SIGNAL ON) was not active when a HALT or SYNTAX error condition occurs, program is concluded. Appropriate error messages are displayed.

If a condition handler (CALL ON or SIGNAL ON) was not active when any other error conditions described above occur, the program continues to operate as though an error did not occur.

Condition trapping

When a trap label receives control as a consequence of an error condition, information describing the situation is available by using the condition built-in function. For ERROR and FAILURE conditions, the special RC variable contains the associated command completion code. When SYNTAX conditions occur, the special RC variable contains the associated syntax error number.

The special SIGL variable contains the source line number of the instruction associated with the error condition.

Note: in some implementations you can invoke a program editor when a SYNTAX error occurs. The SIGL value is passed to the editor. The editor can automatically position, and highlight, the source line associated with the error.

Note: there are various additional considerations regarding the handling of error conditions, that are described in TRL-2. For example, conditions can be delayed while a CALL ON handler is processing a condition. These additional considerations are beyond the scope of this tutorial.

The information presented in this tutorial should be satisfactory for most of the condition handling scenarios you will encounter during your Rexx programming endeavors.