MQOutput node

Use the MQOutput node to send messages to client applications using the WebSphere® MQ Enterprise Transport.

The MQOutput node is available in the following operation modes:
  • Developer
  • Application Integration Suite
  • Standard
  • Advanced
  • Express
  • Scale
  • Adapter
For more information, see Operation modes.

WebSphere MQ is available as a separate installation package, and your IBM® Integration Bus license entitles you to install and use WebSphere MQ with IBM Integration Bus. For more information, see Enhanced flexibility in interactions with WebSphere MQ and Installing WebSphere MQ.

This topic contains the following sections:

Purpose

The MQOutput node delivers an output message from a message flow to a WebSphere MQ queue.

On distributed systems, you can configure the MQOutput node to put a message to a WebSphere MQ queue on any local or remote queue manager, or to the destinations identified in the local environment associated with the message. You can either specify the queue manager explicitly by setting the MQ Connection properties on the MQOutput node, or specify an MQEndpoint policy on the Policy tab.

If the integration node has a queue manager associated with it, then the MQ message flow node by default connects to that queue manager with server bindings. If you configure properties on the MQ Connection tab, then these properties will be used to connect to the specified queue manager. If you specify a MQEndpoint policy, then the values in the policy will be used instead of the values defined in the MQ Connection tab.

On z/OS®, only local connections to queue managers are supported. You must have a queue manager specified for the integration node, but you can also connect to other local queue managers on an MQOutput node by using server bindings for the connection.

You can connect to a secured local or remote queue manager by using the Security identity property on the MQOutput node to pass a user name and password to the queue manager. The identity is defined using the mqsisetdbparms command. You can use the Security identity property to provide the security credentials on local and client connections, but it is not available for client connections that use a client channel definition table (CCDT). You can also choose whether to use the SSL protocol when a client connection is made to a remote queue manager. Select the Use SSL property on the MQOutput node to provide confidentiality on the client connection by using SSL. You can also set this property through an MQEndpoint policy. For more information about using security identities and SSL, see Connecting to a secured WebSphere MQ queue manager.

You can request that messages are processed under transaction control; for information about how to configure the MQOutput node for transactions, see Configuring MQ nodes for transactions.

You can define the queue as a WebSphere MQ clustered queue or shared queue. When you are using a WebSphere MQ clustered queue, if you leave the Object Queue Manager property empty, the cluster will route the message to an appropriate queue manager in the cluster.

The MQOutput node checks for the presence of an MQMD (WebSphere MQ message descriptor) header in the message tree. If no MQMD header is present, the MQOutput node creates one in the message tree, and populates it with MQMD default properties. If an MQMD header is found, the MQOutput node checks that it is a WebSphere MQ type header; if it is not, the Message Context property is set to Default. For information about the content of fields in MQMD, see Contents of the WebSphere MQ reply message.

The MQOutput node treats any other transport headers in the message tree as data. If such headers are not required as part of the message body, use a transformation node to remove them from the message tree before the MQOutput node. If the message tree is sourced from JMS, you can use a JMSMQTransform node to construct a message tree compatible with MQ. For further details, see JMS message transformation.

The MQOutput node is contained in the WebSphere MQ drawer of the palette, and is represented in the IBM Integration Toolkit by the following icon:

MQOutput node icon

Using this node in a message flow

For an example of how to use this node, assume that you have written a publishing application that publishes stock updates on a regular basis. The application sends the messages to the integration node on an MQInput node, and the message flow makes the publications available to multiple subscribers through a Publication node. You configure a Compute node to create a new output message whenever one particular stock is changed, and connect this node to an MQOutput node to record each price change for this stock.

Working with WrittenDestination data

After the message has been put, the WrittenDestination folder in the local environment is updated with the destination information. WrittenDestination data for an MQOutput node has the following format:
WrittenDestination = (
   MQ  = (
       DestinationData = (
         queueName        = 'OUT'
         queueManagerName = 'MYQUEUEMANAGER'
         replyIdentifier = X'4d...2e'
         msgId           = X'3c...2c'
         correlId        = X'2a...00'
         GroupId         = X'3a...00'
         bindingType     = 'CLIENT' (CHARACTER)
         destinationQueueManager = 'QM1_REG1' (CHARACTER)
         queueManagerHostname    = 'MYQUEUEMANAGERHOSTNAME' (CHARACTER)
         listenerPortNumber      = 9000 (INTEGER)
         channelName             = 'MYCHANNELNAME' (CHARACTER)
      )
   )
)

Behavior of a node that adds a request to a group

When a supported node successfully processes a message for output, it adds the information about the request that was just sent to the group that was most recently created in the message flow. The reply ID that the group expects is determined automatically from the transport, and the folder name is taken from the Folder name attribute.

Overrides

By default, the output node adds the request to the most recently created group. If multiple groups are being constructed in the same thread, a local environment override can be used to specify the group ID of the target group: LocalEnvironment.Destination.GroupScatter.RequestNode.GroupId. Requests can only be added to a group that is in construction in the current message flow thread. An exception is issued if no such group is available.

Transactions

Where a transport is transactional, the message obeys the usual transactional rules for the given transport. However, the group information is updated outside of the scope of the transaction. Therefore, if the transaction and output message are rolled back, the request is still added to the group.

Error

If Add Request to Group is true, and Folder name is blank, a configuration exception is issued. The thread context is used to determine which group to add a request to.

If Add Request to Group is true but no group is in construction in this thread, an exception is issued.

If a group ID override is specified and the ID is invalid, or does not correspond to a group that is in construction in the current thread, an exception is issued.

Connecting the terminals

Connect the In terminal to the node from which outbound messages are routed.

Connect the Out or Failure terminal of this node to another node in this message flow to process the message further, process errors, or send the message to an additional destination.

If you use aggregation in your message flows, you must use the output terminals.

Terminals and properties

When you add an MQOutput node to a message flow, you can use the Properties view in the Message Flow editor to configure it. To display field help, click within a field, and then click the information icon that is displayed at the beginning of the field. All mandatory properties that do not have a default value defined are marked with an asterisk. For general configuration information see Configuring a message flow node. You can also use an MQ Service to configure the MQOutput node, but this is supported only if a queue manager has been specified on the integration node. See Configuring an MQ node by using an MQ Service.

You can create and attach operational policies to control particular connection properties for this type of node at run time. For more information about policy, see Operational policy properties.

The following tables describe the node terminals and the node properties that you can set on a specified tab in the Properties view in the Message Flow editor. The column headed M indicates whether the property is mandatory (marked with an asterisk if you must enter a value when no default is defined).

Overriding Reply-to properties

If the MsgType field of the incoming MQMD is set to MQMT_REQUEST, the values in the Reply-to queue and Reply-to queue Manager properties are overridden with the corresponding node properties, if present.

You can enable previous behavior, which is deprecated, where incoming MQMD values for Reply-to queue and Reply-to queue Manager are passed to the outgoing message, by setting or exporting the environment variable MQSI_STRICT_REPLYTO_OVERRIDE_OFF with any value: for example, MQSI_STRICT_REPLYTO_OVERRIDE_OFF=1

Table of node terminals

Table 1. The terminals of the MQOutput node
Terminal Description
In The input terminal that accepts a message for processing by the node.
Failure The output terminal to which the message is routed if a failure is detected when the message is put to the output queue.
Out The output terminal to which the message is routed if it has been successfully put to the output queue.

Tables of node properties

Table 2. The Description properties of the node
Property M Default Description
Node name No The node type, MQOutput The name of the node.
Short description No   A brief description of the node.
Long description No   Text that describes the purpose of the node in the message flow.
Table 3. The Basic properties of the node
Property M Default Description
Queue name No   To send the output message to a single destination queue that is defined by this node, enter the name of the WebSphere MQ output queue to which the message flow sends messages.

If you set the Destination Mode property to Queue Name, you must specify a value for the Queue Name property. If you set Destination Mode to another value, this property is ignored.

Table 4. The MQ Connection properties of the node
Property M Default Description
Connection No Local queue manager This property specifies how a connection is made to WebSphere MQ:
  • Select Local queue manager to make a local connection to a specified queue manager. If this option is selected, specify a queue manager in the Destination queue manager name property.

    If this property is set without a Destination queue manager name value, and no MQEndpoint policy is specified on the Policy tab, the MQ node uses the connection details of the queue manager specified for the integration node at run time. If no queue manager was specified for the integration node, then the message flow will not deploy.

  • Select MQ client connection properties to make a client connection to a remote queue manager by specifying the client connection details. If this option is selected, the following properties must also be specified:
    • Queue manager host name
    • Listener port number
    • Channel name
    • Destination queue manager name
  • Select Client channel definition table (CCDT) file to use client connection details that are specified in a client channel definition table (CCDT) file. If this option is selected, you must also specify the queue manager name.
    Specify the location of the CCDT file by running the mqsichangeproperties command, using the integration node registry object property mqCCDT. For example, enter the following command on one line:
    mqsichangeproperties IBNODE -o BrokerRegistry -n mqCCDT 
    -v "C:\Program Files (x86)\IBM\WebSphere MQ\Qmgrs\QM1\@ipcc\AMQCLCHL.TAB"
    For more information, see Integration node registry object parameter values.

    If you select Connect with CCDT and mqCCDT is not set, then a run time error occurs when IBM Integration Bus attempts to connect to the specified queue manager. The mqCCDT property applies to a specific integration node, so if you want to connect to different queue managers using CCDT, then you must define separate client connection channels in the CCDT file for each queue manager.

Valid values for mqsiapplybaroverride are SERVER, CLIENT, and CCDT.

Destination queue manager name No   This property specifies the name of the queue manager on which the destination message queues are defined.
Queue manager host name No   This property specifies the host name of the queue manager.

To achieve high availability, you can specify more than one host name by separating each host name with a comma. The first host name in the list is used as the primary host name. If the connection to the host name becomes unavailable, the next host name is used, and so on. For more information about high availability in WebSphere MQ, see the WebSphere MQ Version 7.5 product documentation online.

Listener port number No   This property specifies the port on which the queue manager is listening.
Channel name No   This property specifies the name of the channel used by the queue manager to receive messages.
Security identity No   This property specifies an identity that is used to provide username and password credentials for connections to a secured local or remote queue manager. It can be used to provide credentials on local and client connections, but it is not available for client connections that are configured using a client channel definition table (CCDT).

The identity is defined using the mqsisetdbparms command. When you set the security identity by using this command, ensure that it is prefixed by mq::. Do not include the prefix when setting the security identity on the node or in the MQEndpoint policy.

For more information, see Connecting to a secured WebSphere MQ queue manager.

Use SSL No No This property controls whether the SSL protocol is used when a client connection is made to a remote queue manager. Select this property to provide confidentiality on the client connection by using SSL. You can also set this property through an MQEndpoint policy.

You can use SSL for client connections that are configured using either the MQ client connection properties or a client channel definition table (CCDT).

If you select Use SSL and specify the connection details through MQ client connection properties, you can also set the following properties:
  • SSL peer name
  • SSL cipher specification
The SSL peer name and SSL cipher specification properties are not used for client connections that use a client channel definition table (CCDT); you can specify this information in the CCDT.
If you select the Use SSL property, you must also specify the location of the SSL key repository. The SSL key repository is created using the WebSphere MQ GSkit, and it holds the required private and public certificates appropriate to the chosen certificate policy for the queue manager. You specify the key repository location by using the mqsichangeproperties command; it is specified as the SSL key repository full file path minus the .kdb file extension. For example, if the SSL key repository is located in C:\SSL\key.kdb, you set it by using the following command :
mqsichangeproperties IB10NODE -o BrokerRegistry -n mqKeyRepository -v C:\SSL\key

The SSL key repository password stash file key repository file name.sth must be located in same folder location as the key repository. The stash file is created using WebSphere MQ GSKit.

Use the MQSC REFRESH SECURITY command to pick up the changes to the SSL key repository.

For more information, see Connecting to a secured WebSphere MQ queue manager.

SSL peer name No   This property specifies the name that is passed to the remote queue manager when making the client connection; there must be a positive match for the connection to succeed.

You can specify this property if the Use SSL property is selected and the client connection details are specified through MQ client connection properties. It is not used for client connections that use a client channel definition table (CCDT); you can specify this information in the CCDT.

SSL cipher specification No   This property specifies the name of the symmetric key cryptography algorithm through which the remote queue manager is secured.

You can specify this property if the Use SSL property is selected and the client connection details are specified through MQ client connection properties. It is not used for client connections that use a client channel definition table (CCDT); you can specify this information in the CCDT.

Configure the connection details to enable a message to be retrieved from a queue on a local or remote queue manager. Values that are set on the MQ Connection tab are used at run time, unless overridden by a value in an MQEndpoint policy that is specified on the Policy tab.

Table 5. The Advanced properties of the node
Property M Default Description
Destination mode Yes Queue Name The queues to which the output message is sent.
  • If you select Queue Name (the default), the message is sent to the queue that is named in the Queue Name property. If you select this option, you must set Queue Name property.
  • If you select Reply To Queue, the message is sent to the queue that is named in the ReplyToQ field in the MQMD.

    When you select this value, the MQOutput node constructs a WebSphere MQ reply message. For more information about the settings that are used by the MQOutput node and the Root.MQMD folder in this situation, see Contents of the WebSphere MQ reply message.

  • If you select Destination List, the message is sent to the list of queues that are named in the local environment that is associated with the message. The data that you have provided is used in the DestinationData subtree of the local environment. For more information about the DestinationData subtree, see Data types for elements in the MQ DestinationData subtree. For more information about destination lists, see Creating destination lists.
Transaction mode Yes Automatic This property controls whether the message is put transactionally.
  • If you select Automatic (the default), the message transactionality is derived from the way that it was specified at the input node.
  • If you select Yes, the message is put transactionally.
  • If you select No, the message is put non-transactionally.

For more information, see Configuring MQ nodes for transactions.

Persistence mode Yes Automatic This property controls whether the message is put persistently.
  • If you select Automatic (the default), the message persistence is determined by the properties of the incoming message, as set in the MQMD (the WebSphere MQ message descriptor).
  • If you select Yes, the message is put persistently.
  • If you select No, the message is put non-persistently.
  • If you select As Defined for Queue, the message persistence is set as defined for the WebSphere MQ queue. The node specifies the MQPER_PERSISTENCE_AS_Q_DEF option in the MQMD.
Object queue manager No   This property specifies the name of a second WebSphere MQ queue manager, which is the target queue manager to which messages are routed from the queue manager that is connected to the MQOutput node.

The Object Queue Manager property is used only if the specified queue is defined on another queue manager or is a cluster queue. If it is a cluster queue, the Object Queue Manager can optionally be specified if you want to specify which queue manager receives the message. If you leave the Object Queue Manager property empty, the cluster will route the message to an appropriate queue manager in the cluster. For more information, see the WebSphere MQ Version 7.5 product documentation online.

New message ID Yes Cleared If you select this check box, WebSphere MQ generates a new message identifier to replace the contents of the MsgId field in the MQMD. This property maps to the MQPMO_NEW_MSG_ID option of the MQPMO of the MQI. Clear the check box if you do not want to generate a new ID. A new message ID is still generated if you select the Request property on the Request tab.

For more information about the options to which this property maps, see the Application Programming Reference section of the WebSphere MQ Version 7.5 product documentation online.

New correlation ID Yes Cleared If you select this check box, WebSphere MQ generates a new correlation identifier to replace the contents of the CorrelId field in the MQMD. This property maps to the MQPMO_NEW_CORREL_ID option of the MQPMO of the MQI. Clear the check box if you do not want to generate a new ID.

For more information about the options to which this property maps, see the Application Programming Reference section of the WebSphere MQ Version 7.5 product documentation online.

Segmentation allowed Yes Cleared If you select this check box, WebSphere MQ breaks the message into segments in the queue manager. Clear the check box if you do not want segmentation to occur. For more information about message segmentation, see Sending message segments in a WebSphere MQ message.

For more information about the options to which this property maps, see the Application Programming Reference section of the WebSphere MQ Version 7.5 product documentation online.

Message context Yes Pass All This property controls how origin context is handled.
  • Pass All maps to the MQPMO_PASS_ALL_CONTEXT option of the MQPMO of the MQI.
  • Pass Identity maps to the MQPMO_PASS_IDENTITY_CONTEXT option of the MQPMO of the MQI.
  • Set All maps to the MQPMO_SET_ALL_CONTEXT option of the MQPMO of the MQI.
  • Set Identity maps to the MQPMO_SET_IDENTITY_CONTEXT option of the MQPMO of the MQI.
  • Default maps to the MQPMO_DEFAULT_CONTEXT option of the MQPMO of the MQI.
  • None maps to the MQPMO_NO_CONTEXT option of the MQPMO of the MQI.

When a security profile is associated with the node and is configured to perform identity propagation, the chosen context can be overridden to ensure that the outgoing identity is set.

For more information about the options to which these properties map, see the Application Programming Reference section of the WebSphere MQ Version 7.5 product documentation online.

Alternate user authority Yes Cleared If you select this check box, alternate authority is used when the output message is put and the MQOO_ALTERNATE_USER_AUTHORITY option is set in the open options (MQOO) of the MQI. If you select this check box, this option is specified when the queue is opened for output. The alternative user information is retrieved from the context information in the message. Clear the check box if you do not want to specify alternative user authority. If you clear the check box, the integration node service user ID is used when the message is put.

The Advanced node properties define the transactional control for the message and the way in which the message is put to the queue.

Table 6. The Request properties of the node
Property M Default Description
Request Yes Cleared If you select the check box, each output message in the MQMD is generated as a request message (MQMT_REQUEST), and the message identifier field is cleared (and set to MQMI_NONE) so that WebSphere MQ generates a new identifier. Clear the check box to indicate that each output message is not marked as a request message. If you have set Destination Mode to Reply To Queue, you cannot select this check box.

A new message identifier is generated even if the New Message ID check box is not selected on the Advanced tab.

If the check box is not selected and the values that were previously configured for Reply-to queue and Reply-to queue Manager are grayed out, these grayed out values are not used to override the MQMD header of the outgoing message.

Reply-to queue Manager No   The name of the WebSphere MQ queue manager to which the output queue, which is specified in Reply-to Queue, is defined. This name is inserted into the MQMD of each output message as the reply-to queue manager.
Reply-to queue No   The name of the WebSphere MQ queue to which to put a reply to this request. This name is inserted into the MQMD of each output message as the reply-to queue.

The Request properties define the characteristics of each output message that is generated.

Table 7. The Validation properties of the node
Property M Default Description
Validate No Inherit This property controls whether validation takes place. Valid values are None, Content and Value, Content, and Inherit.
Failure action 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.

For a full description of these properties, see Validation properties.

Table 8. The Policy properties of the node
Property M Default Description
Policy URL No   Set the value of this field to the location of an MQEndpoint policy to use the connection details defined in that policy for this MQ node.

If an MQEndpoint policy is specified, the property values that are set in the policy are used at run time. The properties that are set in the policy override the corresponding properties that are set on the MQ Connection tab. If an MQEndpoint policy is not specified, then property values that are set on the MQ Connection tab are used.

If no MQEndpoint policy is specified, and the Connection property on the MQ Connection tab is set to Local queue manager with no queue manager specified (the default state), then the MQ node uses the connection details for the queue manager that was specified for the integration node. If no queue manager was specified for the integration node, then the message flow will not deploy.

If an MQEndpoint policy is specified, then any equivalent properties that are set on the MQ Connection tab are ignored at run time. For more information about operational policies that can be applied to MQ nodes, see MQEndpoint policy.

Table 9. The Monitoring properties of the node
Property M Default Description
Events No   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.

Configurable properties

The following table describes the node properties that are configurable (you can change the property value when you add the message flow to the BAR file for deployment by using the mqsiapplybaroverride command). The table maps the message flow node properties to the corresponding properties of the mqsiapplybaroverride command.

For more information about configurable properties, see Configurable properties in a BAR file.

Table of configurable properties

Table 10. List of node properties that can be configured using the mqsiapplybaroverride command
Property mqsiapplybaroverride command property
Queue name queueName
Connection type connection
Destination queue manager name destinationQueueManagerName
Queue manager host name queueManagerHostname
Listener port number listenerPortNumber
Channel name channelName
Security identity securityIdentity
Use SSL useSSL
SSL peer name SSLPeerName
SSL cipher specification SSLCipherSpec
Reply to queue manager replyToQMgr
Reply to queue replyToQ
Validate validateMaster
Policy URL policyUrl

Operational policy properties

You can create and attach MQEndpoint policies to MQ nodes to control the behavior of the node at run time. The following table maps the operational properties of the message flow node to the corresponding properties of the node policy document. Operational properties are properties that you can control the value of at run time by using an operational policy.

If you set the ccdt property in the policy document to use a CCDT file, you must also run mqsichangeproperties to specify the CCDT file path. Use the following form, where file_path represents the path to the CCDT file:
mqsichangeproperties IBNODE -o BrokerRegistry -n mqCCDT -v file_path

For more information about operational policy and how to use a policy in a message flow, see Operational policy and MQEndpoint policy.

Table of operational properties

Table 11. List of node properties that can be controlled at run time by using an MQEndpoint policy
Property Policy document property
Connection type connection
Destination queue manager name destinationQueueManagerName
Queue manager host name queueManagerHostname
Listener port number listenerPortNumber
Channel name channelName
Security identity securityIdentity
Use SSL useSSL
SSL peer name SSLPeerName
SSL cipher specification SSLCipherSpec