MQOutput node

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.

This topic contains the following sections:

Purpose

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 or queues that you specify.

If appropriate, define the queue as a WebSphere MQ clustered queue or shared queue. When you use 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 that is defined on any queue manager that is accessible by the broker's queue manager, or to the destinations identified in the LocalEnvironment (also known as the DestinationList) that is associated with the message.

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; 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, choose another supported output node.

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

MQOutput node icon

Using this node in a message flow

Look at the following samples to see how to use this node:

You can view samples only when you use the information center that is integrated with the Message Brokers Toolkit.

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 broker 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.

Configuring the MQOutput node

When you have put an instance of the MQOutput 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. To display the properties of the node either double-click the node, or right-click the node and click Properties.

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

Configure the MQOutput node.

  1. Optional: On the Description tab, enter a short description, a long description, or both. You can also rename the node on this page.
  2. On the Basic tab:
    • 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 Destination Mode property on the Advanced tab (described later in this section) to Queue Name. If you set Destination Mode to another value, these properties are ignored.
  3. The properties on the Advanced tab define the transactional control for the message and the way in which the message is put to the queue. Many of these properties map to options on the MQPUT call.
    • Select the Destination Mode from the list. This property identifies the queues to which the output message is put:
      • Queue Name (the default). The message is sent to the queue that is named in the Queue Name property. The Queue Manager Name and Queue Name properties on the Basic tab are mandatory if you select this option.
      • Reply To Queue. The message is sent to the queue that is named in the ReplyToQ field in the MQMD.

        Start of changeWhen you select this option, the MQOutputnode constructs a WebSphere MQ reply message. See Contents of the WebSphere MQ reply message for further information on the settings used by the MQOutput node and the Root.MQMD folder in this situation.End of change

      • Destination List. The message is sent to the list of queues that are named in the LocalEnvironment (also known as DestinationList) that is associated with the message.
    • Select the Transaction Mode from the 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.
      For more information, see Configuring for coordinated transactions.
    • Select the Persistence Mode from the 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 New Message ID to generate a new message ID for this message. 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 Request on the Request tab.

      More information about the options to which this property maps is available in the Application Programming Reference section of the WebSphere MQ Version 6 information center online, or the Version 5.3 book on the WebSphere MQ library Web page.

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

      More information about the options to which this property maps is available in the Application Programming Reference section of the WebSphere MQ Version 6 information center online, or the Version 5.3 book on the WebSphere MQ library Web page.

    • Select Segmentation Allowed if you want WebSphere MQ to segment the message within the queue manager when appropriate. Clear the check box if you do not want segmentation to occur. Start of changeSee Sending message segments in a WebSphere MQ message for more information about message segmentation.End of change

      More information about the options to which this property maps is available in the Application Programming Reference section of the WebSphere MQ Version 6 information center online, or the Version 5.3 book on the WebSphere MQ library Web page.

    • Select the Message Context to indicate how origin context is 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 Application Programming Reference section of the WebSphere MQ Version 6 information center online, or the Version 5.3 book on the WebSphere MQ library Web page.

    • Select Alternate User Authority if you want the MQOO_ALTERNATE_USER_AUTHORITY option to be 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 broker service user ID is used when the message is put.
  4. On the Request tab, set the properties to define the characteristics of each output message that is generated.
    • Select Request to mark each output message in the MQMD as a request message (MQMT_REQUEST), and clear the message identifier field (which is 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.

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

    • Enter a queue manager name in Reply-to Queue Manager. This name is inserted into the MQMD of each output message as the reply-to queue manager.
    • Enter a queue name in Reply-to Queue. This name is inserted into the MQMD of each output message as the reply-to queue.
  5. On the Validation tab, set the validation properties if you want the parser to validate the body of messages against the message set. (If a message is propagated to the Failure terminal of the node, it is not validated.)

    For more details, see Validating messages and Validation 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 to process the message further, process errors, or send the message to an additional destination.

If you connect one of these output terminals to another node in the message flow, the LocalEnvironment that is associated with the message is enhanced with the following information for each destination to which the message has been put by this node:
  • Queue name
  • Queue manager name
  • Message reply identifier (this identifier is set to the same value as message ID)
  • Message ID (from the MQMD)
  • Correlation ID (from the MQMD)
  • Group ID (from the queue manager)

These values are written in WrittenDestination within the LocalEnvironment tree structure.

If you do not connect either terminal, the LocalEnvironment tree is unchanged.

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

Start of change

Contents of the WebSphere MQ reply message

The:
  • Values of the following fields in MQMD are set, irrespective of the settings you make:
      MQMD.Report = 0;
      MQMD.PutApplType = MQAT_BROKER;
      MQMD.PutDate = Taken from current Timestamp
      MQMD.PutTime = Taken from current Timestamp
      MQMD.PutApplName = MsgTree.MQMD.ReplyToQMgr (first 28 chars)  
  • Values of the following fields are set from the values in the Root.MQMD folder:
      MQMD.Version
      MQMD.Format
      MQMD.Priority
      MQMD.Persistence
      MQMD.Expiry
      MQMD.Encoding
      MQMD.CodedCharSetId
      MQMD.GroupId
      MQMD.MsgSeqNumber
      MQMD.Offset
      MQMD.MsgFlags
      MQMD.OriginalLength
  • Following values in MQMD are set conditionally, based on values in the MQOutput node and the Root.MQMD folder:
      IF MsgTree.MQMD.MsgType = MQMT_REQUEST THEN                       
        MQMD.MsgType = MQMT_REPLY;                                      
      IF Nodes Message Context is Default, PassAll or PassIdentity THEN 
        MQMD.UserIdentifer = MsgTree.MQMD.UserIdentifier;               
      IF MsgTree.MQMD.Report contains MQRO_PASS_CORREL_ID THEN          
        MQMD.CorrelId = MsgTree.MQMD.CorrelId;                          
      ELSE                                                              
        MQMD.CorrelId = MsgTree.MQMD.MsgId;                       
      IF MsgTree.MQMD.Report contains MQRO_PASS_MSG_ID THEN             
        MQMD.MsgId = MsgTree.MQMD.MsgId;                                
      ELSE                                                              
        MQMD.MsgId = MQMI_NONE;  
  • Value of the MQMD.Persistence field is set based on the Persistence mode on the MQOutput node.

When the output MQMD structure has been constructed, the Message Context on the MQOutput node is ignored, and the behavior is as set All.

The values that are overridden, are done only in the output MQMD structure; no updates are made to the MQMD folder in the message tree.

End of change

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 sync point:
  • If you select Yes, the message is written under sync point (that is, within a WebSphere MQ unit of work).
  • If you select Automatic (the default), the message is written under sync point if the incoming input message is marked as persistent.
  • If you select No, the message is not written under sync point.
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 you select Yes, the message is marked as persistent.
  • If you select Automatic (the default), the message persistence is determined from the properties of the incoming message, as set in the MQMD.
  • If you select No, the message is not marked as persistent.
  • If you select 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 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 Description properties are described in the following table.

Property M C Default Description
Node name No No The node type, MQOutput 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 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, which is 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 Destination List, Reply To Queue, and Queue Name.
Transaction Mode Yes No Automatic This property controls whether the message is put transactionally. Valid values are Automatic, Yes, and No.
Persistence Mode Yes No Automatic This property controls whether the message is put persistently. Valid values are Automatic, Yes, No, and As Defined for Queue.
New Message ID Yes No 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.
New Correlation ID Yes No 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.
Segmentation Allowed Yes No Cleared If you select this check box, WebSphere MQ breaks the message into segments in the queue manager.
Message Context Yes No Pass All This property controls how origin context is handled. Valid values are Pass All, Pass Identity, Set All, Set Identity, and Default.
Alternate User Authority Yes No Cleared If you select this check box, alternate authority is used when the output message is put.

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

Property M C Default Description
Request Yes No Cleared If you select the check box, each output message is generated as a request message.
Reply-to Queue Manager No Yes   The name of the WebSphere MQ queue manager to which the output queue, which is 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 Validation properties of the MQOutput node are described in the following table.

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

Property M C Default Description
Validate No Yes Inherit This property controls whether validation takes place. Valid values are None, Content and Value, Content, and Inherit.
Failure Action No 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.
Include All Value Constraints Yes No Selected You cannot edit this property. If you select the check box, basic value constraint checks are included in Content and Value validation.
Fix Yes No None You cannot edit this property.
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2009Copyright IBM Corporation 1999, 2009.
Last updated : 2009-01-07 15:20:03

ac04570_