HANDLE CONDITION

Handle conditions.

Read syntax diagramSkip visual syntax diagram
HANDLE CONDITION

                     .------------------------.   
                     V                        |   
>>-HANDLE CONDITION----condition--+---------+-+----------------><
                                  '-(label)-'     

This command is threadsafe.

 

Description

You use HANDLE CONDITION to specify the label to which control is to be passed if a condition occurs. You must include the name of the condition and, optionally, a label to which control is to be passed if the condition occurs.

If you omit “label”, any HANDLE CONDITION command for the condition is deactivated, and the default action is taken if the condition occurs. This is independent of the setting of the generalized ERROR condition.

You must ensure that the HANDLE CONDITION command is executed before the command that may give rise to the associated condition.

You cannot include more than sixteen conditions in the same command; the conditions should be separated by at least one space. You must specify additional conditions in further HANDLE CONDITION commands.

If a condition occurs that is not specified in a HANDLE CONDITION or IGNORE CONDITION command, the default action is taken. If, however, the default action for a condition not specified in a HANDLE CONDITION or IGNORE CONDITION command terminates the task abnormally, and the condition ERROR has been specified, the action for ERROR is taken.

The execution key that the label receives control in, is the execution key that the program was running in when the HANDLE CONDITION command was issued.

Scope

The HANDLE CONDITION command for a given condition applies only to the program in which it is specified. The HANDLE CONDITION command:
  • Remains active while the program is being executed, or until:
    • An IGNORE CONDITION command for the same condition is encountered, in which case the HANDLE CONDITION command is overridden
    • Another HANDLE CONDITION command for the same condition is encountered, in which case the new command overrides the previous one.
    • A LINK command is executed to call another CICS® program. The HANDLE CONDITION options are not inherited by the linked-to program.
  • Is temporarily deactivated by the NOHANDLE or RESP option on a command.

Language considerations

Start of changeIn an assembler language application program, when a branch to a label is caused by a condition, the registers in the application program are restored to their values in the program at the point where the command that caused the condition is issued.End of change

In a PL/I application program, a branch to a label in an inactive procedure or in an inactive begin block, caused by a condition, produces unpredictable results.

The C language does not support HANDLE CONDITION.

Options

condition(label)
specifies the name of the condition; “label” specifies the location within the program to be branched to if the condition occurs.

For more information about the conditions, see EXEC interface block.

Examples

The following example shows you how to handle conditions, such as DUPREC, LENGERR, and so on, that can occur when you use a WRITE command to add a record to a data set.

Suppose that you want DUPREC to be handled as a special case; that you want default action (that is, to terminate the task abnormally) to be taken for LENGERR; and that you want all other conditions to be handled by the error routine ERRHANDL. You would code:
EXEC CICS HANDLE CONDITION
          ERROR(ERRHANDL)
          DUPREC(DUPRTN) LENGERR