Contact Us 1-800-596-4880
  1. Homepage

  2. IBM CICS Transaction Gateway Connector (0.3.9)

All Connectors

IBM CICS Transaction Gateway Connector - Mule 3

Anypoint Connector for IBM CICS Transaction Gateway (IBM CTG Connector) provides integration with back-end CICS applications using the CICS Transaction Gateway. For Java platforms, CTG implements the JCA resource adapter to connect Java applications to the CICS system. This connector provides access between Mule applications and the CTG.

Release Notes: IBM CICS Transaction Gateway Connector Release Notes
Exchange: IBM CICS Transaction Gateway Connector

Before You Begin

To use this information, you should be familiar with Mule runtime engine (Mule), Anypoint Connectors, Anypoint Studio essentials, elements in a Mule flow, and global elements.

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.

Install the Connector

  1. In Anypoint Studio, click the (X) Exchange icon in the Studio taskbar.

  2. In Anypoint Exchange, click Login

  3. In Exchange, search for this connector, select the connector’s card, and click Install.

  4. Follow the prompts to install the connector.

Connector Namespace and Schema

In Anypoint Studio, when you drag the connector from the palette onto the Anypoint Studio canvas, Studio automatically populates the XML code with the connector namespace and schema location.

Namespace: http://www.mulesoft.org/schema/mule/ibm-ctg
Schema Location: http://www.mulesoft.org/schema/mule/connector/current/mule-ibm-ctg.xsd

If you are manually coding the Mule application in Studio’s XML editor or another text editor, define the namespace and schema location in the header of your Configuration XML, inside the <mule> tag.

<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:ibm-ctg="http://www.mulesoft.org/schema/mule/ibm-ctg"
      xsi:schemaLocation="
               http://www.mulesoft.org/schema/mule/core
               http://www.mulesoft.org/schema/mule/core/current/mule.xsd
               http://www.mulesoft.org/schema/mule/ibm-ctg
               http://www.mulesoft.org/schema/mule/ibm-ctg/current/mule-ibm-ctg.xsd">

      <!-- put your global configuration elements and flows here -->

</mule>

Note: Use current in the schema path. Studio interprets this to the current Mule version.

Maven Dependency Information

For Maven dependency management, include this XML snippet in your pom.xml file.

<dependency>
  <groupId>org.mule.modules</groupId>
  <artifactId>mule-ibmctg-connector</artifactId>
  <version>x.x.x</version>
</dependency>

Replace x.x.x with the version that corresponds to the connector you are using.

To obtain the most up-to-date pom.xml file information, access the connector in Anypoint Exchange and click Dependency Snippets.

Configure the Connector

Place the connector in your flow as applicable for your use case.

To use the IBM CTG connector in your Mule application, configure a global IBM CTG Configuration element that can be used by the connector.

The IBM CTG connector provides the following global configuration:

Field Description

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.

Keystore Location

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

Keystore Password

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

Connection Timeout

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

Response Timeout

Enter the response timeout value for a connection to CTG. This timeout represents the maximum amount of time in milliseconds that a managed connection attempts to wait for a response for a request. A value of 0 represents no timeout. Default value is 30000 milliseconds (30 seconds). †

CTG Trace

If checked, all debug levels of CTG tracing are turned on. Default value is false.

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

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

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

ibm ctg global el props

Operations

The IBM CTG connector supports the following four operations:

Name Description

Create ChannelAndContent Instance

Create an instance of ChannelAndContent to use in the input list of the Execute with multiple channels operation.

Execute

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

Execute using COMMAREA

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

Execute with multiple channels

Invoke a CICS program with multiple channels and containers.

Connector Performance

To define the pooling profile for the connector manually, access the Pooling Profile tab in the applicable global element for the connector.

For background information on pooling, see Tuning Performance.

Enable Logging

To enable logging of the interactions of the connector with IBM CTG (request and response), configure a logger in the log4j2.xml file of the Mule application as follows (inside the Loggers tag in log4j2.xml):

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

This feature is available in IBM CTG Connector version 1.2.2 and later.

Use Cases

To successfully run use cases 1 to 3, the invoked CICS programs must be available on the target CICS system.

Use Case 1: Invoke a COMMAREA Program

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

ibm ctg use case 1

  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 connector onto the canvas and leave the default values for Host and Port and set the path to /test/ec01.

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

    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 connection 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 components. The connector does not provide dynamic/static metadata but allows users to define custom types using the Metadata Type tool.

    1. 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 }

    2. Map the fields in the DataWeave transformer.

      %dw 1.0
%output text/plain schemaPath = "ec01-type.ffd", segmentIdent = "DFHCOMMAREA", encoding="cp037"
---
[{
    LK-DATE-OUT: "",
    LK-SPACE-OUT: "",
    LK-TIME-OUT: "",
    LK-LOWVAL-OUT: ""
}]

    3. Create a flowVar named commareaRequest and configure the following fields (see section Load Java Metadata):

      %dw 1.0
%output application/java
---
{
  commareaLength: 18,
  encoding: "IBM037",
  programName: "EC01",
  replyLength: 18,
  tpnName: "CSMI"
} as :object {
  class : "org.mule.modules.ibmctg.internal.model.CommareaRequest"
}

      See Load Java Metadata to obtain metadata for the CommareaRequest.

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

    %dw 1.0
%output application/json
---
{
  date: payload[0].LK-DATE-OUT,
  time: payload[0].LK-TIME-OUT
}

  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: "06/09/17",
    time: "13:41:17"
}

Use Case 2: Invoke a Channel Program

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

  • A data and 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.

ibm ctg use case 2

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

  2. Double-click the IBM CTG component, select the operation Execute 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 components.

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

      form: COPYBOOK
id: 'DFHCOMMAREA'
values:
- { name: 'CICS-DATE-TM', type: String, length: 8 }

    2. Map the fields in the DataWeave transformer.

      %dw 1.0
%output text/plain schemaPath = "ec03-type.ffd", segmentIdent = "DFHCOMMAREA", encoding="cp037"
---
[{
  CICS-DATE-TM: ""
}]

    3. Create a flowVar named request and configure the following fields (see section Load Java Metadata):

      %dw 1.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"
}

  4. Add a Transform Messager after the IBM CTG to convert the result into readable format.

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

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

    {
   cics-date-time: "06/09/2019 13:57:25"
}

Use Case 3: Invoke a COMMAREA or Channel Program inside a Transactional Scope

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

ibm ctg use case 3

  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 or static metadata but allows users to define custom types using the Metadata Type tool.

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

      form: COPYBOOK
id: 'DFHCOMMAREA'
values:
- { name: 'LK-COUNT', type: String, length: 40 }

    2. Map the fields in the DataWeave transformer.

      %dw 1.0
%output text/plain schemaPath = "ec02-type.ffd" , segmentIdent = "DFHCOMMAREA", encoding="cp037"
---
[{
  LK-COUNT: "000001234TH RUN OF EC02"
}]

    3. Create a flowVar named request and configure the following fields (see section Load Java Metadata):

      %dw 1.0
%output application/java
---
{
  commareaLength: 18,
  encoding: "IBM037",
  programName: "EC01",
  replyLength: 18,
  tpnName: "CSMI"
} as :object {
  class : "org.mule.modules.ibmctg.internal.model.CommareaRequest"
}

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

    %dw 1.0
%output application/json
---
{
  count: trim payload[0].LK-COUNT,
  lowVal: payload[0].LK-LOWVAL
}

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

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

    {
    count: "000001235TH RUN OF EC02",
    lowVal: null
}

Use Case 4: Invoke a Channel Program with Multiple Requests

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, 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.

  1. Perform Steps 1 to 3 from the previous example and set the HTTP path to /multiChannel.

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

    Parameter Value

    Encoding

    US-ASCII

    Channel And Content List Reference

    #[payload]

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

    1. In the payload use the schema file ec03-type.ffd to complete the fields for the content:

      %dw 1.0
%output text/plain schemaPath = "ec03-type.ffd", segmentIdent = "DFHCOMMAREA", encoding="cp037"
---
[{
	CICS-DATE-TM: ""
}]

    2. Create a flowVar named request and configure the following fields (see section Load Java Metadata):

      %dw 1.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"
}

  4. Add a IBM CTG component after the Transform Message and select the Create ChannelAndContent Instance operation:

    1. In the Content Reference set the #[payload] reference.

    2. In the Request Reference set the #[flowVars.request] reference.

    3. In the Target Property set the name of the variable (for example, ChannelAndContent1) where the result of operation save the new ChannelAndContent instance.

  5. After the previous component, add other Transform Message with the same content of the step 3.

  6. After the previous Transform Message, add other IBM CTG component and select the Create ChannelAndContent Instance operation:

    1. In the Content Reference set the #[payload] reference.

    2. In the Request Reference set the #[flowVars.request] reference.

    3. In the Target Property set the name of the variable (for example, ChannelAndContent2) where the result of operation save the new ChannelAndContent instance.

  7. After the previous IBM Component, add other Transform Message that stores the ChannelAndContent in a List, which is the Input of the operation Execute With Multiple Channels:

    %dw 1.0
%output application/java
---
[
	flowVars.ChannelAndContent1,
	flowVars.ChannelAndContent2
]

  8. Add a Transform Message after the IBM CTG Multiple Channel to convert the result into readable format.

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

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

    {
  "cics-date-time": [
    "20/03/2019 10:57:56",
    "20/03/2019 10:57:56"
  ]
}

Use Case 5: Add Custom Metadata

The IBM CTG connector does not provide dynamic or static metadata out-of-the-box, but allows users to define custom types using the Metadata Type tool. Follow the below guide to define input and output metadata:

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

    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 the Add metadata button. Select Input:Payload and click the Edit icon to open de Metadata Editor.

    ibm ctg use case 4 1

  3. Click Add to create a new type and provide and ID for it (that is, ec01-in-type for the program EC01 input data).

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

  5. This populates a drop-down with a list of available data segments. Choose the one you need and click the Select button to save the configuration.

    ibm ctg use case 4 2

  6. Drag a DataWeave transformer before the IBM CTG component. Metadata fields will become available to build the mapping.

    ibm ctg use case 4 3

Metadata definition is not a required step to use the IBM CTG connector but it is essential to improve the usability of the connector. Refer to Defining Metadata for additional information.

Use Case 6: Load Java Metadata

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

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

  2. Select type Java, then 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.

    ibm ctg use case 5

  4. Click Select to save the configuration.

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

See Also

Back to top
View on GitHub