Introduction:
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.
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:
Request the following setup on existing CICS region.
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
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. 
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.
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> )
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 )
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.
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.
