Introducing Anypoint Connector for IBM CICS Transaction Gateway

IBM Customer Information Control System (CICS) is a transaction server that runs primarily on IBM mainframe systems under z/OS and z/VSE. According to IBM CICS Report 2015, 92 of the top 100 banks use the mainframe to provide at-your-fingertip banking services to their customers. And nine out of the top 10 global life and health insurance providers process their high-volume transactions on a System z mainframe.

IBM CICS offers various ways for users to connect with the system – including MQ, Web Services, and IBM CICS Transaction Gateway –  and today we are thrilled to announce a new way to connect with this system using MuleSoft’s Anypoint Connector for IBM CICS Transaction Gateway.

The Anypoint Connector for IBM CICS Transaction Gateway has advantages in operations management, millions of instructions per second (MIPS), and provides better transactionality support over methods such as MQ or web services.

In this blog, I’d like to walk you through a simple demo app to show you how to use the IBM CTG Connector. Before you start with the demo app, please make sure you have the connector for IBM CICS Transaction Gateway (CTG) v1.0.0 downloaded from Anypoint Exchange.

After you install the IBM CTG Connector and import the demo app into Anypoint Studio, you will see the following flows:

Let’s configure this IBM CTG Connector first. If you go to Global Elements, you will find “IBM CTG.” After selecting “IBM CTG,” please click on “Edit.”

In the IBM CTG configuration, you can specify the configuration of the IBM CTG server. You can directly add your IBM CTG information in the configuration, but I recommend you use the properties file to add your configuration information.

mule-app.properties include the following keys-value pairs:

ibm.host=
ibm.port=
ibm.serverName=
ibm.username=
ibm.password=

This connector also requires the following four JAR files:

1. ccf2.jar (CICS Common Connector Framework)
2. cicsjee.jar (CICS JEE)
3. ctgclient.jar (CTG Client Library)
4. ctgserver.jar (CTG Server Library)

These files can be located in your CTG installation. In addition, you need a fifth JAR file, the geronimo-j2ee-connector_1.6_spec-1.0.jar (JCA 1.6 Specification). This file is required to avoid conflicts with JCA 1.5 shipped with the Mule Runtime. You can download the geronimo-j2ee-connector_1.6_spec-1.0.jar here.

After the configuration is complete, you can check your configuration with “Test Connection.” Please make sure your IBM CTG is up and running.

We are going to use three demo app running in IBM CICS.

• EC01: A COMMAREA-based program that outputs the current datetime in a formatted EBCDIC string
  • COMMAREA: A block of contiguous memory used to pass data between programs. It is the binary equivalent of a COBOL structure and it is character-based
• EC02: A COMMAREA-based program that returns a simple run counter.
• EC03: A channel-based program that takes an input data container and returns three containers:
  • A data/time container
  • The length of the input data and returns uses channels and containers in a CICS program
  • An output container that contains a copy of the input data, or an error message

Let’s take a look at the first flow called commareaFlow. This flow is configured to execute the EC01 program.

The demo app includes cobol copybook metadata for EC01, EC02, and EC03 programs under “src/main/resource”. For the first flow, let’s define the input metadata according to section Add Custom Metadata using the schema file ec01-type.ffd:

form: COPYBOOK
id: 'DFHCOMMAREA'
values:
- { name: 'LK-DATE-OUT', type: String, length: 8 }
- { name: 'LK-SPACE-OUT', type: String, length: 1 }
- { name: 'LK-TIME-OUT', type: String, length: 8 }
- { name: 'LK-LOWVAL-OUT', type: String, length: 1 }

You can see the metadata you added, which is in DataWeave output. For the demo app, we will just pass an empty string for each input parameter.

If you click the FlowVar – request in the Output window for DataWeave and follow Load Java Metadata (link will be added), you will see that the following parameters are defined for the request variable.

If you run this demo app, and hit localhost:8081/ec01, the EC01 program running in IBM CICS will return the current datetime.

{
   "date": "28/09/17",
   "time": "11:54:40"
}

Let’s take a look at the second flow, which  uses the transactional scope for “Execute Commarea.” Bitronix Transaction Manager is already added in the Global Elements tab without the further configurations, and “BEGIN_OR_JOIN” is selected for the XA Transaction.

This flow will call the EC02 app, which returns the count value based on the input. When you add the custom schema (ec02-type.ffd), and load the java metadata, CommareaRequest.

If you run this demo app, and hit localhost:8081/ec02, EC02 program running in IBM CICS will return the count. As the demo app passes LK-Count: “000001234TH RUN OF EC02”, you will receive the following values.

{
   "count": "1235th run OF EC02",
   "lowVal": null
}

Let’s see how the “Execute” operation works. When you add the custom schema (ec03-type.ffd), your output for DataWeave will look like the following image:

Since we are using the channel rather than the commarea, you can define the new Java metadata called ChannelRequest.

If you run this demo app, and hit the localhost:8081/ec03, the EC03 program running in IBM CICS will return the current datetime.

{
   "cics-date-time": "28/09/2017 13:05:51"
}

For new users, try the above example to get started, and for others, please share with us how you are planning to use the IBM CTG connector!