INQUIRE IPCONN

Description

The INQUIRE IPCONN command retrieves information about an IPIC connection. An IPCONN resource is a Transmission Control Protocol/Internet Protocol (TCP/IP) communication link from your local CICS® region to another CICS region or another system.

Browsing

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

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

APPLID(data-area)

Returns the 8-character name by which the remote system is known to the network. This name is the application identifier (APPLID) of the remote system, as specified on the APPLID option of its system initialization parameter. For XRF systems, it is the generic APPLID.

For HA IPCONNs that are acquired, the value is the APPLID of the specific region in the high-availability cluster to which this IPCONN connected.

AUTOCONNECT(cvda)

Returns a CVDA value identifying which AUTOCONNECT option has been specified in the IPCONN definition. CVDA values are as follows:

AUTOCONN

AUTOCONNECT(YES) has been specified on the IPCONN definition.

NONAUTOCONN

AUTOCONNECT(NO) has not been specified for the IPCONN definition.

CERTIFICATE(data-area)

Returns a 32-character area containing the label of the certificate, in the key ring, that is used as a client certificate in the SSL handshake for outbound IPCONN connections. If the label is blank, the certificate nominated as the default for the key ring is used.

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.

CIPHERS(data-area)

Returns either a 56–character area that contains the list of cipher suites that is used to negotiate with clients during the SSL handshake or the name of the SSL cipher suite specification file, which is a z/OS® UNIX file in the security/ciphers subdirectory of the directory that is specified by the USSCONFIG system initialization parameter. For more information, see SSL cipher suite specification file.

If you do not specify a list, then this list is defaulted to a set of ciphers based on the ENCRYPTION system initialization parameter. See Customizing encryption negotiations.

CLIENTLOC(data-area)

Returns a 32-character area that represents an evaluation of the SO_CLUSTERCONNTYPE options returned by z/OS Communications Server, for all the sockets used by the IPIC connection. For a description of SO_CLUSTERCONNTYPE and an explanation of the bit settings, see z/OS Communications Server IP Sockets Application Programming Interface Guide and Reference. Multiple sockets might provide the IPIC connection with a number of different paths to the partner system. Each character in CLIENTLOC is displayed as either zero or one. CLIENTLOC represents the most diverse route between the CICS region and its partner system.

CONNSTATUS(cvda)

Returns a CVDA value identifying the state of the IPIC connection between CICS and the remote system. CVDA values are as follows:

ACQUIRED

The IPIC connection is acquired. The criterion for ACQUIRED is that the capabilities exchange is complete. The capabilities exchange is the way that two connected CICS regions discover the levels of service that they can collectively support; for example, the sync point level, and security protocols such as SSL.

FREEING

The IPIC connection is being released.

OBTAINING

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

RELEASED

The IPIC 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 the following conditions:

• The remote system has not yet initialized.
• No IPCONN definition exists on the remote system and autoinstall was not active or not successful.
• The IPCONN definition on the remote system has been set out of service.
• AUTOCONNECT(NO) has been specified on the IPCONN definition.
• The IPIC connection had been acquired but has since been released by an explicit operator command.

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.

HA(cvda)

Returns a CVDA value indicating whether the IPCONN can be used to connect to a high-availability cluster. CVDA values are as follows:

NOTREQUIRED

The IPCONN cannot be used to connect to a high-availability cluster.

REQUIRED

The IPCONN must connect to a region that is part of a high-availability cluster.

HOST(data-area)

Returns the 116-character host name of the remote system or its IPv4 or IPv6 address. The HOST option can be a character host name, an IPv4 address, or an IPv6 address. HOST is specified in the resource definition. HOST displays all IPv4 addresses as native IPv4 dotted decimal addresses, for example, 1.2.3.4, irrespective of which type of address format is used. You can specify IPv4 and IPv6 addresses in a number of acceptable formats. See IP addresses for more information on address formats.

HOSTTYPE(cvda)

Returns the address format of the HOST option. HOSTTYPE is set by the domain when the IPIC connection is installed. CVDA values are as follows:

HOSTNAME

The HOST option contains a character host name. The IP address that corresponds to the host name is looked up in the domain name server.

IPV4

The address is an IPv4 address.

IPV6

The address is an IPv6 address.

NOTAPPLIC

An incorrect host address was returned (HOST=0.0.0.0).

IDPROP(cvda)

Indicates whether the sender includes the distributed identity in requests over the IPIC connection. The IDPROP option is meaningful only if a connection extends outside a sysplex and is used primarily to prevent distributed identities being transmitted between enterprises. If the connection is between systems in the same sysplex, the value returned by this option is ignored, and the connection operates as if IDPROP(OPTIONAL) is specified.

CVDA values are as follows:

NOTALLOWED

A user ID associated with the sending transaction is sent for requests using this connection. NOTALLOWED is the default value.

OPTIONAL

A distributed identity is sent, if available. The user ID associated with the sending transaction is also sent.

REQUIRED

A distributed identity is required for requests using this connection. If REQUIRED is specified, the receiving system must support distributed identities. The user ID associated with the sending transaction is not sent.

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.

IPCONN(data-value)

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

IPFAMILY(cvda)

Returns the address format of the IPRESOLVED option. IPFAMILY is set only when the IPIC connection is acquired. CDVA values are as follows:

IPV4

The address is specified in IPv4 dotted decimal address format.

IPV6

The address is specified in IPv6 colon hexadecimal address format.

UNKNOWN

The IPRESOLVED option is not yet in use or the address cannot be resolved. UNKNOWN is the default when IPRESOLVED is 0.0.0.0.

IPRESOLVED(data-area)

Returns a 39-character field that specifies the IPv4 or IPv6 address of the HOST option. If the IPCONN resource has not yet been acquired or has been released, or the address cannot be resolved, a default value of 0.0.0.0 is returned. After the IPIC connection is acquired, IPRESOLVED displays the last resolved IP address that was used by the IPCONN resource. IPRESOLVED is reset to 0.0.0.0 when the resource is out of service and released. The content of IPRESOLVED is not recoverable after a warm or emergency restart.

For HA IPCONNs that are acquired, the value will be that of the specific region in the HA cluster this IPCONN connected to.

LINKAUTH(cvda)

Returns a CVDA value that specifies how the user ID for link security is established in a CICS system with security initialized (SEC=YES).

CERTUSER

TCP/IP communication with the partner system must be configured for SSL and a certificate must be received from the partner system during SSL handshake.

The IPCONN must refer to a TCPIPSERVICE that is defined with SSL(CLIENTAUTH).

The received certificate must be defined to the external security manager so that it is associated with a user ID, which is used to establish link security.

SECUSER

Specifies that the user ID specified in SECURITYNAME is used to establish link security.

This value is the default.

MAXQTIME(data-area)

Returns a fullword binary value giving the maximum time, in seconds, for which allocate requests can be queued. The value is in the range 0 - 9999, or has the standard null value of -1 if MAXQTIME(NO) is specified on the IPCONN definition.

MIRRORLIFE(cvda)

Returns the minimum lifetime of the mirror task for function-shipped file control, transient data, and temporary storage requests received by this region. CVDA values are as follows:

REQUEST

The mirror task terminates as soon as possible. This is the default value.

TASK

The mirror task remains available to the application that issues the remote request until the task of the application ends.

UOW

The mirror transaction remains available to the application that issues the remote request until the next sync point is issued.

NETWORKID(data-area)

Returns the network ID of the remote system. The value returned is an 8-byte character string, which is the value of the NETWORKID option of the IPCONN definition. If NETWORKID is not specified on the IPCONN definition, the value returned is the VTAM® NETID or, for the z/OS Communications Server VTAM=NO systems, the value of the UOWNETQL system initialization parameter of this CICS; that is, the CICS on which the IPCONN definition is installed.

The NETWORKID is used with the APPLID to ensure unique naming for connecting systems.

NUMCIPHERS(data-area)

Returns a binary halfword data area that contains the number of cipher suites that are specified in the CIPHERS attribute. If CIPHERS contains a file name, this field contains zero.

PARTNER(data-area)

Returns a 64-character field indicating the product token of the partner system. The field is blank when the connection is not acquired or if the partner system does not indicate a product type when the connection is established. For example, the partner system is IBM_CICS_Transaction_Server/4.1.0(zOS) for a CICS TS 4.1 partner.

PENDSTATUS(cvda)

Shows whether this IPIC connection has any pending units of work. CDVA values are as follows:

NOTPENDING

No mismatch of lognames has occurred with the partner.

PENDING

Resynchronization work is outstanding for the connection but the partner system has performed an initial start, preventing completion of the resynchronization process. You can use the SET IPCONN 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 IPCONN NOTPENDING command to clear the PENDING condition.

If this IPIC connection is CICS-to-CICS, no new sync point work, that is, work involving sync level 2 protocols, can be transmitted across the connection until a SET IPCONN NOTPENDING command has been issued.

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 IPCONN NOTPENDING command to be issued automatically by specifying XLNACTION(FORCE) on the IPCONN definition.

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

PORT(data-area)

Returns a fullword binary value, in the range 1 through 65535, containing the port number to be used for outbound requests on this IPIC connection; that is, the number of the port on which the remote system listens.

If the IPIC connection is defined with PORT(NO), the value is -1.

For HA IPCONNs that are acquired, the value will be that of the specific region in the HA cluster this IPCONN connected to.

QUEUELIMIT(data-area)

Returns a fullword binary value giving the maximum number of allocate requests that can be queued for this IPIC connection. The value is in the range 0 - 9999, or has the standard null value of -1 if QUEUELIMIT(NO) is specified on the IPCONN definition.

RECEIVECOUNT(data-area)

Returns a fullword binary value giving the number of RECEIVE sessions defined for this IPIC connection.

RECOVSTATUS(cvda)

Returns a CVDA value indicating whether resynchronization work is outstanding for the IPIC 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.

RECOVSTATUS is set to NORECOVDATA when the IPIC connection is installed but not yet acquired. If the value remains the same after the IPIC connection is acquired, it is due to one of the following causes:

• Resynchronization was not attempted. This is usually due to a cold start of one of the systems.
• The partner system failed to resynchronize. A DFHIS6006 message is issued.

NRS

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

RECOVSTATUS is set to NRS in all normal situations. This value indicates that there is no outstanding recoverable work and that resynchronization completed successfully. After a warm start all acquired IPIC connections in the CICS region should be showing NRS.

RECOVDATA

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

RECOVSTATUS is set to RECOVDATA when resynchronization fails on the local system. DFHIS600* messages are issued to indicate what the failure was in this case. The PENDSTATUS is also set to PENDING to indicate that there are outstanding units of work to resolve before further work can be done. RECOVDATA can also be set when a transaction has a failure during syncpoint processing. It is this situation that causes the setting to change on an already installed and acquired IPCONN. In this case you might not have to take any action. In most cases, the transaction and unit of work are automatically backed out. The condition clears when the IPIC connection is next acquired and a full resynchronization is done.

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.

SECURITYNAME(data-area)

Returns the security name of the remote system.

In a CICS system with security initialized (SEC=YES), and for an IPIC connection defined with LINKAUTH(SECUSER), the security name is used to establish the authority of the remote system.

The security name must be a valid RACF® user ID on this region. Access to protected resources on this region is based on the RACF user profile and its group membership. If the security name is not a valid RACF user ID when the IPCONN is installed, CICS uses the default user ID for the security name.

In a CICS system without security initialized (SEC=NO), or for an IPIC connection that is not defined with LINKAUTH(SECUSER), returns the value specified in the IP connection resource definition.

SENDCOUNT(data-area)

Returns a fullword binary value giving the number of SEND sessions defined for this IPIC connection.

SERVSTATUS(cvda)

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

INSERVICE

Data can be sent and received.

OUTSERVICE

Data cannot be sent or received.

SSLTYPE(cvda)

Returns a CVDA value specifying the level of secure sockets support that is being used for this service. CVDA values are as follows:

NOSSL

The Secure Sockets Layer is not being used for this service.

SSL

The Secure Sockets Layer without client authentication is being used for this service.

TCPIPSERVICE(data-area)

Returns the 8-character name of a PROTOCOL(IPIC) TCPIPSERVICE definition that defines the attributes of the inbound processing for this IPIC connection.

USERAUTH(cvda)

Returns a CVDA value that specifies the level of attach-time user security required for the connection. CVDA values are as follows:

LOCAL

CICS does not accept a user ID or password from clients. All requests will run under the link user ID.

IDENTIFY

Incoming attach requests must specify a user ID.

VERIFY

Incoming attach requests must specify a user ID and password.

DEFAULTUSER

CICS will not accept a user ID and password from the partner system. All requests run under the default user ID.

Conditions

END

RESP2 values:

2

No more resource definitions of this type exist.

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 IPIC connection cannot be found.