ENQUEUE - Documentation for BMC AMI iStrobe Web 23.01

The enqueue domain suspends a task if it requests access to a recoverable 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:

Use the CEMT INQUIRE UOWENQ command. For definitive information about CEMT INQUIRE UOWENQ, see the CICS Supplied Transactions manual.
Use the NQ section of a system dump. Some types of enqueue wait are not displayed by the CEMT INQUIRE UOWENQ command. In these cases, you can use a system dump to identify the owner of the enqueue (for an example, see "Using a system dump to resolve enqueue waits," below. The following resource names identify the enqueue waits that this applies to:

JOURNALS

KCADDR

KCSTRNG

LOGSTRMS

It is possible for an enqueue wait to be caused by a deadlock.

Using a system dump to resolve enqueue waits

The CEMT INQUIRE UOWENQ command does not return information about enqueues on some types of resources. The following table shows the resources that this applies to.

Resource name	Type of resource
JOURNALS	CICS journal names used during creation, deletion, or use of a journal entry.
KCADDR	Addresses locked internally by CICS.
KCSTRNG	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.

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 may 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 CICS Operations and Utilities Guide). The following shows an example summary for the transient data enqueue (TDNQ) 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

Important

These values were reset at 15.44.39 (the last statistics interval collection)

The following example shows a system dump, showing summary information for the TDNQ enqueue pool.

Example

==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

Important

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 A8EBC70A534BC82 1 0 13
Q002FROMQ 9 Act 053D0880 TDRD 00435 A8EBD91A579B7D2 2 0 24 Waiter : 0540BBC0 TDRD 00467 A8EBDAC692B7C10 0 1 24 Waiter : 0537CE70 TDDL 00512 A8EBDAE6FFB56F2 1 0 24
Q007FROMQ 9 Act 0540CC80 ENQY 00217 A8EBB7FE2367C44 0 1 51 Waiter : 0538F320 ENQY 00265 A8EBBF084600FC0 0 1 51 Waiter : 0518C5C0 ENQY 00322 A8EBC393B9C66D8 0 1 51
Q002TOQ 9 Ret 0520B260 ---- ----- A8EBD82AFD4CD82 1 0 53
Q009FROMQ 9 Act 0540A140 TDRD 00366 A8EBC84D3F80250 1 0 62

In the table at the bottom of the figure, 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	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: File control uses six enqueue pools for its various types of lock. Each enqueue contains the address of a control block (for example, DSNB, FCTE) in its first four bytes. If the enqueue is a record lock, this is followed by the record identifier. Depending upon the type of the data set or file, the remainder of the enqueue name could, for example, be an RRN in an RRDS, or a record key in a KSDS data set. In the summary, the remainder of the enqueue name is displayed in both hex and character formats. This takes up two summary lines instead of one.
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 recoverable 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 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 the CICS Application Programming Reference.)

A resource name of EXECSTRN 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 the 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. Note that, for EXECADDR-type waits, to display the address of the resource specified on the EXEC CICS ENQ command you will need to use the hexadecimal display option of CEMT.