Contact Free trial Login

IBM CICS Transaction Gateway Connector - Mule 4

Support Category: Premium

IBM CICS Transaction Gateway Connector Version 2.3

Anypoint Connector for IBM CICS Transaction Gateway (IBM CTG Connector) provides integration with back-end CICS apps using the CICS Transaction Gateway. For Java platforms, CTG implements the Java Cryptography Architecture (JCA) resource adapter to connect Java applications to the Customer Information Control System (CICS) system. The connector serves as a link between Mule apps and the IBM CTG.

Prerequisites

To use this information, you must be familiar with IBM CTG, Mule runtime engine (Mule), Anypoint Connectors, Anypoint Studio, Mule concepts, elements in a Mule flow, and Global Elements.

You need login credentials to test your connection to your target resource.

To use this connector with Apache Maven, view the pom.xml file dependency information from the Dependency Snippets link in Anypoint Exchange.

Terminology

CICS (Customer Information Control System)

Set of enterprise application servers with support for high-transaction workloads in a secure, scalable, cost efficient environment. CICS applications are written in a variety of languages, from Java to COBOL.

CICS Region

Named collection of resources that are controlled by CICS as a unit. A CICS resource is any facility or component of a CICS system that is required to perform a task.

CICS TG (CICS Transaction Gateway)

Set of client and server software components that allow a remote client application to invoke services in a CICS region. The client application can be either a Java application or a non-Java application. The CICS TG is available through the following two products: CICS TG on z/OS and CICS TG for Multiplatforms.

COMMAREA

Block of contiguous memory used to pass data between programs. It is the binary equivalent of a COBOL structure and it is character-based.

ECI (External Call Interface)

Simple remote procedural call style interface, used for linking to CICS applications. The COMMAREA or channel is the data interface used for the exchange of data between the client application and the CICS.

JCA

Standard architecture for connecting the J2EE platform to heterogeneous Enterprise Information Systems (EIS), such as CICS. The JCA enables an EIS vendor to provide a standard resource adapter for its EIS. A resource adapter is the middle tier between a Java application and an EIS and connects the Java application to the EIS.

Connect in Design Center

Design Center enables you to create apps visually. To use Design Center, work with your Anypoint Platform administrator to ensure that you have a Design environment. For more information, see the Flow Designer Tour.

To create an app in Design Center:

  • Configure the input source (trigger) for your app.

  • Add the connector as a component to process the input for the app.

For information about Design Center field values, see the Connector Reference.

Configure the Trigger

  1. In Design Center, click Create.

  2. Click Create new application.

  3. Specify a value for Project name and click Create.

  4. Click a trigger to be the input source, such as HTTP Listener or Scheduler trigger.

    The IBM CTG Connector does not provide a trigger operation.

    Trigger options
  5. To create an HTTP input source for the connector, set these fields:

    HTTP Listener configuration
    Field Description

    Protocol

    Protocol selected for the HTTP endpoint: either HTTP or HTTPS.

    Host

    IP address where a Mule app listens for requests.

    Port

    Port address where a Mule app listens for requests.

    Base

    Path where a Mule app listens for requests.

  6. Select the plus sign (+) to add a component.

    add connector
  7. Select the connector as a component.

  8. Select the operation.

    config connector
    Name Description

    Execute

    Invokes a CICS program with data encapsulated as channels and containers.

    Execute using COMMAREA

    Invokes a CICS program with data encapsulated as a COMMAREA. Requests are limited to a maximum of 32 KB.

  9. Configure the Global Element for the connector:

    config connector
    Field Description

    Host

    Enter the host name of the CICS transaction gateway (TG).

    Port

    Enter the port on which the CICS TG is running. Default value is 2006.

    Server Name

    Enter the name of the target CICS server as defined in the CICS TG configuration file. Optional.

    Username

    Enter the CICS user ID. Optional, if security is not enabled in the CICS region.

    Password

    Enter the password for the CICS user ID. Optional, if security is not enabled in the CICS region.

  10. Go to add dependencies.

    dependency connector
    dependency connector
    Field Description

    Required Dependencies

    • ccf2.jar (CICS Common Connector Framework)

    • cicsjee.jar (CICS JEE)

    • ctgclient.jar (CTG Client Library)

    • ctgserver.jar (CTG Server Library)

    • geronimo-j2ee-connector_1.6_spec-1.0.jar

      Use the JAR files that come bundled within the installation of the IBM CTG server instead of downloading the SDK ZIP from IBM’s web site. This ensures compatibility between the connector and the IBM CTG system.

  11. Go to the Additional Settings tab and complete the configuration.

    config connector
    Field Description

    Keystore Location

    Enter the location of the keystore containing the certificates required for an SSL client. Optional.

    Keystore Password

    Enter the password required to access the keystore for an SSL client. Optional.

    Connection Timeout

    Enter the socket timeout for the client to CTG. Default value is 0 (no timeout).

    Response Timeout

    Enter the response timeout for the client to CTG. Default value is 30000 milliseconds (30 seconds).

    CTG Trace

    If set to True, all debug levels of CTG tracing are enabled. Default value is False.

    Response Timeout is overridden by the IBM ecitimeout parameter if configured on the server side. See IBM ECI Timeout.

Add the Connector to a Studio Project

Anypoint Studio provides two ways to add the connector to your Studio project: from the Exchange button in the Studio taskbar or from the Mule Palette view.

Add the Connector Using Exchange

  1. In Studio, create a Mule project.

  2. Click the Exchange icon (X) in the upper-left of the Studio task bar.

  3. In Exchange, click Login and supply your Anypoint Platform username and password.

  4. In Exchange, search for "ctg".

  5. Select the connector and click Add to project.

  6. Follow the prompts to install the connector.

Add the Connector in Studio

  1. In Studio, create a Mule project.

  2. In the Mule Palette view, click (X) Search in Exchange.

  3. In Add Modules to Project, type "ctg" in the search field.

  4. Click this connector’s name in Available modules.

  5. Click Add.

  6. Click Finish.

Configure a Studio Project

  1. Drag a connector’s operation to the Studio canvas.

  2. Configure the Global Element for the connector:

    config connector
    Field Description

    Required Libraries

    • ctgserver.jar (CTG Server Library)

    • cicsjee.jar (CICS JEE)

    • ccf2.jar (CICS Common Connector Framework)

    • ctgclient.jar (CTG Client Library)

    • geronimo-j2ee-connector_1.6_spec.jar

    Note: Use the JAR files that come bundled within the installation of the CTG server instead of downloading the SDK ZIP from IBM’s web site to ensure the compatibility between the connector and the CTG system.

    Host

    Enter the host name of the CICS TG.

    Port

    Enter the port on which the CICS TG is running. Default value is 2006.

    Server name

    Enter the name of the target CICS server as defined in the CICS TG configuration file. Optional.

    Username

    Enter the CICS user ID. Optional, if security is not enabled in the CICS region.

    Password

    Enter the password for the CICS user ID. Optional, if security is not enabled in the CICS region.

  3. To add the dependencies, select Add dependency and complete the fields.

    dependecy connector
  4. Go to the Additional Settings tab and complete the configuration:

    config connector
    Field Description

    Keystore location

    Enter the location of the keystore containing the certificates required for an SSL client. Optional.

    Keystore Password

    Enter the password required to access the keystore for an SSL client. Optional.

    Connection Timeout

    Enter the socket timeout for the client to CTG. Default value is 0 (no timeout).

    Response Timeout

    Enter the response timeout for the client to CTG. Default value is 30000 milliseconds (30 seconds).

    CTG Trace

    If set to True, enables all debug levels of CTG tracing. Default value is False.

    Response Timeout is overridden by the ecitimeout parameter if configured on the server side. See IBM ECI Timeout.

  5. Choose the operation.

    operations connector

    The IBM CTG connector supports the following two outbound operations:

    Name Description

    Execute

    Invokes a CICS program with data encapsulated as channels and containers.

    Execute using COMMAREA

    Invokes a CICS program with data encapsulated as a COMMAREA. Requests are limited to a maximum of 32 KB.

POM File Information

<dependency>
  <groupId>com.mulesoft.connectors</groupId>
  <artifactId>mule-ibm-ctg-connector</artifactId>
  <version>RELEASE</version>
  <classifier>mule-plugin</classifier>
</dependency>

Mule converts RELEASE to the latest version. To specify a version, view Anypoint Exchange and click Dependency Snippets.

Enable Logging for Requests and Responses

To enable logging of the interactions of the connector with IBM CTG, a logger must be configured in the log4j2.xml file of the Mule app as follows. Put the AsyncLogger statement in the Loggers block in the log4j2.xml file:

<AsyncLogger
	name="org.mule.modules.ibmctg.internal.service.CTGServiceImpl"
	level="DEBUG"/>

Common Use Cases

  • Invoke a COMMAREA program

  • Invoke a channel program

  • Invoke a COMMAREA or channel program inside a Transactional Scope

  • Add custom metadata

To successfully run the first three use cases, the target CICS system must have the specified programs.

Invoke a COMMAREA Program

This application calls EC01, a COMMAREA-based program that outputs the current datetime in a formatted EBCDIC string.

CTG COMMAREA flow
  1. Create a new Mule Project in Anypoint Studio and fill in the IBM CTG credentials in src/main/resources/mule-app.properties.

    ctg.host=<HOST>
    ctg.port=<PORT>
    ctg.serverName=<SERVER_NAME>
    ctg.username=<USERNAME>
    ctg.password=<PASSWORD>
  2. Drag an HTTP Listener operation onto the canvas, leave the default values for Host and Port, and set the Path to /test/ec01.

  3. Drag an IBM CTG operation onto the canvas and add a new Global Element to configure a standard (non-SSL) client.

    Parameter Value

    Host

    ${ctg.host}

    Port

    ${ctg.port}

    Server Name

    ${ctg.serverName}

    Username

    ${ctg.username}

    Password

    ${ctg.password}

    Click Test Connection to confirm that Mule can connect with the IBM CTG instance. If the client is successful, click OK to save the configuration. Otherwise, review or correct any invalid parameters and test again.
  4. Double-click the IBM CTG component, select the Execute operation and configure the following parameters:

    Parameter Value

    Content Reference

    #[payload]

    Request Reference

    #[flowVars.commareaRequest]

  5. Add a Transform Message between the HTTP and the IBM CTG operation.

    The connector does not provide dynamic or static metadata, but allows users to define custom types using the Metadata Type tool.

    1. Define the input metadata for Add Custom Metadata using the ec01-type.ffd schema file:

      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 }
    2. Map the fields in the DataWeave transformer.

      %dw 2.0
      output text/plain schemaPath = "ec01-type.ffd", segmentIdent = "DFHCOMMAREA"
      ---
      [{
          LK-DATE-OUT: "",
          LK-SPACE-OUT: "",
          LK-TIME-OUT: "",
          LK-LOWVAL-OUT: ""
      }]
    3. Create a flow variable named commareaRequest and configure the following fields, as described in Load Java Metadata:

      %dw 2.0
      output application/java
      ---
      
      {
      	channel: "EC03",
      	encoding: "US-ASCII",
      	errorContainer: "OUTPUTMESSAGE",
      	programName: "EC03",
      	requestContainer: "INPUTDATA",
      	responseContainer: "CICSDATETIME",
      	tpnName: "CSMI"
      } as Object {
      	class : "org.mule.modules.ibmctg.internal.model.ChannelRequest"
      }

      See Load Java Metadata for how to obtain metadata for the CommareaRequest.

  6. Add a Transform Message after the IBM CTG to extract the results in a JSON format.

    %dw 2.0
    output application/json
    ---
    {
    	date: payload
    }
  7. Add a Logger at the end of the flow.

  8. Save the changes and deploy the Mule Application. Open a browser and make a request to http://localhost:8081/ec01. The result should be similar to:

    {
        date: "08/01/2019 13:41:17"
    }

Invoke a Channel Program

This application calls EC03, a channel-based program that takes an input data container and returns three containers:

  • A data and time container

  • The length of the input data, use channels, and containers in a CICS program

  • An output container that contains a copy of the input data, or an error message

Channel Program
  1. Perform steps 1 to 3 from the previous example and set the HTTP path to /ec03.

  2. Double-click the IBM CTG operation, select the Execute operation, and configure the following parameters:

    Parameter Value

    Content Reference

    #[payload]

    Request Reference

    #[flowVars.request]

  3. Add a Transform Message between the HTTP and the IBM CTG operation.

  4. Define the input metadata according to Add Custom Metadata using the schema file ec03-type.ffd:

    form: COPYBOOK
    id: 'DFHCOMMAREA'
    values:
    - { name: 'CICS-DATE-TM', type: String, length: 8 }
  5. Map the fields in the DataWeave transformer.

    %dw 2.0
    output text/plain schemaPath = "ec03-type.ffd", segmentIdent = "DFHCOMMAREA"
    ---
    [{
    	CICS-DATE-TM: ""
    }]
  6. Create a flowVar variable named request and configure the following fields, as described in Load Java Metadata:

    %dw 2.0
    output application/java
    ---
    {
    	channel: "EC03",
    	encoding: "US-ASCII",
    	errorContainer: "OUTPUTMESSAGE",
    	programName: "EC03",
    	requestContainer: "INPUTDATA",
    	responseContainer: "CICSDATETIME",
    	tpnName: "CSMI"
    } as Object {
    	class : "org.mule.modules.ibmctg.internal.model.ChannelRequest"
    }
  7. Add a Transform Messager after the IBM CTG operation to convert the result into a readable format.

  8. Add a Logger at the end of the flow.

  9. Save the changes and deploy the Mule app.

  10. Open a browser and make a request to http://localhost:8081/ec03.

    The result should be similar to:

    {
       cics-date-time: "08/01/2019 13:57:25"
    }

Invoke a COMMAREA or Channel Program inside a Transactional Scope

This application calls EC02, a COMMAREA-based program that returns a simple run counter.

Use case flow in Studio
  1. Perform steps 1 to 3 from the previous example and set the HTTP path to /test/ec02.

  2. In the Global Elements tab, add a new Bitronix Transaction Manager without further configurations.

  3. Drag a Transactional element next to the HTTP and configure according to the table below:

    Parameter Value

    Type

    XA Transaction

    Action

    BEGIN_OR_JOIN

  4. Double-click the IBM CTG component, select the operation Execute using COMMAREA and configure the following parameters:

    Parameter Value

    Content Reference

    #[payload]

    Request Reference

    #[flowVars.request]

  5. Add a Transform Message between the HTTP and the IBM CTG components. The connector does not provide dynamic/static metadata but allows users to define custom types using the Metadata Type tool.

  6. Define the input metadata according to Add Custom Metadata using the schema file ec02-type.ffd:

    form: COPYBOOK
    id: 'DFHCOMMAREA'
    values:
    - { name: 'LK-COUNT', type: String, length: 40 }
  7. Map the fields in the DataWeave transformer.

    %dw 2.0
    %output text/plain schemaPath = "ec02-type.ffd" , segmentIdent = "DFHCOMMAREA"
    ---
    [{
    	LK-COUNT: "000001234TH RUN OF EC02"
    }]
  8. Create a flowVar named request and configure the following fields, as described in Load Java Metadata:

    %dw 2.0
    output application/java
    ---
    {
    	commareaLength: 40,
    	encoding: "IBM037",
    	programName: "EC02",
    	replyLength: 40,
    	tpnName: "CSMI"
    } as Object {
    	class : "org.mule.modules.ibmctg.internal.model.CommareaRequest"
    }
  9. Add a Transform Message after the IBM CTG to extract the results in a JSON format.

    %dw 2.0
    output application/json
    ---
    {
    	count: payload
    }
  10. Add a Logger at the end of the flow.

  11. Save the changes and deploy the Mule app.

  12. Open a browser and make a request to http://localhost:8081/ec02. The result should be similar to:

    {
        count: "1st RUN OF EC02"
    }

Add Custom Metadata

The IBM CTG Connector does not provide dynamic or static metadata out of the box, but it enables users to define custom types using the Metadata Type tool. Define input and output metadata as follows:

  1. Place a schema file under src/main/resources directory, normally in .ffd format.

    Note: These schema files must be supplied by the user. They can be obtained from COBOL copybooks, which are included in the CICS installation.

  2. Go to the Metadata tab of the connector operation and click Add metadata.

    • Select Input:Payload and click Edit to open the Metadata Editor:

      Metadata Editor
  3. Click Add to create a new type and provide and ID for it, that is, ec03-in-type for the program EC03 input data.

  4. Select type Copybook, select Schema, and provide the location of the schema file.

  5. From the list of available data segments drop-down menu that appears, choose the one you need and click Select to save the configuration.

  6. Drag a DataWeave transformer in front of the IBM CTG component in the flow.

    Metadata fields become available to build the mapping.

    Metadata fields

    Having a metadata definition is not required to use IBM CTG Connector, but it is essential to improve the usability of the connector. See Create Metadata.

Load Java Metadata

In DataWeave, click Define Metadata to open the Metadata window.

  1. Click Add and provide an ID, such as CommareaRequest.

  2. Select type Java and then select a Java object in the Data Structure table.

  3. Search the class CommareaRequest or the fully qualified name org.mule.modules.ibmctg.internal.model.CommareaRequest, and click OK.

  4. Click Select to save the configuration.

  5. Perform the same steps to load metadata for the ChannelRequest type.

Use Case: XML

<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:bti="http://www.mulesoft.org/schema/mule/ee/bti"
	xmlns:ibmctg="http://www.mulesoft.org/schema/mule/ibmctg"
	xmlns:ee="http://www.mulesoft.org/schema/mule/ee/core"
	xmlns:http="http://www.mulesoft.org/schema/mule/http"
	xmlns="http://www.mulesoft.org/schema/mule/core"
	xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="
http://www.mulesoft.org/schema/mule/ee/bti
http://www.mulesoft.org/schema/mule/ee/bti/current/mule-bti-ee.xsd
http://www.mulesoft.org/schema/mule/core
http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/http
http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/ee/core
http://www.mulesoft.org/schema/mule/ee/core/current/mule-ee.xsd
http://www.mulesoft.org/schema/mule/ibmctg
http://www.mulesoft.org/schema/mule/ibmctg/current/mule-ibmctg.xsd">
	<configuration-properties file="automation-credentials.properties"/>
	<http:listener-config
		name="HTTP_Listener_config"
		doc:name="HTTP Listener config"
		basePath="/" >
		<http:listener-connection host="0.0.0.0" port="8081" />
	</http:listener-config>
	<bti:transaction-manager />
	<ibmctg:config name="IBMCTG_Config" doc:name="IBMCTG Config">
		<ibmctg:connection host="${config.host}"
		port="${config.port}"
		serverName="${config.serverName}"
		username="${config.username}"
		password="${config.password}" />
	</ibmctg:config>
	<flow name="ibmdemoFlow">
		<http:listener doc:name="/ec01"
			config-ref="HTTP_Listener_config"
			path="/ec01"/>
		<ee:transform doc:name="Transform Message">
			<ee:message >
				<ee:set-payload ><![CDATA[%dw 2.0
output application/flatfile schemaPath = "ec01-type.ffd", segmentIdent = "DFHCOMMAREA"
---
[{
	"LK-DATE-OUT": "",
	"LK-SPACE-OUT": "",
	"LK-TIME-OUT": "",
	"LK-LOWVAL-OUT": ""
}]]]></ee:set-payload>
			</ee:message>
			<ee:variables >
				<ee:set-variable variableName="request" ><![CDATA[%dw 2.0

output application/java
---
{
	commareaLength: 18,
	encoding: "IBM037",
	programName: "EC01",
	replyLength: 18,
	tpnName: "CSMI"
} as Object {
	class : "org.mule.modules.ibmctg.internal.model.CommareaRequest"
}]]></ee:set-variable>
			</ee:variables>
		</ee:transform>
		<ibmctg:execute-using-commarea doc:name="Execute using commarea"
		commareaRequestType="#[vars.request]" config-ref="IBMCTG_Config"/>
		<ee:transform doc:name="Transform Message">
			<ee:message >
				<ee:set-payload ><![CDATA[%dw 2.0
output application/json
---
{
	date:payload
}]]></ee:set-payload>
			</ee:message>
		</ee:transform>
	</flow>
	<flow name="ibmdemoFlow2">
		<http:listener doc:name="/ec02" config-ref="HTTP_Listener_config" path="/ec02"/>
		<try doc:name="Try" transactionalAction="ALWAYS_BEGIN" transactionType="XA">
			<ee:transform doc:name="Transform Message">
				<ee:message>
					<ee:set-payload ><![CDATA[%dw 2.0
output application/flatfile schemaPath = "ec02-type.ffd" , segmentIdent = "DFHCOMMAREA"
---
[{
	"LK-COUNT": "000001234TH RUN OF EC02"
}]]]></ee:set-payload>
				</ee:message>
				<ee:variables >
					<ee:set-variable variableName="request" ><![CDATA[%dw 2.0
output application/java
---
{
	commareaLength: 40,
	encoding: "IBM037",
	programName: "EC02",
	replyLength: 40,
	tpnName: "CSMI"
} as Object {
	class : "org.mule.modules.ibmctg.internal.model.CommareaRequest"
}]]></ee:set-variable>
				</ee:variables>
			</ee:transform>
			<ibmctg:execute-using-commarea doc:name="Execute using commarea"
			config-ref="IBMCTG_Config" commareaRequestType="#[vars.request]"/>
			<ee:transform doc:name="Transform Message">
				<ee:message >
					<ee:set-payload ><![CDATA[%dw 2.0
output application/json
---
{
	count:payload
}]]></ee:set-payload>
				</ee:message>
			</ee:transform>
		</try>
	</flow>
	<flow name="ibmdemoFlow1">
		<http:listener doc:name="/ec03" config-ref="HTTP_Listener_config" path="/ec03"/>
		<try doc:name="Try" transactionalAction="ALWAYS_BEGIN" transactionType="XA">
			<ee:transform doc:name="Transform Message">
				<ee:message >
					<ee:set-payload ><![CDATA[%dw 2.0
output application/flatfile
schemaPath = "ec03-type.ffd" , segmentIdent = "DFHCOMMAREA"
---
[{
	"CICS-DATE-TM": null
}]]]></ee:set-payload>
				</ee:message>
				<ee:variables >
					<ee:set-variable variableName="request" ><![CDATA[%dw 2.0

output application/java
---
{
	channel: "EC03",
	encoding: "US-ASCII",
	errorContainer: "OUTPUTMESSAGE",
	programName: "EC03",
	requestContainer: "INPUTDATA",
	responseContainer: "CICSDATETIME",
	tpnName: "CSMI"
} as Object {
	class : "org.mule.modules.ibmctg.internal.model.ChannelRequest"
}]]></ee:set-variable>
				</ee:variables>
			</ee:transform>
			<ibmctg:execute doc:name="Execute" channelRequest="#[vars.request]"
			config-ref="IBMCTG_Config"/>
			<ee:transform doc:name="Transform Message">
				<ee:message >
					<ee:set-payload ><![CDATA[%dw 2.0
output application/json
---
{
	"cics-date-time":payload
}
]]></ee:set-payload>
				</ee:message>
			</ee:transform>
		</try>
	</flow>
</mule>

We use cookies to make interactions with our websites and services easy and meaningful, to better understand how they are used and to tailor advertising. You can read more and make your cookie choices here. By continuing to use this site you are giving us your consent to do this.