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 name of the current trapped condition
The name of the instruction processed as a result of the condition trap (CALL or SIGNAL)
The status of the trapped condition
A descriptive string (see Descriptive Strings) associated with that condition
Optional additional object information (see Additional Object Information)
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.
The descriptive string varies, depending on the condition trapped:
The string that was processed and resulted in the error condition.
The string that was processed and resulted in the failure condition.
Any string associated with the halt request. This can be the null string if no string was provided.
The number with excessive digits that caused the LOSTDIGITS condition.
The name of the method that could not be found.
The readable string representation of the object causing the NOSTRING condition.
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.
The derived name of the variable whose attempted reference caused the NOVALUE condition.
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.
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.
The language processor can provide additional information, depending on the condition trapped:
The object that raised the NOMETHOD condition.
The object that caused the NOSTRING condition.
The stream object that raised the NOTREADY condition.
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.
Any object specified by an ADDITIONAL or ARRAY option of the RAISE instruction that raised the condition.
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.
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.
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:
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.
The string describing the condition. The Description option of the CONDITION built-in function also returns this value.
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.
The name of the trapped condition. The Condition name option of the CONDITION built-in function also returns this value.
Any result specified on the RETURN or EXIT options of a RAISE instruction.
The major Rexx error number for a SYNTAX condition. This is the same error number assigned to the special variable RC.
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.
The primary error message for a SYNTAX condition. This is the same message available from the ERRORTEXT built-in function.
The secondary error message for a SYNTAX condition. The message also contains the content of the ADDITIONAL information.
The line number in source code at which a SYNTAX condition was raised.
The name of the program where a SYNTAX condition was raised.
A single-index list of formatted traceback lines.
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.