IPIC connections - IPCONN

In a TCP/IP network, IPIC connection (IPCONN) views display the state of currently-installed IP intercommunications connections (also known as "IPIC connections").

Supplied views

To access from the main menu, click:

CICS operations views > TCP/IP service operations views > IPIC connections

Table 1. Views in the supplied IPIC connections (IPCONN) view set
View Notes
IPIC connections

EYUSTARTIPCONN.ACQUIRE

Acquire a connection
IPIC connections

EYUSTARTIPCONN.BACKOUT

Back out all units of work that have been shunted because of the failure of this IPIC connection.
IPIC connections

EYUSTARTIPCONN.CANCEL

Cancel all automatic initiation descriptors (AIDs) queuing for the IPIC connection.
IPIC connections

EYUSTARTIPCONN.COMMIT

Commit all units of work that have been shunted because of the failure of this IP connection.
IPIC connections

EYUSTARTIPCONN.DETAIL4

Detailed information about the resource signature.
IPIC connections

EYUSTARTIPCONN.DETAILED

Detailed information about a selected IP interconnectivity (IPIC) connection.
IPIC connections

EYUSTARTIPCONN.DETAILED2

Detailed session information and allocate requests for a selected IP interconnectivity (IPIC) connection.
IPIC connections

EYUSTARTIPCONN.DETAILED3

Detailed function ship information for a selected IP interconnectivity (IPIC) connection.
IPIC connections

EYUSTARTIPCONN.DISCARD

Discard a connection from the CICS system where it is installed. The connection must be out of service before it can be discarded.
IPIC connections

EYUSTARTIPCONN.FORCE

Force all UOWs shunted because of the failure of this IPIC connection to BACKOUT or COMMIT, as specified on the ACTION option of the TRANSACTION definition.
IPIC connections

EYUSTARTIPCONN.FORCECANCEL

Cancel all AIDs, including system AIDs, queuing for the IPIC connection.
IPIC connections

EYUSTARTIPCONN.FORCEPURGE

Force transactions associated with the IP connection purged immediately.
IPIC connections

EYUSTARTIPCONN.INSERVICE

Place a connection in service.
IPIC connections

EYUSTARTIPCONN.KILL

Terminate the task allocated to the IPCONN session. System and data integrity is not guaranteed. The KILL option extends the PURGE and FORCEPURGE options. It should be used only after an attempt has been made to PURGE or FORCEPURGE a task. The KILL option does not guarantee integrity of any kind but in some situations it allows you to free up a stalled region, enabling the region to continue processing. In some cases, for example, if a task is killed during backout processing, CICS terminates abnormally.
IPIC connections

EYUSTARTIPCONN.NORECOVDATA

Force all in-doubt units of work, forget any outstanding resynchs, and erase the logname previously received from the partner system.
IPIC connections

EYUSTARTIPCONN.NOTPENDING

Force all in-doubt units of work and forget any outstanding resynchs created before the initial (or cold) start of the partner system. This overrides the resynchronization process.
IPIC connections

EYUSTARTIPCONN.OUTSERVICE

Take a connection out of service.
IPIC connections

EYUSTARTIPCONN.PURGE

Purge normally the transactions associated with the IPIC connection. CICS terminates the transactions associated with this connection only if system and data integrity can be maintained. Note: A transaction is not purged if its definition specifies SPURGE=NO.
IPIC connections

EYUSTARTIPCONN.RELEASE

Release the IPIC connection.
IPIC connections

EYUSTARTIPCONN.RESYNC

Attempt exchange lognames resynchronization.
IPIC connections

EYUSTARTIPCONN.SET

Display the Set view in order to change the attributes of a selected connection.
IPIC connections

EYUSTARTIPCONN.TABULAR

Tabular information about IP interconnectivity (IPIC) connections.

Actions

Table 2. Actions available for IPCONN views
Action Description
ACQUIRE Acquire a connection
BACKOUT Back out all units of work that have been shunted because of the failure of this IPIC connection.
CANCEL Cancel all automatic initiation descriptors (AIDs) queuing for the IPIC connection.
COMMIT Commit all units of work that have been shunted because of the failure of this IP connection.
DISCARD Discard a connection from the CICS system where it is installed. The connection must be out of service before it can be discarded.
FORCE Force all UOWs shunted because of the failure of this IPIC connection to BACKOUT or COMMIT, as specified on the ACTION option of the TRANSACTION definition.
FORCECANCEL Cancel all AIDs, including system AIDs, queuing for the IPIC connection.
FORCEPURGE Force transactions associated with the IP connection purged immediately.
INSERVICE Place a connection in service.
KILL Terminate the task allocated to the IPCONN session. System and data integrity is not guaranteed. The KILL option extends the PURGE and FORCEPURGE options. It should be used only after an attempt has been made to PURGE or FORCEPURGE a task. The KILL option does not guarantee integrity of any kind but in some situations it allows you to free up a stalled region, enabling the region to continue processing. In some cases, for example, if a task is killed during backout processing, CICS terminates abnormally.
NORECOVDATA Force all in-doubt units of work, forget any outstanding resynchs, and erase the logname previously received from the partner system.
NOTPENDING Force all in-doubt units of work and forget any outstanding resynchs created before the initial (or cold) start of the partner system. This overrides the resynchronization process.
OUTSERVICE Take a connection out of service.
PURGE Purge normally the transactions associated with the IPIC connection. CICS terminates the transactions associated with this connection only if system and data integrity can be maintained. Note: A transaction is not purged if its definition specifies SPURGE=NO.
RELEASE Release the IPIC connection.
RESYNC Attempt exchange lognames resynchronization.
SET Display the Set view in order to change the attributes of a selected connection.

Fields

Table 3. Fields in IPCONN views
Field Attribute name Description
Number of allocations failed for other reasons ALLCFAILOTH The number of session allocations that have failed on this connection for non-link related reasons.
Remote application ID APPLID The name by which the remote system is known to the network (taken from the APPLID option of the IPCONN definition). This is the application identifier ( applid ) of the remote system, as specified on the APPLID option of its system initialization table. For XRF systems it is the generic applid.
Autoconnect option AUTOCONNECT Identifies which AUTOCONNECT option has been specified in the IPCONN definition:
  • NOAUTOCONN
    • CICS does not try to establish sessions when the IPIC connection is installed.
  • AUTOCONN
    • CICS tries to establish sessions when the IPIC connection is installed.
BAS resource definition version BASDEFINEVER The BAS version number of this definition.
Certificate CERTIFICATE The name of a certificate within the key ring file that is to be used as a client certificate in the SSL handshake for outbound IPCONN connections.
Last modification agent CHANGEAGENT The change agent identifier that made the last modification.
  • CSDAPI - The resource was last changed by a CEDA transaction, by the programmable interface to DFHEDAP or by an EXEC CICS CSD command.
  • CSDBATCH - The resource was last changed by a DFHCSDUP job.
  • DREPAPI - The resource was last changed by a CICSPlex SM BAS API command.
  • DREPBATCH - The resource was last changed by a CICSPlex SM utility.
  • AUTOINSTALL - The resource was last autoinstalled.
  • CREATESPI - The resource was last changed by an EXEC CICS CREATE command.
  • NOTAPPLIC - This is not applicable for this resource.
Last modification agent release CHANGEAGREL If the connection was installed using a CICSPlex SM SYSLINK definition, this is the CICS release level of the CICS system where the connection is installed. For connections not installed using SYSLINK this is the CICS release level of the agent that made the last modification to the IPIC connection definition.
Last modification time CHANGETIME If the connection was installed using a CICSPlex SM SYSLINK definition, this is the local date and time of the install. For connections not installed using SYSLINK this is the local date and time when the IPIC connection definition was last changed.
Last modification user ID CHANGEUSRID If the connection was installed using a CICSPlex SM SYSLINK definition, this is the user ID that requested the install. For connections not installed using SYSLINK this is the user ID that made the last modification to the IPIC connection definition.
SSL cipher suite codes CIPHERS A value specifying up to 28 cipher suites, in the form of hexadecimal pairs. From CICS Transaction Server 5.1 this field can alternatively specify the name of an XML file residing on zFS which contains a list of ciphers. An XML file can be up to 28 characters.
Most diverse route to partner system CLIENTLOC An IPCONN may use a number of sockets to provide different paths to its partner system. The SO_CLUSTERCONNTYPE options returned by z/OS Communications Server for all the sockets used by the IPCONN are evaluated, and the options representing the most diverse route are returned here.

The binary format of SO_CLUSTERCONNTYPE is converted to characters and displayed here as either zeros or ones. See the z/OS 1.9 Communications Server IP Sockets Application Programming Interface Guide in the z/OS 1.9 Information Center for a description of SO_CLUSTERCONNTYPE and an explanation of the bit settings.

Connection status CONNSTATUS The state of the IPIC connection between CICS and the remote system:
  • ACQUIRED
    • The IPIC connection is acquired. The criterion for ACQUIRED is that the capabilities exchange is complete. (The capabilities exchange is how two connected CICS regions discover the levels of service that they can collectively support; for example, the syncpoint 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 may also be in INSERVICE status, it is not usable.
Number of receive sessions in use CRECVSESS The number of receive sessions in use on this connection.
Number of send sessions in use CSENDSESS The number of send sessions in use on this connection.
Current number of allocates queued CURRQUEUED The number of session allocations currently queued on this connection.
Source of the resource definition DEFINESOURCE The source of the definition, depending on which agent made the last change.
Creation time DEFINETIME If the connection was installed using a CICSPlex SM SYSLINK definition, this is the local date and time of the install. For connections not installed using SYSLINK this is the local date and time when the IPIC connection definition record was created on DFHCSD or EYUDREP.
Number of XISQUE allocates purged EXITALLCPUR The number of sessions on this connection that have been purged by the XISQUE exit module.
Number of XISQUE allocation queue purges EXITALLCQPUR The number of session allocations on this connection that have been purged by the XISQUE exit module.
Number of XISQUE allocate rejections EXITALLCREJ The number of session allocations on this connection that have been rejected by the XISQUE exit module.
Number of FC function shipped bytes received FSFCBYTERECD The number of bytes received by file control requests.
Number of FC function shipped bytes sent FSFCBYTESENT The number of bytes sent by file control requests.
Number of FC function shipped requests FSFCREQS The number of file control requests for function shipping on this connection.
Number of IC function shipped bytes received FSICBYTERECD The number of bytes received on interval control requests.
Number of IC function shipped bytes sent FSICBYTESENT The number of bytes sent on interval control requests.
Number of IC function shipped requests FSICREQS The number of interval control requests for function shipping on this connection.
Number of PC function shipped bytes received FSPCBYTERECD The number of bytes received on LINK requests.
Number of PC function shipped bytes sent FSPCBYTESENT The number of bytes sent on LINK requests.
Number of PC function shipped requests FSPGREQS The number of program control LINK requests for function shipping on this connection.
Number of TD function shipped bytes received FSTDBYTERECD The number of bytes received on transient data requests.
Number of TD function shipped bytes sent FSTDBYTESENT The number of bytes sent on transient data requests.
Number of TD function shipped requests FSTDREQS The number of transient data requests for function shipping on this connection.
Number of TS function shipped bytes received FSTSBYTERECD The number of bytes received on temporary storage requests.
Number of TS function shipped bytes sent FSTSBYTESENT The number of bytes sent on temporary storage requests.
Number of TS function shipped requests FSTSREQS The number of temporary storage requests for function shipping on this connection.
GMT connection create time GMTCTIME The time when the connection was created in Greenwich Mean Time (GMT) format.
GMT connection delete time GMTDTIME The time when the connection was deleted in Greenwich Mean Time (GMT) format
High availability status HA Indicate whether the IPIC connection requires high availability.
  • REQUIRED
    • The IPIC connection requires high availability.
  • NOTREQUIRED
    • The IPIC connection does not require high availability.
Remote host name HOST The host name or IP address of the remote system. The HOSTTYPE option gives the format of this value as either a name, an IPv4 address or an IPv6 address.
Host name's address format HOSTTYPE The format of the host's address. These are the possible values:
  • HOSTNAME - HOST contains a character host name. The IP address that corresponds to the host name is looked up using DNS.
  • IPV4 - HOST contains an IPv4 address specified in dotted decimal address format.
  • IPV6 - HOST contains an IPv6 address specified in colon hexadecimal address format.
  • NOTAPPLIC - The HOST name or address is incorrect (HOST=0.0.0.0 or HOST=*).
Identity propagation IDPROP Specifies whether the Distributed ID will be transmitted to the connected system by the sender. The IDPROP attribute is meaningful only if a connection extends outside a sysplex and is used primarily to prevent distributed identities being distributed between enterprises. If the connection is between systems in the same sysplex, the connection operates as if IDPROP(OPTIONAL) is specified and ignores any other setting.
  • 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. If you specify IDPROP(REQUIRED), a task using the IPIC connection must have an associated distributed identity, otherwise the request fails with a security error.
Installation agent INSTALLAGENT The install agent identifier that made the installation.
  • CSDAPI - The resource was installed by a CEDA transaction, by the programmable interface to DFHEDAP or by an EXEC CICS CSD command.
  • CREATESPI - The resource was installed by an EXEC CICS CREATE command.
  • AUTOINSTALL - The resource was autoinstalled.
  • GRPLIST - The resource was installed by GRPLIST INSTALL.
Installation time INSTALLTIME The local date and time when the definition was installed.
Installation user ID INSTALLUSRID The user ID that installed the resource definition.
The format of the resolved IP address IPFAMILY The format of the resolved IP address, IPRESOLVED. These are the possible values:
  • IPV4 - The address is specified in IPv4 dotted decimal address format.
  • IPV6 - The address is specified in IPv6 colon hexadecimal address format.
  • UNKNOWN - IPRESOLVED is not yet in use, or the address cannot be resolved. This is the default when IPRESOLVED is 0.0.0.0
Remote host's IP address IPRESOLVED The resolved IPv4 or IPv6 address of the HOST to which this IPCONN applies, or 0.0.0.0 if it is unavailable or unknown. The format of this IP address is given by the IPFAMILY option.
Link security LINKAUTH 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. For example, the TCPIPSERVICE in the partner CICS system should be defined with SSL(YES) or SSL(CLIENTAUTH) In addition, this received certificate must be defined to the external security manager so that it is associated with a user ID. This user ID is used to establish link security.
  • SECUSER - The user ID specified in SECURITYNAME is used to establish link security. This is the default value.
Local connection create time LOCCTIME The local time when the connection was created.
Local connection delete time LOCDTIME The local time when the connection was deleted.
Maximum queue time MAXQTIME The maximum time, in seconds, for which allocate requests may be queued. The value is in the range 0-9999, or will have the standard null value of -1 if MAXQTIME(NO) is specified on the IPCONN definition.
Minimum mirror lifetime MIRRORLIFE Indicates the minimum lifetime of the mirror task for function shipped requests received by this region. This parameter only takes affect when specified on the IPCONN on the resource-owning region and is not to be honored for function shipping interval control or linkrequests.
  • REQUEST: The mirror task will terminate as soon as possible.
  • TASK: The mirror task remains available to the application issuing the remote request the until the end of this application's task.
  • UOW: The mirror transaction remains available to the application issuing the remote request until the next syncpoint is issued.
Number of queue time allocates purged MQTALLPURG The number of session allocations that have been purged on this connection because the queue time value has been exceeded.
Number of queue time allocation queue purges MQTALLQPURG The number of session allocations that have failed on this connection because the queue time value has been exceeded.
IPIC connection ID NAME The 8-character identifier of the remote system or region (that is, the name assigned to its IPCONN definition).
Remote network ID NETWORKID The network ID of the remote system. This 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 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).

NETWORKID is used in combination with the APPLID option to ensure unique naming for connecting systems.

Number of SSL cipher suite codes NUMCIPHERS The count of cipher suite codes, which are specified as hexadecimal pairs. A value of 0 could indicate the use of an XML cipher file.
Product token of partner system PARTNER The product token of the partner system, unless the partner system is CICS TS 5.3 or later and is making use of the HTTPUSRAGENTHDR system initialization parameter. The field is blank when the connection is not acquired or if the partner system has not indicated a product token 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.
Number of peak queued session allocations PEAKQUEUED The maximum number of session allocations queued on this connection at any one time.
Pending status PENDSTATUS Identifies whether there are any pending units of work for this IPIC connection:
  • NOTPENDING
    • There has been no mismatch of lognames with the partner.
  • PENDING
    • There is resynchronization work outstanding for the IPIC 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.

      No new syncpoint 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.

Port number PORT The port number used for outbound requests on this IPIC connection; that is, the number of the port on which the remote system is listening. If the IPCONN is defined with PORT(NO), the value is -1.
Maximum number of receive sessions used PRECVSESS The maximum number of receive sessions in use on this connection at any one time.
Maximum number of send sessions used PSENDSESS The maximum number of send sessions in use on this connection at any one time.
Purge type PURGETYPE How associated transactions are purged:
  • CANCEL
    • AIDs queuing for the specified IPCONN are canceled.
  • FORCECANCEL
    • All AIDs, including system AIDs, queuing for the IPCONN are canceled. Note: FORCECANCEL does not remove transient data AIDs with an associated triggered task. You can remove these AIDs by purging the associated task.
  • FORCEPURGE
    • All transactions running on sessions on the connected system are immediately terminated abnormally. This can lead to unpredictable results and should be used only in exceptional circumstances.

      In some extreme cases (for example, if an error occurs during backout processing), CICS might terminate abnormally.

      For in-doubt and shunted UOWs, FORCEPURGE has no effect.

      Note: To force shunted UOWs, the operator must issue SET IPCONN COMMIT, BACKOUT, or FORCE following a FORCEPURGE. This can lead to unpredictable results and should be used only in exceptional circumstances.
  • KILL
    • The task allocated to the IPCONN session is terminated. System and data integrity is not guaranteed. The KILL option extends the PURGE and FORCEPURGE options. It should be used only after an attempt has been made to PURGE or FORCEPURGE a task. The KILL option does not guarantee integrity of any kind but in some situations it allows you to free up a stalled region, enabling the region to continue processing. In some cases, for example, if a task is killed during backout processing, CICS terminates abnormally.
  • PURGE
    • Transactions running on the connected system are abnormally terminated. Transactions are terminated only if system and data integrity can be maintained. A transaction is not purged if its definition specifies SPURGE=NO, or if the UOW is shunted.
Number of queue limit allocate rejections QLIMALLOCREJ The number of session allocations that have failed on this connection because the queue limit value has been reached.
Queue limit QUEUELIMIT The maximum number of allocate requests that can be queued for this IPIC connection. The value is in the range 0-9999, or will have the standard null value of -1 if QUEUELIMIT(NO) is specified on the IPCONN definition.
Receive count RECEIVECOUNT The number of RECEIVE sessions defined for this IPIC connection.
Recovery status RECOVSTATUS Identifies whether there is resynchronization work outstanding for the IPIC connection. The connection may never have been connected, have been quiesced and all resynchronization work completed, or disrupted without quiescence, in which case resynchronization may be necessary.
  • NORECOVDATA
    • Neither side has recovery information outstanding.
  • NRS
    • CICS does not have recovery outstanding for the connection, but the partner may have.
  • RECOVDATA
    • There are in-doubt units of work associated with the IPIC connection, or there are outstanding resynchronization tasks awaiting FORGET on the connection. Resynchronization takes place when the connection next becomes active, or when the UOW is unshunted.
Remote terminal starts REMTRMSTRT The number of remote terminal starts over this connection.
Security name of the remote system SECURITYNAME This is the security name of the remote system and is applicable to PROTOCOL(IPIC) only. 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 your system. The default value for the security name is the default user ID.
Send count SENDCOUNT The number of SEND sessions defined for this IPIC connection. If a value of 0 is shown, then this IPIC connection may only receive data.
Service status SERVSTATUS Identifies whether data can be sent and received on the IPIC connection:
  • INSERVICE
    • Data can be sent and received.
  • OUTSERVICE
    • Data cannot be sent or received.
Secure sockets layer (SSL) type SSLTYPE Whether the service uses secure sockets layer.
  • NOSSL - The service does not use secure sockets layer.
  • SSL - Secure sockets layer is used by this service except for client authentication.
TCP/IP service TCPIPSERVICE The 8-character name of a PROTOCOL(IPIC) TCPIPSERVICE definition that defines the attributes of the inbound processing for this IPCONN.
Total number of session allocations TOTALLOC The total number of sessions that have been used on this connection.
Number of transactions attached TRANSATTCH The number of transactions that have been attached on this connection.
Number of TR function shipped bytes received TRBYTERECD The number of bytes received for transaction routing on this connection.
Number of TR function shipped bytes sent TRBYTESENT The number of bytes sent for transaction routing on this connection.
Number of TR function shipped requests TRREQS The number of transaction routing requests over this connection.
Number of unsupported requests UNSUPREQS The number of attempts to function ship unsupported requests across this connection.
UOW Action UOWACTION The action taken for units of work (UOWs) that are shunted because of the failure of this IPIC connection:
  • BACKOUT
    • All UOWs shunted because of the failure of this IPIC connection are backed out.
  • COMMIT
    • All UOWs shunted because of the failure of this IPIC connection are committed.
  • FORCEUOW
    • All UOWs shunted because of the failure of this IPIC connection are forced to BACKOUT or COMMIT, as specified on the ACTION option of the TRANSACTION definition.
  • RESYNC
    • Any UOWs shunted because of the failure of this IPIC connection are retried (that is, exchange lognames resynchronization for this connection is attempted). This process should normally be started automatically when a connection is acquired or when a UOW is unshunted.
Attach-time user security level USERAUTH The level of attach-time user security required for the connection:
  • DEFAULTUSER - CICS will not accept a user ID and password from the partner system. All requests run under the default user ID.
  • LOCAL - CICS will not accept a user ID and password from the partner system. All requests will run under the user ID determined for link security.
  • VERIFY - Incoming attach requests must specify a user identifier and a user password.
  • IDENTIFY - Incoming attach requests must specify a user identifier. For CICS TS Version 4 Release 1 system, this allows the distributed ID to be transmitted to the connected system by the sender, should it be required.


eyua3_ipconn_views.html | Timestamp icon Last updated: Sunday, 4 June 2017