INQUIRE UOWENQ
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.
Conditions: END, ILLOGIC, NOTAUTH, UOWNOTFOUND
For more information about the use of CVDAs, see CICS-value data areas (CVDAs).
Description
The INQUIRE UOWENQ command is for use only in browse mode and retrieves information about enqueues. CICS uses enqueues 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.
- Supply a value for UOW on the START command to return only the enqueues held or waited on by the specified UOW.
- Supply a value for RESOURCE on the START command to return only information about UOWs owning or waiting on the specified enqueue.
- Supply a value for ENQSCOPE on the START command to return only enqueues with the specified enqscope. If ENQSCOPE is specified as blanks, only local enqueues are returned.
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 analyze 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 indoubt failure, user ENQs are released while CICS enqueues are usually converted to the retained state until the indoubt 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.
Browsing
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 before 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).
- If there are many enqueues in the system, CICS may take a long time to process a browse. If this happens, consider increasing the runaway interval of tasks that perform browses. (Do this by increasing the value of the RUNAWAY attribute on the associated TRANSACTION definition).
- Both UOW-lifetime and task-lifetime enqueues are returned by INQUIRE UOWENQ. (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.
Options
- DURATION(data-area)
- Returns, as a fullword value binary value, the elapsed time in seconds since the enqueue entered its current state of owner, waiter or retained.
- ENQFAILS(data-area)
- Returns,
for retained enqueues, the number of failed enqueue attempts for this
resource after the enqueue was last acquired. This indicates how many
UOWs have received a LOCKED response because this enqueue was held
in retained state. For active enqueues, ENQFAILS Returns zero.
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.
- ENQSCOPE(data-area)
- If
the enqueue has sysplex scope, ENQSCOPE Returns the 4-character name
which was used to qualify the sysplex-wide ENQUEUE request issued
by this CICS region. If it has region scope, ENQSCOPE Returns blanks.
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.
- NETUOWID(data-area)
- Returns the 1- through 27-character network-wide LU6.2 ID of the UOW that owns or is waiting for the enqueue for which data is being returned.
- QUALIFIER(data-area)
- Returns a 0- through 255-character optional qualifier that further identifies the resource associated with the enqueue. The data (if any) returned in this field depends on the TYPE of the enqueue, as summarized in Table 1.
- QUALLEN(data-area)
- Returns a halfword binary value indicating the length of the data, in the range 0 through 255, returned in the QUALIFIER field. If no QUALIFIER data is applicable to the resource (that is, for EXECQENQ, EXECENQADDR, and TSQUEUE), a value of zero is returned.
- RELATION(cvda)
- Returns
a CVDA value indicating whether the data being returned is associated
with the owner of the enqueue or with a task waiting for the enqueue.
CVDA values are:
- OWNER
- The UOW, NETUOWID, TASKID, and TRANSID are those of the owner of the enqueue.
- WAITER
- The UOW, NETUOWID, TASKID, and TRANSID are those of a waiter for the enqueue.
- RESLEN(data-area)
- Returns
a halfword binary value indicating the length of the data, in the
range 1 through 255, returned in the RESOURCE field.
If RESOURCE is used as input on a START command, a RESLEN input is also required.
- RESOURCE(data-area)
- Returns
the 1- through 255-character name of the resource associated with
the enqueue lock. The data returned in this field depends on the TYPE
of the enqueue, as summarized in Table 1.
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.
- STATE(cvda)
- Returns
a CVDA value indicating the state that the enqueue being returned
is held in. It is returned on the INQUIRE UOWENQ NEXT command. CVDA
values are:
- 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(data-area)
- Returns a 4-byte packed-decimal value giving the number of the task associated with the UOW. If the UOW is shunted, this is the task number associated with the UOW before it was shunted.
- TRANSID(data-area)
- Returns the 1- through 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(cvda)
- Returns
a CVDA value identifying the type of resource being enqueued upon.
CVDA values are:
- DATASET
- The resource is a record in a VSAM data set opened in non-RLS mode (or a CICS-maintained data table). RESOURCE contains the name of the data set, and QUALIFIER contains the record identifier. Note that CICS does not hold enqueues on non-RLS data sets opened in RLS mode; in this case VSAM does the locking.
- EXECENQ
- The resource is associated with an EXEC CICS ENQ request. RESOURCE contains the enqueue argument passed on the request.
- EXECENQADDR
- 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)
- 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 then the record identifier is prefixed by the BDAM block identifier. Note that truncation occurs if this combination exceeds 255 characters.
- TDQUEUE
- The resource is a logically-recoverable transient data queue.
RESOURCE contains the name of the queue. QUALIFIER contains either
the string
FROMQ
orTOQ
, indicating whether an input or output lock is held for that queue.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 TDQUEUE definition attributes.
A READQ TD request acquires the
FROMQ
lock, whereas a WRITEQ TD request acquires theTOQ
lock associated with the queue. A DELETEQ TD request acquires both theTOQ
and theFROMQ
locks. - TSQUEUE
- The resource is a recoverable temporary storage queue. RESOURCE
contains the name of the queue.
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 indoubt 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 1.
Table 1. Data returned in RESOURCE and QUALIFIER 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 - UOW(data-area)
- Returns
the 16-byte local identifier of the UOW that owns or is waiting
for the enqueue for which data is being returned. The last eight bytes
are always null (X'00').
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.
Conditions
- END
- RESP2 values:
- 2
- All enqueues have been retrieved.
- ILLOGIC
- RESP2 values:
- 1
- For INQUIRE UOWENQ START, means that a browse of this resource type is already in progress. For INQUIRE UOWENQ NEXT and INQUIRE UOWENQ END, means that an INQUIRE UOWENQ START command has not been issued.
- NOTAUTH
- RESP2 values:
- 100
- The use of this command is not authorized.
- UOWNOTFOUND
- RESP2 values:
- 1
- The named UOW cannot be found.