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:
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.
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.
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:
Figure 26 shows two-phase commit and describes the activities taking place.
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.
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.
If DBCTL fails and is subsequently restarted, all in-flight units of recovery are backed out.
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 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".
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.
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
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.
Use the following DBCTL operator commands to commit or backout a unit of work.
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
/CHANGE CCTL DBDCCICS PRTKN 00010040 COMMIT
would commit the in-doubt shown in Figure 28.When the action you specified has been completed, the recoverable in-doubt structure (RIS) for the in-doubt UOW is removed.