14.5. Errors during Input and Output

The Rexx language offers considerable flexibility in handling errors during input or output. This is provided in the form of a NOTREADY condition that the CALL ON and SIGNAL ON instructions can trap. The STATE and DESCRIPTION methods can elicit further information.

When an error occurs during an input or output operation, the function or method called usually continues without interruption (the output method returns a nonzero count). Depending on the nature of the operation, a program has the option of raising the NOTREADY condition. The NOTREADY condition is similar to the ERROR and FAILURE conditions associated with commands in that it does not cause a terminating error if the condition is raised but is not trapped. After NOTREADY has been raised, the following possibilities exist:

If the NOTREADY condition is not trapped, processing continues without interruption. The NOTREADY condition remains in the OFF state.
If SIGNAL ON NOTREADY traps the NOTREADY condition, the NOTREADY condition is raised. Processing of the current clause stops immediately, and the SIGNAL takes place as usual for condition traps.
If CALL ON NOTREADY traps the NOTREADY condition, the NOTREADY condition is raised, but execution of the current clause is not halted. The NOTREADY condition is put into the delayed state, and processing continues until the end of the current clause. While processing continues, input methods that refer to the same stream can return the null string and output methods can return an appropriate count, depending on the form and timing of the error. At the end of the current clause, the CALL takes place as usual for condition traps.
If the NOTREADY condition is in the DELAY state (CALL ON NOTREADY traps the NOTREADY condition, which has already been raised), processing continues, and the NOTREADY condition remains in the DELAY state.

After the NOTREADY condition has been raised and is in DELAY state, the "O" option of the CONDITION function returns the stream object being processed when the stream error occurred.

The STATE method of the Stream class returns the stream object state as ERROR, NOTREADY, or UNKNOWN. You can obtain additional information by using the DESCRIPTION method of the Stream class.

Note

SAY .OUTPUT and PULL .INPUT never raise the NOTREADY condition. However, the STATE and DESCRIPTION methods can return NOTREADY.