Chapter 11. Conditions and Condition Traps

A condition is an event or state that CALL ON or SIGNAL ON can trap. A condition trap can modify the flow of execution in a Rexx program. Condition traps are turned on or off using the ON or OFF subkeywords of the SIGNAL and CALL instructions (see Section 2.3, “CALL” and Section 2.28, “SIGNAL”).


>>-+-CALL---+--------------------------------------------------->
   +-SIGNAL-+

>--+-OFF--+-condition-----------+--------------------+--;------><
   |      +-USER--usercondition-+                    |
   +-ON--+-condition-----------+--+----------------+-+
         +-USER--usercondition-+  +-NAME--trapname-+

condition, usercondition, and trapname are single symbols that are taken as constants. Following one of these instructions, a condition trap is set to either ON (enabled) or OFF (disabled). The initial setting for all condition traps is OFF.

If a condition trap is enabled and the specified condition or usercondition occurs, control passes to the routine or label trapname if you have specified trapname. Otherwise, control passes to the routine or label usercondition or condition. CALL or SIGNAL is used, depending on whether the most recent trap for the condition was set using CALL ON or SIGNAL ON, respectively.

Note

If you use CALL, the trapname can be an internal label, a built-in function, or an external routine. If you use SIGNAL, the trapname can only be an internal label.

The conditions and their corresponding events that can be trapped are:

ANY

traps any condition that a more specific condition trap does not trap. For example, if NOVALUE is raised and there is no NOVALUE trap enabled, but there is a SIGNAL ON ANY trap, the ANY trap is called for the NOVALUE condition. For example, a CALL ON ANY trap is ignored if NOVALUE is raised because CALL ON NOVALUE is not allowed.

ERROR

raised if a command indicates an error condition upon return. It is also raised if any command indicates failure and none of the following is active:

CALL ON FAILURE
SIGNAL ON FAILURE
CALL ON ANY
SIGNAL ON ANY

The condition is raised at the end of the clause that called the command but is ignored if the ERROR condition trap is already in the delayed state. The delayed state is the state of a condition trap when the condition has been raised but the trap has not yet been reset to the enabled (ON) or disabled (OFF) state.

FAILURE

raised if a command indicates a failure condition upon return. The condition is raised at the end of the clause that called the command but is ignored if the FAILURE condition trap is already in the delayed state.

An attempt to enter a command to an unknown subcommand environment also raises a FAILURE condition.

HALT

raised if an external attempt is made to interrupt and end execution of the program. The condition is usually raised at the end of the clause that was processed when the external interruption occurred. When a Rexx program is running in a full-screen or command prompt session, the Ctrl+Break key combination raises the halt condition. However, if Ctrl+Break is pressed while a command or non-Rexx external function is processing, the command or function ends.

Notes:

Application programs that use the Rexx language processor might use the RXHALT exit or the RexxStart programming interface to halt the execution of a Rexx macro. (See the Open Object Rexx: Programming Guide for details about exits.)
Only SIGNAL ON HALT or CALL ON HALT can trap error 4, described in Appendix C, Error Numbers and Messages.

LOSTDIGITS

raised if a number used in an arithmetic operation has more digits than the current setting of NUMERIC DIGITS. Leading zeros are not counted in this comparison. You can specify the LOSTDIGITS condition only for SIGNAL ON.

NOMETHOD

raised if an object receives a message for which it has no method defined, and the object does not have an UNKNOWN method. You can specify the NOMETHOD condition only for SIGNAL ON.

NOSTRING

raised when the language processor requires a string value from an object and the object does not directly provide a string value. See Section 4.2.11, “Required String Values” for more information. You can specify the NOSTRING condition only for SIGNAL ON.

NOTREADY

raised if an error occurs during an input or output operation. See Section 14.5, “Errors during Input and Output”. This condition is ignored if the NOTREADY condition trap is already in the delayed state.

NOVALUE

raised if an uninitialized variable is used as:

A term in an expression
The name following the VAR subkeyword of a PARSE instruction
A variable reference in a parsing template, an EXPOSE instruction, a PROCEDURE instruction, or a DROP instruction
A method selection override specifier in a message term

Note

SIGNAL ON NOVALUE can trap any uninitialized variables except tails in compound variables.

Example 11.1. NOVALUE no raised for stems

/* The following does not raise NOVALUE. */
signal on novalue
a.=0
say a.z
say "NOVALUE is not raised."
exit

novalue:
say "NOVALUE is raised."

You can specify this condition only for SIGNAL ON.

SYNTAX

raised if any language-processing error is detected while the program is running. This includes all kinds of processing errors:

True syntax errors
"Run-time" errors (such as attempting an arithmetic operation on nonnumeric terms)
Syntax errors propagated from higher call or method invocation levels
Untrapped HALT conditions
Untrapped NOMETHOD conditions

You can specify this condition only for SIGNAL ON.

Notes:

SIGNAL ON SYNTAX cannot trap the errors 3 and 5.
SIGNAL ON SYNTAX can trap the errors 6 and 30 only if they occur during the execution of an INTERPRET instruction.

For information on these errors, refer to Appendix C, Error Numbers and Messages.

USER

raised if a condition specified on the USER option of CALL ON or SIGNAL ON occurs. USER conditions are raised by a RAISE instruction that specifies a USER option with the same usercondition name. The specified usercondition can be any symbol, including those specified as possible values for condition.

Any ON or OFF reference to a condition trap replaces the previous state (ON, OFF, or DELAY, and any trapname) of that condition trap. Thus, a CALL ON HALT replaces any current SIGNAL ON HALT (and a SIGNAL ON HALT replaces any current CALL ON HALT), a CALL ON or SIGNAL ON with a new trap name replaces any previous trap name, and any OFF reference disables the trap for CALL or SIGNAL.

11.1. Action Taken when a Condition Is Not Trapped

When a condition trap is currently disabled (OFF) and the specified condition occurs, the default action depends on the condition:

For HALT and NOMETHOD, a SYNTAX condition is raised with the appropriate Rexx error number.
For SYNTAX conditions, the clause in error is terminated, and a SYNTAX condition is propagated to each CALL instruction, INTERPRET instruction, message instruction, or clause with function or message invocations active at the time of the error, terminating each instruction if a SYNTAX trap is not active at the instruction level. If the SYNTAX condition is not trapped at any of the higher levels, processing stops, and a message (see Appendix C, Error Numbers and Messages) describing the nature of the event that occurred usually indicates the condition.
For all other conditions, the condition is ignored and its state remains OFF.