HANDLE CONDITION

Handle conditions.

HANDLE CONDITION

This command is threadsafe.

Description

Use the HANDLE CONDITION command 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.

Restriction: This command is supported only in COBOL, PL/I, and assembler language applications (but not AMODE(64) assembler language applications). It is not supported in all other supported high level languages.

If you omit the label parameter, 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 might result in the associated condition.

You cannot include more than 16 conditions in the same command. The conditions must be separated by at least one space. You must specify any 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. However, if the default action for such a condition terminates the task abnormally, and the condition ERROR has been specified, the action for ERROR is taken.

The label receives control in the same execution key as 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 one of the following situations occurs:

An IGNORE CONDITION command for the same condition is encountered. The HANDLE CONDITION command is overridden.
Another HANDLE CONDITION command for the same condition is encountered. 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.

The HANDLE CONDITION command is temporarily deactivated by the NOHANDLE or RESP option on a command.

Language considerations

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

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.

Options

condition(label): Specifies the name of the condition. label specifies the location in the program to be branched to if the condition occurs.

For more information about the conditions, see EIB fields.

Examples

The following example shows how to handle conditions such as DUPREC and LENGERR that can occur when you use a WRITE command to add a record to a data set. DUPREC is handled as a special case. Default action is taken for LENGERR (that is, the task is terminated abnormally). All other conditions are handled by the error routine ERRHANDL.

EXEC CICS HANDLE CONDITION
          ERROR(ERRHANDL)
          DUPREC(DUPRTN) LENGERR