This topic contains sections marked as revised for this release
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:
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.
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:
You can view samples only when you use the information center that is integrated with the Message Brokers Toolkit.
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:
<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.
Leave Message Set blank for XML, XMLNS, XMLNSC, JMS, MIME, and BLOB parsers.
Leave Message Type blank for XML, XMLNS, XMLNSC, JMS, MIME, BLOB, and IDOC parsers.
Leave Message Format blank for XML, XMLNS, XMLNSC, JMS, MIME, and BLOB parsers.
For more details about using this option, see Configuring the node to handle message groups.
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.
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 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 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.
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:
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.
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.
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.
<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.
For more details, see Validating messages and Validation properties.
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.
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:
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.
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:
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.
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. | |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
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. |
Property | M | C | Default | Description |
---|---|---|---|---|
Additional instances pool | No | Yes | Use Pool Associated with Message Flow | The pool from which additional instances are obtained.
|
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. |