Chapter 11. Conditions and Condition Traps

Table of Contents
Action Taken when a Condition Is Not Trapped
Action Taken when a Condition Is Trapped
Condition Information

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 CALL and 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:

  1. 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.)

  2. 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 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 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.

/* 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:

  1. SIGNAL ON SYNTAX cannot trap the errors 3 and 5.

  2. 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 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.

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: