Handling Errors

The EXEC CICS ASSIGN Command

The CICS ASSIGN command requests values from outside the application program’s local environment. The syntax is as follows:

EXEC CICS ASSIGN ABCODE(data-area)
                 ABPROGRAM(data-area)
                 ASRAINTRPT(data-area)
                 ASRAKEY(cvda)
                 ASRAPSW(data-area)
                 ASRAREGS(data-area)
                 ASRASPC(cvda)
                 ASRASTG(cvda)
                 FCI(data-area)
                 INVOKINGPROG(data-area)
                 NETNAME(data-area)
                 PROGRAM(data-area)
                 RETURNPROG(data-area)
                 STARTCODE(data-area)
                 TERMCODE(data-area)
                 RESP(data-area) RESP2(data-area)
END-EXEC

The options in this command are:

ABCODE(data-area)

Returns a four-character abend code. (Abend codes are documented in the CICS Messages and Codes manual that is on the CD-ROM). If an abend has not occurred, the variable is set to blanks.

ABPROGRAM(data-area)

Returns an eight-character name of the failing program for the latest abend. If the abend originally occurred in a DPL server program running in a remote system, ABPROGRAM returns the DPL server program name.

This field is set to binary zeros if it is not possible to determine the failing program at the time of the abend.

ASRAINTRPT(data-area)

Returns an eight-character program status word (PSW) containing interrupt information at the point when the latest abend with a code of ASRA, ASRB, ASRD, or AICA occurred.

The field contains binary zeros if no ASRA, ASRB, ASRD, or AICA abend occurred during the execution of the issuing transaction, or if the abend originally occurred in a remote DPL server program.

ASRAKEY(cvda)

Returns the execution key at the time of the last ASRA, ASRB, AICA, or AEYD, abend, if any. CVDA values are:

ASRAPSW(data-area)

Returns an eight-character program status word (PSW) at the point when the latest abend with a code of ASRA, ASRB, ASRD, or AICA occurred.

The field contains binary zeros if no ASRA, ASRB, ASRD, or AICA abend occurred during the execution of the issuing transaction, or if the abend originally occurred in a remote DPL server program.

ASRAREGS(data-area)

Returns the contents of general registers 0–15 at the point when the latest ASRA, ASRB, ASRD, or AICA abend occurred.

The contents of the registers are returned in the data area (64 bytes long) in the order 0, 1…, 14, 15.

ASRASPC(cvda)

Returns the type of space in control at the time of the last ASRA, ASRB, AICA, or AEYD abend, if any. The CVDA values on the ASRASPC option are:

SUBSPACE: Returned if the task was executing in either its own subspace or the common subspace at the time of the latest ASRA, ASRB, AICA, or AEYD abend.
BASESPACE: Returned if the task was executing in the base space at the time of the last ASRA, ASRB, AICA, or AEYD abend.
Tip
All tasks execute in base space if transaction isolation is not active.
NOTAPPLIC: Returned if there has not been an ASRA, ASRB, AICA, or AEYD abend.

ASRASTG(cvda)

Returns the type of storage being addressed at the time of the last ASRA or AEYD abend, if any. The CVDA values are:

FCI(data-area)

Returns a one-byte facility control indicator. This indicates the type of facility associated with the transaction; for example, X'01’ indicates a terminal or logical unit. A value is always returned.

INVOKINGPROG(data-area)

Returns the eight-character name of the application program that used the LINK or XCTL command to link or transfer control to the current program. If you issue the ASSIGN INVOKINGPROG command:

In a remote program that was invoked by a distributed program link (DPL) command, CICS returns the name of the program that issued the DPL command.
In an application program at the highest level, CICS returns eight blanks.
In a user-replaceable program, a Bridge Exit program or a program list table program, CICS returns eight blanks.
From a global user exit, task-related exit, or application program linked to from such an exit, CICS returns the name of the most recent invoking program that was not a global user exit (GLUE) or task-related user exit (TRUE).

NETNAME(data-area)

Returns the eight-character name of the logical unit in the VTAM network. If the task is not initiated from a terminal, INVREQ occurs. If the principal facility is not a local terminal, CICS returns the netname of the remote terminal. If this command was issued by a user transaction that was started by a bridged-to transaction, the value returned is the termid of the Bridge Facility.

Program(data-area)

Returns an eight-character name of the currently running program.

RETURNPROG(data-area)

Returns the eight-character name of the program to which control is to be returned when the current program has finished executing. The values returned depend on how the current program was given control, as follows:

If the current program was invoked by a LINK command, including a distributed program link, RETURNPROG returns the same name as INVOKINGPROG.
If the current program was invoked by an XCTL command, RETURNPROG returns the name of the application program in the chain that last issued a LINK command.
If the program that invoked the current program with an XCTL command is at the highest level, CICS returns eight blanks.
If the ASSIGN RETURNPROG command is issued in the program at the top level, CICS returns eight blanks.
If the ASSIGN RETURNPROG command is issued in a user-replaceable module, or a program list table program, CICS returns eight blanks.
If the ASSIGN RETURNPROG is issued in a global user exit, task-related exit, or application program linked to from such an exit, CICS returns the name of the program that control is returned to when all intermediate global user exit and task-related user exit programs have completed.

STARTCODE(data-area)

Returns a two-byte indicator showing how the transaction issuing the request was started. It can have the following values:

Code	Transaction Start By
D	A distributed program link (DPL) request that did not specify the SYNCONRETURN option. The task cannot issue I/O requests against its principal facility, nor can it issue any syncpoint requests.
DS	A distributed program link (DPL) request, as in code D, that did specify the SYNCONRETURN option. The task cannot issue I/O requests against its principal facility, but can issue syncpoint requests.
QD	Transient data trigger level.
S	START command without data.
SD	START command with data.
SZ	FEPI START command.
TD	Terminal input or permanent transid.
U	User attached task.

TERMCODE(data-area)

Returns a two-byte code giving the type and model number of the terminal associated with the task. The first byte is a code identifying the terminal type, derived from the terminal resource definition. This is the DEVICE attribute (described in the CICS Resource Definition Guide). The second byte is a single-character model number as specified in the TERMMODEL attribute.

The EXEC CICS ASSIGN command as used in the NACT04 program

First we obtain various information from CICS about the environment and the problem. We use this to determine what actions to take and whether the program was entered using CICS ABEND handling or whether an application program transferred control to it using a CICS XCTL command or called it using a CICS LINK or COBOL Dynamic CALL. The syntax is as follows:

EXEC CICS ASSIGN ABCODE(AA-ABCODE)
                 ABPROGRAM(AA-ABPROGRAM)
                 ASRAINTRPT(AA-ASRAINTRPT)
                 ASRAKEY(AA-ASRAKEY)
                 ASRAPSW(AA-ASRAPSW)
                 ASRAREGS(AA-ASRAREGS)
                 ASRASPC(AA-ASRASPC)
                 ASRASTG(AA-ASRASTG)
                 FCI(AA-FCI)
                 INVOKINGPROG(AA-INVOKINGPROG)
                 NETNAME(AA-NETNAME)
                 PROGRAM(AA-PROGRAM)
                 RETURNPROG(AA-RETURNPROG)
                 STARTCODE(AA-STARTCODE)
                 TERMCODE(AA-TERMCODE)
                 RESP(AA-RESP)
END-EXEC

The EXEC CICS INQUIRE PROGRAM Command

Having determined how the error handling program received control (through the LINK or XCTL command), the EXEC CICS INQUIRE PROGRAM is used in two ways: one to confirm that this was the program where the error occurred, and secondly, if it is not, then to browse the other programs to see if it can find the culprit.

The syntax of the EXEC CICS INQUIRE PROGRAM is as follows:

EXEC CICS INQUIRE PROGRAM(name)
                  LOADPOINT(ptr-ref) ENTRYPOINT(ptr-ref)
                  LENGTH(data-area)
END-EXEC

Description

The INQUIRE PROGRAM command returns information about a particular program, map set, or partition set installed in your CICS system. All of these resources are load modules and, therefore, CICS uses the same INQUIRE command for all three. To avoid confusion, we use the word module to refer to the object of your inquiry, except in some cases where the option applies only to executable programs.

CICS determines the information you request from both the resource definition and, where applicable, the load module. Information from the module takes precedence over that in the definition if there is a conflict. However, CICS inspects a module only if it is already loaded and is the copy currently available for use. CICS does not do a load for an INQUIRE PROGRAM command, nor attempt to autoinstall a resource for which it has no definition.

ENTRYPOINT(ptr-ref): Returns the entry point address of the module, if it is loaded. The top bit of the address is set on if the addressing mode is 31 and off if it is 24. If the module has not been loaded, or is a remote program, or is a Java Virtual Machine (JVM) program, a null pointer (X’FF000000’) is returned.
LENGTH(data-area): Returns a full-word binary field giving the length of the module in bytes. A value of 0 is returned if the module has not been loaded in the current CICS session. A value of –1 is returned if it is a remote program, or a JVM program.
LOADPOINT(ptr-ref): returns the load address of the module. If it is not currently loaded, or if the program is running under a JVM, a null pointer (X’FF000000’) is returned.

Browsing

You can also browse through the definitions of these three attributes of resources in your system by using the browse options (START, AT, NEXT, and END) on INQUIRE PROGRAM commands. In browse mode, the definitions are returned in alphabetical order, and you can specify a starting point with the AT option if you wish.

This command has introduced an argument value of cvda, which stands for a CICS-value data area. It is implemented in a similarly to DFHRESP, so to test the value returned in the ASRAKEY argument, you would code:

IF AA-ASRAKEY = DFHVALUE(USEREXECKEY)

The EXEC CICS INQUIRE PROGRAM as used in the NACT04 program

NACT04 uses the INQUIRE PROGRAM command as follows:

EXEC CICS INQUIRE PROGRAM(AA-ABPROGRAM)
                  ENTRYPOINT(WF-ENTRY-POINT) LOADPOINT(WF-LOAD-POINT)
                  LENGTH(WF-LENGTH)
                  RESP(WF-RES)
END-EXEC

And for browsing:

EXEC CICS INQUIRE PROGRAM START
                  RESP(WF-RES)
END-EXEC
PERFORM UNTIL (MA-ABPROGRAM NOT = '*UNKNOWN')
         OR   (WF-RESP = DFHRESP(END))
   EXEC CICS INQUIRE PROGRAM(AA-ABPROGRAM) NEXT
                     ENTRYPOINT(WF-ENTRY-POINT) LOADPOINT(WF-LOAD-POINT)
                     LENGTH(WF-LENGTH)
                     RESP(WF-RES)
   END-EXEC
    ADD WF-LENGTH TO     WF-LOAD-POINT
                  GIVING WF-END-POINT
    IF  AA-ASRAPSW-NSI < WF-END-POINT
    AND AA-ASRAPSW-NSI > WF-LOAD-POINT
        MOVE AA-ABPROGRAM   TO MA-ABPROGRAM
    END-IF
END-PERFORM
EXEC CICS INQUIRE PROGRAM END
                  RESP(WF-RES)
END-EXEC

The EXEC CICS DUMP TRANSACTION Command

The DUMP TRANSACTION command dumps all, a series, or any single main storage area related to a task, any or all of the CICS resource definitions (DCT, FCT, SIT, or TCT), or all of these together.

Warning

If you issue a DUMP TRANSACTION for a DUMPCODE that is defined in the transaction dump table with SYSDUMP, you also get a system dump.

If there is no entry in the system dump table for the specified DUMPCODE, a temporary entry is made. This entry is lost on the next CICS start. The system dump table is described in the CICS Problem Determination Guide. The syntax for this command is:

EXEC CICS DUMP TRANSACTION DUMPCODE(name)
          RESP(data-area)
END-EXEC

The option in this command is:

DUMPCODE(name)

Specifies a name (1–4 characters) that identifies the dump. If the name contains any leading or imbedded blanks, the dump is produced but INVREQ is raised. No entry is added to the system dump table.

If you omit all the options except DUMPCODE, you get the same dump as if you specified TASK, but without the DL/I control blocks.

EXEC CICS DUMP TRANSACTION as used in NACT04

We take a dump but with a code based on the type of error we have encountered. This way we ensure we do not conflict with any CICS dump codes. Note that if these are not wanted, they can be suppressed by operational procedures:

EXEC CICS DUMP TRANSACTION DUMPCODE(DUMP-CODE)
          RESP(AA-RESP)
END-EXEC

The EXEC CICS SYNCPOINT ROLLBACK Command

The SYNCPOINT ROLLBACK command backs out any updates to protected resources and returns them to a state they were in before this transaction began. The syntax is as follows:

EXEC CICS SYNCPOINT ROLLBACK
END-EXEC

ROLLBACK specifies that all changes to recoverable resources made by the task since its last syncpoint are to be backed out. This option can be used to tidy up protected resources in a HANDLE ABEND routine, or to revoke database changes after the application program finds irrecoverable errors in its input data.

Warning

A failure occurring during the backout phase (phase 2) of syncpoint processing does not return an error condition and the transaction is not abnormally terminated. Subsequent units of work in the transaction are allowed to continue normally. See CICS Recovery and Restart Guide for further information.

The EXEC CICS SYNCPOINT ROLLBACK command as used in the NACT04 program

In order to reset all CICS recoverable resources because the transaction has not finished we backout the current UOW by performing the following command:

EXEC CICS SYNCPOINT ROLLBACK
END-EXEC

The EXEC CICS WRITE OPERATOR Command

The WRITE OPERATOR command enables an application to write a message to one or more system consoles and, if necessary, wait for a reply. The command can specify route codes. This is of particular use to application packages that need to issue their own system operator messages.

As a result of a change in the way CICS handles messages sent to the console, text lengths of greater than 113 characters are split into two lines:

EXEC CICS WRITE OPERATOR
          TEXT(data-value)
END-EXEC

Tip

If ACTION (or one of the equivalent CVDA values below) is specified, the message is retained until the console operator explicitly deletes it or CICS terminates.

The option for this command is:

TEXT(data-value): A data value containing the text to be sent. In COBOL programs use a data-area that contains the text to be sent to the operator, rather than a data-value.

The EXEC CICS WRITE OPERATOR command as used in the NACT04 program

By writing these messages out to the sytem operator, we enable automated operations policies to be implemented and this will depend on the way your CICS systems are set up for running transactions. The syntax for this command is:

EXEC CICS WRITE OPERATOR
          TEXT(MA-STD-INFO)
END-EXEC

In the code there is another WRITE OPERATOR that sends a second message held in data variable MA-XTR-INFO.

Other Commands

In addition to the previous commands, the error handling program also uses a number of other commands including those which enable you to add a date and time stamp in a variety of formats to the messages. They are EXEC CICS ASKTIME and EXEC CICS FORMATTIME. Finally, the command EXEC CICS ISSUE DISCONNECT is used when you need to drop the session of the end user’s terminal. For the details of these commands, look in the CICS Application Programming Reference.