CICS Transaction Server for z/OS two-tier connectivity

The CICSRequest node support in IBM® Integration Bus provides direct communication with CICS® Transaction Server for z/OS® (two-tier connection) by sending Distributed Program Link (DPL) requests over TCP/IP-based IP InterCommunications (IPIC) protocol.

The CICSRequest node also supports communication with CICS through CICS Transaction Gateway (three-tier connection). For more information about three-tier connections, see CICS Transaction Server for z/OS three-tier connectivity.

A direct two-tier connection from IBM Integration Bus to CICS can be made by using the CICSConnection configurable service or by setting the properties directly on the CICSRequest node.

CICSConnection configurable service connections:

A CICS connection from IBM Integration Bus is made to a listening TCPIPSERVICE resource in CICS. When that connection is established, the active connection between IBM Integration Bus and CICS is represented by an IPCONN resource.

Each CICSConnection configurable service results in a separate connection to CICS, so for every configurable service that is being used, there is an IPCONN resource in CICS. The properties of the IPCONN resource determine the properties of the link between IBM Integration Bus and CICS.

The IPCONN resource that represents an IBM Integration Bus to CICS connection can be created in two different ways; autoinstall or pre-defined.

Autoinstall:
Autoinstalling a connection means that when IBM Integration Bus connects, the resource is created, and when IBM Integration Bus disconnects, the resource is discarded. In this setup, the IPCONN is created from a template IPCONN that is named by a user-replaceable-module (URM), which is named in the TCPIPSERVICE resource. Properties of the IPCONN are based on that template resource.
Pre-defined:
Alternatively, the IPCONN can be pre-defined by using standard CICS resource definition mechanisms, such as CICS Explorer, CEDA, or CICSPlex® Systems Manager (CICSPLEX SM). If the IPCONN definition is created in advance, it is matched to the incoming connection by using the IPCONN APPLID and Network ID properties, which correlate to the clientApplid and clientQualifier properties that can be set on a CICSConnection configurable service.
The advantage of pre-specifying the IPCONN is that you can tightly control the properties of incoming connections, including the security properties and the number of simultaneous requests. However the following rules apply:
  • Do not configure different integration servers to use the same CICSConnection clientApplid and clientQualifier combination to connect to the same CICS region. An IPCONN is tied to IBM Integration Bus through the CICSConnection configurable service properties clientApplid and clientQualifier. If this is attempted, only the first configurable service successfully connects.
  • Do not specify a host name and port when defining the IPCONN resource in CICS. These fields are used for connections between CICS regions only, they must not be set for IBM Integration Bus connections.
The following diagram shows how IBM Integration Bus can directly connect to CICS by using a CICSConnection configurable service.
The diagram shows how IBM Integration Bus can connect to CICS Transaction Server for z/OS by using a CICSConnection configurable service.
The two-tier direct CICS connection model is based on the following rules:
  • Each configurable service name results in a separate connection to CICS.
  • The CICSConnection configurable service must only be used from one integration server, because any further integration servers attempting to use the same configurable service thereafter fail to connect.
  • The clientApplid and clientQualifier properties in the configurable service are used to find the IPCONN resource in CICS. A chosen clientApplid and clientQualifier combination must be unique to the CICS region. Only one IPCONN resource can exist with that combination.
  • More than one message flow instance can use the CICS connection, however each request that goes through a CICSRequest node uses a conversation on the connection for the duration of the request.

When defining an IPCONN resource in CICS, consider the following properties:

  • CICS APPLID and Network ID

    The CICS APPLID and Network ID properties must match the CICSConnection configurable service clientApplid and clientQualifier properties.

  • CICS host name and Port number

    The CICS host name and port properties must be used for connections between CICS regions only, they must not be set for IBM Integration Bus connections.

  • CICS TCPIPSERVICE

    IPCONNs are owned by a parent TCPIPSERVICE resource in CICS.

  • CICS Receivecount

    The CICS Receivecount property controls the number of simultaneous requests that can be performed over the connection. The number of simultaneous requests defaults to 100 for autoinstalled connections.

  • CICS Sendcount

    The Sendcount property must be set to 0 because the Sendcount property is used for CICS connections only, and must not be used for IBM Integration Bus connections.

  • CICS LINKAUTH

    The CICS LINKAUTH property controls how the link security is managed. To use a resource in CICS, two security checks are performed; the "flowed" user, which checks the security credentials that are sent from IBM Integration Bus, and the "link" user, which must also have permission for the resource. Both user IDs must have permission to use the resource before the request is granted. The link user ID is given low privileges, which means that even if the flowed user has many permissions, the link user ID can be used to cap the privilege of the connection. If LINKAUTH is set to SECUSER, the SECURITYNAME field is used to specify the link user ID. If set to CERTUSER, the link user is determined from an SSL client certificate that is mapped by RACF®. If USERAUTH(IDENTIFY) or USERAUTH(VERIFY) is specified, the link user ID is not used. Only the user ID received from the TOR is used to determine security.

  • CICS USERAUTH

    The CICS USERAUTH property determines how the flowed user security is configured. If USERAUTH is set to "LOCAL" or "DEFAULTUSER", no user ID or password is to be sent to CICS on a request. This means that all requests use the CICS region ID. If USERAUTH is set to "IDENTIFY", user IDs are flowed without a password. If USERAUTH is set to "VERIFY", user IDs and passwords are required. If USERAUTH(IDENTIFY) or USERAUTH(VERIFY) is specified, the link user ID is not used. Only the user ID received from the TOR is used to determine security.

Each CICSRequest node in a message flow acts as a request on one of the connections to CICS. Which connection is used is determined by the configurable service that is used.

For more information about configuring the CICSRequest node to get connection details from a CICSConnection configurable service, see Changing connection information for the CICSRequest node.

You can configure the CICSRequest node or a CICSConnection configurable service to use SSL protocol. For more information, see Securing the connection to CICS Transaction Server for z/OS by using SSL.

CICSRequest node connections:

If a CICSConnection configurable service is not specified on the CICSRequest node, and a host name is used directly in the CICS server property, the request shares a connection with other resources that have specified the same CICS server URL. The first CICSRequest node to be used opens the connection to CICS, regardless of whether a URL or a configurable service is specified in the CICS server property.