CICS

Since Camel 4.10

Only producer is supported

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

Maven users will need to add the following dependency to their pom.xml for this component:

<dependency>
    <groupId>org.fusesource</groupId>
    <artifactId>camel-cics</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>

Only synchronous mode calls are supported.

URI format

cics://[interfaceType]/[dataExchangeType][?options]

Where interfaceType is the CICS set of the external API that this component will invoke. At the moment, only ECI (External Call Interface) is supported. This component can communicate with 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 use commarea:

cics://eci?host=xxx&port=xxx...

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

cics://eci/channel?host=xxx&port=xxx...

Configuring Options

Camel components are configured on two separate levels:

  • component level

  • endpoint level

Configuring Component Options

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.

Configuring Endpoint Options

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.

Component Options

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

Name Description Default Type

ctgDebug (producer)

Enable debug mode on the underlying IBM CTG client.

false

Boolean

eciBinding (producer)

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

CICSEciBinding

eciTimeout (producer)

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 (producer)

Encoding to convert COMMAREA data to before sending.

Cp1145

String

gatewayFactory (producer)

Autowired The connection factory to be use.

CICSGatewayFactory

host (producer)

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

localhost

String

initialFlow (producer)

When a JavaGateway instance connects to a remote Gateway, an initial flow takes place.

false

Boolean

lazyStartProducer (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.

false

boolean

port (producer)

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

2006

int

protocol (producer)

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

tcp

String

server (producer)

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

String

sslKeyring ( security)

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

String

sslPassword ( security)

The password for the encrypted key ring class or keystore.

String

autowiredEnabled (advanced)

Whether autowiring is enabled. This is used for automatic autowiring options (the option must be marked as autowired) by looking up in the registry to find if there is a single instance of matching type, which then gets configured on the component. This can be used for automatic configuring JDBC data sources, JMS connection factories, AWS Clients, etc.

true

boolean

configuration (advanced)

Autowired To use a shared CICS configuration.

CICSConfiguration

socketConnectionTimeout (advanced)

The socket connection timeout.

0

int

password (security)

Password to use for authentication.

String

userId (security)

User ID to use for authentication.

String

Endpoint Options

The CICS endpoint is configured using URI syntax:

cics://interfaceType/[dataExchangeType][?options]

With the following path and query parameters:

Path Parameters (3 parameters)

Name Description Default Type

interfaceType (producer)

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

eci

String

dataExchangeType (producer)

Use channel instead of commarea data structure.

Enum values:

  • channel

  • commarea

commarea

CICSDataExchangeType

callType (producer)

CICS ECI call type. The default value is ECI_SYNC.

1

int

Query Parameters (16 parameters)

Name Description Default Type

ctgDebug (producer)

Enable debug mode on the underlying IBM CTG client.

false

Boolean

eciBinding (producer)

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

CICSEciBinding

eciTimeout (producer)

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 (producer)

Encoding to convert COMMAREA data to before sending.

Cp1145

String

gatewayFactory (producer)

Autowired The connection factory to be use.

CICSGatewayFactory

host (producer)

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

localhost

String

initialFlow (producer)

When a JavaGateway instance connects to a remote Gateway, an initial flow takes place.

false

Boolean

port (producer)

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

2006

int

protocol (producer)

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

tcp

String

server (producer)

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

String

lazyStartProducer (producer (advanced))

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.

false

boolean

sslKeyring ( security)

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

String

sslPassword ( security)

The password for the encrypted key ring class or keystore.

String

socketConnectionTimeout (advanced)

The socket connection timeout.

0

int

password (security)

Password to use for authentication.

String

userId (security)

User ID to use for authentication.

String

Message Headers

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

Name Description Default Type

CICS_RETURN_CODE (producer)

Constant: CICS_RETURN_CODE_HEADER

Return code from this flow operation.

int

CICS_RETURN_CODE_STRING (producer)

Constant: 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.

String

CICS_EXTEND_MODE (producer)

Constant: CICS_EXTEND_MODE_HEADER

Extend mode of request. The default value is ECI_NO_EXTEND.

int

CICS_LUW_TOKEN (producer)

Constant: CICS_LUW_TOKEN_HEADER

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

int

CICS_PROGRAM_NAME (producer)

Constant: CICS_PROGRAM_NAME_HEADER

Program to invoke on CICS server.

String

CICS_TRANSACTION_ID (producer)

Constant: CICS_TRANSACTION_ID_HEADER

Transaction ID to run CICS program under.

String

CICS_COMM_AREA_SIZE (producer)

Constant: CICS_COMM_AREA_SIZE_HEADER

Length of COMMAREA. The default value is 0.

int

CICS_CHANNEL_NAME (producer)

Constant: CICS_CHANNEL_NAME_HEADER

The name of the channel to create.

String

CICS_CONTAINER_NAME (producer)

Constant: CICS_CONTAINER_NAME_HEADER

The name of the container to create.

String

CICS_CHANNEL_CCSID (producer)

Constant: CICS_CHANNEL_CCSID_HEADER

The CCSID the channel should set as its default.

int

CICS_SERVER (producer)

Constant: CICS_SERVER_HEADER

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

String

CICS_USER_ID (producer)

Constant: CICS_USER_ID_HEADER

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

String

CICS_PASSWORD (producer)

Constant: CICS_PASSWORD_HEADER

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

String

CICS_ABEND_CODE (producer)

Constant: CICS_ABEND_CODE_HEADER

CICS transaction abend code.

String

CICS_ECI_REQUEST_TIMEOUT (producer)

Constant: 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 (producer)

Constant: CICS_ENCODING_HEADER

Encoding to convert COMMAREA data to before sending the request.

String

CICS_CALL_TYPE (producer)

Constant: CICS_CALL_TYPE_HEADER

CICS ECI call type. The default value is ECI_SYNC.

int

Samples

Use Commarea

In the following sample we configure a route that run 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.

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");

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 Caamel Exchange Body.

Use Channel with a single input container

In the sample below we 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");

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.

Use Channel with multiple input 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");