CICSRequest node

Use the CICSRequest node to call CICS® Transaction Server for z/OS® programs over TCP/IP-based IP InterCommunications (IPIC) protocol.

The CICSRequest node is available in the following operation modes:

Developer
Application Integration Suite
Standard
Advanced
Adapter

For more information, see Operation modes.

This topic contains the following sections:

Purpose
Using the CICSRequest node in a message flow
Local environment overrides
Terminals and properties

Purpose

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.

Using the CICSRequest node in a message flow

Use a CICSRequest node to connect to a CICS application in a synchronous message flow. You can achieve this connection by creating the following message flow:

The diagram shows how you can use a CICSRequest node to connect to a CICS Transaction Server for z/OS application.

The CICSRequest node support in IBM Integration Bus provides direct communication with CICS (two-tier connection) by sending Distributed Program Link (DPL) requests over TCP/IP-based IPIC, or communication with CICS through CICS Transaction Gateway (three-tier connection). For more information about the two-tier and three-tier connection models, see CICS Transaction Server for z/OS overview for a high-level overview, or CICS Transaction Server for z/OS two-tier connectivity and CICS Transaction Server for z/OS three-tier connectivity for detailed conceptual information.

You can specify either a COMMAREA data structure or a channel data structure on the CICSRequest node to use as input for linking to CICS programs. The data structure that is specified as input returns the same data structure as output. Channels are an alternative for COMMAREAs, providing relief from the COMMAREA maximum size of 32767 bytes, and allowing greater flexibility in input/output data structures. For more information about using a COMMAREA or channel data structure, see COMMAREA or channel data structures.

CICS channels hold a number of structures called containers. In IBM Integration Bus, a CICS channel is represented as a message collection structure. A message collection can hold child messages, each treated as a container by the CICSRequest node. For information about using ESQL to create a message collection, see Creating a message collection by using ESQL.

If a single container is required for input only, a message collection does not need to be constructed. Instead a regular message can be used, provided the 16-character maximum alphanumeric channel name and the single 16-character maximum alphanumeric container name are specified in the local environment. For more information about using single message mode, see COMMAREA or channel data structures.

Because it is not possible to know how many containers are in the response, a message collection is always produced as output. However, the CICSRequest node Result data location property can be used to reduce the result tree down to a single message folder, or down to a single field or subtree for output.

You can add name-value attributes to a message collection to create CICS containers. Name-value attributes in the message collection, apart from CollectionName, can be used in lieu of full message-folders for simple data. For example, a name-value string attribute can be set in the message collection and used directly by the CICSRequest node without needing to create a message set for the element. For information about using attributes, see COMMAREA or channel data structures.

Name-value attributes can be produced from containers on output, as well as accepted for input. To create an attribute instead of a message folder from a container, select the check box that is available on the Response Message Parsing tab.

The CICSRequest node is contained in the CICS drawer of the message flow node palette, and is represented in the IBM Integration Toolkit by the following icon:

This image shows the CICSRequest node icon.

The CICSRequest node can use an identity that is present on an input message, and propagate it to CICS, by using the Propagate property on the security profile that is defined for the node. For more information, see Propagating security credentials to CICS Transaction Server for z/OS and Identity and security token propagation.

You can specify a mirror transaction name on the CICSRequest node for CICS tasks and programs to run under. This grouping greatly assists stat collection, accounting, and aids decision making about task priority. For more information about mirror transactions, see CICS Transaction Server for z/OS mirror transactions.

Using configurable services for the CICSRequest node:

You can configure the CICSRequest node to get connection details from a configurable service. For details about creating, changing, reporting, and deleting the configurable services, see Changing connection information for the CICSRequest node.

When you have put an instance of the CICSRequest node into a message flow, you can configure it; see Configuring a message flow node. The properties of the node are displayed in the Properties view.

All mandatory properties for which you must enter a value (properties that do not have a default value defined) are marked with an asterisk.

Configuring the CICSRequest node for coordinated transactions:

The value that you set for Transaction mode defines whether the requests to the CICSRequest node are treated as transactional or non-transactional. You can also specify a globally-coordinated (two-phase commit) transaction on distributed systems and on z/OS. For more information, see Configuring the CICSRequest node for global transactions on distributed systems and Configuring the CICSRequest node for global transactions on z/OS.

If an abend occurs and the CICSRequest node is configured to participate in the integration node transaction, the CICS task is immediately rolled back. If multiple CICS nodes are involved in the unit of work, the CICS activity of each of the nodes is rolled back, whether or not the abend is handled through an error or failure terminal. Any further work carried out by CICS as part of processing the message is carried out under a new unit of work.

Local environment overrides

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.

Terminals and properties

The CICSRequest node terminals are described in the following table.

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.

The CICSRequest node Description properties are described in the following table.

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.

The CICSRequest node Basic properties are described in the following table.

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: `protocol` can be tcp or ssl. `hostname` is the Internet Protocol version 4 (IPv4) TCP/IP address or DNS-resolvable hostname of the CICS host. `port` is the port number of the TCPIPSERVICE listener in CICS that is listening for IPIC requests over TCP/IP or Secure Sockets Layer (SSL) protocol. You can enter an integer in the range 1 - 65535. 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: `$LocalEnvironment/Destination/CICS/CICSProgramName`
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: `$LocalEnvironment/Destination/CICS/CICSCommareaLen` 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

The CICSRequest node Transactionality properties are described in the following table.

Property	M	C	Default	Description
Transaction mode	No	No	Automatic	Specifies how updates are managed. If you select Yes, the CICSRequest node takes part in the transaction that is started by the message flow's input node. If an abend occurs and the CICSRequest node is configured to participate in the integration node transaction, the CICS task is immediately rolled back. If multiple CICS nodes are involved in the unit of work, the CICS activity of each of the nodes is rolled back, whether or not the abend is handled through an error or failure terminal. Any further work carried out by CICS as part of processing the message is carried out under a new unit of work. For more information, see Processing responses from a CICSRequest node. If you select No, the CICSRequest node does not take part in the local transaction that is started by the message flow's input node. If you select Automatic, the message transactionality is inherited from the Transaction mode setting on the input node at the start of the message flow. For example, if the message flow is driven by an MQInput node, the CICSRequest node assumes the Transaction mode value that is set on the MQInput node. For more information about using these properties in transactions, see Configuring the CICSRequest node for global transactions on distributed systems and Configuring the CICSRequest node for global transactions on z/OS.

Property

Default

Description

Transaction mode

Automatic

Specifies how updates are managed.

If you select Yes, the CICSRequest node takes part in the transaction that is started by the message flow's input node. If an abend occurs and the CICSRequest node is configured to participate in the integration node transaction, the CICS task is immediately rolled back. If multiple CICS nodes are involved in the unit of work, the CICS activity of each of the nodes is rolled back, whether or not the abend is handled through an error or failure terminal. Any further work carried out by CICS as part of processing the message is carried out under a new unit of work. For more information, see Processing responses from a CICSRequest node.
If you select No, the CICSRequest node does not take part in the local transaction that is started by the message flow's input node.
If you select Automatic, the message transactionality is inherited from the Transaction mode setting on the input node at the start of the message flow. For example, if the message flow is driven by an MQInput node, the CICSRequest node assumes the Transaction mode value that is set on the MQInput node.

For more information about using these properties in transactions, see Configuring the CICSRequest node for global transactions on distributed systems and Configuring the CICSRequest node for global transactions on z/OS.

The CICSRequest node Request properties are described in the following table.

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.

The CICSRequest node Result properties are described in the following table.

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. See Combining a result message with an input message when fetching data from external systems.
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. See Combining a result message with an input message when fetching data from external systems.
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.

The CICSRequest node default Response Message Parsing properties are described in the following table.

Property	M	C	Default	Description
Message domain	No	No	None	If using a COMMAREA data structure: The domain to use to parse the response COMMAREA bit stream. If using a channel data structure: The domain to use to parse the response container bit stream. You can override this property in the local environment by specifying a value in the following location: `$LocalEnvironment/Destination/CICS/Response/messageDomain`
Message model	No	No	None	If using a COMMAREA or channel data structure: The name or location of the message set in which the response message is defined. 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: `$LocalEnvironment/Destination/CICS/Response/messageSet`
Message	No	No	None	If using a COMMAREA or channel data structure: The type of the response message. You can override this property in the local environment by specifying a value in the following location: `$LocalEnvironment/Destination/CICS/Response/messageType`
Physical format	No	No	None	If using a COMMAREA or channel data structure: The name of the physical format of the response message. You can override this property in the local environment by specifying a value in the following location: `$LocalEnvironment/Destination/CICS/Response/messageFormat`
Message coded character set ID	No	No	EBCDIC (037)	If using a COMMAREA data structure: The ID of the coded character set (CCSID) that is used to interpret bytes of the response COMMAREA. This property defines the CCSID for the message that is returned from CICS. If using a channel data structure: The ID of the coded character set (CCSID) that is used to interpret bytes of the response container, however this is ignored for character containers. You can override this property in the local environment by specifying a value in the following location: `$LocalEnvironment/Destination/CICS/Response/messageCCSID` For a list of valid values, see Supported code pages.
Message encoding	No	No	Big Endian, with S390 Floating Point (785)	If using a COMMAREA data structure: The encoding scheme for numbers and large characters that is used to interpret bytes of the response COMMAREA. This property defines the message encoding for the message that is returned from CICS. If using a channel data structure: The encoding scheme for numbers and large characters that is used to interpret bytes of the response container, however this is ignored for character containers. Valid values are: Little Endian, with IEEE Floating Point (546) Big Endian, with IEEE Floating Point (273) Big Endian, with S390 Floating Point (785) (the default value) Integration node System Determined For more information about encoding, see Data conversion. You can override this property in the local environment by specifying a value in the following location: `$LocalEnvironment/Destination/CICS/Response/messageEncoding`

Channel Options: If a value of Channel is selected for the Data structure property on the Basic tab, an additional table is available on the Response Message Parsing tab named Channel Options. The Channel Options table allows you to override the default message template properties by specifying parsing options for individual response containers, on a per-folder basis, when output from the CICSRequest node. You can also create a name-value attribute in the message collection to hold the container by selecting the check box provided.
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.

For a full description of these properties see Validation properties.

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.

The Monitoring properties of the node are described in the following table.

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.