Configuring an IPIC connection in CICS

Follow these steps to configure an IPIC connection in CICS® Transaction Server.

1. Set the System Initialization (SIT) parameter TCPIP=YES.
2. Define the TCP/IP address and host name for the IBM® z/OS® Connect server. By default, they are defined in the PROFILE.TCPIP and TCPIP.DATA data sets.
3. Add a TCP/IP listener to CICS.
   Use the following CEDA command to define a TCPIPSERVICE in a group:

   CEDA DEF TCPIPSERVICE(service-name) GROUP(group-name)

   Ensure that the group in which you define the service is in the startup GRPLIST so that the listener starts when CICS is started. The following list shows the key attributes:

   POrtnumber

   The port on which the TCP/IP service listens.

   PRotocol

   The protocol of the service is IPIC.

   TRansaction

   The transaction that CICS runs to handle incoming IPIC requests. Set it to CISS (the default).

   Backlog

   The number of TCP/IP requests that are queued before TCP/IP starts to reject incoming requests.

   HOST

   Specifies the 116-character IPv4 or IPv6 address or host name on which CICS listens for incoming connections. For configurations with more than one IP stack, specify ANY to make the TCPIPSERVICE listen on all addresses. When configuring the specific TCPIPSERVICE definition for an HA connection and using the HA reconnection capability, refer to Setting preferredSpecificHost="local".

   SOcketclose

   Specifies whether CICS waits to close the socket after it issues a receive for incoming data on that socket. Use NO for IPIC connections to ensure that the connection from IBM z/OS Connect always remains open.

   SSL

   Specifies whether the TCP/IP service is to use the secure sockets layer (SSL) for encryption and authentication.

   • Set this value to No when SSL is not to be used on the connection with the IBM z/OS Connect server.
   • Set this value to Yes when SSL is to be used on the connection with the IBM z/OS Connect server.
   • Set this value to Clientauth when SSL is to be used on the connection with the IBM z/OS Connect server. In this case, CICS also expects to receive a client certificate from the IBM z/OS Connect server during the SSL handshake, when the connection is being acquired. You must specify this value if you send an authenticated identity to CICS and the CICS region is in a different sysplex from the IBM z/OS Connect server.

   CErtificate

   This attribute is only applicable when SSL(Yes) or SSL(Clientauth) is also specified. Specifies the label of an X.509 certificate that is used as the server certificate during the SSL handshake when the connection with the IBM z/OS Connect server is acquired. If this attribute is omitted, the default certificate that is defined in the key ring for the CICS region user ID is used. The certificate must be stored in a key ring in the database of the external security manager.

4. Use the following command to install the TCPIPSERVICE definition:
   CEDA INS TCPIPSERVICE(service-name) GROUP(group-name)
5. Choose whether to predefine or to autoinstall IPIC connections in CICS Transaction Server.
   You can predefine IPCONN connection definitions in CICS, or connections can be configured to be auto-installed by either the default or a customized autoinstall program. When IBM z/OS Connect connects to CICS, it flows the zosConnectApplid and zosConnectNetworkid values that are defined on the zosconnect_cicsIpicConnection element in server.xml. If these values match the Applid and Networkid attributes of an IPCONN definition, then that definition is used to install the connection. If no matching IPCONN definition exists, the connection is auto-installed, if auto-install is enabled.

   Note: If the zosConnectNetworkid is not specified in server.xml and the Networkid is left blank in the IPCONN definition, a match will not occur because CICS defaults the blank Networkid to the local network ID.

   You can customize auto-installed IPIC connections. To do this, you must create an IPCONN definition with the customized attributes to act as a template and this definition must be referenced as the template in a customized IPCONN autoinstall user program. The name of the autoinstall user program must be specified on the URM option of the installed TCPIPSERVICE definition.

6. Create a predefined or auto-installed IPCONN definition.
   The following list shows the key attributes:

   APplid

   For a predefined IPCONN, set this value to the value of the zosConnectApplid attribute that is specified on the zosconnect_cicsIpicConnection element in server.xml. For an auto-installed IPCONN, optionally set this value to identify the instance of the connection.

   Networkid

   For a predefined IPCONN, set this value to the value of the zosConnectNetworkid attribute that is specified on the zosconnect_cicsIpicConnection element in server.xml. For an auto-installed IPCONN, optionally set this value to identify the instance of the connection.

   TCPIPService

   Set this value to match the name of the TCPIPService defined earlier.

   Receivecount

   Set this value to specify the number of requests that can be processed in parallel. This should match the number set in the sendSessions attribute that is specified on the zosconnect_cicsIpicConnection element in IBM z/OS Connect. For information on how the actual number of sessions is determined on connection establishment, see IP interconnectivity (IPIC) overview.

   SENdcount

   Set this value to zero because IPIC connections are always inbound to CICS from IBM z/OS Connect, unlike CICS to CICS connections for which the value must not be zero.

   Inservice

   Set this value to Yes.

   Linkauth

   Set this value to Secuser to use the user ID that is specified in the SECurityname attribute.

   Set this value to Certuser to use an SSL client certificate that is mapped to a SAF user ID. The referenced TCPIPSERVICE definition must be configured for SSL and client authentication.

   SECurityname

   Set this value to a SAF user ID that is authorized to establish IPIC connections.

   Userauth

   Set this value to Local or Defaultuser when no user credentials are required to be passed from IBM z/OS Connect. The CICS program then runs under the link user ID or default user ID.

   Set this value to Identify when user identity propagation or identity assertion is required and IBM z/OS Connect is configured to use distributed identities or flow an asserted SAF user ID. In this instance, if the IBM z/OS Connect server is not in the same sysplex as the CICS region, you must use an IPIC SSL connection that is configured with client authentication.

   Set this value to Verify when connection level user security is required and a zosconnect_authData element is referenced on the zosconnect_cicsIpicConnection element in server.xml.

   SSL

   This attribute is not applicable for a connection to IBM z/OS Connect. This attribute is used when a CICS region acts as the client end of an IPIC connection to another CICS region.

   CErtificate

   This attribute is not applicable for a connection to IBM z/OS Connect. This attribute is used when a CICS region acts as the client end of an IPIC connection to another CICS region.