IBM Integration Bus, Version 9.0.0.8 Operating Systems: AIX, HP-Itanium, Linux, Solaris, Windows, z/OS

See information about the latest product version

IMSRequest node

Use the IMSRequest node to send a request to run a transaction on a local or remote IMS™ system, and wait for a response. IMS Connect must be configured and running on the IMS system.

This topic contains the following sections:

Purpose

The following example illustrates a situation in which you would use an IMSRequest node.

IBM® Integration Bus can be used to expose an existing target IMS banking application as a Web Service. For example, the IMS application provides transactions that operate on a database that contains information about customers' bank accounts. In this example, the Web service consumer sends a SOAP message across HTTP to IBM Integration Bus and synchronously waits for the response. The IBM Integration Bus message flow transforms the SOAP message to IMS format (including the LLZZ and transaction code fields), then sends that bit stream to IMS. The message flow waits for a response. IMS schedules the destination program and queues the request data for that program. The target program accesses the customer account database, builds a response message that consists of the account statement, and returns it to the IBM Integration Bus message flow. The message flow transforms the IMS format to a SOAP format and sends that SOAP response back across HTTP to the Web service consumer.

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

This image shows the IMSRequest node icon.

Using the IMSRequest node in a message flow

The IMSRequest node sends requests to IMS by using IMS Connect. The node takes the incoming message's bit stream and sends it to IMS. It then receives a bit stream, which it passes to the response parser. The bit stream that is sent to IMS must conform to the format that is shown in the following diagram:
This diagram shows the bit stream and is described in the surrounding text.
The message flow that contains the IMSRequest node ensures that the message that is received by the IMSRequest node has this structure where:
  • LLZZ is a four-byte field. The first two bytes indicate the length of the bit stream, and the other two bytes are reserved for use by IMS.
  • For request segments, the transaction code must follow. The transaction code can contain up to eight characters; if it contains less than eight characters, the transaction code must be delimited by a space. The response segments do not need to have the transaction name, but an IMS program can add it.
  • The rest of the data comprises anything else that the IMS program needs.
The IMS program produces many messages. You can receive all messages as a single transmission bit stream, or you can receive them separately. Each message can contain multiple segments; all segments for each message are returned at the same time.
The IMSRequest node has two modes of operation, which you specify by selecting or clearing the Use connection properties defined on node check box. If you select the check box, all properties are taken from the node by using the following properties in the node connection details section:
  • Hostname
  • Port number
  • Data store name
If you clear the Use connection properties defined on node check box, all connection details are retrieved from the configurable services. However, if the Security identity property is set, the security identity on the configurable service is ignored and the value of the node property is used instead.

The IMSRequest node can also use an identity that is present on an input message, and propagate it to IMS, by using the Propagate property on the security profile that is defined for the node. For more information, see Propagating security credentials to IMS.

View the following sample to see how to use this node:

You can view information about samples only when you use the product documentation that is integrated with the IBM Integration Toolkit or the online product documentation. You can run samples only when you use the product documentation that is integrated with the IBM Integration Toolkit.

Using configurable services for IMS nodes

You can configure IMS nodes 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 IMSRequest node.

Terminals and properties

When you have put an instance of the IMSRequest 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 (those that do not have a default value defined) are marked with an asterisk.

The IMSRequest node terminals are described in the following table.

Terminal Description
In The input terminal that receives the message that triggers the node.
Out The output terminal to which the node sends a message after it has been received from the external resource. The message is sent to the terminal unchanged, except for some added status information.
Failure If an error occurs in the IMSRequest node, the message is sent to the Failure terminal.
Timeout The output terminal to which the message is sent if a timeout occurs. The input message is propagated to this terminal with an exception list that describes the timeout. If the Timeout terminal is not connected and a timeout occurs, the message is routed to the Failure terminal. A timeout can occur in either of the following situations:
  • The IMS program has not responded by the time the execution timeout has expired. The execution timeout is configured by using the Timeout waiting for a transaction to be executed property on the IMSRequest node.
  • IBM Integration Bus has not received the response across the TCP/IP network by the time the socket timeout expires. You can configure the socket timeout on the configurable service.

The following tables describe the node properties. The columns headed M indicate whether the property is mandatory (marked with an asterisk on the panel if you must enter a value when no default is defined); the columns headed C indicate whether the property is configurable (you can change the value when you add the message flow to the BAR file to deploy it).

The IMSRequest node Description properties are described in the following table.
Property M C Default Description
Node name No No The node type, IMSRequest The name of the node.
Short description No No   A brief description of the node.
Long description No No   Text that describes the purpose of the node in the message flow.
The IMSRequest node Basic properties are described in the following table.
Property M C Default Description mqsiapplybaroverride command property
Use connection properties defined on node No Yes Selected If you select this check box, the connection properties that are defined on the node are used instead of a configurable service and security identity that are defined on the broker.

If you clear this check box, you must set the Configurable service and Security identity properties.

  
Hostname Yes Yes   The IP address or host name of the computer that is running the target IMS Connect system. This property is mandatory if the Use connection properties defined on node check box is selected and can be set only if the Use connection properties defined on node check box is selected. hostname
Port number Yes Yes 0 The port number on which IMS Connect is listening for TCP/IP connections. You can obtain the port number from the IMS Connect job log on the IMS system. This property is mandatory only if the Use connection properties defined on node check box is selected and can be set only if the Use connection properties defined on node check box is selected. portNumber
Data store name Yes Yes   The name of the data store that IMS Connect is using. This value must match the ID parameter of the Datastore statement that is specified in the IMS Connect configuration member. This name also serves as the XCF member name for IMS during internal XCF communications between IMS Connect and IMS OTMA. You can obtain the data store name from the IMS Connect job log on the IMS system. This property is mandatory only if the Use connection properties defined on node check box is selected and can be set only if the Use connection properties defined on node check box is selected. dataStoreName
Timeout waiting for a transaction to be executed No No 60 The time (in seconds) that the node waits for IMS to process a transaction. If IMS fails to process a transaction in this time, the node issues an exception, but the connection is not closed.

You can set this property only if the Use connection properties defined on node check box is selected. If the check box is cleared, the ExecutionTimeoutSec property on the configurable service is used.

  
Configurable service Yes Yes   The configurable service from which to get the connection details. All connection details are obtained from the configurable service, except for security information, which is obtained from the Security identity property.

This property is mandatory if the Use connection properties defined on node check box is cleared, and can be set only if the Use connection properties defined on node is cleared.

 configurableService
Security identity No Yes An empty string The security identity to look up in the broker to get the user name and password to use. You use the mqsisetdbparms command to set the security identity on the broker. The default value for this property is an empty string, which signifies that the user ID and password are not passed to IMS Connect. securityIdentity
The IMSRequest node Advanced properties are described in the following table.
Property M C Default Description
Commit mode Yes No 1: SEND_THEN_COMMIT The commit mode to use when processing IMS transactions. Available values are:
  • 1: SEND_THEN_COMMIT: (the default value) The transaction is processed using commit mode 1 in IMS. The request transaction is run and data is sent back to the node. After the node acknowledges that it has received the response, the transaction is committed. You cannot process the response before it is committed. The node sends the response after the acknowledgment is sent to IMS.
  • 0: COMMIT_THEN_SEND: The transaction is processed using commit mode 0 in IMS. The request transaction is run and committed before data is sent back to the node. The node waits for all response messages to be returned before it continues processing.
Sync level Yes No 1: CONFIRM The synchronization level to use when processing IMS transactions. If Commit mode is set to 0, the Sync level is automatically set to 1: CONFIRM. If Commit mode is set to 1, the Sync level property can have either of the following values:
  • 1: CONFIRM: (the default value) The node sends an acknowledgment to IMS after it receives the replies. The node then sends the response after the acknowledgment is sent to IMS. If you set the Sync level to 1: CONFIRM, the IMS program is blocked until the IMSRequest node acknowledges the transaction output, which might affect performance.
  • 0: NONE: The node does not send any acknowledgments. This value is applicable only when Commit mode is set to 1.

Typically, Sync level can be set to 0: NONE for read-only types of interactions, such as queries, which do not need an acknowledgment. However, for critical transactions that involve updates and deletions, it is important to be able to acknowledge the output from IMS. If the acknowledgment is not received (for example, because of a connection failure between IBM Integration Bus and IMS Connect), the transaction is backed out, avoiding the need for a compensation transaction.
The IMSRequest 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 IMSRequest node to IMS. 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 IMS.
The IMSRequest node Result properties are described in the following table.
Property M C Default Description
Output data location No No $OutputRoot The message tree location to which the IMSRequest node copies the response message tree in the outgoing message assembly. The default value, $OutputRoot, replaces the incoming message with the response.

See Combining a result message with an incoming message.
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 IMSRequest node Response Message Parsing properties are described in the following table.
Property M C Default Description mqsiapplybaroverride command property
Message domain No No   The domain to use to parse the message from the external resource's supplied bit stream.  
Message set No No Set automatically The name of the message set in which the incoming message is defined.

If you set this property, then subsequently update the project dependencies to remove this message set reference, a warning is issued. Either update the Message set property, or restore the reference to this message set project.

  
Message type No No   The name of the response message.  
Message format No No   The name of the physical format of the response message.  
Message coded character set ID Yes No EBCDIC (500) The ID of the coded character set that is used to interpret bytes of the data that is being read. Valid values are EBCDIC (500) and Broker System Default. messageCodedCharSetIdProperty
Message encoding Yes No Big Endian, with S390 Floating Point (785) The encoding scheme for numbers and large characters that is used to interpret bytes of the data that is being read. Valid values are:
  • Little Endian, with IEEE Floating Point (546)
  • Big Endian, with IEEE Floating Point (273)
  • Big Endian, with S390 Floating Point (785)
  • Broker System Determined
For more information about encoding, see Data conversion.		 messageEncodingProperty

The IMSRequest 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 IMSRequest 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 using monitoring properties for details.

You can enable and disable events that are shown here by selecting or clearing the Enabled check box.
Related concepts:
IBM Information Management System (IMS)
IMS nodes
Related tasks:
Preparing the environment for IMS nodes
Changing connection information for the IMSRequest node
Resolving problems when you use IMS nodes
Related reference:
mqsisetdbparms command
ac66120_.htm | Last updated Friday, 21 July 2017