CEMT INQUIRE UOWENQ
Retrieve information about enqueues held or waited on by a unit of work (UOW), or about UOWs holding or waiting on a specified enqueue.
In the CICS Explorer, the Unit of work enqueues operations view provides a functional equivalent to this command.
Description
The INQUIRE UOWENQ command returns information about the enqueues held by a UOW. Enqueues are used by CICS® to lock recoverable resources such as file records or queues to the UOW that is updating them. User enqueues obtained by the EXEC CICS ENQ command are also returned.
You can use the INQUIRE UOWENQ command to indicate which records and queues would be affected if the UOW were forced.
The transaction also returns information about UOWs that are waiting on the enqueues. You can use this to diagnose enqueue deadlocks between tasks that want to update the same resources.
Enqueues
are typically held in active state, which means that other tasks are
allowed to wait for the enqueue. However, if the UOW that owns the
enqueue suffers an indoubt failure, the enqueue is usually converted
to the retained state until the indoubt failure can be resolved. The INQUIRE
UOWENQ command also retrieves information about these enqueues
and can be used to identify which records and queues would be affected
if the UOW were forced.
Note:
- Both UOW-lifetime and task-lifetime enqueues are returned by the INQUIRE UOWENQ command. (For an explanation of UOW- and task-lifetime enqueues, see the MAXLIFETIME option of the EXEC CICS ENQ command.)
- On an indoubt failure, user enqueues are released, unless the EXEC CICS ENQ command specified MAXLIFETIME(TASK) and it is not the end-of-task syncpoint that suffers the failure.
Input
Press the Clear key to clear the screen.
You can start this transaction in two ways:
- Type
CEMT INQUIRE UOWENQ(or suitable abbreviations for the keywords). The resulting display lists all enqueues for all the current UOWs. - Type
CEMT INQUIRE UOWENQ(or suitable abbreviations for the keywords), followed by the attributes that are necessary to limit the range of information that you require. For example, if you entercemt i uowe d, the resulting display shows the details only of enqueues on records in VSAM data sets open in non-RLS mode or CICS-maintained data tables.
Sample screen
INQ UOWE
STATUS: RESULTS
Uow(AC143001D4A72601) Tra(CECI) Tas(0000038) Act Exe Own
Res(ACCOUNTS.DBASE1 ) Rle(015) Enq(00000000)
Uow(AC143001D4A72601) Tra(CECI) Tas(0000038) Act Add Own
Res(g... ) Rle(004) Enq(00000000)
Note: When a value does not apply, or is negative (the value
begins with No), the fields on the screen are blank. To modify these
fields, locate them by tabbing (they appear in the same sequence as
in the expanded format), and overtype with input valid for that field.
You might find it more convenient to use the expanded format when
setting one of these values.
If you place the cursor against a specific entry in the list and press ENTER, CICS displays an expanded format, as shown in Figure 2.
INQ UOWE
RESULT
Uowenq
Uow(AC143001D4A72601)
Transid(CECI)
Taskid(0000038)
State(Active)
Type(Execenq)
Relation(Owner)
Resource(ACCOUNTS.DBASE1)
Rlen(015)
Enqfails(00000000)
Netuowid(..GBIBMIYA.IYA2T5C2...Mx...)
Qualifier()
Qlen(000)
Displayed fields
- DURATION(value)
- Displays the elapsed time (in seconds) since the enqueue entered its current state of OWNER, WAITER, or RETAINED.
- ENQFAILS (value)
- Displays,
for enqueues held in retained state, the number of failed enqueue
attempts for this resource since the enqueue was last acquired. This
indicates how many UOWs have received LOCKED responses due to this
enqueue. The ENQFAILS option helps you identify which UOWs are causing
bottlenecks.
For enqueues held in action state, ENQFAILS displays zero.
- ENQSCOPE (value)
- If
the enqueue has sysplex scope, ENQSCOPE displays the 4-character name
that was used to qualify the sysplex-wide ENQUEUE request issued by
this CICS region. If it has
region scope, ENQSCOPE displays blanks.
All CICS systems with the same ENQSCOPE value share the same sysplex Enqueue namespace.
- NETUOWID(value)
- Displays
a 27-character string that contains the network-wide LU6.2 name of
the UOW that owns, or is waiting for, the enqueue. Note: Nondisplayable characters appear as periods. You can use PF2 on the expanded panel: to see the value in hexadecimal.
- QLEN (value)
- Displays the length of the data, in the range 0 through 255, displayed in the QUALIFIER field.
- QUALIFIER (value)
- Displays a 1- through 255-character qualifier (for example, record id) that further identifies the resource associated with the enqueue lock. The data displayed depends on the type of enqueue, as shown in Table 1. If no QUALIFIER data applies (that is for EXECENQ, ADDREXECENQ, or TSQ), a value of zero is displayed.
- RELATION
- Displays
whether the data is associated with the owner of the enqueue or with
a task waiting for the enqueue. The values are as follows:
- OWNER
- The (value), NETUOWID, TASKID, and TRANSID are those of the owner of the enqueue.
- WAITER
- The (value), NETUOWID, TASKID, and TRANSID are those of a waiter for the enqueue.
- RESOURCE (value)
- Displays
a 1- through 255-character string that contains the name of the resource
associated with the enqueue lock. The data displayed depends on the
type of enqueue, as shown in Table 1.
Note: Nondisplayable characters appear as periods. You can use PF2 on the expanded panel: to see the value in hexadecimal.
- RLEN (value)
- Displays the length of the data, in the range 0 through 255, displayed in the RESOURCE field.
- STATE
- Displays
the state that the enqueue is held in. The values are as follows:
- ACTIVE
- The enqueue is held in active state.
- RETAINED
- The enqueue is held in retained state. Its owning UOW has been shunted, or is in the process of being shunted.
- TASKID (value)
- Displays the number of the task associated with the UOW. If the UOW is shunted, it is the task number associated with the UOW before it was shunted.
- TRANSID (value)
- Displays the 4-character identifier of the transaction associated with the UOW. If the UOW is shunted, it is the identifier of the transaction associated with the UOW before it was shunted.
- TYPE
- Displays
the type of resource being enqueued upon. The values are as follows:
- DATASET
- The resource is a record in a VSAM data set (or a CICS-maintained data table). RESOURCE contains the name of the data set and QUALIFIER contains the record identifier.
- FILE
- The
resource is a record in either a BDAM file or a user-maintained data
table. RESOURCE contains the name of the file and QUALIFIER contains
the record identifier.
When the file is a BDAM file, the record identifier is prefixed by the BDAM block identifier. If this combination exceeds 255 characters, truncation occurs.
- EXECENQ
- The resource is associated with an EXEC CICS ENQ request. RESOURCE contains the enqueue argument passed on the request.
- ADDREXECENQ
- The resource is associated with an EXEC CICS ENQ request. RESOURCE contains the address enqueue argument passed on the request (that is, the LENGTH parameter was omitted on the request).
- TDQ
- The
resource is a logically-recoverable transient data queue. RESOURCE
contains the name of the queue. QUALIFIER contains either the string
FROMQ or TOQ, indicating whether a read or write lock is held for
the queue.
A READQ TD request acquires the FROMQ lock, whereas a WRITEQ TD request acquires the TOQ lock associated with the queue. A DELETEQ TD request acquires both the TOQ and the FROMQ locks.
- TSQ
- The resource is a recoverable temporary storage queue. RESOURCE contains the name of the queue.
The data displayed in the RESOURCE and QUALIFIER fields depends on the resource type, as shown in Table 1.
Table 1. Data displayed in RESOURCE and QUALIFIER Type Resource Qualifier DATASET Data set name Record identifier EXECENQ EXEC enqueue argument None ADDREXECENQ Address of EXEC enqueue argument None FILE File name Record identifier TDQ TD queue name FROMQ or TOQ TSQ TS queue name None - UOW(value)
- Displays the 16-character local identifier of the associated unit of work.