changes to the file by any process is logged in the journal receiver. Commitment control of the transactions for a particular process using that file does not start until the process starts commitment control. More information about recoverability can be found in the
CICS for iSeries Administration and Operations Guide
.
Syncpointing
To facilitate recovery in the event of abnormal termination of a CICS task or of failure of the CICS system, the system programmer can, during CICS table generation, define specific resources (for example, files) as recoverable. If a task is terminated abnormally, these resources are restored to the condition they were in at the start of the task, which can then be rerun. The process of restoring the resources associated with a task is termed
backout
.
If an individual task fails, backout is performed by the commitment control facilities of OS/400 and by CICS component modules. If the CICS system fails, backout is performed as part of the emergency restart process.
However, for long-running programs, it may be undesirable to have a large number of changes, accumulated over a period of time, exposed to the possibility of backout in the event of task or system failure. This possibility can be avoided by using the EXEC CICS SYNCPOINT command to split the program into logically separate sections known as logical units of work (LUWs); the end of an LUW is referred to as a synchronization point (
syncpoint
).
If failure occurs after a syncpoint but before the task has been completed, only changes made after the syncpoint are backed out.
LUWs must be entirely logically independent, not merely with regard to protected resources, but also with regard to execution flow. Typically, an LUW comprises a complete conversational operation bounded by EXEC CICS SEND and EXEC CICS
RECEIVE commands. A browse is another example of an LUW; an EXEC CICS
ENDBR command must therefore precede the syncpoint.
User journaling
CICS provides facilities for defining and managing CICS
user journals
during
CICS processing. CICS user journals are special-purpose nonrecoverable sequential files.
CICS user journals may be used as an audit trail, or as a change file of file updates and additions, or for any other purpose needed by a CICS application program.
Journal control commands are provided to allow the application programmer to create a journal record (EXEC CICS WRITE JOURNALNUM).
Exception conditions that occur during execution of a journal control command are
handled as described in Chapter 6, “Dealing with exception conditions,” on page
87..
Journal records
CICS user journals are defined to CICS in the journal control table (JCT). Data may be written to any journal specified in the JCT. The JCT may define one or more journals on direct access storage. Each journal is identified by a number known as the journal identifier. This number is in the range from 1 through 99. Generally the
106
CICS for iSeries Application Programming Guide V5
system administrator is responsible for defining the JCT entries. For more information about defining journals, see the
CICS for iSeries Administration and
Operations Guide
.
Each journal record begins with a standard length field (LL), a user-specified identifier, and a system-supplied prefix. This data is followed in the journal record by any user-supplied prefix data (optional), and finally by the user-specified data.
Journal control is designed so that the application programmer requesting output services need not be concerned further with the detailed layout and precise contents of journal records. The programmer needs to know which journal to use, what user data to specify, and what user-identifier to supply.
The layout of the journal records is defined in the
CICS for iSeries Administration and Operations Guide
. CICS user journals are defined as variable-length record physical files. To use these files in a batch application, you must know the physical file information for the journal you want, and the format of the CICS user journal records.
The use of the information recorded on a CICS user journal is left up to the needs of the application. This information can be used by reading the physical file records on the journal. For example: v An application could use any before and after record images recorded on a CICS user journal to recreate updates to a file if desired. v
The application may create an audit trail report indicating the updates that took place and the areas of the records that had changed. v
The application could also report the date and time of the update, the id of the user performing the update, and the CICS terminal ID where the changes were made.
Journal output synchronization
References to journals in this section mean CICS user journals.
Journal output takes place at the time of the EXEC CICS WRITE JOURNALNUM command. The WAIT and STARTIO options are allowed within CICS/400, but are treated as null operations (no-ops).
If an out-of-space condition occurs while trying to execute an EXEC CICS WRITE
JOURNALNUM command, the action taken by CICS varies based on how the journal file is defined in the JCT. See the
CICS for iSeries Administration and
Operations Guide
for details.
If the requested journal file is defined as switchable, CICS switches to a new journal file and writes the journal record to the newly created journal file automatically when the first journal file is full. The task requesting the write waits until the journal record is written to the new journal file. If the second file becomes full, another switch to a new journal file occurs. Journal switching occurs when necessary, until the maximum number of switched journal files has been reached. If this occurs, the JCT entry for that journal file is marked CLOSED and DISABLED.
If the journal file is defined as nonswitchable, CICS closes the journal file, marks the JCT entry as CLOSED and returns an IOERR condition to the application program. If the program has an active EXEC CICS HANDLE CONDITION command set up to deal with an IOERR condition, control is returned to the program (to the location requested in the HANDLE CONDITION request). If there
Chapter 8. Recovery considerations
107
is no HANDLE CONDITION command set for an IOERR condition, the default action for an IOERR condition is taken; that is, to abend the transaction.
108
CICS for iSeries Application Programming Guide V5
Chapter 9. Abnormal termination recovery
A program-level abend exit facility is provided in CICS so that you can write exits of your own that can be given control during abnormal termination of a task. An example of a function performed by such an abend exit is the “cleanup” of a program that has started but not completed normally.
Abnormal termination can occur because of: v
A user request by, for example:
EXEC CICS ABEND ABCODE(...) v
A CICS request as a result of an invalid user request.
The EXEC CICS HANDLE ABEND command activates or reactivates a program-level abend exit within your application program; you can also use this command to cancel a previously activated exit.
When activating an exit, you must use the PROGRAM option to specify the name of a program to receive control, or (in COBOL) the LABEL option to specify a routine label to which control will branch when an abnormal termination condition occurs.
An EXEC CICS HANDLE ABEND command overrides any preceding such command in any application program at the same logical level. Each application program of a transaction can have its own abend exit, but only one abend exit at
each logical level can be active. (Logical levels are explained in Chapter 20,
“Program control,” on page 199.)
When a task is abnormally terminated, CICS searches for an active abend exit, starting at the logical level of the application program in which the abend occurred, and proceeding, if necessary, to successively higher levels. The first active
abend exit found, if any, is given control. This procedure is shown in Figure 28 on page 111, which also shows how subsequent abend processing is determined by
the user-written abend exit.
If no abend exit is found, CICS terminates the task abnormally.
To prevent recursive abends in an abend exit, CICS deactivates the exit upon entry to the exit routine or program. If a retry of the operation is desired, the application programmer can branch to a point in the program that was in control at the time of the abend and issue an EXEC CICS HANDLE ABEND RESET command to reactivate the abend exit. This command can also be used to reactivate an abend exit (at the logical level of the issuing program) that was canceled previously by an
EXEC CICS HANDLE ABEND CANCEL command. You can suspend the EXEC
CICS HANDLE ABEND command by means of the EXEC CICS PUSH HANDLE
and EXEC CICS POP HANDLE commands as described in “How to use EXEC
CICS PUSH HANDLE and POP HANDLE commands” on page 95.
The EXEC CICS HANDLE ABEND command cannot intercept abends resulting from OS/400 machine event errors.
© Copyright IBM Corp. 1998, 2004
109
