INQUIRE CONNECTION

Description

The INQUIRE CONNECTION command retrieves information about a connection from your local CICS® region to another CICS region or another system.

Browsing

The resource signature

You can use this command to retrieve the resource signature fields. You can use these fields to manage resources by capturing details of when the resource was defined, installed, and last changed. For more information, see Auditing resources. The resource signature fields are BUNDLE, CHANGEAGENT, CHANGEAGREL, CHANGETIME, CHANGEUSRID, DEFINESOURCE, DEFINETIME, INSTALLAGENT, INSTALLTIME, and INSTALLUSRID. See Summary of the resource signature field values for detailed information about the content of the resource signature fields.

Options

ACCESSMETHOD(cvda)

Returns a CVDA value indicating the type of connection between the local system and the one about which you are inquiring. CVDA values are as follows:

INDIRECT

Communication between the local CICS system and the system defined by this connection is through the system named in the INDSYS operand of the CONNECTION definition.

IRC

The connection is used for multiregion operation (MRO) and has been defined to use DFHIRP for communication. If the CONNSTATUS is ACQUIRED, the MRO partner is running on the same MVS™ image. If the CONNSTATUS is RELEASED, the MRO partner might not be on the same MVS image; if it is not, the XCF access method is used when the connection becomes ACQUIRED.

VTAM® (now z/OS® Communications Server)

The connection is used for intersystem communication (ISC).

XCF

The connection is used for multiregion operation (MRO), and communication uses the cross-system coupling facility (XCF) of z/OS. XCF is used for MRO links between CICS regions on different MVS images in a z/OS sysplex. It is selected dynamically by CICS for such links when the access method is defined as IRC or XM in the CONNECTION definition.

XM

The connection is used for multiregion operation (MRO) and has been defined to use MVS cross-memory (XM) services for communication. If the CONNSTATUS is ACQUIRED, the MRO partner is running on the same MVS image. If the CONNSTATUS is RELEASED, the MRO partner might not be on the same MVS image; if it is not, the XCF access method is used when the connection becomes ACQUIRED.

ACQSTATUS(cvda) (APPC only)

Returns the same value as the CONNSTATUS option and is retained only for compatibility purposes. Use CONNSTATUS in new applications.

AUTOCONNECT(cvda) (z/OS Communications Server only)

Returns a CVDA value identifying which AUTOCONNECT option has been specified in the CONNECTION definition. For parallel APPC connections (those with SINGLESESS(NO) specified), the AUTOCONNECT operand controls the binding of the LU services manager sessions whenever communication with z/OS Communications Server is started. For single-session APPC connections and for LUTYPE6.1 connections, the AUTOCONNECT operand on the CONNECTION definition is ignored and the value returned is not meaningful. CVDA values are as follows:

ALLCONN

AUTOCONNECT(ALL) has been specified on the CONNECTION definition. This specification is the same as specifying AUTOCONNECT(YES), but it can be used for consistency with the associated SESSIONS definition, which allows AUTOCONNECT(ALL).

AUTOCONN

AUTOCONNECT(YES) has been specified on the CONNECTION definition. CICS will try to bind the LU services manager sessions.

NONAUTOCONN

AUTOCONNECT(NO) has been specified for the CONNECTION definition. CICS does not bind LU services manager sessions.

CHANGEAGENT(cvda)

Returns a CVDA value that identifies the agent that made the last change to the resource definition. The possible values are as follows:

AUTOINSTALL

The resource was autoinstalled.

CREATESPI

The resource definition was last changed by an EXEC CICS CREATE command.

CSDAPI

The resource definition was last changed by a CEDA transaction or the programmable interface to DFHEDAP.

CSDBATCH

The resource definition was last changed by a DFHCSDUP job.

DREPAPI

The resource definition was last changed by a CICSPlex SM BAS API command.

CHANGEAGREL(data-area)

Returns a 4-digit number of the CICS release that was running when the resource definition was last changed.

CHANGETIME(data-area)

Returns an ABSTIME value that represents the time stamp when the resource definition was last changed. For more information about the format of the ABSTIME value, see FORMATTIME.

CHANGEUSRID(data-area)

Returns the 8-character user ID that ran the change agent.

CONNECTION(data-value)

Specifies the 4-character identifier of the remote system or region about which you are inquiring; that is, the name assigned to its CONNECTION definition.

CONNSTATUS(cvda) (APPC and MRO only)

Returns a CVDA value identifying the state of the connection between CICS and the remote system. The remote system can be an APPC partner or a CICS MRO partner; CONNSTATUS is not applicable to EXCI or LU6.1 connections. The ACQUIRED and RELEASED CVDA values are common to both APPC and MRO; the others are unique to APPC. CVDA values are as follows:

ACQUIRED

The connection is acquired. These criteria apply to ACQUIRED for z/OS Communications Server links:

• The partner LU has been contacted.
• The initial CHANGE-NUMBER-OF-SESSIONS (CNOS) exchange has been done.

These criteria apply to ACQUIRED for MRO links:

• Both sides of the link are in service.
• Both sides of the link are successfully logged on to DFHIRP.
• A connection request by each side has been successful for at least one session, and therefore each side can send and receive data.

AVAILABLE (APPC only)

The connection is acquired but no sessions are currently bound because they were unbound for limited resource reasons.

FREEING (APPC only)

The connection is being released.

NOTAPPLIC

The connection is not a CICS-to-CICS MRO connection or an APPC connection.

OBTAINING (APPC only)

The connection is being acquired. The connection remains in the OBTAINING state until all the criteria for ACQUIRED have been met.

RELEASED

The connection is RELEASED. Although it might also be in INSERVICE status, it is not usable.

The RELEASED status can be caused by any one of a number of general conditions:

• The remote system has not yet initialized.
• No CONNECTION definition exists on the remote system.
• The connection on the remote system has been set out of service.

In the case of a CICS-to-CICS MRO connection, the RELEASED status might also be because of these reasons:

• The remote CICS region has not yet logged on to DFHIRP.
• The remote CICS region has closed interregion communication.

In the case of an APPC ISC connection, the RELEASED status might also be because of these reasons:

• The remote CICS region has not yet opened its z/OS Communications Server ACB.
• AUTOCONNECT(NO) has been specified on the CONNECTION or SESSIONS definition.

CONNTYPE(cvda) (EXCI only)

Returns a CVDA value identifying the type of external CICS interface (EXCI) sessions, or pipes, defined for this connection. This option applies only to EXCI connections. CVDA values are as follows:

GENERIC

The connection is generic. A GENERIC connection is an MRO link with many sessions to be shared by multiple users.

NOTAPPLIC

The connection is not an EXCI connection.

SPECIFIC

The connection is specific. A SPECIFIC connection is an MRO link with one or more sessions dedicated to a single user.

See Inquiring on the state of EXCI connections for more information about EXCI connections.

CQP(cvda)

Returns a CVDA indicating the status of the connection quiesce protocol for the connection. The CVDA values are as follows:

COMPLETE

The quiesce protocol completed successfully when the connection was released. This value reverts to UNATTEMPTED if the connection is reacquired.

FAILED

The protocol failed for one of several reasons, such as a session failure during execution of the protocol or because the partner receiving the CQP flow has outstanding work.

UNATTEMPTED

The connection supports the protocol, but it has not yet been invoked because the connection status is ACQUIRED.

NOTSUPPORTED

The connection does not support the quiesce protocol because, for example, the partner is a back-level CICS region that does not support the connection quiesce protocol.

DEFINESOURCE(data-area)

Returns the 8-character source of the resource definition. The DEFINESOURCE value depends on the CHANGEAGENT value. For more information, see Summary of the resource signature field values.

DEFINETIME(data-area)

Returns an ABSTIME value that represents the time stamp when the resource definition was created.

EXITTRACING(cvda) (z/OS Communications Server only)

Returns a CVDA value indicating whether the terminal exit program is tracing the sessions associated with this connection. CVDA values are as follows:

EXITTRACE

Tracing is on.

NOEXITTRACE

Tracing is off.

NOTAPPLIC

The connection is not LU6.1 or APPC.

GRNAME(data-area)

Returns, for an APPC connection to a generic resource when this system is also a generic resource, the 8-character generic resource name of the connected LU. Otherwise, it returns blanks. CICS assumes that the partner is a generic resource if the two NETNAMEs sent with a BIND are different. This information can also be returned for a partner that is not a generic resource but uses XRF.

INSTALLAGENT(cvda)

Returns a CVDA value that identifies the agent that installed the resource. The possible values are as follows:

AUTOINSTALL

The resource was autoinstalled.

CREATESPI

The resource was installed by an EXEC CICS CREATE command.

CSDAPI

The resource was installed by a CEDA transaction or the programmable interface to DFHEDAP.

GRPLIST

The resource was installed by GRPLIST INSTALL.

INSTALLTIME(data-area)

Returns an ABSTIME value that represents the time stamp when the resource was installed.

INSTALLUSRID(data-area)

Returns the 8-character user ID that installed the resource.

LINKSYSTEM(data-area)

Returns the 4-character name of the connection that is the real link towards the TOR for a remote or indirect system entry, if it is available. It is not set if some connection definitions in the chain from the remote or indirect entry to the link system are missing.

MEMBERNAME(data-area)

Returns, for an APPC connection to a generic resource when this system is also a generic resource, the 8-character member name (APPLID) of the connected LU. Otherwise, it returns blanks. CICS assumes that the partner is a generic resource if the two NETNAMEs sent with a BIND are different. This information can also be returned for a partner that is not a generic resource but uses XRF.

NETNAME(data-area)

Returns, from the NETNAME value specified in the CONNECTION definition, the 8-character name by which the remote system is known to the network.

For an ISC connection, the NETNAME corresponds to the z/OS Communications Server APPLID of the remote system.

For a CICS-to-CICS MRO connection, the NETNAME is the name that the remote system uses to log on to DFHIRP (from the system initialization APPLID option).

For a SPECIFIC EXCI connection, NETNAME is the name of the client program that is passed on the EXCI INITIALIZE_USER command; for a GENERIC EXCI connection, NETNAME is always blanks.

For an indirect connection, NETNAME corresponds to the APPLID, as specified in the system initialization APPLID option, of the terminal-owning region.

NQNAME(data-area)

Returns the 17-character network-qualified name for any connection that received an NQNAME from z/OS Communications Server at logon time.

NQNAME, which is supported for problem determination purposes only, is returned for both autoinstalled and RDO-defined resources if it has been supplied by z/OS Communications Server. However, it is not catalogued for RDO-defined resources and is therefore not available on a restart until that resource logs on again.

If the resource is not z/OS Communications Server, NQNAME is blank. If the resource is a z/OS Communications Server resource but has not yet received an NQNAME, CICS returns the known netname.

PENDSTATUS(cvda) (APPC and MRO only)

Returns a CVDA value identifying whether there are any pending units of work for this connection. CVDA values are as follows:

NOTAPPLIC

This session is not an APPC parallel-session or a CICS-to-CICS MRO connection.

NOTPENDING

No mismatch of lognames with the partner has occurred.

Note: MRO connections to systems earlier than CICS Transaction Server for OS/390® do not use lognames. Therefore, for these connections, PENDSTATUS always returns NOTPENDING.

PENDING

Resynchronization work is outstanding for the connection, but the partner system has performed an initial start, preventing completion of the resynchronization process. (If the partner system is a CICS version earlier than CICS Transaction Server for OS/390, a cold start performed on the partner system has the same effect.) You can use the SET CONNECTION NOTPENDING command to unilaterally commit or back out the units of work associated with the connection, according to their associated transaction definitions. You can also investigate the units of work individually and force them to commit or back out, in which case you must also complete the recovery activity by using a SET CONNECTION NOTPENDING command to clear the PENDING condition.

If this connection is an APPC connection, no new sync point work (that is, work involving sync level 2 protocols) can be transmitted across it until a SET CONNECTION NOTPENDING command has been issued. This restriction does not apply to MRO connections.

If you are not concerned by the loss of synchronization caused by the initial or cold start of the partner, you can cause the SET CONNECTION NOTPENDING command to be issued automatically by specifying XLNACTION(FORCE) on the CONNECTION definition.

For further information about pending units of work, see Troubleshooting intersystem problems.

PROTOCOL(cvda) (z/OS Communications Server and EXCI only)

Returns a CVDA value identifying the protocol in use if this is a z/OS Communications Server or EXCI connection. CVDA values are as follows:

APPC

The connection uses the z/OS Communications Server LUTYPE6.2 protocol for intersystem communication.

EXCI

The connection uses the external CICS interface for communication between CICS and a non-CICS client program.

LU61

The connection uses the z/OS Communications Server LUTYPE6.1 protocol.

NOTAPPLIC

The connection is used for CICS-to-CICS MRO communication or it is INDIRECT.

RECEIVECOUNT(data-area) (MRO only)

Returns a fullword binary value giving the number of RECEIVE sessions defined for this connection. This option applies only to MRO connections; for others, the value returned is -1.

RECOVSTATUS(cvda) (APPC and MRO only)

Returns a CVDA value indicating whether resynchronization work is outstanding for the connection. The connection might never have been connected, have been quiesced and all resynchronization work completed, or disrupted without quiesce, in which case resynchronization might be necessary. CVDA values are as follows:

NORECOVDATA

Neither side has recovery information outstanding.

NOTAPPLIC

This session is not an APPC parallel-session or a CICS-to-CICS MRO connection, and it does not support 2-phase commit protocols.

NRS

CICS does not have recovery outstanding for the connection, but the partner might have.

RECOVDATA

Indoubt units of work are associated with the connection, or outstanding resyncs are awaiting FORGET on the connection. Resynchronization takes place when the connection next becomes active or when the UOW is unshunted.

If recovery is outstanding, on completion of exchange lognames either resynchronization takes place or, in the case of a cold exchange, the PENDING condition is created.

REMOTENAME(data-area)

Returns the 4-character name by which this connection is known in a remote system, if the subject of the inquiry is a remote connection.

REMOTESYSNET(data-area)

Returns the 8-character netname of the owning TOR, if the subject of this inquiry is a remote connection. If it is blank, but the connection is remote, the system named in the REMOTESYSTEM field has not been installed, and no value was specified for the REMOTESYSNET option when the connection was defined.

REMOTESYSTEM(data-area)

Returns the 4-character name of a connection, if the subject of the inquiry is a remote connection. The named connection can be either a connection entry that links towards the TOR or an indirect connection, which provides the netname of the TOR, and itself points to another connection.

Otherwise this field is blank.

SENDCOUNT(data-area) (MRO only)

Returns a fullword binary value giving the number of SEND sessions defined for this connection. For EXCI connections, the SENDCOUNT is always zero. This option applies only to MRO connections; for others, the value returned is -1.

SERVSTATUS(cvda)

Returns a CVDA value indicating whether data can be sent and received on the connection. CVDA values are as follows:

GOINGOUT

OUTSERVICE has been requested on a SET CONNECTION command, and the request cannot be acted on until some current work has completed.

INSERVICE

Data can be sent and received.

OUTSERVICE

Data cannot be sent and received.

XLNSTATUS(cvda) (APPC only)

Returns a CVDA value identifying the status of the exchange log names (XLN) process. CVDA values are as follows:

NOTAPPLIC

The XLN process is not applicable because the link is in one of these states:

• Is released
• Is MRO, LUTYPE6.1, or single-session APPC
• Does not support synchronization level 2 conversations.

For information about the APPC exchange log names process, see Troubleshooting intersystem problems.

XNOTDONE

The XLN flow for the APPC connection has not completed successfully. The CSMT log can contain information relating to this state. Synchronization level 2 conversations are not allowed on the connection, but synchronization levels 0 and 1 are still allowed.

XOK

The XLN process for the APPC connection has completed successfully.

ZCPTRACING(cvda) (z/OS Communications Server only)

Returns a CVDA value indicating whether the z/OS Communications Server control component of CICS is tracing activity on the sessions associated with this connection. CVDA values are as follows:

NOTAPPLIC

The connection is not LUTYPE6.1 or APPC.

NOZCPTRACE

ZCP tracing is not active.

ZCPTRACE

ZCP tracing is active.

Conditions

END

RESP2 values:

2

There are no more resource definitions of this type.

ILLOGIC

RESP2 values:

1

You have issued a START command when a browse of this resource type is already in progress, or you have issued a NEXT or an END command when a browse of this resource type is not in progress.

NOTAUTH

RESP2 values:

100

The user associated with the issuing task is not authorized to use this command.

SYSIDERR

RESP2 values:

1

The connection cannot be found.