Use the CICSRequest node to call CICS® Transaction Server for z/OS® programs over TCP/IP-based IP InterCommunications (IPIC) protocol.
You can use the CICSRequest node to connect IBM® Integration Bus to CICS applications. The CICSRequest node communicates
with CICS by sending Distributed
Program Link (DPL) requests. DPL requests are made over TCP/IP-based
InterCommunications protocol (IPIC), or by a connection to a
middle-tier CICS Transaction
Gateway daemon
process. A three-tier CICS Transaction
Gateway configuration
enables more transports, high-availability, and workload management
options. You can create a message flow that contains a CICSRequest node, which
calls a CICS application
on a targeted region. The CICSRequest node can be
used by a message flow that is deployed to any integration node platform.
The CICSRequest node
supports CICS Transaction
Server for z/OS; see IBM Integration Bus system
requirements for the latest supported
version.
You can dynamically override values, on a per message basis, in the local environment. You can override the CICS program that you are calling, the COMMAREA length, mirror transactions, and the processing of the response message. For more information, see Local environment overrides for the CICSRequest node.
Terminal | Description |
---|---|
In | The input terminal that accepts a message for processing by the node. The CICSRequest node is driven by a message arriving on the In terminal. Data is taken from the message tree and is sent to CICS. |
Out | The output terminal from which the message tree is propagated, including the data returned from CICS. |
Failure | The output terminal to which a message is routed if a CICSRequest node exception is detected, or a CICSRequest node to CICS connection failure occurs. |
Error | The output terminal to which a message is propagated if a CICS error (abend) occurs. The input message is propagated with a CICS\AbendCode field in the LocalEnvironment. If the Error terminal is not connected and CICS abend occurs, the abend is lost. |
Timeout | The output terminal to which the message is propagated if a per-request timeout occurs when an individual request is sent to CICS, but the request takes too long. The output message contains the input message body and a timeout exception in the ExceptionList. If the Timeout terminal is not connected and a timeout occurs, the request timeout exception is routed to the Failure terminal. If the Failure terminal is not connected, the integration node throws an exception and returns control to the closest upstream node that can process it. The default behavior is that the message is returned to the input node. |
The following tables describe the CICSRequest node properties.
The table column headed M indicates whether the property is mandatory. For example, the property is marked with an asterisk meaning that you must enter a value if no default is defined.
The column headed C indicates whether the property is configurable. For example, you can change the value when you add the message flow to the BAR file to deploy it.
Property | M | C | Default | Description |
---|---|---|---|---|
Node name | Yes | No | CICS Request | The name of the node. |
Short description | No | No | None | A brief description of the node. |
Long description | No | No | None | Text that describes the purpose of the node in the message flow. |
Property | M | C | Default | Description | mqsiapplybaroverride command property |
---|---|---|---|---|---|
CICS server | Yes | Yes | None | The CICS server property is defined
either as a configurable service name, for example: myCICSConnection,
or as a URL. A URL allows you to specify a protocol, host name, and
port number, which is the minimum information you need to connect
to the CICS target region. The URL must be made up of the following structure: protocol://hostname:port Where:
For example: tcp://mycicsregion.com:12345 or ssl://mycicsregion.com:56789. You can obtain the hostname and port values from the IPIC TCPIPSERVICE definition in the target CICS region. |
cicsServer |
Program name | Yes | No | None | The Program name property
is the name of the application that is on the target CICS region that you are calling. Programs that use COMMAREAs or channels are supported. You
can override this property in the local environment by specifying
a value in the following location:
|
|
Data structure | Yes | No | Commarea | Whether to use a COMMAREA or a channel data structure. The default for this property is Commarea. The decision depends on the targeted CICS program, for example; whether the target program is channel-based or not. | |
Commarea length | Yes | No | 0 | The Commarea length property is the size, in bytes, of the COMMAREA that is used by the CICS program. The byte size value is sent to CICS, and before the program is started, an area of memory is created to match that number. For example, if you send a Commarea length value of 100, 100 bytes are allocated. The program accesses this area as the DFHCOMMAREA. Ensure that the Commarea length property value is large enough to contain the input request data, or the output response data, but that it does not exceed the maximum value of 32767 bytes. If the Commarea length value is not large enough to be used for the response data, or the request data, a memory leak occurs in CICS. The size of the COMMAREA cannot be changed by the CICS program. If the serialized request data is larger than the Commarea length, the data is truncated to the Commarea length. You can obtain the Commarea length value from the CICS administrator or developer. You can override this property
in the local environment by specifying a value in the following location:
This property is not configurable if a value of Channel is selected for the Data structure property. |
|
Security identity | No | Yes | None | The name of the security identity object that
is created and configured by the mqsisetdbparms command, which
contains the user ID and password to be used by the integration node
to authenticate the connection to CICS. Use the mqsisetdbparms command to set
the security identity user ID and password to be accessed by the integration
node. The default value for this property is None, which signifies that the user ID and password are not passed to CICS. For more information about CICS security identity support, see mqsisetdbparms command. |
securityIdentity |
Request timeout (in seconds) | Yes | Yes | 120 | If individual requests sent to CICS take more time than specified
here, the request attempt is abandoned. A request timeout causes an exception to be propagated from the Timeout terminal. If the Timeout terminal is not connected, the request timeout exception is routed to the Failure terminal. If the Failure terminal is not connected, the integration node throws an exception and returns control to the closest upstream node that can process it. The default behavior is that the message is returned to the input node. A value of 0 indicates that no timeout occurs. |
requestTimeoutSecs |
Mirror transaction ID | No | Yes | None | You can specify a mirror transaction name by configuring this property, however the Mirror transaction ID property value that you specify must correspond to a defined TRANSACTION resource in CICS. For example, if you have a defined TRANSACTION resource of ATRN in CICS, and you want tasks and programs to run under that transaction, you must configure ATRN as the Mirror transaction ID property value. When the message flow containing the configured CICSRequest node is deployed, any CICS programs that are started thereafter appear in CICS as running under the specified mirror transaction. If the value of the Mirror transaction ID property is not set, the mirror transaction name defaults to CPMI if called by a distributed platform, or CSMI if called by a z/OS system. For more information about mirror transactions, see CICS Transaction Server for z/OS mirror transactions. |
mirrorTran |
Set EIBTRNID only | No | Yes | Cleared | You can use a weaker form of mirror transaction that does not change the TRANSACTION resource, but instead sets a variable called EIBTRNID, which is available to the called program. You can configure the EIBTRNID variable to tell the program what TRANSACTION resource it is running under, without the TRANSACTION resource being defined in CICS. For example, you can specify this weaker form of mirror transaction by configuring the Mirror transaction ID property with the name of the required TRANSACTION resource; for example ATRN, and by selecting this property. When the message flow containing the configured CICSRequest node is deployed, any CICS programs that are started thereafter appear in CICS as running under the specified mirror transaction. If the value of the Mirror transaction ID property is not set, the mirror transaction name defaults to CPMI if called by a distributed platform, or CSMI if called by a z/OS system. For more information about mirror transactions, see CICS Transaction Server for z/OS mirror transactions. |
eibtrnidOnly |
Property | M | C | Default | Description |
---|---|---|---|---|
Transaction mode | No | No | Automatic | Specifies how updates are managed.
|
Property | M | C | Default | Description |
---|---|---|---|---|
Data location | Yes | No | $Body | The location in the incoming message tree from which data is retrieved to form the request that is sent from the CICSRequest node to CICS. The default value, $Body, represents the incoming message body. You can enter any XPath or ESQL expression that defines the location of the message tree to serialize and send to CICS. |
Program name override location | No | No | $LocalEnvironment/Destination/CICS/CICSProgramName | The element of the message assembly that contains the name of the program to run in CICS. |
Property | M | C | Default | Description |
---|---|---|---|---|
Result data location | No | No | $ResultRoot | This property specifies which subtree of the result to place in the message. If a value is not specified for this property, $ResultRoot is used as the default and the whole response is placed in the output message at the location that is specified in Output data location. |
Output data location | No | No | $OutputRoot | The message tree location to which the CICSRequest node sends output. The default value, $OutputRoot, replaces the incoming message with the response. |
Copy local environment | No | No | Selected | This property controls whether to copy the incoming local environment or propagate the incoming local environment. By default, this check box is selected, which signifies that the local environment is copied so that the incoming local environment is preserved. The additions to the local environment are visible only to nodes downstream of this node. If this check box is cleared, the incoming local environment is used for the outgoing message. Any modifications that are made to the local environment by this node are visible to both downstream and upstream nodes after this node has completed. |
Property | M | C | Default | Description |
---|---|---|---|---|
Message domain | No | No | None |
You can override this property in the local
environment by specifying a value in the following location:
|
Message model | No | No | None |
If you set this property, and then update the project dependencies to remove this message set reference, a warning is issued. Either update the Message model property, or restore the reference to this message set project. You
can override this property in the local environment by specifying
a value in the following location:
|
Message | No | No | None |
You can override this property in the local
environment by specifying a value in the following location:
|
Physical format | No | No | None |
You can override this property in the local
environment by specifying a value in the following location:
|
Message coded character set ID | No | No | EBCDIC (037) |
You can override this property in the local
environment by specifying a value in the following location:
For a list of valid values, see Supported code pages. |
Message encoding | No | No | Big Endian, with S390 Floating Point (785) |
Valid values are:
You
can override this property in the local environment by specifying
a value in the following location:
|
If the container details are specified in the Channel Options table, those container details are used in preference to the default message template properties. If the container details are not specified in the Channel Options table and the attribute check box is selected, a name-value pair is created. If the container details are not specified in the Channel Options table and the name-value attribute check box is not selected, the default message template properties are used.
The CICSRequest node Parser Options properties are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
Parse timing | Yes | No | On Demand | This property controls when a response message
is parsed. Valid values are On
Demand, Immediate,
and Complete. For a full description of this property, see Parsing on demand. |
Build tree using XML schema data types | Yes | No | Cleared | This property controls whether the XMLNSC parser creates syntax elements in the message tree with data types taken from the XML Schema. You can select this property only if you set the Validate property on the Validation tab to Content or Content and Value. |
Use XMLNSC compact parser for XMLNS domain | Yes | No | Cleared | This property controls whether the XMLNSC Compact Parser is used for messages in the XMLNS Domain. If you set this property, the response message data appears under XMLNSC in nodes that are connected to the output terminal when the input MQRFH2 header or Response Message Parsing properties Domain is XMLNS. |
Retain mixed content | Yes | No | Cleared | This property controls whether the XMLNSC parser creates elements in the message tree when it encounters mixed text in a response message. If you select the check box, elements are created for mixed text. If you clear the check box, mixed text is ignored and no elements are created. |
Retain comments | Yes | No | Cleared | This property controls whether the XMLNSC parser creates elements in the message tree when it encounters comments in a response message. If you select the check box, elements are created for comments. If you clear the check box, comments are ignored and no elements are created. |
Retain processing instructions | Yes | No | Cleared | This property controls whether the XMLNSC parser creates elements in the message tree when it encounters processing instructions in a response message. If you select the check box, elements are created for processing instructions. If you clear the check box, processing instructions are ignored and no elements are created. |
Opaque elements | No | No | Blank | This property is used to specify a list of elements in the response message that are to be opaquely parsed by the XMLNSC parser. Opaque parsing is performed only if validation is not enabled (that is, if Validate is None); entries that are specified in Opaque Elements are ignored if validation is enabled. |
The CICSRequest node Validation properties are described in the following table.
Property | M | C | Default | Description | mqsiapplybaroverride command property |
---|---|---|---|---|---|
Validate | Yes | Yes | None | This property controls whether validation takes place. Valid values are None, Content and Value, Content, and Inherit. | validateMaster |
Failure action | Yes | No | Exception | This property controls what happens if validation fails. You can set this property only if you set Validate to Content or Content and Value. Valid values are User Trace, Local Error Log, Exception, and Exception List. |
Property | M | C | Default | Description |
---|---|---|---|---|
Events | No | No | None | Events that you have defined for the node are
displayed on this tab. By default, no monitoring events are defined
on any node in a message flow. Use Add, Edit,
and Delete to create, change or delete monitoring
events for the node; see Configuring monitoring event sources by using monitoring properties for details. You can enable and disable events that are shown here by selecting or clearing the Enabled check box. |