Handling exception conditions by in-line code

This section describes the method of handling exception conditions which is recommended for new applications and is the only available choice if your programs are in C or C++ language. If your program is not written in C or C++, it involves either using the NOHANDLE option or specifying the RESP option on EXEC CICS® commands, which prevents CICS performing its default exception handling. Additionally, the RESP option makes the value of the exception condition directly available to your program, for it to take remedial action.

If your program is written in C or C++, in-line code is the only means you have of handling exception conditions.

If you use the NOHANDLE or RESP option, you should ensure that your program can cope with whatever condition may arise in the course of executing the commands. The RESP value is available to enable your program to decide what to do and more information which it may need to use is carried in the EXEC interface block (EIB). In particular, the RESP2 value is contained in one of the fields of the EIB. See the CICS Application Programming Reference manual for more information on the EIB. Alternatively, if your program specifies RESP2 in the command, the RESP2 value is returned by CICS directly.

The DFHRESP built-in translator function makes it very easy to test the RESP value. It allows, you to examine RESP values symbolically. This is easier than examining binary values that are less meaningful to someone reading the code.

How to use the RESP and RESP2 options

The argument of RESP is a user-defined fullword binary data area (long integer). On return from the command, it contains a value corresponding to the condition that may have been raised. Normally its value is DFHRESP(NORMAL).

Use of RESP and DFHRESP in COBOL and PL/I

Here is an example of an EXEC CICS call in COBOL which uses the RESP option. A PL/I example would be similar, but would end in ";" instead of END-EXEC.

EXEC CICS WRITEQ TS FROM(abc)
          QUEUE(qname)
          NOSUSPEND
          RESP(xxx)
          END-EXEC.

An example of using DFHRESP to check the RESP value is:

IF xxx=DFHRESP(NOSPACE) THEN ...

Use of RESP and DFHRESP in C and C++

Here is an example of an EXEC CICS call in C, which uses the RESP option, including the declaration of the RESP variable:

long response;

·
·
·
EXEC CICS WRITEQ TS FROM(abc) QUEUE(qname) NOSUSPEND RESP(response);

An example of using DFHRESP to check the RESP value is:

if (response == DFHRESP(NOSPACE))
{

·
·
·
}

Use of DFHRESP in assembler

An example of a test for the RESP value in assembler language is:

  CLC   xxx,DFHRESP(NOSPACE)
  BE    ...

An example of exception handling in C

The following example is a typical function which could be used to receive a BMS map and to cope with exception conditions:

Figure 73. An example of exception handling in C
int ReadAccountMap(char *mapname, void *map)
{
    long     response;
    int      ExitKey;
    EXEC CICS RECEIVE MAP(mapname)
              MAPSET("ACCOUNT")
              INTO(map)
              RESP(response);
    switch (response)
    {
    case DFHRESP(NORMAL):
        ExitKey = dfheiptr->eibaid;
        ModifyMap(map);
        break;
    case DFHRESP(MAPFAIL):
        ExitKey = dfheiptr->eibaid;
        break;
    default:
        ExitKey = DFHCLEAR;
        break;
    }
    return ExitKey;
}

The ReadAccountMap function has two arguments:

  1. mapname is the variable which contains the name of the map which is to be received.
  2. map is the address of the area in memory to which the map is to be written.

The RESP value will be returned in response. The declaration of response sets up the appropriate type of automatic variable.

The EXEC CICS statement asks for a map of the name given by mapname, of the mapset ACCOUNT, to be read into the area of memory to which the variable map points, with the value of the condition being held by the variable response.

The condition handling can be done by using if statements. However, to improve readability, it is often better, as here, to use a switch statement, instead of compound if ... else statements. The effect on program execution time is negligible.

Specific cases for two conditions:

  1. A condition of NORMAL is what is normally expected. If a condition of NORMAL is detected in the example here, the function then finds out what key the user pressed to return to CICS and this value is passed to ExitKey. The program then makes some update to the map held in memory by the ModifyMap function, which need not concern us further.
  2. A condition of MAPFAIL, signifying that the user has made no updates to the screen, is also fairly normal and is specifically dealt with here. In this case the program again updates ExitKey but does not call ModifyMap.

In this example, any other condition is held to be an error. The example sets ExitKey to DFHCLEAR--the same value that it would have set if the user had cleared the screen--which it then returns to the calling program. By checking the return code from ReadAccountMap, the calling program would know that the map had not been updated and that some remedial action is required.

An example of exception handling in COBOL

The following example is a typical function which could be used to receive a BMS map and to cope with exception conditions:

Start of changeFigure 74. An example of exception handling in COBOL
03   RESPONSE                             PIC S9(8)  BINARY.
03   EXITKEY                              PIC X.

·
·
·
EXEC CICS RECEIVE MAP(MAPNAME) MAPSET('ACCOUNT') INTO(MAP) RESP(RESPONSE) END-EXEC. IF (RESPONSE NOT = DFHRESP(NORMAL)) AND (RESPONSE NOT = DFHRESP(MAPFAIL)) MOVE DFHCLEAR TO EXITKEY ELSE MOVE EIBAID TO EXITKEY IF RESPONSE = DFHRESP(NORMAL) GO TO MODIFYMAP END-IF END-IF.
·
·
·
MODIFYMAP.
·
·
·
End of change

MAPNAME is the variable which contains the name of the map which is to be received.

The RESP value is returned in RESPONSE. RESPONSE is declared as a fullword binary variable in the data section.

The EXEC CICS statement asks for a map of the name given by MAPNAME, of the mapset ACCOUNT, to be read, with the value of the condition being held by the variable RESPONSE.

The condition handling is done by using IF ... statements. If the condition is neither NORMAL nor MAPFAIL the program behaves as if the user had cleared the screen.

If the condition is either NORMAL or MAPFAIL the program saves the value of the key which the user pressed to exit the screen in EXITKEY. In addition, if the condition is NORMAL, the program branches to MODIFYMAP to perform some additional function.

[[ Contents Previous Page | Next Page Index ]]