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.

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.

If you use CALL, the trapname can be an internal label, a built-in function, or an external routine. When calling trapname, the current Condition Object is supplied as an argument.

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.

If the package contains an ::OPTIONS ERROR SYNTAX directive and ERROR is not trapped with CALL/SIGNAL ON/OFF ERROR/ANY, a SYNTAX condition is raised instead.

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.

If the package contains an ::OPTIONS FAILURE SYNTAX directive and FAILURE is not trapped with CALL/SIGNAL ON/OFF FAILURE/ANY, a SYNTAX condition is raised instead.

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 RXHLT exit or the RexxStart programming interface to halt the execution of a Rexx macro. (See the Open Object Rexx: Application Programming Interfaces 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.

If the package contains an ::OPTIONS LOSTDIGITS SYNTAX directive and LOSTDIGITS is not trapped with SIGNAL ON/OFF LOSTDIGITS/ANY, a SYNTAX condition is raised instead.

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.

If the package contains an ::OPTIONS NOSTRING SYNTAX directive and NOSTRING is not trapped with SIGNAL ON/OFF NOSTRING/ANY, a SYNTAX condition is raised instead.

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.

If the package contains an ::OPTIONS NOTREADY SYNTAX directive and NOTREADY is not trapped with CALL/SIGNAL ON/OFF NOTREADY/ANY, a SYNTAX condition is raised instead.

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 an EXPOSE instruction, a PROCEDURE instruction, or a DROP instruction
A method selection override specifier in a message term

Notes:

NOVALUE is not raised for any uninitialized variables in tails in compound variables.

If the package contains an ::OPTIONS NOVALUE SYNTAX directive and NOVALUE is not trapped with SIGNAL ON/OFF NOVALUE/ANY, a SYNTAX condition is raised instead.

Example 11.1. NOVALUE not 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.