Investigating an indoubt failure

This example shows how to investigate a unit of work (UOW) that has failed indoubt. For the purposes of the example, the CICS-supplied transaction CIND has been used to create the failure - one of the FILEA sample application transactions, UPDT, has been made to fail indoubt.

For more information about CIND, see CIND - indoubt testing tool.

To retrieve information about a unit of work (UOW), you can use either the CEMT, or EXEC CICS®, INQUIRE UOW command. For the purposes of this illustration, the CEMT method is used. You can filter the command to show only UOWs that are associated with a particular transaction. For example, Figure 1 shows one UOW (AC0CD65E5D990800) associated with transaction UPDT.

Figure 1. The CEMT INQUIRE UOW command showing UOWs associated with a transaction

 
INQUIRE UOW TRANS(UPDT)
STATUS:  RESULTS - OVERTYPE TO MODIFY
 Uow(AC0CD65E5D990800) Ind Shu Tra(UPDT) Tas(0003155)
    Age(00000680) Ter(S233) Netn(IGBS233 ) Use(CICSUSER) Con Lin(DFHINDSP)

Each UOW identifier is unique within the local CICS system. To see more information about the UOW, move the cursor to the UOW row and press ENTER. This display the following screen:

Figure 2. CEMT INQUIRE UOW - details of UOW AC0CD65E5D990800

 
INQUIRE UOW TRA(UPDT)
RESULT - OVERTYPE TO MODIFY
  Uow(AC0CD65E5D990800)
  Uowstate( Indoubt )
  Waitstate(Shunted)
  Transid(UPDT)
  Taskid(0003155)
  Age(00000826)
  Termid(S233)
  Netname(IGBS233)
  Userid(CICSUSER)
  Waitcause(Connection)
  Link(DFHINDSP)
  Sysid()
  Netuowid(..GBIBMIYA.IGBS233 .O;)r...)

The UOWSTATE for this UOW is Indoubt. The TRANSACTION definition attribute WAIT(YES|NO) controls the action that CICS takes when a UOW fails indoubt. CICS does one of two things:

Makes the UOW wait, pending recovery from the failure. (In other words, the UOW is shunted.) Updates to recoverable resources are suspended,
Takes an immediate decision to commit or backout the recoverable resource updates.

The WAITSTATE of Shunted shows that this UOW has been suspended.

Figure 2 reveals other information about the UOW:

The original transaction was UPDT, the taskid was 3155, and the termid was S233. Any of these can be used to tie this particular failure with messages written to CSMT.
The UOW has been indoubt for 826 seconds (AGE).
The cause of the indoubt failure was a Connection failure. (The connection is the dummy connection used by CIND DFHINDSP.)

When a UOW has been shunted indoubt, CICS retains locks on the recoverable resources that the UOW has updated. This prevents further tasks from changing the resource updates while they are indoubt. To display CICS locks held by a UOW that has been shunted indoubt, use the CEMT INQUIRE UOWENQ command. You can filter the command to show only locks that are associated with a particular UOW. (Note that the INQUIRE UOWENQ command operates only on non-RLS resources on which CICS has enqueued, and for RLS-accessed resources you should use the INQUIRE UOWDSNFAIL command.) For example:

Figure 3. CEMT INQUIRE UOWENQ—used to display locks associated with a UOW

 
INQUIRE UOWENQ UOW(*0800)
STATUS:  RESULTS
 Uow(AC0CD65E5D990800) Tra(UPDT) Tas(0003155) Ret Dat Own
    Res(DCXISCG.IYLX.FILEA        ) Rle(018) Enq(00000003)

To see more information about this UOWENQ, put the cursor alongside it and press ENTER:

Figure 4. CEMT INQUIRE UOWENQ—details of a lock associated with a UOW

 
INQUIRE UOWENQ UOW(*0800)
RESULT
  Uowenq
  Uow(AC0CD65E5D990800)
  Transid(UPDT)
  Taskid(0003155)
  State(Retained)
  Type(Dataset)
  Relation(Owner)
  Resource(DCXISCG.IYLX.FILEA)
  Rlen(018)
  Enqfails(00000003)
  Netuowid(..GBIBMIYA.IGBS233 .O;)r...)
  Qualifier(000001)
  Qlen(006)

We can now see that:

This UOW is the Owner of a Retained lock on a Data Set. Retained locks differ from active locks in that a further task requiring this lock is not suspended; instead, the transaction receives the LOCKED condition—if the condition is not handled by the application, this results in an AEX8 abend.
The data set is DCXISCG.IYLX.FILEA, and the Qualifier (in this case, the key of the record which is indoubt) is 000001.
Three other tasks have attempted to update the indoubt record (ENQFAILS).

Because CIND was used to create this indoubt failure, it can also be used to resolve the indoubt UOW. For an example of how to resolve a real indoubt failure, see Problem determination examples.