Investigating enqueue waits

A task is suspended by the enqueue domain if it requests access to a resource on which another task already holds an enqueue (lock). Do not use the EXEC CICS® ENQ command for recoverable resources.

There are two ways in which you can discover the owner of the enqueue that the task is waiting on:

It is possible for an enqueue wait to be caused by a deadlock. For more information on how to resolve a deadlock, see Resolving deadlocks in a CICS region.

Using a system dump to resolve enqueue waits

The CEMT INQUIRE UOWENQ (or CEMT INQUIRE ENQ) command does not return information about enqueues on some types of resources. Table 5 shows the resources that this applies to.

Table 5. Resources for which INQUIRE UOWENQ does not return information
Resource name Type of resource
JOURNALS CICS journal names used during creation, deletion, or use of a journal entry. See Log manager waits for information to help you diagnose problems with the MVS™ system logger.
KCADDR Addresses locked internally by CICS.
Start of changeKCSTRINGEnd of change Strings locked internally by CICS.
LOGSTRMS MVS logstream names used during connection of streams to the MVS logger. A long wait could indicate a problem with the logger. See Log manager waits for information to help you diagnose problems with the MVS system logger.

To investigate enqueue waits on these resources, you can use the NQ section of a system dump. (You can use a system dump to investigate enqueue waits on other types of resource, but you might find the INQUIRE UOWENQ command more convenient.)

CICS maintains a separate enqueue pool for each type of resource that can be enqueued upon. To produce a summary of each enqueue pool, specify '1' on the NQ dump formatting keyword (dump formatting keywords are described in topic A summary of system dump formatting keywords and levels). Figure 7 shows an example summary for the transient data enqueue (TDNQ) pool.

Figure 7. Example system dump, showing summary information for the TDNQ enqueue pool
==NQ: ENQUEUE POOL SUMMARY - TDNQ
 
  Default shunt action:                  Retain
 *Total enqueue requests:                34
 *Total requests that have waited:       8
 *Total requests failed busy:            6
 *Total requests failed locked:          2
 *Total requests timed out:              1
 *Total enqueues that were retained:     1
 
*NOTE: These values were reset at 15.44.39 (the last statistics interval collection)
 
                                                  OWNER  /  WAITER
                                         NQEA   Tran Tran                   Lifetime Hash
         Enqueue Name          Len Sta Address   Id   Num     Local Uowid   Uow Tsk  Indx
------------------------------ --- --- -------- ---- ----- ---------------- --- ---  ----
Q007TOQ                          9 Act 052C4580 TDWR 00356 A8EBC70A53A4BC82   1   0   13
Q002FROMQ                        9 Act 053D0880 TDRD 00435 A8EBD91A57D9B7D2   2   0   24
                          Waiter  :    0540BBC0 TDRD 00467 A8EBDAC692BB7C10   0   1   24
                          Waiter  :    0537CE70 TDDL 00512 A8EBDAE6FF0B56F2   1   0   24
Q007FROMQ                        9 Act 0540CC80 ENQY 00217 A8EBB7FE23067C44   0   1   51
                          Waiter  :    0538F320 ENQY 00265 A8EBBF0846C00FC0   0   1   51
                          Waiter  :    0518C5C0 ENQY 00322 A8EBC393B90C66D8   0   1   51
Q002TOQ                          9 Ret 0520B260 ---- ----- A8EBD82AFDA4CD82   1   0   53
Q009FROMQ                        9 Act 0540A140 TDRD 00366 A8EBC84D3FF80250   1   0   62

In the table at the bottom of Figure 7, each enqueue in the pool appears on a new line. If the enqueue has waiters, they are displayed in order on subsequent lines. Waiters are identified by the string ‘Waiter’. The meanings of the table headings are:

Enqueue Name
The string that has been enqueued upon. Normally, up to 30 characters of the name are displayed; however, the summary reports for file control and address enqueue pools format the enqueue name differently:
Len
The length of the enqueue name.
Sta
The state that the enqueue is held in. This field contains either:
Act
The enqueue is held in active state--that is, other transactions are allowed to wait on the enqueue.
Ret
The enqueue is held in retained state--that is, other transactions are not allowed to wait on the enqueue. Typically, this is because the enqueue is owned by a shunted unit of work.
NQEA Address
The address of the NQEA corresponding to the enqueue owner or waiter. The NQEA contains the full enqueue name if it was too large to display fully.
TranId
The transaction identifier of the enqueue owner or waiter. If the enqueue is owned by a shunted UOW, this field contains '----'.
TranNum
The task number of the enqueue owner or waiter. If the enqueue is owned by a shunted UOW, this field contains '-----'.
Local Uowid
The local UOW identifier of the enqueue owner or waiter.
Uow Lifetime
For an enqueue owner, the number of times the enqueue is owned with UOW lifetime. For an enqueue waiter, whether the waiter has requested the enqueue for the lifetime of the UOW.
Tsk Lifetime
For an enqueue owner, the number of times the enqueue is owned with task lifetime. For an enqueue waiter, whether the waiter has requested the enqueue for the lifetime of the task.
Hash Indx
An index into the pool’s internal hash table.

EXEC CICS ENQ waits

These are a particular type of enqueue wait. They occur when an application issues an EXEC CICS ENQ command to acquire an enqueue on a resource, and another task already holds an enqueue on it.

A resource name of EXECADDR indicates that the LENGTH option of the EXEC CICS ENQ command was omitted--that is, the RESOURCE option supplied the address of the resource to be enqueued upon.

A resource name of EXECSTRN indicates that the LENGTH option of the EXEC CICS region ENQ command was specified--that is, the RESOURCE option supplied the name of the resource to be enqueued upon. (For detailed information about the EXEC CICS ENQ command, see CICS Application Programming Reference.)

A resource name of EXECPLEX indicates that the LENGTH option of the EXEC CICS sysplex ENQ command was specified--that is, the RESOURCE option supplied the name of the resource to be enqueued upon. (For detailed information about the EXEC CICS ENQ command, see CICS Application Programming Reference.)

You can use the CEMT INQUIRE UOWENQ command to discover the owner of the enqueue that the suspended task is waiting on providing the owner is on the same region. This cannot detect owners on other regions. Note that, for EXECADDR-type waits, to display the address of the resource specified on the EXEC CICS ENQ command you need to use the hexadecimal display option of CEMT.

Related tasks
Formatting system dumps
Related references
The system dump table
[[ Contents Previous Page | Next Page Index ]]