Using the HANDLE CONDITION command

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 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 16 conditions in the same command. You must specify any additional conditions in further HANDLE CONDITION commands. You can also use the ERROR condition within the same list to specify that all other conditions are to cause control to be passed to the same label.

The HANDLE CONDITION command for a given condition applies only to the program in which it is specified. The HANDLE CONDITION command:

When control passes to another program, by a LINK or XCTL command, the HANDLE CONDITION commands that were active in the calling program are deactivated. When control returns to a program from a program at a lower logical level, the HANDLE CONDITION commands that were active in the higher-level program before control was transferred from it are reactivated, and those in the lower-level program are deactivated. (Refer to Application program logical levels for information about logical levels.)

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 standard system 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
  END-EXEC.

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.

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

RESP and NOHANDLE options

You can temporarily deactivate the effect of any HANDLE CONDITION command by using the RESP or NOHANDLE option on a command. The way to use these options is described in Handling exception conditions by in-line code. If you do this, you lose the ability to use any system default action for that command. In other words, you have to do your own "catch-all" error processing.

How CICS keeps track of what to do

CICS® has a table of the conditions referred to by HANDLE CONDITION and IGNORE CONDITION commands in your application. Each execution of one of these commands either updates an existing entry in this table, or causes CICS to make a new entry if this is the first time the condition has been quoted in such a command. Each entry tells CICS what to do by indicating one of the three exception-handling states your application can be in, namely:

  1. Let the program continue, with control coming straight back from CICS to the next instruction following the command that has failed in your program. You can then find out what happened by testing, for example, the RESP value that CICS returns after executing a command. The result of this test enables you decide what to do next. For details, see Handling exception conditions by in-line code.

    This is the recommended method, which is the approach taken in the "File A" sample programs referred to in the Sample Applications Guide and in the COBOL sample application in the Designing and Programming CICS Applications. It is also the recommended approach for any new CICS applications. It lends itself to structured code and removes the need for implied GOTOs that CICS required in the past.

  2. Pass control to a specified label if a named condition arises. You do this by using a HANDLE CONDITION command or HANDLE CONDITION ERROR command to name both the condition and the label of a routine in your code to deal with it. For details, see Using the HANDLE CONDITION command and Using the HANDLE CONDITION ERROR command.
  3. Taking the CICS system default action, where for most conditions, this is to terminate the task abnormally and means that you do nothing by way of testing or handling conditions.

For the conditions ENQBUSY, NOJBUFSP, NOSTG, QBUSY, SESSBUSY, and SYSBUSY, the normal default is to force the task to wait until the required resource (for example, storage) becomes available, and then resume processing the command. You can change this behavior to ignoring the condition by using the NOSUSPEND option. For the condition NOSPACE, the normal default is to wait if processing a WRITEQ TS command, but to abend the task if processing a WRITEQ TD, WRITE, or REWRITE command. Coding the WRITEQ TS command with the NOSUSPEND option makes it ignore any NOSPACE condition that arises. For more information see the CICS Application Programming Reference manual.

CICS keeps a table of these conditions for each link level. Essentially, therefore, each program level has its own HANDLE state table governing its own condition handling.

This behavior is modified by HANDLE CONDITION ERROR and IGNORE CONDITION.

[[ Contents Previous Page | Next Page Index ]]