This topic contains sections marked as revised for this release

WebSphere Message Brokers
File: ac04560_
Writer: Terry Cowling

Reference topic

This build: July 31, 2007 21:17:20

MQInput node

Use the MQInput node to receive messages from 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 MQInput node receives a message from a WebSphere MQ message queue that is defined on the broker's queue manager. The node uses MQGET to read a message from a specified queue, and establishes the processing environment for the message. If appropriate, you can define the input queue as a WebSphere MQ clustered queue or shared queue.

Message flows that handle messages that are received across WebSphere MQ connections must always start with an MQInput node. You can set the properties of the MQInput node to control the way in which messages are received, by causing appropriate MQGET options to be set. For example, you can indicate that a message is to be processed under transaction control. You can also request that data conversion is performed on receipt of every input message.

The MQInput node handles messages in the following message domains:
  • MRM
  • XML
  • XMLNS
  • XMLNSC
  • JMSMap
  • JMSStream
  • MIME
  • BLOB
  • IDOC

If you include an output node in a message flow that starts with an MQInput node, it can be any of the supported output nodes, including user-defined output nodes; you do not need to include an MQOutput node. You can create a message flow that receives messages from WebSphere MQ clients and generates messages for clients that use any of the supported transports to connect to the broker, because you can configure the message flow to request that the broker provides any conversion that is necessary.

If you create a message flow to use as a subflow, you cannot use a standard input node; you must use an instance of the Input node as the first node to create an In terminal for the subflow.

If your message flow does not receive messages across WebSphere MQ connections, you can choose one of the supported input nodes.

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

MQInput node icon

Using the MQInput node in a message flow

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

Configuring the MQInput node

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

Configure the MQInput node as follows:

  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, enter the name of the queue from which the message flow receives messages. You must predefine this WebSphere MQ queue to the queue manager that hosts the broker to which the message flow is deployed.
  3. On the Input Message Parsing page, set values for the properties that describe the message domain, message set, message type, and message format that the node uses to determine how to parse the incoming message.
    • If the incoming message has an MQRFH2 header, you do not need to set values for the Input Message Parsing properties because the values can be derived from the <mcd> folder in the MQRFH2 header; for example:
      <mcd><Msd>MRM</Msd><Set>DHM4UO906S001</Set><Type>receiptmsg1</Type>
      <Fmt>XML</Fmt></mcd>

      If you set values, and those values differ from those in the MQRFH2 header, the values in the MQRFH2 header take precedence.

    • In Message Domain, select the name of the parser that you are using from the list. You can choose from the following names:
      • MRM
      • XML
      • XMLNS
      • XMLNSC
      • JMSMap
      • JMSStream
      • MIME
      • BLOB
      • IDOC
    • If you are using the MRM or IDOC parser, select the correct message set from the list in Message Set. This list is populated with available message sets when you select MRM or IDOC as the domain.

      Leave Message Set blank for XML, XMLNS, XMLNSC, JMS, MIME, and BLOB parsers.

    • If you are using the MRM parser, select the correct message from the list in Message Type. This list is populated with messages that are defined in the message set that you have selected.

      Leave Message Type blank for XML, XMLNS, XMLNSC, JMS, MIME, BLOB, and IDOC parsers.

    • If you are using the MRM or IDOC parser, select the format of the message from the list in Message Format. This list includes all the physical formats that you have defined for this message set.

      Leave Message Format blank for XML, XMLNS, XMLNSC, JMS, MIME, and BLOB parsers.

  4. On the Parser Options tab, Parse Timing is, by default, set to On Demand, which causes validation to be delayed until the message is parsed by partial parsing. If you change this value to Immediate, partial parsing is overridden and everything in the message is parsed and validated, except for those complex types with a composition of Choice or Message that cannot be resolved at the time. If you change this value to Complete, partial parsing is overridden and everything in the message is parsed and validated; complex types with a composition of Choice or Message that cannot be resolved at the time cause a validation failure.
  5. On the Advanced tab, set the properties that determine how the message is processed, such as its transactional characteristics. Many of these properties map to options on the MQGET call.
    • Select Transaction Mode from the list to define the transactional characteristics of how this message is handled:
      • If you select Automatic, the incoming message is received under syncpoint if it is marked persistent, otherwise it is not. The transactionality of any derived messages that are sent subsequently by an output node is determined by the incoming persistence property, unless the output node has overridden transactionality explicitly.
      • If you select Yes, the incoming message is received under syncpoint. Any derived messages that are sent subsequently by an output node in the same instance of the message flow are sent transactionally, unless the output node has overridden transactionality explicitly.
      • If you select No, the incoming message is not received under syncpoint. Any derived messages that are sent subsequently by an output node in the message flow are sent non-transactionally, unless the output node has specified that the messages must be put under syncpoint.
    • Select Order Mode from the list to determine the order in which messages are retrieved from the input queue. This property has an effect only if the message flow property Additional Instances is set to greater than zero; that is, if multiple threads read the input queue. Valid values are:
      • Default. Messages are retrieved in the order that is defined by the queue attributes, but this order is not guaranteed because the messages are processed by the message flow.
      • By User ID. Messages that have the same UserIdentifier in the MQMD are retrieved and processed in the order that is defined by the queue attributes; this order is guaranteed to be preserved when the messages are processed. A message that is associated with a particular UserIdentifier that is being processed by one thread, is completely processed before the same thread, or another thread, can start to process another message with the same UserIdentifier. No other ordering is guaranteed to be preserved.
      • By Queue Order. Messages are retrieved and processed by this node in the order that is defined by the queue attributes; this order is guaranteed to be preserved when the messages are processed. This behavior is identical to the behavior that is exhibited if the message flow property Additional Instances is set to zero.

      For more details about using this option, see Configuring the node to handle message groups.

    • Select Logical Order to ensure that messages that are part of a message group are received in the order that has been assigned by the sending application. This option maps to the MQGMO_LOGICAL_ORDER option of the MQGMO of the MQI.

      If you clear the check box, messages that are sent as part of a group are not received in a predetermined order. If a broker expects to receive messages in groups, and you have not selected this check box, either the order of the input messages is not significant, or you must design the message flow to process them appropriately.

      You must also select Commit by Message Group if you want message processing to be committed only after the final message of a group has been received and processed.

      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.

      For more details about using this option, see Configuring the node to handle message groups.

    • Select All Messages Available if you want message retrieval and processing to be done only when all messages in a single group are available. This property maps to the MQGMO_ALL_MSGS_AVAILABLE option of the MQGMO of the MQI. Clear this check box if message retrieval does not depend on all messages in a group being available before processing starts.

      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.

    • Enter a message identifier in Match Message ID if you want the input node to receive only messages that contain a matching message identifier value in the MsgId field of the MQMD.

      Enter an even number of hexadecimal digits (characters 0 to 9, A to F, and a to f are valid) up to a maximum of 48 digits. If the ID that you enter is shorter than the size of the MsgId field, it is padded on the right with X'00' characters. This property maps to the MQMO_MATCH_MSG_ID option of the MQGMO of the MQI.

      Leave this property blank if you do not want the input node to check that the message ID matches.

      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.

    • Enter a message identifier in Match Correlation ID if you want the input node to receive only messages that contain a matching correlation identifier value in the CorrelId field of the MQMD.

      Enter an even number of hexadecimal digits (characters 0 to 9, A to F, and a to f are valid) up to a maximum of 48 digits. If the ID that you enter is shorter than the size of the CorrelId field, it is padded on the right with X'00' characters. This property maps to the MQMO_MATCH_CORREL_ID option of the MQGMO of the MQI.

      Leave this property blank if you do not want the input node to check that the CorrelID matches.

      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.

    • Select Convert if you want WebSphere MQ to perform data conversion on the message when it is retrieved from the queue. This option is useful if you are handling messages in the BLOB domain, or are using a user-defined parser. Do not select this option if you are parsing messages with the XML or MRM domains, because the parser does the conversion.

      WebSphere MQ converts the incoming message to the encoding and coded character set that is specified in the MQMD that the input node supplies on the MQGET call to retrieve the message from the input queue. The broker uses the MQGMO_CONVERT option on the MQGET call; normal rules for WebSphere MQ conversion apply. The values that you specify in the Convert Encoding and Convert coded character set ID options are used in the MsgDesc Encoding and CCSID fields in the MQGET call. WebSphere MQ can convert the incoming message only if the MQMD Format field is a built-in MQ value that identifies character data, or if a data conversion exit exists in WebSphere MQ.

      This property maps to the MQGMO_CONVERT option of the MQGMO of the MQI.

      Clear the check box if you do not want WebSphere MQ to convert the message.

      If you select this check box, you can also specify:

      • Convert Encoding. Enter the number that represents the encoding to which you want to convert numeric data in the message body. Valid values include:
        • 546 for DOS and all Windows systems
        • 273 for all Linux and UNIX systems
        • 785 for z/OS systems
        The encoding is used only in these circumstances:
        • If a user-defined WebSphere MQ data conversion exit uses the encoding; or
        • If the built-in WebSphere MQ conversion exit uses the encoding to convert messages in any of the predefined WebSphere MQ formats.
        If you specify an invalid value, no conversion is done.
      • Convert Coded Char Set ID. Enter the number that represents the character set identifier to which you want to convert character data in the message body.

        If you specify an invalid value, no conversion is done.

      For more information about WebSphere MQ data conversion, and why you might choose to use this option, see the Application Programming Guide section of the WebSphere MQ Version 6 information center online. For further information about the values that you can specify for Convert Encoding and Convert Coded Char Set ID, see the Application Programming Reference section of the WebSphere MQ Version 6 information center online.

    • Select Commit by Message Group if you want message processing to be committed only after the final message of a group has been received and processed. If you leave this check box cleared, a commit is performed after each message has been propagated completely through the message flow.

      This property is relevant only if you have selected Logical Order.

      Set the Order Mode property to By Queue Order if the messages in a group must be retrieved and processed in the order in which they appear on the queue.

    • z/OS platform On z/OS only: Enter a serialization token in z/OS Serialization Token if you want to use the serialized access to shared resources that is provided by WebSphere MQ.

      The value that you provide for the serialization token must conform to the rules described in the Application Programming Reference section of the WebSphere MQ Version 6 information center online.

      For more information about serialization and queue sharing on z/OS, refer to the Concepts and Planning Guide section of the WebSphere MQ Version 6 information center online.

    • Optional: You can associate a message with a publish/subscribe topic using the Topic property. You can enter any characters as the topic name. When messages pass through the MQInput node, they assume whatever topic name you have entered. (If you are using publish/subscribe, you can subscribe to a topic and see any messages that passed through the MQInput node and were published under that topic name.) If the incoming message has an MQRFH2 header, you do not need to set a value for the Topic property because the value can be obtained from the <psc> folder in the MQRFH2 header; for example:
      <psc><Topic>stockquote</Topic></psc>
      If you set a Topic property value, and that value differs from the <Topic> value in the MQRFH2 header, the value in the MQRFH2 header takes precedence.
    • Start of changeSelect Browse Only to specify that the message should be retained on the queue when it is read.End of change
    • Start of changeProvide a value for Reset Browse Timeout to specify how many milliseconds to wait between the last eligible message being browsed on the input queue and the browse being reset to the beginning of the queue. If you do not provide a value, the default value of -1 is used to indicate that the browse is not reset.End of change
  6. On the Validation page, set the validation properties if you want the MRM parser to validate the body of messages against the dictionary that is generated from 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.

  7. Start of changeOptional: On the Security page, set values for the properties that control the authentication, authorization, and propagation of an identity on a message.
    • Optional: Select an option from the Identity Token Type list to specify the type of identity in the incoming message. If you leave this option blank, the identity is retrieved from the transport headers, and the type is set to username.
    • Optional: In Identity Token Location, enter the location in the message where the identity is specified. If you leave this option blank, the identity is retrieved from the MQMD.UserIdentifier transport header.
    • Optional: In Identity Password Location, enter the location in the message where the password is specified. This option can be set only if the Identity Token Type is set to usernameAndPassword. If you leave this option blank, the password is not set.
    • Optional: In Identity IssuedBy Location, specify a string or path expression to show where (in the message) information about the issuer of the identity is held. If you leave this blank, the MQMD.PutApplName value is used.
    • Optional: In Security Profile, specify the name of the security profile to be used for processing the incoming identity.
    • Optional: Select Treat Security Exceptions as normal exceptions if you want security exceptions (such as Access Denied) to be treated as normal exceptions and propagated down the catch terminal (if it is wired). By default this is turned off, which ensures that the security exceptions cause the message to be backed out even if the catch terminal is wired.
    End of change
  8. Start of changeOptional: On the Instances page, set values for the properties that control the additional instances that are available for a node. For more details, see Configurable message flow properties.End of change

Connecting the terminals

The MQInput node routes each message that it retrieves successfully to the Out terminal. If this action fails, the message is retried. If the backout count is exceeded (as defined by the BackoutThreshold attribute of the input queue), the message is routed to the Failure terminal; you can connect nodes to this terminal to handle this condition. If you have not connected the Failure terminal, the message is written to the backout queue.

If the message is caught by this node after an exception has been thrown further on in the message flow, the message is routed to the Catch terminal. If you have not connected the Catch terminal, the message loops continually through the node until the problem is resolved.

You must define a backout queue or a dead-letter queue (DLQ) to prevent the message from looping continually through the node.

Configuring for coordinated transactions

When you include an MQInput node in a message flow, the value that you set for Transaction Mode defines whether messages are received under syncpoint:
  • If you set the property to Automatic, the message is received under syncpoint if the incoming message is marked as persistent; otherwise, it is not. Any message that is sent subsequently by an output node is put under syncpoint, as determined by the incoming persistence property, unless the output node has overridden this explicitly.
  • If you set the property to Yes (the default), the message is received under syncpoint (that is, within a WebSphere MQ unit of work). Any messages that are sent subsequently by an output node in the same instance of the message flow are put under syncpoint, unless the output node has overridden this explicitly.
  • If you set the property to No, the message is not received under syncpoint. Any messages that are sent subsequently by an output node in the message flow are not put under syncpoint, unless an individual output node has specified that the message must be put under syncpoint.
The MQOutput node is the only output node that you can configure to override this option.

Start of changeIf you have set the Browse Only property, the value that is set for the Transaction Mode property is ignored because a message cannot be browsed under syncpoint. However, any derived messages that are propagated subsequently by an output node in the same instance of the message flow follow the behavior that is described above in accordance with the specified Transaction Mode value.End of change

Configuring the node to handle message groups

WebSphere MQ supports message groups; you can specify that a message belongs to a group and that its processing and the processing of all other messages in the group must be handled as one transaction; that is, if the processing on one message in the group fails, all messages in the group are backed out. The message processing is committed after all messages have been processed successfully.

If you include messages in a group, and it is important that all of the messages within the group are read from the queue and processed in the order in which they are defined in the group, you must complete all the actions stated below:

  • Select Commit by Message Group.
  • Select Logical Order.
  • Set Order Mode to By Queue Order or set the message flow property Additional Instances to zero. (You can modify message flow properties when you add the message flow to the bar file for deployment.)

    If you choose either of these options (or both), the message flow processes the messages on a single thread of execution, and a message is processed to completion before the next message is retrieved from the queue. In all other cases, it is possible that multiple threads within a single message flow are processing multiple messages, and the final message in a group, which prompts the commit or roll back action, is not guaranteed to be processed to completion after all other messages in the group.

You must also ensure that you do not have another message flow that is retrieving messages from the same input queue. If you do, the order in which the messages within a group are processed is not guaranteed.

MQGET buffer size

The MQGET buffer size is implemented internally by the broker and you cannot change it. The following description is provided for information only. You should not rely on it when you develop your message flows, because the internal implementation could change.

When the MQInput node initializes, it sets the size of the default buffer for the first MQGET to 4 KB. However, the node monitors the size of messages and increases or reduces the size of the buffer, as follows:

  1. If an MQGET fails because the message is larger than the size of the buffer, the node immediately increases the size of the buffer to accommodate the message, issues the MQGET again, and zeroes a message count.
  2. When 10 messages have been counted since the increase in the size of the buffer, the node compares the size of the largest of the 10 messages with the size of the buffer. If the size of the largest message is less than 75% of the size of the buffer, the buffer is reduced to the size of the largest of the 10 messages. If an MQGET fails during the 10 messages because the message is larger than the size of the buffer, the node takes action 1, as above.

For example, if the first message that the node receives is 20 MB, and the next 10 messages are each 14 MB, the size of the buffer is increased from 4 KB to 20 MB and remains at 20 MB for 10 messages. However, after the 10th message the size of the buffer is reduced to 14 MB.

Terminals and properties

The terminals of the MQInput node are described in the following table.

Terminal Description
Failure The output terminal to which the message is routed if an error occurs. Even if the Validation property is set, messages propagated to this terminal are not validated.
Out The output terminal to which the message is routed if it is successfully retrieved from the WebSphere MQ queue.
Catch The output terminal to which the message is routed if an exception is thrown downstream and caught by this node.

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 Description properties of the MQInput node are described in the following table.

Property M C Default Description
Node name No No The node type, MQInput 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 Basic properties of the MQInput node are described in the following table.

Property M C Default Description
Queue Name Yes Yes   The name of the WebSphere MQ input queue from which this node retrieves messages (using MQGET) for processing by this message flow.

The Input Message Parsing properties of the MQInput node are described in the following table.

Property M C Default Description
Message Domain No No   The domain that is used to parse the incoming message.
Message Set No No   The name or identifier of the message set in which the incoming message is defined.
Message Type No No   The name of the incoming message.
Message Format No No   The name of the physical format of the incoming message.

The properties of the Parser Options for the MQInput node are described in the following table.

Property M C Default Description
Parse Timing Yes No On Demand This property controls when an input message is parsed. Valid values are On Demand, Immediate, and Complete.

For a full description of this property, see Parsing on demand.

Use MQRFH2C compact parser for MQRFH2 header Yes No Cleared This property controls whether the MQRFH2C compact parser, instead of the MQRFH2 parser, is used for MQRFH2 headers.
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 message data appears under XMLNSC in nodes that are connected to the output terminal when the input MQRFH2 header or Input 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 an input 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 an input 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 an input 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.

The Advanced properties of the MQInput node are described in the following table.

Property M C Default Description
Transaction Mode Yes No Yes This property controls whether the incoming message is received under syncpoint. Valid values are Automatic, Yes, and No.
Order Mode Yes No Default The order in which messages are retrieved from the input queue and processed. Valid values are Default, By User ID, and By Queue Order.
Logical Order Yes No Selected If you select this check box, messages are received in logical order, as defined by WebSphere MQ.
All Messages Available Yes No Cleared If you select the check box, all messages in a group must be available before retrieval of a message is possible.
Match Message ID No No   A message ID that must match the message ID in the MQMD of the incoming message.
Match Correlation ID No No   A correlation ID that must match the correlation ID in the MQMD of the incoming message.
Convert Yes No Cleared If you select this check box, WebSphere MQ converts data in the message to be received, in conformance with the CodedCharSetId and Encoding values set in the MQMD.
Convert Encoding No No   The representation used for numeric values in the message data, expressed as an integer value. This property is valid only if you have selected Convert.
Convert Coded Character Set ID No No   The coded character set identifier of character data in the message data, expressed as an integer value. This property is valid only if you have selected Convert.
Commit By Message Group Yes No Cleared This property controls when a transaction is committed when processing messages that are part of a message group. If you select the check box, the transaction is committed when the message group has been processed.
z/OS® Serialization Token No No   A user-defined token for serialized application support. The value that is specified must conform to the rules for a valid ConnTag in the WebSphere MQ MQCNO structure. .
Topic No Yes   The default topic for the input message.
Start of changeBrowse OnlyEnd of change Start of changeNoEnd of change Start of changeNoEnd of change Start of changeClearedEnd of change Start of changeThis property controls whether a message is removed from the queue when it is read. If you select this check box, the message is not removed from the queue when it is read.End of change
Start of changeReset Browse Timeout (ms)End of change Start of changeYesEnd of change Start of changeYesEnd of change Start of change-1End of change Start of changeThe time, in milliseconds, between the last eligible message being browsed on the input queue and the browse being reset to the beginning of the queue. The default value of -1 indicates that the browse is not reset.End of change

The Validation properties of the MQInput node are described in the following table.

For a full description of these properties, see Validation properties.
Property M C Default Description
Validate Yes Yes None This property controls whether validation takes place. Valid values are None, Content, and Content And Value.
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.
Include All Value Constraints Yes No Selected You cannot edit this property. Basic value constraint checks are included in Content and Value validation.
Fix Yes No None You cannot edit this property.
Start of changeThe Instances properties of the MQInput node are described in the following table. For a full description of these properties, refer to Configurable message flow properties.
Property M C Default Description
Additional instances pool No Yes Use Pool Associated with Message Flow The pool from which additional instances are obtained.
  • If you select Use Pool Associated with Message Flow, additional instances are obtained from the message flow value.
  • If you select Use Pool Associated with Node, additional instances are allocated from the node's additional instances based on the number specified in the Additional instances property.
Additional instances No Yes 0 The number of additional instances that the node can start if the Additional instances pool property is set to Use Pool Associated with Node. By default, no additional instances are given to the node.
End of change
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2007Copyright IBM Corporation 1999, 2007. All Rights Reserved.
This build: July 31, 2007 21:17:21

ac04560_ This topic's URL is: