Retrieve information about enqueues held or waited on by a UOW, or about UOWs holding or waiting on a specified enqueue.
INQUIRE ENQ is a synonym for INQUIRE UOWENQ.
The INQUIRE UOWENQ command can be used only in browse mode.
INQUIRE UOWENQ >>-INQUIRE UOWENQ-----------------------------------------------> .---------------------------------------------. V | >----+-----------------------------------------+-+--------------> +-ENQSCOPE(data-value)--------------------+ +-RESOURCE(data-value)-RESLEN(data-value)-+ '-UOW(data-value)-------------------------' .--------------------------. V | >----+----------------------+-+-------------------------------->< +-DURATION(data-area)--+ +-ENQFAILS(data-area)--+ +-NETUOWID(data-area)--+ +-QUALIFIER(data-area)-+ +-QUALLEN(data-area)---+ +-RELATION(cvda)-------+ +-RESLEN(data-area)----+ +-RESOURCE(data-area)--+ +-STATE(cvda)----------+ +-TASKID(data-area)----+ +-TRANSID(data-area)---+ +-TYPE(cvda)-----------+ '-UOW(data-area)-------'
Conditions: END, ILLOGIC, NOTAUTH, UOWNOTFOUND
For more information about the use of CVDAs, see CICS-value data areas (CVDAs).
The INQUIRE UOWENQ command retrieves information about enqueues. 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.
The browse can be filtered in three ways:
A CICS-wide browse occurs when you do not supply a value for UOW, RESOURCE or ENQSCOPE on the INQUIRE UOWENQ START command. All enqueue owners and enqueue waiters on the local system are returned by the browse. They are returned by considering each UOW in turn. After all the enqueues owned by one UOW have been returned, those owned by the next UOW in the system are considered.
As well as returning information about the owners of the enqueues, the command also returns information about UOWs that are waiting on these enqueues. This enables you to diagnose enqueue deadlocks between tasks wanting to update the same resources. It provides a performance improvement over other methods of answering the question "Which UOW is holding the Enqueue?" when you want to analyse what the cause of a delay is.
Enqueues are typically held in active state, which means that other tasks are allowed to wait for the enqueue. However, if a UOW that owns enqueues suffers an in-doubt failure, user ENQs are released while CICS enqueues are usually converted to the retained state until the in-doubt failure can be resolved. User ENQs are not to be used to lock recoverable resources, as they are not held across a CICS failure. The INQUIRE UOWENQ command also retrieves information about retained enqueues and can be used to identify which records and queues would be affected if the UOW were forced.
INQUIRE UOWENQ only returns information about UOWs on the local system. For Enqueues with SYSPLEX SCOPE the OWNER may be on the local system with some or all of the waiters elsewhere, or the enqueue OWNER may be elsewhere in the sysplex with some or all of the waiters on the local system; In this case, only the local waiters are returned.
Using the browse options (START, NEXT, and END) on INQUIRE UOWENQ commands, you can browse through all of the enqueues held by a specific UOW, or through all the enqueues currently in your system. See Browsing resource definitions for general information about browsing, including syntax, exception conditions, and examples.
The browse returns both enqueue owners and enqueue waiters. They are returned by considering each UOW that owns an enqueue in turn. After all the enqueues owned by one UOW have been returned, those owned by the next UOW in the system are considered. Enqueue waiters are returned subsequent to the enqueue they are waiting on, but prior to the next enqueue owned by the current UOW. Note that the INQUIRE UOWENQ START does not retrieve data for the first enqueue. Also, because the enqueues are not returned in a defined order, you cannot specify a start point.
A CICS-wide browse occurs when you do not supply a value for UOW on the INQUIRE UOWENQ START command. All enqueue owners and waiters are returned by the browse. The first time an INQUIRE UOWENQ NEXT command is used, it returns the data for the first enqueue that is owned. This is returned with RELATION(OWNER). If the enqueue has any waiters, the same enqueue is returned for each of these waiters, but this time with RELATION(WAITER). The UOW, NETUOWID, TASKID, and TRANSID fields each correspond to that particular waiter. All other data should be the same as when it was returned with RELATION(OWNER). After the last waiter has been returned, the next time the command is issued it returns the next enqueue that is owned (if any).
If you supply a value for UOW on the START command, it acts as a "filter", which means that only those enqueues owned by that particular UOW are returned (with a RELATION of OWNER). If the UOW happens to be waiting for an enqueue then this too is returned (but with a RELATION of WAITER).
Note that the enqueue state is not locked for the duration of the browse, or even between consecutive INQUIRE NEXT commands. To receive a consistent view of the state, the task performing the browse should not give up control to another task while the browse is in progress. If the owner of the last enqueue returned by the browse changes between successive INQUIRE NEXT commands, the browse returns the enqueue again with its new owner and waiters.
Because the ENQFAILS option indicates how many UOWs are failing because of retained locks, you can use it to help identify which shunted UOWs are causing "bottlenecks".
All CICS systems with the same ENQSCOPE value share the same sysplex Enqueue name space.
ENQSCOPE may also be used to supply a value on the START command. This limits the INQUIRE to return only enqueues with the specified scope name. If ENQSCOPE is specified as blanks, only local enqueues are returned.
If RESOURCE is used as input on a START command, a RESLEN input is also required.
RESOURCE may also be used to supply a value on the START command. This limits the INQUIRE to return only information about UOWs owning or waiting on the specified enqueue.
When the file is a BDAM file then the record identifier is prefixed by the BDAM block identifier. Note that truncation occurs if this combination exceeds 255 characters.
Note that the definition of the WAITACTION attribute on the TDQUEUE resource definition determines what happens to TDQUEUE enqueues on an indoubt failure. For information on defining the WAITACTION attribute, see the CICS® Resource Definition Guide.
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.
Unlike other components, enqueues associated with recoverable temporary storage queues are only ever the retained kind; owned by a UOW that has been shunted as a result of an in-doubt failure. The temporary storage component uses its own mechanism for locking queues to in-flight UOWs.
The data returned in the RESOURCE and QUALIFIER fields depends on the resource TYPE, as shown in Table 4.
TYPE | RESOURCE | QUALIFIER |
---|---|---|
DATASET | Data set name | Record identifier |
EXECENQ | EXEC enqueue argument | None |
EXECENQADDR | Address of EXEC enqueue argument | None |
FILE | File name | Record identifier |
TDQUEUE | TD queue name | FROMQ or TOQ |
TSQUEUE | TS queue name | None |
The UOW field may also be used to supply a value on the START command. This limits the INQUIRE to return only the enqueues held or waited on by the specified UOW.