Product Site

7.4.18. CONDITION

Returns the condition information associated with the current trapped condition. (See Chapter 11, Conditions and Condition Traps for a description of condition traps.) You can request the following pieces of information:

  • The name of the current trapped condition

  • Any descriptive string associated with that condition

  • Any condition-specific information associated with the current trapped condition

  • The instruction processed as a result of the condition trap (CALL or SIGNAL)

  • The status of the trapped condition

In addition, you can request a condition object containing all of the preceding information.

To select the information to be returned, use the following options. (Only the capitalized letter is needed; all characters following it are ignored.)
Additional

returns any additional object information associated with the current trapped condition. See Section 11.3.2, “Additional Object Information” for a list of possible values. If no additional object information is available or no condition has been trapped, the language processor returns .nil.
Condition name

returns the name of the current trapped condition. For user conditions, the returned string is a concatenation of the word USER and the user condition name, separated by a whitespace character.
Description

returns any descriptive string associated with the current trapped condition. See Section 11.3.1, “Descriptive Strings” for the list of possible values. If no description is available or no condition has been trapped, it returns a null string.
Extra

returns the Rexx error subcode associated with a trapped SYNTAX condition. If no SYNTAX condition has been trapped, it returns a null string.
Instruction

returns either CALL or SIGNAL, the keyword for the instruction processed when the current condition was trapped. This is the default if you omit option. If no condition has been trapped, it returns a null string.
Object

returns an object that contains all the information about the current trapped condition. See Section 11.3.5, “Condition Object” for more information. If no condition has been trapped, it returns .nil.
Reset

resets any currently trapped condition and returns the null string. After a reset, all CONDITION options will return their default values, as if no condition has been trapped.
Status

returns the status of the current trapped condition. This can change during processing, and is one of the following:

  • ON - the condition is enabled

  • OFF - the condition is disabled

  • DELAY - any new occurrence of the condition is delayed or ignored

If no condition has been trapped, a null string is returned.

Example 7.25. Builtin function CONDITION
CONDITION()            -->    "CALL"        /* perhaps */
CONDITION("C")         -->    "FAILURE"
CONDITION("I")         -->    "CALL"
CONDITION("D")         -->    "FailureTest"
CONDITION("S")         -->    "OFF"        /* perhaps */

Note

The CONDITION function returns condition information that is saved and restored across subroutine calls (including those a CALL ON condition trap causes). Therefore, after a subroutine called with CALL ON trapname has returned, the current trapped condition reverts to the condition that was current before the CALL took place (which can be none). CONDITION returns the values it returned before the condition was trapped.