MQInput node

This topic contains the following sections:

Purpose

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.

The MQInput node receives message input to a message flow from a WebSphere MQ message queue 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 that 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
  • JMSMap
  • JMSStream
  • BLOB

Start of changeIf 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 have 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.End of change

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 these other input nodes:

  • HTTPInput
  • MQeInput
  • Real-timeInput
  • SCADAInput
  • A user-defined input node

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

MQInput node icon

Using the MQInput node in a message flow

Look at the following samples to see how you can use the MQInput node:

Configuring the MQInput node

When you have put an instance of the MQInput 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 in the properties dialog.

All mandatory properties that do not have a default value defined are marked with an asterisk on the properties dialog.

Configure the MQInput node as follows:

  1. 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.
  2. Select Default in the properties dialog navigator and 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, and the default topic associated with the message.
    • If the incoming message has an MQRFH2 header, you do not have to set values for the Default 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 drop-down list. You can choose from the following names:
      • MRM
      • XML
      • XMLNS
      • JMSMap
      • JMSStream
      • BLOB
    • If you are using the MRM or IDOC parser, select the correct message set from the drop-down 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, JMS, , and BLOB parsers.

    • If you are using the MRM parser, select the correct message from the drop-down 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, JMS, , BLOB, and parsers.

    • If you are using the MRM or IDOC parser, select the format of the message from the drop-down 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, JMS, , and BLOB parsers.

    • Enter the message topic in Topic. 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 under that topic name.)
  3. Select Advanced in the properties dialog navigator to set properties that determine how the message is processed, for example its transactional characteristics. Many of these properties map to options on the MQGET call.
    • Select Transaction Mode from the drop-down 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 subsequently sent by an output node is determined by the incoming persistence property, unless the output node has explicitly overridden transactionality.
      • If you select Yes, the incoming message is received under syncpoint. Any derived messages subsequently sent by an output node in the same instance of the message flow are sent transactionally, unless the output node has explicitly overridden transactionality.
      • If you select No, the incoming message is not received under syncpoint. Any derived messages subsequently sent by an output node in the flow are sent non-transactionally, unless the output node has specified that the messages must be put under syncpoint.
    • Select Order Mode from the drop-down 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 0, that is, if multiple threads read the input queue. Valid values are:
      • Default. Messages are retrieved in the order defined by the queue attributes, but this order is not guaranteed as 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 defined by the queue attributes; this order is guaranteed to be preserved when the messages are processed. A message 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 defined by the queue attributes; this order is guaranteed to be preserved when the messages are processed. This behavior is identical to the behavior exhibited if the message flow property Additional Instances is set to 0.

      See Configuring the node to handle message groups for more details about this option.

    • Select the Logical Order check box if you want 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 sent as part of a group are not received in a predetermined order. If a broker expects to receive messages in groups and this check box is not selected, either the order of the input messages is not significant, or the message flow must be designed to process them appropriately.

      You must also select the Commit by Message Group check box 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 WebSphere MQ Application Programming Reference.

      See Configuring the node to handle message groups for more details about this option.

    • Select the All Messages Available check box if you want message retrieval and processing to be done only when all messages in a single group are available. This 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 WebSphere MQ Application Programming Reference.

    • 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 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 WebSphere MQ Application Programming Reference.

    • 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 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 message ID matches.

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

    • Select the Convert check box if you want WebSphere MQ to perform data conversion on the message when it is retrieved from the queue.

      WebSphere MQ converts the incoming message to the encoding and coded character set specified in the MQMD that the input node supplies on the MQGET call to retrieve the message from the input queue. The message flow generates all its output messages using these values, and puts them to target queues with these Encoding and CodedCharSetID values set in the MQMD.

      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 box, you can also specify:

      • Convert Encoding. Enter the number representing the encoding to which you want to convert numeric data in the message body. Valid values include:
        • 546 for DOS and all Windows systems
        • 785 for z/OS systems

        If you do not specify a value, the value in the incoming message MQMD is used.

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

      • Convert Coded Char Set ID. Enter the number representing the character set identifier to which you want to convert character data in the message body.

        If you do not specify a value, the value in the incoming message MQMD is used.

        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 WebSphere MQ Application Programming Guide. For further information about the values that you can specify for Convert Encoding and Convert Coded Char Set ID, see the WebSphere MQ Application Programming Reference.

    • Select the Commit by Message Group check box 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.

  4. Select Validation in the properties dialog navigator if you want the MRM parser to validate the body of messages against the dictionary generated from the message set. (If a message is propagated to the failure terminal of the node, it is not validated.)
    • Validate is initially set to None. Change this to Content and Value to request both content validation (type content and composition checks) and value validation (value data type checks, null permitted checks, length checks, range checks, enumeration checks, and so on).
    • To determine what happens if validation fails, select one of the following options for Failure Action:
      • User Trace: all validation failures are written to user trace and processing continues.
      • Local Error Log: all validation failures are written to the event log and processing continues.
      • Exception: an exception is thrown on the first validation failure. This is the default behavior.
      The first two options are useful when validation is first invoked because you see all validation failures, not just the first encountered. When you have analyzed the failures, you might typically select Exception for future use.

      The failure destinations behave like those for Trace node output. So if, for example, you select User Trace, trace entries are written regardless of the setting of the user trace flag for the message flow.

    • Set a value for Timing from the following list:
      • Deferred: a message is validated only as each field is parsed. This is the default behavior.
      • Immediate: a message is validated immediately, but subsets are permitted to remain unresolved (this supports Composition values Choice and Message under circumstances where the element is not yet resolved).
      • Complete: the entire message is validated immediately.
      The options available for this property take advantage of the partial parsing capability of parsers in that you can choose either to validate only the fields that are accessed (Deferred), or to validate the entire message (Immediate and Complete). The former provides improved performance, the latter increased security.
    • The Include All Value Constraints check box property is selected and cannot be changed from its default setting. This setting means that full data type checks and value checks are made.
    • The Fix property cannot be changed from its default setting of None. If Failure Action is not set to Exception, limited remedial action is taken when validation fails. If Failure Action is set to Exception, no remedial action is taken, and an exception is thrown at the first validation failure.
  5. Select Description in the properties dialog navigator to enter a short description, a long description, or both.
  6. Click Apply to make the changes to the MQInput 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

MQInput routes each message that it retrieves successfully to the out terminal. If this fails, the message is retried. If the retry timeout expires (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 looping continuously 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 it to Yes (the default), the message is received under syncpoint (that is, within a WebSphere MQ unit of work). Any messages subsequently sent by an output node in the same instance of the message flow are put under syncpoint, unless the output node has explicitly overridden this.
  • If you set it to Automatic, the message is received under syncpoint if the incoming message is marked persistent. Otherwise, it is not. Any message subsequently sent by an output node is put under syncpoint, as determined by the incoming persistence property, unless the output node has explicitly overridden this.
  • If you set it to No, the message is not received under syncpoint. Any messages subsequently sent by an output node in the 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.)

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 when the last message in the group has been processed successfully only if processing of all messages has been successful.

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 the Commit by Message Group check box.
  • Select the Logical Order check box.
  • Set the Order Mode to By Queue Order or set the message flow property Additional Instances to 0. (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 there is no guarantee that the final message in a group, which prompts the commit or roll back action, is 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, there is no guarantee about the order in which the messages within a group are processed.

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

Property M C Default Description
Message Domain No No   The domain that will be 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.
Topic No Yes   The default topic for the input message.

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

Property M C Default Description
Transaction Mode Yes No Yes 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 Whether messages are received in logical order, as defined by WebSphere MQ. If you select the check box, this action is performed.
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 Whether WebSphere MQ converts data in the message to be received, in conformance with the CodedCharSetId and Encoding values set in the MQMD. If you select the check box, this action is performed.
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 the Convert check box.
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 the Convert check box.
Commit By Message Group Yes No Cleared 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.

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

Property M C Default Description
Validate Yes Yes None Whether validation takes place. Valid values are None, and Content and Value.
Failure Action Yes No Exception What happens if validation fails. You can set this property only if you set Validate to Content and Value. Valid values are User Trace, Local Error Log, and Exception.
Timing Yes No Deferred When validation occurs. You can set this property only if you set Validate to Content and Value. Valid values are Deferred, Immediate, and Complete.
Include All Value Constraints Yes No Selected This property cannot be edited. The default action, indicated by the check box being selected, is that all value constraints are included in the validation.
Fix Yes No None This property cannot be edited. Minimal fixing is provided.

The Description properties of the MQInput node 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.