Ce contenu n'est pas disponible dans la langue sélectionnée.
Chapter 20. 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.
Only synchronous mode call are supported.
20.1. Dependencies
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>
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>
This JAR is provided by IBM and is included in the cics system.
20.2. URI format
cics://[interfaceType]/[dataExchangeType][?options]
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.
-
commareais a block of storage, limited to 32763 bytes, allocated by the program. -
channelis 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...
To use the channel and the container you must specify it explicitly in the URI
cics://eci/channel?host=xxx&port=xxx...
20.3. Configuring Options
Camel components are configured on two levels:
- Component level
- Endpoint level
20.3.1. Component Level Options
The component level is the highest level. The configurations you define at this level are inherited by all the endpoints. For example, a component can have security settings, credentials for authentication, urls for network connection, and so on.
Since components typically have pre-configured defaults for the most common cases, you may need to only configure a few component options, or maybe none at all.
You can configure components with Component DSL in a configuration file (application.properties|yaml), or directly with Java code.
20.3.2. Endpoint Level Options
At the Endpoint level you have many options, which you can use to configure what you want the endpoint to do. The options are categorized according to whether the endpoint is used as a consumer (from) or as a producer (to) or used for both.
You can configure endpoints directly in the endpoint URI as path and query parameters. You can also use Endpoint DSL and DataFormat DSL as type safe ways of configuring endpoints and data formats in Java.
When configuring options, use Property Placeholders for urls, port numbers, sensitive information, and other settings.
Placeholders allows you to externalize the configuration from your code, giving you more flexible and reusable code.
20.4. Component Options
The CICS component supports 17 options, which are listed below.
| Name | Description | Default | Type |
|---|---|---|---|
| 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 |
20.5. Endpoint Options
The CICS endpoint is configured using URI syntax:
cics://[interfaceType]/[dataExchangeType][?options]
With the following path and query parameters:
20.5.1. Path Parameters (2 parameters)
| Name | Description | Default | Type |
|---|---|---|---|
| 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 | com.redhat.camel.component.cics.support.CICSDataExchangeType |
20.5.2. Query Parameters (15 parameters)
| Name | Description | Default | Type |
|---|---|---|---|
| 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 |
20.6. Message Headers
The CICS component supports 15 message header(s), which is/are listed below:
| Name | Description | Default | Type |
|---|---|---|---|
|
CICS_RETURN_CODE | Return code from this flow operation. | int | |
|
CICS_RETURN_CODE_STRING | 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 | Extend mode of request. The default value is ECI_NO_EXTEND. | int | |
|
CICS_LUW_TOKEN | Extended Logical Unit of Work token. The default value is ECI_LUW_NEW. | int | |
|
CICS_PROGRAM_NAME | Program to invoke on CICS server. | java.lang.String | |
|
CICS_TRANSACTION_ID | Transaction ID to run CICS program under. | java.lang.String | |
|
CICS_COMM_AREA_SIZE | Length of COMMAREA. The default value is 0. | int | |
|
CICS_CHANNEL_NAME | The name of the channel to create com.redhat.camel.component.cics.CICSConstants#CICS_CHANNEL_NAME_HEADER | java.lang.String | |
|
CICS_CONTAINER_NAME | The name of the container to create. | java.lang.String | |
|
CICS_CHANNEL_CCSID | The CCSID the channel should set as its default. | int | |
|
CICS_SERVER | CICS server to direct request to. This header overrides the value configured in the endpoint. | java.lang.String | |
|
CICS_USER_ID | User ID for CICS server. This header overrides the value configured in the endpoint. | java.lang.String | |
|
CICS_PASSWORD | Password or password phrase for CICS server. This header overrides the value configured in the endpoint. | java.lang.String | |
|
CICS_ABEND_CODE | CICS transaction abend code. | java.lang.String | |
|
CICS_ECI_REQUEST_TIMEOUT | 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 | Encoding to convert COMMAREA data to before sending. | String |
20.7. Samples
20.7.1. Using Commarea
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.
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_CODEheader - The COMMAREA output data is stored in the Camel Exchange Body.
20.7.2. Using Channel with a single input container
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");
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.
20.7.3. Using 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");20.8. Spring Boot Auto-Configuration
The component supports 17 options, which are listed below.
| Name | Description | Default | Type |
|---|---|---|---|
| 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 |
