This topic contains the following sections:
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.
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 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.
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 represented in the workbench by the following icon:
Look at the following sample to see how you can use 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:
See Configuring the node to handle message groups for more details about this option.
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.
More information about the options to which this property maps is available in the WebSphere MQ Application Programming Reference.
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 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.
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:
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.
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.
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 WebSphere MQ Application Programming Reference.
For more information about serialization and queue sharing on z/OS, refer to the WebSphere MQ Concepts and Planning Guide.
Click Cancel to close the dialog and discard all the changes that you have made to the properties.
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.
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:
(The MQOutput node is the only output node that you can configure to override this option.)
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:
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.
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 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. |
z/OS Serialization Token | No | No | A user-defined token for serialized application support. The value specified must conform to the rules for a valid ConnTag in the WebSphere MQ MQCNO structure. These rules are described in the WebSphere MQ Application Programming Reference. |
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. |
Notices |
Trademarks |
Downloads |
Library |
Support |
Feedback
![]() ![]() |
ac04560_ |