Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 23. CICS

Since Camel 4.4-redhat

Only producer is supported.

This component allows you to interact with the IBM CICS® general-purpose transaction processing subsystem.

Note

Only synchronous mode call are supported.

23.1. Dependencies
Copy link

When using camel-cics with Red Hat build of Camel Spring Boot, add the following Maven dependency to your pom.xml to have support for auto configuration: 

<dependency>
    <groupId>org.apache.camel.springboot</groupId>
    <artifactId>camel-cics-starter</artifactId>
</dependency>
Copy to Clipboard Toggle word wrap

You must also declare the ctgclient.jar dependency when working with camel-cics starer. 

<dependency>
    <artifactId>com.ibm</artifactId>
    <groupId>ctgclient</groupId>
    <scope>system</scope>
    <systemPath>${basedir}/lib/ctgclient.jar</systemPath>
</dependency>
Copy to Clipboard Toggle word wrap

This JAR is provided by IBM and is included in the cics system.

23.2. URI format
Copy link

cics://[interfaceType]/[dataExchangeType][?options]
Copy to Clipboard Toggle word wrap

Where interfaceType is the CICS set of the external API that the camel-cics invokes. At the moment, only ECI (External Call Interface) is supported. This component communicates with the CICS server using two kinds of dataExchangeType.

  • commarea is a block of storage, limited to 32763 bytes, allocated by the program.
  • channel is the new mechanism for exchanging data, analogous to a parameter list.

By default, if dataExchangeType is not specified, this component uses commarea: 

cics://eci?host=xxx&port=xxx...
Copy to Clipboard Toggle word wrap

To use the channel and the container you must specify it explicitly in the URI 

cics://eci/channel?host=xxx&port=xxx...
Copy to Clipboard Toggle word wrap

23.3. Configuring Options
Copy link

Camel components are configured on two separate levels:

  • component level
  • endpoint level

23.3.1. Configuring Component Options
Copy link

At the component level, you set general and shared configurations that are, then, inherited by the endpoints. It is the highest configuration level. For example, a component may have security settings, credentials for authentication, urls for network connection and so forth. Some components only have a few options, and others may have many. Because components typically have pre-configured defaults that are commonly used, then you may often only need to configure a few options on a component; or none at all.

You can configure components using:

  • the Component DSL.
  • in a configuration file (application.properties, *.yaml files, etc).
  • directly in the Java code.

23.3.2. Configuring Endpoint Options
Copy link

You usually spend more time setting up endpoints because they have many options. These options help you customize what you want the endpoint to do. The options are also categorized into whether the endpoint is used as a consumer (from), as a producer (to), or both.

Configuring endpoints is most often done directly in the endpoint URI as path and query parameters. You can also use the Endpoint DSL and DataFormat DSL as a type safe way of configuring endpoints and data formats in Java.

A good practice when configuring options is to use Property Placeholders.

Property placeholders provide a few benefits:

  • They help prevent using hardcoded urls, port numbers, sensitive information, and other settings.
  • They allow externalizing the configuration from the code.
  • They help the code to become more flexible and reusable.

The following two sections list all the options, firstly for the component followed by the endpoint.

23.4. Component Options
Copy link

The CICS component supports 17 options, which are listed below.

Expand
NameDescriptionDefaultType

ctgDebug

Enable debug mode on the underlying IBM CGT client.

false

java.lang.Boolean

eciBinding

The Binding instance to transform a Camel Exchange to EciRequest and vice versa

 

com.redhat.camel.component.cics.CICSEciBinding

eciTimeout

The ECI timeout value associated with this ECIRequest object. An ECI timeout value of zero indicates that this ECIRequest will not be timed out by CICS Transaction Gateway. An ECI timeout value greater than zero indicates that the ECIRequest may be timed out by CICS Transaction Gateway. ECI timeout can expire before a response is received from CICS. This means that the client does not receive the confirmation from CICS that a unit of work has been backed out or committed.

0

short

encoding

The transfer encoding of the message.

Cp1145

java.lang.String

gatewayFactory

The connection factory to be used

 

com.redhat.camel.component.cics.pool.CICSGatewayFactory

host

The address of the CICS Transaction Gateway that this instance connects to

 

java.lang.String

lazyStartProducer

Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing.

 

boolean

port

The port of the CICS Transaction Gateway that this instance connects to.

2006

int

protocol

the protocol that this component will use to connect to the CICS Transaction Gateway.

tcp

java.lang.String

server

The address of the CICS server that this instance connects to.

 

java.lang.String

sslKeyring

The full classname of the SSL key ring class or keystore file to be used for the client encrypted connection.

 

java.lang.String

sslPassword

The password for the encrypted key ring class or keystore

 

java.lang.String

configuration

To use a shared CICS configuration

 

com.redhat.camel.component.cics.CICSConfiguration

socketConnectionTimeout

The socket connection timeout

 

int

password

Password to use for authentication

 

java.lang.String

userId

User ID to use for authentication

 

java.lang.String

23.5. Endpoint Options
Copy link

The CICS endpoint is configured using URI syntax: 

cics://[interfaceType]/[dataExchangeType][?options]
Copy to Clipboard Toggle word wrap

With the following path and query parameters:

23.5.1. Path Parameters (2 parameters)
Copy link

Expand
NameDescriptionDefaultType

interfaceType

The interface type, can be eci, esi or epi. at the moment only eci is supported.

eci

java.lang.String

dataExchangeType

The kind of data exchange to use Enum value:

  • commarea
  • channel

commarea

com.redhat.camel.component.cics.support.CICSDataExchangeType

23.5.2. Query Parameters (15 parameters)
Copy link

Expand
NameDescriptionDefaultType

ctgDebug

Enable debug mode on the underlying IBM CGT client.

false

java.lang.Boolean

eciBinding

The Binding instance to transform a Camel Exchange to EciRequest and vice versa

 

com.redhat.camel.component.cics.CICSEciBinding

eciTimeout

The ECI timeout value associated with this ECIRequest object. An ECI timeout value of zero indicates that this ECIRequest will not be timed out by CICS Transaction Gateway. An ECI timeout value greater than zero indicates that the ECIRequest may be timed out by CICS Transaction Gateway. ECI timeout can expire before a response is received from CICS. This means that the client does not receive the confirmation from CICS that a unit of work has been backed out or committed.

0

short

encoding

Encoding to convert COMMAREA data to before sending.

Cp1145

java.lang.String

gatewayFactory

The connection factory to use

 

com.redhat.camel.component.cics.pool.CICSGatewayFactory

host

The address of the CICS Transaction Gateway that this instance connects to

localhost

java.lang.String

port

The port of the CICS Transaction Gateway that this instance connects to.

2006

int

protocol

the protocol that this component will use to connect to the CICS Transaction Gateway.

tcp

java.lang.String

server

The address of the CICS server that this instance connects to

 

java.lang.String

lazyStartProducer

Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing.

 

boolean

sslKeyring

The full class name of the SSL key ring class or keystore file to be used for the client encrypted connection

 

java.lang.String

sslPassword

The password for the encrypted key ring class or keystore

 

java.lang.String

socketConnectionTimeout

The socket connection timeout

 

int

password

Password to use for authentication

 

java.lang.String

userId

User ID to use for authentication

 

java.lang.String

23.6. Message Headers
Copy link

The CICS component supports 15 message header(s), which is/are listed below:

Expand
NameDescriptionDefaultType

CICS_RETURN_CODE
Constant: com.redhat.camel.component.cics.CICSConstants#CICS_RETURN_CODE_HEADER

Return code from this flow operation.

 

int

CICS_RETURN_CODE_STRING
Constant: com.redhat.camel.component.cics.CICSConstants#CICS_RETURN_CODE_STRING_HEADER

The CICS return code as a String. The String is the name of the appropriate Java constant, for example, if this header is ECI_NO_ERROR, then the String returned will be ECI_NO_ERROR. If this header is unknown then the String returned will be ECI_UNKNOWN_CICS_RC.

Note

For CICS return codes that may have more than one meaning the String returned is a concatenation of the return codes. The only concatenated String is: ECI_ERR_REQUEST_TIMEOUT_OR_ERR_NO_REPLY.

 

java.ang.String

CICS_EXTEND_MODE
Constant: com.redhat.camel.component.cics.CICSConstants#CICS_EXTEND_MODE_HEADER

Extend mode of request. The default value is ECI_NO_EXTEND.

 

int

CICS_LUW_TOKEN
Constant: com.redhat.camel.component.cics.CICSConstants#CICS_LUW_TOKEN_HEADER

Extended Logical Unit of Work token. The default value is ECI_LUW_NEW.

 

int

CICS_PROGRAM_NAME
Constant: com.redhat.camel.component.cics.CICSConstants#CICS_PROGRAM_NAME_HEADER

Program to invoke on CICS server.

 

java.lang.String

CICS_TRANSACTION_ID
Constant: com.redhat.camel.component.cics.CICSConstants#CICS_TRANSACTION_ID_HEADER

Transaction ID to run CICS program under.

 

java.lang.String

CICS_COMM_AREA_SIZE
Constant: com.redhat.camel.component.cics.CICSConstants#CICS_COMM_AREA_SIZE_HEADER

Length of COMMAREA. The default value is 0.

 

int

CICS_CHANNEL_NAME
Constant: com.redhat.camel.component.cics.CICSConstants#CICS_CHANNEL_NAME_HEADER

The name of the channel to create com.redhat.camel.component.cics.CICSConstants#CICS_CHANNEL_NAME_HEADER

 

java.lang.String

CICS_CONTAINER_NAME
Constant: com.redhat.camel.component.cics.CICSConstants#CICS_CONTAINER_NAME_HEADER

The name of the container to create.

 

java.lang.String

CICS_CHANNEL_CCSID
Constant: com.redhat.camel.component.cics.CICSConstants#CICS_CHANNEL_CCSID_HEADER

The CCSID the channel should set as its default.

 

int

CICS_SERVER
Constant: com.redhat.camel.component.cics.CICSConstants#CICS_SERVER_HEADER

CICS server to direct request to. This header overrides the value configured in the endpoint.

 

java.lang.String

CICS_USER_ID
Constant: com.redhat.camel.component.cics.CICSConstants#CICS_USER_ID_HEADER

User ID for CICS server. This header overrides the value configured in the endpoint.

 

java.lang.String

CICS_PASSWORD
Constant: com.redhat.camel.component.cics.CICSConstants#CICS_PASSWORD_HEADER

Password or password phrase for CICS server. This header overrides the value configured in the endpoint.

 

java.lang.String

CICS_ABEND_CODE
Constant: com.redhat.camel.component.cics.CICSConstants#CICS_ABEND_CODE_HEADER

CICS transaction abend code.

 

java.lang.String

CICS_ECI_REQUEST_TIMEOUT
Constant: com.redhat.camel.component.cics.CICSConstants#CICS_ECI_REQUEST_TIMEOUT_HEADER

The value, in seconds, of the ECI timeout for the current ECIRequest. A value of zero indicates that this ECIRequest will not be timed out by CICS Transaction Gateway

0

short

CICS_ENCODING
Constant: com.redhat.camel.component.cics.CICSConstants#CICS_ENCODING_HEADER

Encoding to convert COMMAREA data to before sending.

 

String

23.7. Samples
Copy link

23.7.1. Using Commarea
Copy link

Following sample show how to configure a route that runs a program on a CICS server using COMMAREA. The COMMAREA size has to be defined in CICS_COMM_AREA_SIZE header, while the COMMAREA input data is defined in the Camel Exchange body.

Note

You must create a COMMAREA that is large enough to contain all the information to be sent to the server and large enough to contain all the information that can be returned from the server. 

//.....
import static com.redhat.camel.component.cics.CICSConstants.CICS_PROGRAM_NAME_HEADER;
import static com.redhat.camel.component.cics.CICSConstants.CICS_COMM_AREA_SIZE_HEADER;
//....

from("direct:run").
   setHeader(CICS_PROGRAM_NAME_HEADER, "ECIREADY").
   setHeader(CICS_COMM_AREA_SIZE_HEADER, 18).
   setBody(constant("My input data")).
   to("cics:eci/commarea?host=192.168.0.23&port=2006&protocol=tcp&userId=foo&password=bar");
Copy to Clipboard Toggle word wrap

The Outcome of the CICS program invocation is mapped to Camel Exchange in this way:

  • The numeric value of return code is stored in the CICS_RETURN_CODE header
  • The COMMAREA output data is stored in the Camel Exchange Body.

Following sample shows how to use a channel with a single container to run a CICS program. The channel name and the container name are taken from headers, and the container value from the body: 

//.....
import static com.redhat.camel.component.cics.CICSConstants.CICS_PROGRAM_NAME_HEADER;
import static com.redhat.camel.component.cics.CICSConstants.CICS_CHANNEL_NAME_HEADER;
import static com.redhat.camel.component.cics.CICSConstants.CICS_CONTAINER_NAME_HEADER;

//...
from("direct:run").
  setHeader(CICS_PROGRAM_NAME_HEADER, "EC03").
  setHeader(CICS_CHANNEL_NAME_HEADER, "SAMPLECHANNEL").
  setHeader(CICS_CONTAINER_NAME_HEADER, "INPUTDATA").
  setBody(constant("My input data")).
  to("cics:eci/channel?host=192.168.0.23&port=2006&protocol=tcp&userId=foo&password=bar");
Copy to Clipboard Toggle word wrap

The container(s) returned is stored in an java.util.Map<String,Object>, the key is the container name and the value is the output data of the container.

If you need to run a CICS program that takes multiple container as input, you can create a java.util.Map<String,Object> where the keys are the container names and the values are the input data. In this case the CICS_CONTAINER_NAME header is ignored. 

//.....
import static com.redhat.camel.component.cics.CICSConstants.CICS_PROGRAM_NAME_HEADER;
import static com.redhat.camel.component.cics.CICSConstants.CICS_CHANNEL_NAME_HEADER;

//...
from("direct:run").
  setHeader(CICS_PROGRAM_NAME_HEADER, "EC03").
  setHeader(CICS_CHANNEL_NAME_HEADER, "SAMPLECHANNEL").
  process(exchange->{
    byte[] thirdContainerData = HexFormat.of().parseHex("e04fd020ea3a6910a2d808002b30309d");
    Map<String,Object> containers = Map.of(
           "firstContainerName", "firstContainerData",
           "secondContainerName", "secondContainerData",
           "thirdContainerName", thirdContainerData
    );
    exchange.getMessage().setBody(containers);
  }).
  to("cics:eci/channel?host=192.168.0.23&port=2006&protocol=tcp&userId=foo&password=bar");
Copy to Clipboard Toggle word wrap

23.8. Spring Boot Auto-Configuration
Copy link

The component supports 17 options, which are listed below.

Expand
NameDescriptionDefaultType

camel.component.cics.binding

The Binding instance to transform a Camel Exchange to EciRequest and vice versa.

 

com.redhat.camel.component.cics.CICSEciBinding

camel.component.cics.configuration

Configuration.

 

com.redhat.camel.component.cics.CICSConfiguration

camel.component.cics.ctg-debug

Enable debug mode on the underlying IBM CGT client.

 

java.lang.Boolean

camel.component.cics.eci-timeout

The ECI timeout value associated with this ECIRequest object. An ECI timeout value of zero indicates that this ECIRequest will not be timed out by CICS Transaction Gateway. An ECI timeout value greater than zero indicates that the ECIRequest may be timed out by CICS Transaction Gateway. ECI timeout can expire before a response is received from CICS. This means that the client does not receive the confirmation from CICS that a unit of work has been backed out or committed.

 

java.lang.Short

camel.component.cics.enabled

Whether to enable auto configuration of the cics component. This is enabled by default.

 

java.lang.Boolean

camel.component.cics.encoding

The transfer encoding of the message.

Cp1145

java.lang.String

camel.component.cics.gateway-factory

The connection factory to be use. The option is a com.redhat.camel.component.cics.pool.CICSGatewayFactory type.

 

com.redhat.camel.component.cics.pool.CICSGatewayFactory

camel.component.cics.host

The address of the CICS Transaction Gateway that this instance connects to

 

java.lang.String

camel.component.cics.lazy-start-producer

Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing.

 

java.lang.Boolean

camel.component.cics.password

Password to use for authentication

 

java.lang.String

camel.component.cics.port

The port of the CICS Transaction Gateway that this instance connects to.

2006

java.lang.Integer

camel.component.cics.protocol

the protocol that this component will use to connect to the CICS Transaction Gateway.

tcp

java.lang.String

camel.component.cics.server

The address of the CICS server that this instance connects to

 

java.lang.String

camel.component.cics.socket-connection-timeout

The socket connection timeout

 

java.lang.Integer

camel.component.cics.ssl-keyring

The full classname of the SSL key ring class or keystore file to be used for the client encrypted connection

 

java.lang.String

camel.component.cics.ssl-password

The password for the encrypted key ring class or keystore

 

java.lang.String

camel.component.cics.user-id

User ID to use for authentication

 

java.lang.String

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat