MQOutput node

This topic contains the following sections:

Purpose

Use the MQOutput node to send messages to clients that connect to the broker using the WebSphere MQ Enterprise Transport and that use the MQI and AMI application programming interfaces.

The MQOutput node delivers an output message from a message flow to a WebSphere MQ queue. The node uses MQPUT to put the message to the destination queue that you specify.

If appropriate, you can define the queue as a WebSphere MQ clustered queue or shared queue. When using a WebSphere MQ clustered queue, leave the queue manager name empty.

You can configure the MQOutput node to put a message to a specific WebSphere MQ queue defined on any queue manager accessible by the broker's queue manager.

You can set other properties to control the way in which messages are sent, by causing appropriate MQPUT options to be set. For example, you can request that a message is processed under transaction control. You can also specify that WebSphere MQ can, if appropriate, break the message into segments in the queue manager.

If you create a message flow to use as a subflow, you cannot use a standard output node, you must use an instance of the Output node to create an out terminal for the subflow through which to propagate the message.

If you do not want your message flow to send messages to a WebSphere MQ queue, you can choose another supported output node.

The MQOutput node is represented in the workbench by the following icon:

MQOutput node icon

Using this node in a message flow

For an example of how you can 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 broker on an MQInput node, and the message flow makes the publications available to multiple subscribers through a Publication node. You include an MQOutput node to send the message to an application that records each price change that occurs.

Configuring the MQOutput node

When you have put an instance of the MQOutput node into a message flow, you can configure it. Right-click the node in the editor view and click Properties. The node's basic properties are displayed.

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

Configure the MQOutput node as follows:

  1. If you want to send the output message to a single destination queue that is defined by this node, enter the name of the queue to which the message flow sends messages in Queue Name. Enter the name of the queue manager to which this queue is defined in Queue Manager Name. You must set these properties if you set the Advanced property Destination Mode (described below) to Queue Name. If you set Destination Mode to another value, these properties are ignored.
  2. Select Advanced in the properties dialog navigator. These properties define the transactional control for the message and the way that the message is put to the queue. Many of these properties map to options on the MQPUT call.
    • Select the Destination Mode from the drop-down list. This identifies the queues to which the output message is put.
      • Queue Name. The message is sent to the queue named in the Queue Name property. The properties Queue Manager Name and Queue Name (on the Basic tab) are mandatory if you select this option. This is the default.
      • Reply To Queue. The message is sent to the queue named in the ReplyToQ field in the MQMD.
    • Select the Transaction Mode from the drop-down list to determine how the message is put.
      • 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.
      See Configuring for coordinated transactions for more information.
    • Select the Persistence Mode from the drop-down list to determine whether the message is put persistently.
      • If you select Automatic (the default), the persistence is as specified in the incoming message.
      • 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.
    • Select the New Message ID check box to generate a new message ID for this message. This 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. Note that a new message ID is still generated if you select the Request check box in the Request panel of the properties dialog.

      More information about the options to which this property maps is available in the WebSphere MQ Application Programming Reference.

    • Select the New Correlation ID check box to generate a new correlation ID for this message. This 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.

      More information about the options to which this property maps is available in the WebSphere MQ Application Programming Reference.

    • Select the Segmentation Allowed check box if you want WebSphere MQ to segment the message within the queue manager when appropriate. You must also set MQMF_SEGMENTATION_ALLOWED in the MsgFlags field in the MQMD for segmentation to occur. Clear the check box if you do not want segmentation.

      More information about the options to which this property maps is available in the WebSphere MQ Application Programming Reference.

    • Select the Message Context to indicate how origin context is to be handled. Choose one of the following options:
      • 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.)

      More information about the options to which these properties map is available in the WebSphere MQ Application Programming Reference.

    • Select the Alternate User Authority check box if you want the MQOO_ALTERNATE_USER_AUTHORITY option set in the open options (MQOO) of the MQI. If you select this box, this option is specified when the queue is opened for output. The alternate user information is retrieved from the context information in the message. Clear the check box if you do not want to specify alternate user authority. If you clear the box, the broker service user ID is used when the message is put.
  3. Select Request in the properties dialog navigator and set the properties to define the characteristics of each output message generated.
    • Select the Request check box to mark each output message in the MQMD as a request message (MQMT_REQUEST), and clear the message identifier field (set to MQMI_NONE) to ensure that WebSphere MQ generates a new identifier. Clear the check box to indicate that each output message is not marked as a request message. You cannot select this check box if you have selected a Destination Mode of Reply To Queue.

      Note that a new message identifier is generated even if the New Message ID check box is not selected in the Advanced panel of the properties dialog navigator.

    • Enter a queue manager name in Reply-to Queue Manager. This is inserted into the MQMD of each output message as the reply-to queue manager.
    • Enter a queue name in Reply-to Queue. This is inserted into the MQMD of each output message as the reply-to queue.
  4. Select Description in the properties dialog navigator to enter a short description, a long description, or both.
  5. Click Apply to make the changes to the MQOutput node without closing the properties dialog. Click OK to apply the changes and close the properties dialog.

    Click Cancel to close the dialog and discard all the changes that you have made to the properties.

Connecting the terminals

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

Connect the out or failure terminal of this node to another node in this message flow if you want to send the message to an additional destination.

Configuring for coordinated transactions

When you define an MQOutput node, the option that you select for the Transaction Mode property defines whether the message is written under syncpoint:

  • If Yes, the message is written under syncpoint (that is, within a WebSphere MQ unit of work).
  • If Automatic (the default), the message is written under syncpoint if the incoming input message is marked persistent.
  • If No, the message is not written under syncpoint.

Another property of the MQOutput node, Persistence Mode, defines whether the output message is marked as persistent when it is put to the output queue:

  • If Yes, the message is marked as persistent.
  • If Automatic (the default), the message persistence is determined from the properties of the incoming message, as set in the MQMD (the WebSphere MQ message descriptor).
  • If No, the message is not marked as persistent.
  • If As Defined for Queue, the message persistence is set as defined in the WebSphere MQ queue by the MQOutput node specifying the MQPER_PERSISTENCE_AS_Q_DEF option in the MQMD.

Terminals and properties

The MQOutput node terminals are described in the following table.

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, and if further processing is required within this message flow.

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

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

Property M C Default Description
Queue Manager Name No Yes   The name of the WebSphere MQ queue manager to which the output queue, specified in Queue Name, is defined.
Queue Name No Yes   The name of the WebSphere MQ output queue to which this node puts messages (using MQPUT).

The MQOutput node Advanced properties are described in the following table.

Property M C Default Description
Destination Mode Yes No Queue Name The queues to which the output message is sent. Valid values are , Reply To Queue, and Queue Name.
Transaction Mode Yes No Automatic Whether the message is put transactionally. Valid values are Automatic, Yes, and No.
Persistence Mode Yes No Automatic Whether the message is put persistently. Valid values are Automatic, Yes, No, and As Defined for Queue.
New Message ID Yes No Cleared Whether WebSphere MQ generates a new message identifier to replace the contents of the MsgId field in the MQMD. If you select the check box, this action is performed.
New Correlation ID Yes No Cleared Whether WebSphere MQ generates a new correlation identifier to replace the contents of the CorrelId field in the MQMD. If you select the check box, this action is performed.
Segmentation Allowed Yes No Cleared If appropriate, WebSphere MQ breaks the message into segments in the queue manager. If you select the check box, this action is performed.
Message Context Yes No Pass All How to handle origin context. Valid values are Pass All, Pass Identity, Set All, Set Identity, and Default.
Alternate User Authority Yes No Cleared Whether alternate authority is used when the output message is put. If you select the check box, this action is performed.

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

Property M C Default Description
Request Yes No Cleared Whether to generate each output message as a request message. If you select the check box, this action is performed.
Reply-to Queue Manager No Yes   The name of the WebSphere MQ queue manager to which the output queue, specified in Reply-to Queue, is defined.
Reply-to Queue No Yes   The name of the WebSphere MQ queue to which to put a reply to this request.

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

Property M C Default Description
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.