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.

INQUIRE UOWENQ

Conditions: END, ILLOGIC, NOTAUTH, UOWNOTFOUND

This command is threadsafe.

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.

The browse can be filtered in three ways:

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.

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 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).

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.

Notes:

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 or TOQ, 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 the TOQ lock associated with the queue. A DELETEQ TD request acquires both the TOQ and the FROMQ 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.