How to handle CICS requests from IBM Integration Bus(IIB)


This article will outline the necessary steps to be taken with respect to calling existing CICS programs from IBM Integration Bus ( IIB ) using COMMAREA  data structures.

The COMMAREA  specifies the name of a data area ( known as Communication Area in CICS Region) in which data is passed to a program or transaction. The maximum length of the COMMAREA  cannot be larger than 32 KB.

The CICS Request node ( which started from WMB 7 version onwards ) enables IBM Integration Bus ( IIB ) to act as a CICS Client, sending Inter Communication requests over TCPIP   to CICS  Transaction Server and receiving responses back from CICS Transaction Server.

IBM Integration Bus is an Enterprise Service Bus for transforming and routing messages between business-critical applications.

CICS Transaction Server is a widely used Application Server in distributed transaction processing environments as well as in IBM System z ( mainframe ) environments. CICS Transaction Server for z/OS provides general-purpose transaction processing meeting the needs of both large and small enterprises.

Pre-requisites :

CICS Transaction Server ( on z/OS ) version should be on version 3.2 and later to make use of the CICS Request node within IBM Integration Bus.


IBM Integration Bus to CICS Connection brief Architecture overview: 

Following is the architecture diagram snaphot taken from IBM Info center for CICS Request node and how it connects to CICS Region.

CICS IIB Connection options

There are many ways to connect to an existing CICS region but in this article we will focus on  direct connection setup ( 2 tier ) between IBM Integration Bus and existing CICS region ( i.e IPIC connection setup).

“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.”


Business Use Case:

One of the possible use case is to call an existing CICS program call from IBM Integration Bus ( IIB ) using built-in CICSRequest node within a message flow synchronously. Which means we can expose existing CICS program calls on mainframe environment as web services.

In this example we will use an existing CICS program which takes input as store number and outputs corresponding store details.


Existing CICS call in mainframe environment and how it looks like:


CICS Store Validation


Request the following setup on existing CICS region.

IBM / Red Hat - Unlock Potential App Modernization
Unlock Your Potential with Application Modernization

Application modernization is a growing area of focus for enterprises. If you’re considering this path to cloud adoption, this guide explores considerations for the best approach – cloud native or legacy migration – and more.

Get the Guide

1) Define or configure IPIC connections for the existing CICS region.

2) Setup the following info on TCP listener ( IPIC ) .

(Please note that this info is passed from IBM Integration Bus to CICS to identify the source of the request)



Steps on IBM Integration Bus (IIB ) side

1. Create the following CICS Configurable service for use in the message flow

CICS Configurable Service

2. Define the security identity “TSOCRED” with appropriate mainframe CICS credentials if security is enabled on CICS region.

mqsisetdbparms <BrokerName> -n  cics::TSOCRED  -u <username> -p <password>

3.  Model the COBOL copybook associated with the CICS program using DFDL. Request and Response will be part of the message modeled as seen below.


4. Create a sample message flow using CICS Request node. CICS Message Flow

5. Build the sample request something similar to the screenshot below  in the compute node with appropriate mainframe encoding and CCSID set, before sending the request to the CICS Request node.

Build CICS Request

6. Please make sure the basic view of the CICS Request node has the following properties set

       CICS Server             :   CICSConnection ( Configurable Service that was defined in Step 1)

       Program Name      :   OK9997 ( CICS Target Program  )

       Commarea length :  1446 (<Please use the exact commarea length in bytes to avoid memory leaks.  You can request this info from mainframe CICS admins or programmers>  )

Send CICS Request Basic View

7. Also make sure the Response message tab in the CICS Request node is set with proper mainframe Message encoding and Coded Character Set ID ( CCSID )

CICS Request Node - Response Message

Request and Response Captured in debug mode :

CICS Request is triggered by passing dummy Input file to a file input node.

1.Following input request is captured in debug mode when calling an existing CICS program to do a store validation.


2. Successful Output of the request in the debug mode looks like this.


3. CICS Program Errors if any will look like this. The following CICS error talks about DB2 plan access issues for the id that we are connecting to. Once the DB2 Plan access is given to the userid that is connecting to CICS region from IBM Integration Bus,  issue got resolved.

CICS Error


Summary :

1. The real power of IBM’s built-in CICSRequest node within IBM Integration Bus lies in extending the Service Oriented Architecture capabilities seamlessly  to existing legacy online CICS applications  in the form of webservices.

2. Please make sure the existing CICS programs have a proper input and output within the COMMAREA  data  structures so that they can be easily  translated into request and response.

3. If possible use CHANNELS  instead of COMMAREA  data  structures because COMMAREA  structures have many limitations one of them being length.

4.Also memory leaks might happen in CICS Region if the COMMAREA  length passed is less than the actual COMMAREA  layout length.


About the Author

More from this Author

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Subscribe to the Weekly Blog Digest:

Sign Up