INQUIRE UOWLINK

Description

The INQUIRE UOWLINK command retrieves information about a connection involved in a unit of work. The connection can be to a remote system, to a task-related user exit, or to a CFDT server.

If it is to a remote system, INQUIRE UOWLINK returns the netname of the connection, its sysid, and whether it is the coordinator or subordinate. If it is to a task-related user exit, INQUIRE UOWLINK returns the exit entry name and qualifier. If it is to a CFDT server, INQUIRE UOWLINK returns the pool name.

Browsing

You can browse through all UOW links by using the browse options (START, NEXT, and END) on INQUIRE UOWLINK commands. See Browsing resource definitions for general information about browsing, including syntax, exception conditions, and examples.

The browse form of the command returns the state of all the UOW links for connections that are directly connected to the CICS® system from which the command is issued. It indicates which connections are unavailable, or have been initialized via a cold start.

The INQUIRE UOWLINK START command positions an internal pointer at the first UOW link in the CICS recovery manager table. It does not retrieve data for the first one, and it does not allow you to specify a start point.

The first time an INQUIRE UOWLINK NEXT command is used, it returns information about the first UOW link. Each time the command is used again, it retrieves the ID and STATE of the next UOW link, if one exists. You can filter the UOW-links returned by specifying a value in the UOW field.

The browse guarantees that data for each UOW link that exists before the first INQUIRE NEXT, and still exists after the last INQUIRE NEXT, is returned on exactly one INQUIRE NEXT call.

Options

BRANCHQUAL(data-area)

Returns the 64 character branch qualifier of the XA transaction ID, if present.

HOST(data-area)

For TYPE value IPIC, returns the TCP/IP hostname, or a string containing the colon hexadecimal or dotted decimal TCP/IP address, used to refer to the participant in the OTS transaction. This name is useful for identifying the participant, especially when problems occur. HOST is a 255-character data area. Strings of fewer than 255 characters are padded with blanks.

For other TYPE values, HOST returns blanks.

LINK(data-area)

The value returned depends on the TYPE of connection that is returned:

RMI

The entry name of the task-related user exit.

CFTABLE

The 8-character name of the coupling facility data table pool.

IPCONN

The 8-character APPLID of the remote system.

JVMSERVER

The name of the JVMSERVER that initiated the transaction to which this UOWLINK relates.

NETUOWID(data-area)

Returns the 1-27 character network-wide LU6.2 ID of the UOW for which data is returned.

PORT(data-area)

For TYPE value IPIC, returns the TCP/IP port number that the partner system was listening on when the connection was acquired. Port is a number in the range 1 to 65535 and will be zero for other TYPE values.

PROTOCOL(cvda)

Returns a CVDA value indicating the communication protocol used by the connection. CVDA values are as follows:

APPC

Advanced Program to Program Communication.

IRC

Interregion Communication. This connection is an MRO connection.

LU61

LUTYPE 6.1.

IPIC

IP interconnectivity. This type of connection is made using an IPCONN resource.

NOTAPPLIC

This connection is of type CFTABLE or RMI.

OTS

An OTS link that contains the global transaction identifier (GTRID) of the XID for JTA.

RRMS

The UOW is coordinated by RRS/MVS.

RESYNCSTATUS(cvda)

Returns a CVDA value indicating the resynchronization status of the connection. CVDA values are as follows:

COLD

A cold start of the connection has been performed by the partner system. The partner can no longer coordinate any indoubt conditions for this system; nor can this system pass to the partner any decisions remembered for it.

NOTAPPLIC

The connection was not created using recovery protocols. It might be an RMI, an APPC single-session, an APPC sync level 1 connection, an IPCONN, or a CFDT server.

OK

The connection is operating normally. If the partner system has failed, the partner has been restarted and the connection is able to resynchronize the associated UOW.

STARTING

The connection is being acquired, but the exchange lognames process has not yet completed.

UNAVAILABLE

The connection is not currently acquired.

UNCONNECTED

No associated connection.

RMIQFY(data-area)

Returns, for a TYPE value of RMI, the 8-character entry qualifier of the task-related user exit. For a TYPE of CONNECTION, IPCONN, CFTABLE or RMIQFY, returns blanks.

ROLE(cvda)

Returns a CVDA value indicating the role of the connection. CVDA values are:

COORDINATOR

This connection is to the sync point coordinator for the UOW.

SUBORDINATE

This connection is to a sync point subordinate for the UOW.

UNKNOWN

The sync point role of this connection cannot be determined.

SYSID(data area)

Returns, for a TYPE value of CONNECTION, the 4-character SYSID of the connection. If the connection has been discarded, or the type is RMS, CFTABLE, or IPCONN, or the PROTOCOL option returns RRMS, SYSID returns blanks.

TYPE(cvda)

Returns a CVDA value indicating the type of connection. CVDA values are as follows:

CFTABLE

A connection to a CFDT server.

CONNECTION

A connection defined in a CONNECTION resource definition.

IPCONN

A connection defined in an IPCONN resource definition.

JVMSERVER

A connection to a Liberty JVM server.

RMI

A connection to an external resource manager using the resource manager interface (RMI).

UOW(data-area)

Returns the 16-byte local identifier of the UOW for which link data is being returned. The last eight bytes are always null (X'00').

UOWLINK(data-area)

Specifies a 4-byte token identifying the UOW-link for which data is to be returned.

URID(data-area)

If the PROTOCOL field returns RRMS, this option returns the 32-byte hexadecimal representation of the RRMS unit of recovery identifier. For other values of PROTOCOL, including OTS, URID returns blanks.

XID(data-area)

Returns the 64-character global transaction identifier of the XA transaction ID, if present.

Conditions

END

RESP2 values:

2

All authorized resource definitions have been retrieved.

ILLOGIC

RESP2 values:

1

For INQUIRE UOWLINK START, means that a browse of this resource type is already in progress. For INQUIRE UOWLINK NEXT and INQUIRE UOWLINK END, means that an INQUIRE UOWLINK START command has not been issued.

NOTAUTH

RESP2 values:

100

The use of this command is not authorized.

UOWLNOTFOUND

RESP2 values:

1

The named UOW-link cannot be found.

UOWNOTFOUND

RESP2 values:

1

The named UOW cannot be found.