IBM CTG Connector Reference - Mule 4
IBM CICS Transaction Gateway Connector Version 2.3
Anypoint Connector for IBM CICS Transaction Gateway (IBM CTG Connector) provides integration with back-end CICS apps using the CICS Transaction Gateway.
Release Notes: IBM CICS Transaction Gateway Connector Release Notes
Configurations
Config
Parameters
Name | Type | Description | Default Value | Required |
---|---|---|---|---|
Name |
String |
The name for this configuration. Connectors reference the configuration with this name. |
x |
|
Connection |
The connection types to provide to this configuration. |
x |
||
Expiration Policy |
Configures the minimum amount of time that a dynamic configuration instance can remain idle before the runtime considers it eligible for expiration. This does not mean that the platform expires the instance at the exact moment that it becomes eligible. The runtime purges the instances when it sees fit. |
Connection Types
Connection
Parameters
Name | Type | Description | Default Value | Required |
---|---|---|---|---|
Host |
String |
localhost |
||
Port |
String |
2006 |
||
Servers name |
String |
x |
||
Username |
String |
x |
||
Password |
String |
x |
||
Keystore location |
String |
The location of the keystore containing the certificates required for an SSL connection. |
||
Keystore Password |
String |
The password required to access the keystore for an SSL connection. |
||
Connection Timeout |
Number |
Sets the socket connection timeout value for a connection to CICS TG. This timeout represents the maximum amount of time in milliseconds that a managed connection attempts to open a socket connection successfully to a remote Gateway daemon. The timeout is ignored for attempted connections to a local Gateway instance. A value of 0 represents no timeout. |
0 |
|
Response Timeout |
Number |
Set the response timeout value for a connection to CICS TG. This timeout represents the maximum amount of time in milliseconds that a managed connection attempts to wait for a response to a request. A value of 0 represents no timeout. |
30000 |
|
CTG Trace |
Boolean |
Turns all levels of CTG tracing on or off. |
false |
|
Reconnection |
When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment fails if the test doesn’t pass after exhausting the associated reconnection strategy. |
|||
Pooling Profile |
Characteristics of the connection pool. |
Operations
Create Channel And Content Instance
<ibmctg:create-channel-and-content-instance>
Create an instance of ChannelAndContent to use in the input list of the Execute with Multiple channels operation.
Parameters
Name | Type | Description | Default Value | Required |
---|---|---|---|---|
Content |
Binary |
The input data to be passed to the CICS program. |
x |
|
Request |
A ChannelRequest that contains the details for request to CTG, such as: program name, TPN, encoding, channel name and its containers (request, response and error). |
x |
||
Target Variable |
String |
The name of a variable to store the operation’s output. |
||
Target Value |
String |
An expression to evaluate against the operation’s output and store the expression outcome in the target variable. |
#[payload] |
Execute
<ibmctg:execute>
Parameters
Name | Type | Description | Default Value | Required |
---|---|---|---|---|
Configuration |
String |
The name of the configuration to use. |
x |
|
Content |
Binary |
#[payload] |
||
Channel Request |
x |
|||
Transactional Action |
Enumeration, one of:
|
The type of joining action that operations can take regarding transactions. |
JOIN_IF_POSSIBLE |
|
Streaming Strategy |
|
Configure to use repeatable streams. |
||
Target Variable |
String |
The name of a variable to store the operation’s output. |
||
Target Value |
String |
An expression to evaluate against the operation’s output and store the expression outcome in the target variable. |
#[payload] |
|
Reconnection Strategy |
A retry strategy in case of connectivity errors. |
Throws
-
IBMCTG:AEI0
-
IBMCTG:CONNECTION_ERROR
-
IBMCTG:CONNECTIVITY
-
IBMCTG:ECI_ERR_INVALID_CALL_TYPE
-
IBMCTG:ECI_ERR_NO_CICS
-
IBMCTG:ECI_ERR_SECURITY_ERROR
-
IBMCTG:ECOM
-
IBMCTG:ERR_GATEWAY
-
IBMCTG:IBMCCExecution
-
IBMCTG:REQUEST_ERROR
-
IBMCTG:RESOURCE
-
IBMCTG:RETRY_EXHAUSTED
-
IBMCTG:SERVER_ERROR
-
IBMCTG:TRANSACTION
-
IBMCTG:UNKNOWN
Execute Using Commarea
<ibmctg:execute-using-commarea>
Parameters
Name | Type | Description | Default Value | Required |
---|---|---|---|---|
Configuration |
String |
The name of the configuration to use. |
x |
|
Content |
Binary |
#[payload] |
||
Commarea Request Type |
x |
|||
Transactional Action |
Enumeration, one of:
|
The type of joining action that operations can take regarding transactions. |
JOIN_IF_POSSIBLE |
|
Streaming Strategy |
|
Configure to use repeatable streams. |
||
Target Variable |
String |
The name of a variable to store the operation’s output. |
||
Target Value |
String |
An expression to evaluate against the operation’s output and store the expression outcome in the target variable |
#[payload] |
|
Reconnection Strategy |
A retry strategy in case of connectivity errors |
Throws
-
IBMCTG:AEI0
-
IBMCTG:CONNECTION_ERROR
-
IBMCTG:CONNECTIVITY
-
IBMCTG:ECI_ERR_INVALID_CALL_TYPE
-
IBMCTG:ECI_ERR_NO_CICS
-
IBMCTG:ECI_ERR_SECURITY_ERROR
-
IBMCTG:ECOM
-
IBMCTG:ERR_GATEWAY
-
IBMCTG:IBMCCExecution
-
IBMCTG:REQUEST_ERROR
-
IBMCTG:RESOURCE
-
IBMCTG:RETRY_EXHAUSTED
-
IBMCTG:SERVER_ERROR
-
IBMCTG:TRANSACTION
-
IBMCTG:UNKNOWN
Execute With Multiple Channels
<ibmctg:execute-with-multiple-channels>
Calls a remote CICS program sending data encapsulated in channels and containers, allowing users to transfer more than 32 KB in a single request.
A container is a named reference to a storage area managed by CICS that can hold any form of application data. A container can hold data in any format that the application requires and is limited only by the amount of storage available. An application can reference any number of containers.
A channel is a uniquely named reference to a collection of containers. It is analogous to a COMMAREA, but it is not subject to its constraints. Programs can pass a single channel between them. You can think of a channel as a parameter list. The same channel can be passed from one program to another.
Channels and containers are visible only to the program that creates them, and to the programs that they are passed to. When these programs end, CICS automatically deletes the containers and their storage. They are not recoverable. If you require to use recoverable containers, use CICS BTS containers.
Parameters
Name | Type | Description | Default Value | Required |
---|---|---|---|---|
Configuration |
String |
The name of the configuration to use. |
x |
|
Channel And Contents |
Array of Channel And Content |
A java.util.List of ChannelAndContent containing one or more pairs with channel and the details for request to CTG, such as: program name, TPN, encoding, channel name, and its containers (request, response and error); with this respective content. |
#[payload] |
|
Transactional Action |
Enumeration, one of:
|
The type of joining action that operations can take regarding transactions. |
JOIN_IF_POSSIBLE |
|
Target Variable |
String |
The name of a variable to store the operation’s output. |
||
Target Value |
String |
An expression to evaluate against the operation’s output and store the expression outcome in the target variable |
#[payload] |
|
Reconnection Strategy |
A retry strategy in case of connectivity errors |
Throws
-
IBMCTG:AEI0
-
IBMCTG:CONNECTION_ERROR
-
IBMCTG:CONNECTIVITY
-
IBMCTG:ECI_ERR_INVALID_CALL_TYPE
-
IBMCTG:ECI_ERR_NO_CICS
-
IBMCTG:ECI_ERR_SECURITY_ERROR
-
IBMCTG:ECOM
-
IBMCTG:ERR_GATEWAY
-
IBMCTG:IBMCCExecution
-
IBMCTG:REQUEST_ERROR
-
IBMCTG:RESOURCE
-
IBMCTG:RETRY_EXHAUSTED
-
IBMCTG:SERVER_ERROR
-
IBMCTG:TRANSACTION
-
IBMCTG:UNKNOWN
Types
Reconnection
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Fails Deployment |
Boolean |
When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment fails if the test doesn’t pass after exhausting the associated reconnection strategy. |
||
Reconnection Strategy |
The reconnection strategy to use. |
Reconnect
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Frequency |
Number |
How often in milliseconds to reconnect. |
||
Count |
Number |
How many reconnection attempts to make. |
||
blocking |
Boolean |
If false, the reconnection strategy runs in a separate, non-blocking thread. |
true |
Reconnect Forever
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Frequency |
Number |
How often in milliseconds to reconnect. |
||
blocking |
Boolean |
If false, the reconnection strategy runs in a separate, non-blocking thread. |
true |
Pooling Profile
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Max Active |
Number |
Controls the maximum number of Mule components that can be borrowed from a session at one time. When set to a negative value, there is no limit to the number of components that may be active at one time. When maxActive is exceeded, the pool is said to be exhausted. |
||
Max Idle |
Number |
Controls the maximum number of Mule components that can sit idle in the pool at any time. When set to a negative value, there is no limit to the number of Mule components that may be idle at one time. |
||
Max Wait |
Number |
Specifies the number of milliseconds to wait for a pooled component to become available when the pool is exhausted and the exhaustedAction is set to WHEN_EXHAUSTED_WAIT. |
||
Min Eviction Millis |
Number |
Determines the minimum amount of time an object may sit idle in the pool before it is eligible for eviction. When non-positive, no objects will be evicted from the pool due to idle time alone. |
||
Eviction Check Interval Millis |
Number |
Specifies the number of milliseconds between runs of the object evictor. When non-positive, no object evictor is executed. |
||
Exhausted Action |
Enumeration, one of:
|
Specifies the behavior of the Mule component pool when the pool is exhausted. Possible values are: "WHEN_EXHAUSTED_FAIL", which will throw a NoSuchElementException, "WHEN_EXHAUSTED_WAIT", which will block by invoking Object.wait(long) until a new or idle object is available, or WHEN_EXHAUSTED_GROW, which will create a new Mule instance and return it, essentially making maxActive meaningless. If a positive maxWait value is supplied, it will block for at most that many milliseconds, after which a NoSuchElementException will be thrown. If maxThreadWait is a negative value, it will block indefinitely. |
||
Initialisation Policy |
Enumeration, one of:
|
Determines how components in a pool should be initialized. The possible values are: INITIALISE_NONE (will not load any components into the pool on startup), INITIALISE_ONE (will load one initial component into the pool on startup), or INITIALISE_ALL (will load all components in the pool on startup) |
||
Disabled |
Boolean |
Whether pooling should be disabled |
Expiration Policy
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Max Idle Time |
Number |
A scalar time value for the maximum amount of time a dynamic configuration instance should be allowed to be idle before it’s considered eligible for expiration |
||
Time Unit |
Enumeration, one of:
|
A time unit that qualifies the maxIdleTime attribute |
Channel Request
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Channel |
String |
The name of the channel. Value is case-sensitive. |
x |
|
Request Container |
String |
The name of the container used to send the request data to the CICS program. Value is case-sensitive. |
x |
|
Response Container |
String |
The name of the container used to return the data obtained from the CICS program. Value is case-sensitive. |
x |
|
Error Container |
String |
The name of the container used to return error information if something goes wrong in the CICS program. Value is case-sensitive. |
x |
|
Program Name |
String |
The name of the CICS program to call. It is case-sensitive. |
x |
|
Tpn Name |
String |
The transaction identifier of the CICS mirror transaction. Optional. |
||
Encoding |
String |
The data encoding. Default value is IBM037. |
IBM037 |
Repeatable In Memory Stream
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Initial Buffer Size |
Number |
The amount of memory that will be allocated to consume the stream and provide random access to it. If the stream contains more data than can be fit into this buffer, then the buffer expands according to the bufferSizeIncrement attribute, with an upper limit of maxInMemorySize. |
||
Buffer Size Increment |
Number |
This is by how much the buffer size expands if it exceeds its initial size. Setting a value of zero or lower means that the buffer should not expand, meaning that a STREAM_MAXIMUM_SIZE_EXCEEDED error is raised when the buffer gets full. |
||
Max Buffer Size |
Number |
The maximum amount of memory to use. If more than that is used then a STREAM_MAXIMUM_SIZE_EXCEEDED error is raised. A value lower than or equal to zero means no limit. |
||
Buffer Unit |
Enumeration, one of:
|
The unit in which all these attributes are expressed |
Repeatable File Store Stream
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Max In Memory Size |
Number |
Defines the maximum memory that the stream should use to keep data in memory. If more than that is consumed then it will start to buffer the content on disk. |
||
Buffer Unit |
Enumeration, one of:
|
The unit in which maxInMemorySize is expressed |
Commarea Request
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Commarea Length |
Number |
The length of COMMAREA. Default value is -1. This should be set to less than or equal to the length of the byte array passed in the payload. The maximum advised size is 32500 bytes, as this is guaranteed to be flowed successfully across all protocols. COMMAREA sizes greater than this may generate an ECI_ERR_INVALID_DATA_LENGTH return code. |
-1 |
|
Reply Length |
Number |
The length of the data stream to be returned back from the Gateway daemon to the Mule (JCA) application. Default value is -1. Setting this property can reduce the data transmitted over the network if the data returned by CICS is less than the full COMMAREA size, and you know the size of the data in advance. |
-1 |
|
Program Name |
String |
The name of the CICS program to call. It is case-sensitive. |
x |
|
Tpn Name |
String |
The transaction identifier of the CICS mirror transaction. Optional. |
||
Encoding |
String |
The data encoding. Default value is IBM037. |
IBM037 |