Chapter 23. CICS Since Camel 4.4-redhat Only producer is supported. This component allows you to interact with the IBM CICS (R) general-purpose transaction processing subsystem. Note Only synchronous mode call are supported. 23.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. This JAR is provided by IBM and is included in the cics system. 23.2. URI format 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 : To use the channel and the container you must specify it explicitly in the URI 23.3. Configuring Options Camel components are configured on two separate levels: component level endpoint level 23.3.1. 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. 23.3.2. 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. 23.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 23.5. Endpoint Options The CICS endpoint is configured using URI syntax: With the following path and query parameters: 23.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 channel commarea com.redhat.camel.component.cics.support.CICSDataExchangeType 23.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 23.6. Message Headers The CICS component supports 15 message header(s), which is/are listed below: Name Description Default Type 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 23.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. 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"); 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. 23.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. 23.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"); 23.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

Commands:
<dependency> <groupId>org.apache.camel.springboot</groupId> <artifactId>camel-cics-starter</artifactId> </dependency>
<dependency> <artifactId>com.ibm</artifactId> <groupId>ctgclient</groupId> <scope>system</scope> <systemPath>USD{basedir}/lib/ctgclient.jar</systemPath> </dependency>
cics://[interfaceType]/[dataExchangeType][?options]
cics://eci?host=xxx&port=xxx
cics://eci/channel?host=xxx&port=xxx
cics://[interfaceType]/[dataExchangeType][?options]
//.. 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");
//.. 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");
//.. 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");