CEMT INQUIRE IPCONN

Description

An IPCONN (IPIC connection) is a TCP/IP communication link from your local CICS region to another CICS region, or another system. See CEMT INQUIRE CONNECTION for information about MRO and ISC over SNA connections.

You can reset the options either by typing the SET command or by overtyping at the appropriate place on the INQUIRE screen.

If you want to install a new IPCONN definition when one is already installed, you must set the connection OUTSERVICE before using the CEDA INSTALL command for your new definition.

For information about the different kinds of intercommunication connections, see Intercommunication methods.

The resource signature

You can use this command to display 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 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.

Displayed fields

APPLID(value)

Displays the name by which the remote system is known to the network, taken from the APPLID option of the IPCONN definition. This value 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.

When HA is set to YES, this is the name of the HA cluster.

CERTIFICATE(value)

Displays 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(value)

Displays a value that identifies the agent that made the last change to the resource definition. You cannot use CEMT to filter on some of these values because they are duplicated. 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(value)

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

CHANGETIME(date time)

Displays the date and time when the resource definition was last changed. The format of the date depends on the value that you selected for the DATFORM system initialization parameter for your CICS region. The format of the time is hh:mm:ss.

CHANGEUSRID(value)

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

CIPHERS(value)

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.

CONNSTATUS(value)

Indicates the state of the IPCONN between CICS and the remote system. The possible values are as follows:

ACQUIRED

The IPCONN is acquired. The criterion for ACQUIRED is that the capabilities exchange is complete.

FREEING

The IPCONN is being released.

OBTAINING

The IPCONN is being acquired. The IPCONN remains in the OBTAINING state until the criterion for ACQUIRED has been met.

RELEASED

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

Any of the following general conditions can cause the RELEASED status:

• 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(value)

Displays the source of the resource definition. The DEFINESOURCE value depends on the CHANGEAGENT option. For details, see Summary of the resource signature field values.

DEFINETIME(date time)

Displays the date and time when the resource was created. The format of the date depends on the value that you selected for the DATFORM system initialization parameter for your CICS region. The format of the time is hh:mm:ss.

HA(value)

Displays whether the IPCONN can connect to a high-availability cluster end point or not. The possible values are as follows:

NOTREQUIRED

Not for connecting to an HA cluster of regions.

REQUIRED

Connect to a region within an HA cluster.

HOST(value)

Displays the host name, IPv4, or IPv6 address of the remote system. All IPv4 addresses are displayed as native IPv4 dotted decimal addresses, for example, 1.2.3.4, regardless of which type of address format is used. For information about accepted IPv4 formats, see IP addresses.

HOSTTYPE(value)

Displays the address format of the HOST option. The HOSTTYPE option is available using an expanded query only. The possible values are as follows:

HOSTNAME

The HOST option contains a host name.

IPV4HOST

The address is an IPv4 address.

IPV6HOST

The address is an IPv6 address.

IDPROP(value)

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

The possible 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(value)

Displays a value that identifies the agent that installed the resource. You cannot use CEMT to filter on some of these values because they are duplicated. 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(date time)

Displays the date and time when the resource was installed. The format of the date depends on the value that you selected for the DATFORM system initialization parameter for your CICS region. The format of the time is hh:mm:ss.

INSTALLUSRID(value)

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

IPFAMILY(value)

Displays the address format of the IPRESOLVED option. The IPFAMILY option is available using an expanded query only. Filtering interacts with the IPFAMILY option when you filter using wildcard characters. For example, if the value in IPFAMILY is IPv6FAMILY, you must use the colon character to retrieve an IP address. The possible values are as follows:

IPV4FAMILY

The address is an IPv4 address.

IPV6FAMILY

The address is an IPv6 address.

UNKNOWN

IPRESOLVED is not yet in use, or the address cannot be resolved.

IPRESOLVED(value)

Displays the IPv4 or IPv6 address of the host. The IPRESOLVED option is available using an expanded query only.

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

LINKAUTH(value)

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

MAXQTIME(value)

Displays 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(value)

Indicates the minimum lifetime of the mirror task for function-shipped file control, transient data, and temporary storage requests received by this region. This parameter only takes affect when it is specified on the IPCONN definition on the resource-owning region. It is not valid for function shipping interval control or link requests. The possible values are as follows:

REQUEST

The mirror task terminates as soon as possible.

TASK

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

UOW

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

NETWORKID(value)

Displays 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 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 value is used in combination with the APPLID value to ensure unique naming for connecting systems.

PARTNER(value)

Displays a 64-character string 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(value)

Displays whether pending units of work exist for this IPIC connection. The possible 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 is a CICS-to-CICS IPIC connection, 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(value)

Displays the port number to be used for outbound requests on this connection; that is, the number of the port on which the remote system will be listening. This value might be set to NOTAPPLIC if the connection is never used for outbound traffic, as is usually the case for autoinstalled IPCONN resources.

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

QUEUELIMIT(value)

Displays the maximum number of allocate requests that can be queued for this 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(value)

Displays the number of RECEIVE sessions defined for this connection.

RECOVSTATUS(value)

Indicates whether resynchronization work is outstanding for the IPIC connection. The IPIC connection might never have been connected, it might have been quiesced and all resynchronization work completed, or it might have been disrupted without quiesce, in which case resynchronization might be necessary. The possible values are as follows:

NORECOVDATA

Neither side has recovery information outstanding.

NRS

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

RECOVDATA

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

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

SECURITYNAME(value)

Displays the security name of the remote system.

In a CICS system with security initialized (SEC=YES), 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.

SENDCOUNT(value)

Displays the number of SEND sessions defined for this IPIC connection.

SERVSTATUS(value)

Indicates whether data can be sent and received on the IPIC connection. The possible values are as follows:

INSERVICE

Data can be sent and received.

OUTSERVICE

Data cannot be sent or received.

SSLTYPE(value)

Displays the level of secure sockets support that is being used for this service.

NOSSL

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

SSL

The Secure Sockets Layer is being used for this service.

TCPIPSERVICE(value)

Displays the name of a PROTOCOL(IPIC) TCPIPSERVICE definition that defines the attributes of the inbound processing for this IPIC connection.

USERAUTH(value)

Indicates how the user ID for attach-time user security is established in a CICS system with security initialized (SEC=YES). The possible values are as follows:

DEFAULTUSER

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

IDENTIFY

Incoming attach requests must specify a user ID but not a password.

LOCAL

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

VERIFY

Incoming attach requests must specify a user ID and password.