Condition Information

When a condition is trapped and causes a SIGNAL or CALL, this becomes the current trapped condition, and certain condition information associated with it is recorded. You can inspect this information by using the CONDITION built-in function (see CONDITION).

The condition information includes:

The current condition information is replaced when control is passed to a label as the result of a condition trap (CALL ON or SIGNAL ON). Condition information is saved and restored across subroutine or function calls, including one because of a CALL ON trap and across method invocations. Therefore, a routine called by CALL ON can access the appropriate condition information. Any previous condition information is still available after the routine returns.

Descriptive Strings

The descriptive string varies, depending on the condition trapped:

ERROR

The string that was processed and resulted in the error condition.

FAILURE

The string that was processed and resulted in the failure condition.

HALT

Any string associated with the halt request. This can be the null string if no string was provided.

LOSTDIGITS

The number with excessive digits that caused the LOSTDIGITS condition.

NOMETHOD

The name of the method that could not be found.

NOSTRING

The readable string representation of the object causing the NOSTRING condition.

NOTREADY

The name of the stream being manipulated when the error occurred and the NOTREADY condition was raised. If the stream was a default stream with no defined name, then the null string might be returned.

NOVALUE

The derived name of the variable whose attempted reference caused the NOVALUE condition.

SYNTAX

Any string the language processor associated with the error. This can be the null string if you did not provide a specific string. Note that the special variables RC and SIGL provide information on the nature and position of the processing error. You can enable the SYNTAX condition trap only by using SIGNAL ON.

USER

Any string specified by the DESCRIPTION option of the RAISE instruction that raised the condition. If a description string was not specified, a null string is used.

Additional Object Information

The language processor can provide additional information, depending on the condition trapped:

NOMETHOD

The object that raised the NOMETHOD condition.

NOSTRING

The object that caused the NOSTRING condition.

NOTREADY

The stream object that raised the NOTREADY condition.

SYNTAX

An array containing the objects substituted into the secondary error message (if any) for the syntax error. If the message did not contain substitution values, a zero element array is used.

USER

Any object specified by an ADDITIONAL or ARRAY option of the RAISE instruction that raised the condition.

The Special Variable RC

When an ERROR or FAILURE condition is trapped, the Rexx special variable RC is set to the command return code before control is transferred to the target label (whether by CALL or by SIGNAL).

Similarly, when SIGNAL ON SYNTAX traps a SYNTAX condition, the special variable RC is set to the syntax error number before control is transferred to the target label.

The Special Variable SIGL

Following any transfer of control because of a CALL or SIGNAL, the program line number of the clause causing the transfer of control is stored in the special variable SIGL. If the transfer of control is because of a condition trap, the line number assigned to SIGL is that of the last clause processed (at the current subroutine level) before the CALL or SIGNAL took place. The setting of SIGL is especially useful after a SIGNAL ON SYNTAX trap when the number of the line in error can be used, for example, to control a text editor. Typically, code following the SYNTAX label can PARSE SOURCE to find the source of the data and then call an editor to edit the source file, positioned at the line in error. Note that in this case you might have to run the program again before any changes made in the editor can take effect.

Alternatively, SIGL can help determine the cause of an error (such as the occasional failure of a function call) as in the following example:

signal on syntax
a = a + 1      /* This is to create a syntax error */
say "SYNTAX error not raised"
exit

/* Standard handler for SIGNAL ON SYNTAX */
syntax:
say "Rexx error" rc "in line" sigl":" "ERRORTEXT"(rc)
say "SOURCELINE"(sigl)
trace ?r; nop

This code first displays the error code, line number, and error message. It then displays the line in error, and finally drops into debug mode to let you inspect the values of the variables used at the line in error.

Condition Objects

A condition object is a directory returned by the Object option of the CONDITION built-in function. This directory contains all information currently available on a trapped condition. The information varies with the trapped condition. The Nil object is returned for any entry not available to the condition. The following entries can be found in a condition object:

ADDITIONAL

The additional information object associated with the condition. This is the same object that the Additional option of the CONDITION built-in function returns. The ADDITIONAL information may be specified with the ADDITIONAL or ARRAY options of the RAISE instruction.

DESCRIPTION

The string describing the condition. The Description option of the CONDITION built-in function also returns this value.

INSTRUCTION

The keyword for the instruction executed when the condition was trapped, either CALL or SIGNAL. The Instruction option of the CONDITION built-in function also returns this value.

CONDITION

The name of the trapped condition. The Condition name option of the CONDITION built-in function also returns this value.

RESULT

Any result specified on the RETURN or EXIT options of a RAISE instruction.

RC

The major Rexx error number for a SYNTAX condition. This is the same error number assigned to the special variable RC.

CODE

The detailed identification of the error that caused a SYNTAX condition. This number is a nonnegative number in the form nn.nnn. The integer portion is the Rexx major error number (the same value as the RC entry). The fractional portion is a subcode that gives a precise indication of the error that occurred.

ERRORTEXT

The primary error message for a SYNTAX condition. This is the same message available from the ERRORTEXT built-in function.

MESSAGE

The secondary error message for a SYNTAX condition. The message also contains the content of the ADDITIONAL information.

PACKAGE

The Package object associated with the program where a syntax condition was raised.

POSITION

The line number in source code at which a SYNTAX condition was raised.

PROGRAM

The name of the program where a SYNTAX condition was raised.

TRACEBACK

A single-index list of formatted traceback lines.

PROPAGATED

The value 0 (false) if the condition was raised at the same level as the condition trap or the value 1 (true) if the condition was reraised with RAISE PROPAGATE.