INQUIRE UOW

Retrieve information about a unit of work (UOW).

INQUIRE UOW

Conditions: END, ILLOGIC, NOTAUTH, UOWNOTFOUND

For more information about the use of CVDAs, see CICS-value data areas (CVDAs).

Description

The INQUIRE UOW command retrieves information about a unit of work, or about all UOWs in a specified state. It returns the state of the UOW (for example, INDOUBT) and whether it is active, waiting, or shunted. In some cases, it returns the name of the resource that caused the UOW to be shunted, plus the transaction, user, and terminal that started it.

Important: In an intercommunication environment, a unit of work can include actions that are to be taken by two or more connected systems. Such a unit of work is known as a distributed unit of work, because the resources to be updated are distributed across more than one system. A distributed unit of work is made up of two or more local units of work, each of which represents the work to be done on one of the participating systems.

The INQUIRE UOW command always returns information about local UOWs; that is, for a distributed UOW, it returns information only about the work required on the system on which the command is issued. You can assemble information about a distributed UOW by matching the network-wide UOW identifier returned in the NETUOWID field against the network-wide identifiers of local UOWs on other systems.

For further information about local and distributed UOWs, see Troubleshooting intersystem problems.

Browsing

You can also browse through all of the UOWs currently in your system by using the browse options (START, NEXT, and END) on INQUIRE UOW commands. See Browsing resource definitions for general information about browsing, including syntax, exception conditions, and examples.

For example, if you suspect a problem with either a recoverable data set or a connection, you can use INQUIRE UOW to return information about UOWs that have been shunted because of a connection or data set failure.

Restriction: Do not issue SYNCPOINT commands during an INQUIRE UOW browse. The following sequence of commands causes an infinite loop:

EXEC CICS INQUIRE UOW START

 EXEC CICS INQUIRE UOW(data-area) NEXT

SYNCPOINT

EXEC CICS INQUIRE UOW(data-area) NEXT

SYNCPOINT

⋮EXEC CICS INQUIRE UOW END

This is because every time the SYNCPOINT command is executed, a new UOW is created. The new UOW is returned in the next INQUIRE UOW, which is followed by a SYNCPOINT, and so on.

Options

AGE(data-area)

Returns a fullword binary value giving the number of seconds since the UOW entered its current WAITSTATE.

LINK(data-area)

Returns an 8-character value that, for a WAITCAUSE value of CONNECTION, is the netname of the remote system that caused the UOW to wait or be shunted. For other WAITCAUSE values, LINK returns blanks.

NETNAME(data-area)

Returns the 8-character network name of the terminal from which the UOW was started. If the UOW was started from an ISC or MRO session, NETNAME returns the network name of the remote region. If the UOW was not started from a terminal, nor from an ISC or MRO session, NETNAME returns blanks. For OTS transactions, NETNAME returns blanks.

NETUOWID(data-area)

Returns the LU6.2 name for the UOW within this network—that is, the network-wide identifier of the UOW. This is a 27-character data-area.

You can assemble information about a distributed UOW by matching the network-wide UOW identifier against the network-wide identifiers of local UOWs on other systems.

OTSTID(data-area)

Returns the first 128 bytes of the transaction identifier (TID) of the OTS transaction which the UOW is a part. If the OTS name has fewer than 128 bytes, it is padded on the right with binary zeros.

SYSID(data-area)

Returns a 4-character value that, for a WAITCAUSE value of CONNECTION, is the sysid of the connection that caused the UOW to wait or be shunted. If the connection has been discarded, and for other WAITCAUSE values, SYSID returns blanks.

TASKID(data-area)

Returns a 4-byte packed-decimal value giving the task number originally associated with this UOW. If the UOW is shunted, the task terminates. In this case, the number may have been reused by another task.

TERMID(data-area)

Returns the 4-character ID of the terminal or session from which this UOW was started. This is the principal facility for the task. If the transaction is the mirror transaction, CSMI, it is the session. For UOWs that are part of an OTS transaction, TERMID is the session used by the request that attached the task.

TRANSID(data-area)

Returns the 4-character ID of the transaction that started this UOW.

UOW(data-area)

Specifies the 16-byte local identifier of the UOW about which you are inquiring, the last eight bytes of which are always null (X'00').

UOWSTATE(cvda)

Returns a CVDA value indicating the state of the UOW. CVDA values are as follows:

BACKOUT: This UOW is being backed out, or has failed to back out one or more of the recoverable resources involved in the UOW.
COMMIT: A decision to commit the UOW has been made, but the UOW is waiting or has been shunted. This may be because the decision has not yet been communicated to all participants in the syncpoint, or because a failure has occurred during commit processing.
FORCE: An attempt is being made to force the UOW to back out or commit, as specified on the ACTION option of the TRANSACTION resource definition.
HEURBACKOUT: The UOW has been forcibly backed out. A forced decision is taken when a UOW is unable to wait for indoubt resolution—for example, the transaction may have been defined as WAIT(NO), or backed out with a CEMT SET UOW command.
HEURCOMMIT: The UOW has been forcibly committed.
INDOUBT: This UOW is in the indoubt state.
INFLIGHT: The UOW is running normally.

USERID(data-area)

Returns the 8-character user ID for which this transaction was running.

WAITCAUSE(cvda)

Returns a CVDA value identifying the type of resource that caused the UOW to wait or be shunted.

Note: In the case of a wait, it is the UOW that is waiting, not the task.

Because each resource needs fields of the right type, WAITCAUSE also indicates which fields contain the RESOURCE NAME and QUALIFIER. CVDA values are as follows:

CONNECTION: This UOW is waiting or has been shunted because of the failure of a session to the coordinator of the UOW during the indoubt period. NETNAME and SYSID contain the netname and system name of the failed link.
DATASET: This UOW is waiting or has been shunted because of a failure associated with one or more data sets. Use the INQUIRE UOWDSNFAIL command to identify the data sets involved and the reasons why they have caused the UOW to fail.
NOTAPPLIC: The UOW is not waiting.
RLSSERVER: This UOW is waiting or has been shunted because of the failure of an RLS server.
WAITRRMS: This UOW is waiting or has been shunted because communication has been lost with RRS/MVS.
WAITCOMMIT: This UOW is waiting or has been shunted because a failure occurred during commit processing.
WAITFORGET: This UOW is waiting for FORGET from participants in the sync point. Use the INQUIRE UOWLINK command to obtain the netnames and sysids of the participants.
WAITRMI: This UOW is waiting for FORGET from the RMI. Use the INQUIRE UOWLINK command to obtain the entry name and qualifier of the task-related user exit.

WAITSTATE(cvda)

Returns a CVDA value indicating whether the UOW is currently running or waiting. CVDA values are as follows:

ACTIVE: The UOW is running normally.
SHUNTED: Sync point processing of the UOW has been deferred. A reason for this is returned in WAITCAUSE. SHUNTED further indicates that the task, terminal and program storage have been released, and locks have been retained.
WAITING: Sync point processing has completed on this system, but not on all systems involved in the distributed UOW. WAITCAUSE returns either WAITFORGET or WAITRMI, and UOWSTATE returns either BACKOUT or COMMIT to indicate how the UOW was resolved on this system.

Conditions

END

RESP2 values:

2: All authorized resource definitions have been retrieved. All data areas specified on this command are left unchanged.

ILLOGIC

RESP2 values:

1: A browse of this resource type is already in progress, or an INQUIRE UOW 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.