Commit protocols and units of recovery for DBCTL

This section describes what happens when a transaction has updated DBCTL databases, and is issuing a syncpoint, or a TERM request, or is terminating. If a failure occurs at any of these stages, DBCTL may not be able to determine whether CICS® intended these updates to be backed out or committed and has to request this information from CICS when it has been reconnected.

This section covers:

Two-phase commit for DBCTL

DBCTL uses a two-phase commit to record a syncpoint. At the completion of a two-phase commit, the requested processing is committed and if a failure occurs, DBCTL does not ABORT committed changes.

Two-phase commit consists of the PREPARE and COMMIT phases. Within the PREPARE phase, CICS issues a PREPARE request to DBCTL. DBCTL writes to the log and issues its response to the PREPARE request to CICS. Within the COMMIT phase, there are two possible actions: COMMIT and ABORT. The ABORT action for data belonging to full function DL/I databases is backout. There is no backout for data belonging to DEDBs because, as explained below, it is not written to the database before the COMMIT phase. The effect of an ABORT for DEDBs is also referred to as undo. Because a CICS thread may be accessing data belonging to both full function DL/I databases and DEDBs, we use the term ABORT to refer to both backout and undo.

When updates are written to databases

The DEDB terms UNDO and REDO are analogous to the DL/I full function terms BACKOUT and COMMIT respectively. However, although the processes that these terms refer to have the similar end results, the processes themselves differ. The difference is in the stage at which updates are written to the database. This is shown in Figure 25.

Figure 25. When updates are written to databases
 For DL/I databases, updates are made during the first phase of two-phase commit, the PREPARE phase. For DEDBs, updates are made during the second phase, the COMMIT phase. Between the two phases, the unit of recovery is in-doubt.

This difference in timing of writing updates dictates the action taken during the second phase of two-phase commit.

For full function DL/I databases:

For DEDBs:

REDO is also used to refer to the action required for committed DEDBs during emergency restart of IMS. IMS can determine from the log that a COMMIT was initiated, but that phase 2 is not indicated as complete. In this case, DEDB updates must be REDOne. The two phases are:

  1. Phase 1, in which CICS directs syncpoint preparation and asks whether or not the updates to DBCTL databases can be committed.
  2. Phase 2, in which CICS tells DBCTL that it must either COMMIT or ABORT the resources. (CICS can request an ABORT without first issuing a PREPARE request. That is, CICS can bypass the first phase of two-phase commit when an update is being backed out.)

Figure 26 shows two-phase commit and describes the activities taking place.

Figure 26. Two-phase commit
 The notes below the figure have been included in this alternative text for clarity.  At the beginning of phase 1, the PREPARE phase, CICS receives a syncpoint request. The syncpoint request can be EXEC CICS SYNCPOINT, a DL/I TERM call, or a CICS task termination. CICS begins phase 1, sending a PREPARE request via a task-related user exit (TRUE) interface to DBCTL. When DBCTL receives the PREPARE request, it enters phase 1, during which it writes to the log and retains locks. It then sends CICS a response to the PREPARE request. If DBCTL indicates at this stage that it cannot commit the updates, CICS aborts the unit of recovery and the rest of this process does not take place. From the point where DBCTL receives the PREPARE request, to the point where it sends a response to CICS, units of recovery are in-flight, and if DBCTL fails during this stage, all database updates are aborted. When CICS receives the response from DBCTL, it writes to the log, and then phase 1 ends. CICS begins phase 2, the COMMIT phase, by sending a COMMIT request to DBCTL. If CICS tells DBCTL to commit the updates, DBCTL must commit. From the time that DBCTL issues its response to the PREPARE request, to the time it receives a COMMIT request from CICS, units of recovery are in-doubt. DBCTL retains the in-doubt information. When DBCTL is restarted after a failure, it inquires with CICS about the status of the in-doubts. This is part of resynchronization. When DBCTL receives the COMMIT request, it enters phase 2, and the changes are committed. DBCTL writes to the log and releases locks. It then returns an OK message to CICS, and CICS writes an end-of-syncpoint record to the log. The process is now complete.

Notes:
  1. The syncpoint request can be EXEC CICS SYNCPOINT, a DL/I TERM call, or a CICS task termination.
  2. If DBCTL indicates that it cannot commit the updates, CICS aborts the unit of recovery and the rest of the Figure 26 does not apply.
  3. If CICS tells DBCTL to commit the updates, DBCTL must commit.
  4. At this stage, units of recovery are in-flight and, if DBCTL fails, all database updates are aborted.
  5. At this stage, from the time that DBCTL issues its response to the PREPARE request to the time it receives a COMMIT request from CICS, units of recovery are in-doubt. DBCTL retains the in-doubt information. When DBCTL is restarted after a failure, it inquires with CICS about the status of the in-doubts. This is part of resynchronization.

UOWs and resources belonging to multiple resource managers

The two-phase commit process also applies if a UOW is updating resources that belong to more than one resource manager; for example, any of the following: DBCTL databases (DL/I full function or DEDBs, or both), local VSAM files, and DB2® databases. As explained above, CICS is the coordinator of the two-phase commit process; DBCTL is a participant. CICS must ensure that all the resource managers, including DBCTL, are in synchronization. To do this, at phase 1 of two-phase commit, it issues a PREPARE request to all the resource managers involved to find out if a COMMIT can be done. This is as shown in Figure 26, in which CICS is communicating with DBCTL only. If all the other resource managers indicate that a COMMIT is possible, CICS tells them all to COMMIT. If not, CICS tells them all to ABORT. The COMMIT or ABORT must now be carried out in all the resource managers. For this reason, CICS considers the COMMIT or ABORT to be completed at this stage, even if it is slightly delayed.

DBCTL unit of recovery

A DBCTL unit of recovery is created for each processing request when the first schedule request is made by the transaction, and is kept until the two-phase commit is complete. As described in Resolving in-doubt CICS DBCTL units of work manually, commands are available to display the units of recovery and take appropriate actions for committing or ending them.

In-flight unit of recovery

If DBCTL fails and is subsequently restarted, all in-flight units of recovery are backed out.

In-doubt unit of recovery

When a failure occurs, a recoverable in-doubt structure (RIS) is constructed for each in-doubt unit of recovery and is also written to the IMS log. The RIS contains:

The IMS batch backout utility, DFSBBO00, and the IMS database recovery utility, DFSURDB0, process the in-doubt units of recovery.

CICS units of work (UOWs)

CICS UOWs and DBCTL units of recovery are more or less synonymous, except that from CICS’s point of view, a UOW begins at the beginning of a task, and a unit of recovery begins when that task issues its first DL/I request. For simplicity, in the rest of this book, we use the CICS term UOW to refer to both. The IMS publications use the term "unit of recovery".

CICS DBCTL recovery tokens

Recovery tokens are created by CICS and passed to DBCTL. They are unique identifiers for each UOW. The lifetime of a recovery token is the same as for a UOW. You can use them to correlate work done between CICS and DBCTL in the same UOW. Each recovery token is 16 bytes long; the first 8 bytes are the CICS APPLID (passed to DBCTL when CICS is first connected) and the second 8 bytes are a UOW identifier. CICS creates an identifier like this for every UOW. DBCTL validates the recovery token to protect against duplication of UOWs. You can use the recovery token in certain operator commands. For example, you can display it as part of the output of the /DISP CCTL and CEMT INQ TASK commands, and you can enter it in /CHANGE commands, in the form of a pseudo recovery token, as explained below. The recovery token is included in certain messages (for example, the CICS message DFHDB8109, which is issued when a DL/I request has failed). Recovery tokens can be useful in problem determination, because they are displayed in dumps produced by CICS and DBCTL and in trace entries produced by CICS. See Problem determination for DBCTL for more information.

The pseudo recovery token is an 8-character decimal token, which can be used in place of the 8-byte hexadecimal recovery token and is displayed when the status of a thread is in-doubt. It is made shorter than the recovery token so that it is easier to make note of (for example, from /DISPLAY commands) and enter (for example, in /CHANGE commands).

Figure 27 shows a pseudo recovery token (00010040 in the column headed PSEUDO-RTKN) and a recovery token (F0F58879641002C2) for thread number 4 (in the column headed REGID) for PSBNAME PC3COCHD, whose STATUS is INDOUBT.

Figure 27. /DISPLAY CCTL cctlname command showing pseudo recovery token
0080  /DIS CCTL DBDCCICS
0080  DFS000I MESSAGE(S) FROM ID=SYS1 047
0080      CCTL     PSEUDO-RTKN  RECOVERY-TOKEN   REGID  PSBNAME   STATUS
0080      DBDCCICS                                                ATTACHED
0080                            9EDA1F61E11CFA02     6  PC3COCHD  ACTIVE
0080                            9EDA1F4E9B571B02     5  PC3COCHD  ACTIVE
0080               00010040     F0F58879641002C2     4  PC3COCHD  INDOUBT

Resolving in-doubt CICS DBCTL units of work manually

Normally, an emergency restart of DBCTL followed by reconnection of CICS and DBCTL after a failure should resolve in-doubts automatically. However, you may sometimes need to do this yourself. For example, if a CICS system using DBCTL disconnects abnormally from DBCTL (for instance, if CICS or DBCTL abends, or CDBC DISCONNECT IMMEDIATE is issued), there may be some incomplete updates about which DBCTL is in doubt. Even if CICS then needs to be cold started for some reason, it normally recovers enough information to resolve indoubts automatically. However, if CICS is started with the START=INITIAL system initialization parameter, it loses its record of the in-doubt updates and they must be resolved manually. You are strongly advised not to start CICS with START=INITIAL specified when there are in-doubt units of work outstanding.

The DFS2283I message, issued during the resynchronization process, indicates that there are UOWs that have not received a COMMIT or ABORT request, and are therefore in-doubt.

In this situation you must use DBCTL operator commands (described in Using DBCTL operator commands to resolve in-doubts) to resolve the in-doubts.

Using DBCTL operator commands to resolve in-doubts

Use the following DBCTL operator commands to commit or backout a unit of work.

  1. Use /DISPLAY CCTL cctlname INDOUBT, as shown in Figure 28 to obtain the pseudo recovery token that identifies the in-doubt work. (Pseudo recovery tokens are defined in CICS DBCTL recovery tokens.)
    Figure 28. /DISPLAY CCTL cctlname command showing in-doubt
    0080  /DIS CCTL DBDCCICS INDOUBT
    0080  DFS000I MESSAGE(S) FROM ID=SYS1 047
    0080      CCTL     PSEUDO-RTKN  RECOVERY-TOKEN   REGID  PSBNAME   STATUS
    0080      DBDCCICS                                                ATTACHED
    0080               00010040     F0F58879641002C2     4  PC3COCHD  INDOUBT
  2. Use /CHANGE CCTL cctlname PRTKN token command to abort or commit the in-doubt. The cctlname is the APPLID of the CICS system. The PRTKN keyword specifies the pseudo recovery token of the element to be processed. The command is either:

When the action you specified has been completed, the recoverable in-doubt structure (RIS) for the in-doubt UOW is removed.

Related concepts
Recovery and restart operations for DBCTL
Overview of CICS and IMS recovery and restart
IMS database utilities
IMS log utilities
Component failures in the CICS DBCTL environment
[[ Contents Previous Page | Next Page Index ]]