Use the MQInput node to receive messages from clients that connect to the broker by 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 queue manager of the broker. 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, the output node can be any one 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 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 IBM® Integration Toolkit by the following icon:
You can view information about samples only when you use the product documentation that is integrated with the IBM Integration Toolkit or the online product documentation. You can run samples only when you use the product documentation that is integrated with the IBM Integration Toolkit.
The MQInput node routes each message that it retrieves successfully to the Out terminal. If this action fails, the message is tried again. 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.
If 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 sync point. However, any derived messages that are propagated later by an output node in the same instance of the message flow follow the behavior that is described previously in accordance with the specified Transaction mode value.
The MQGET buffer size is implemented internally by the broker and you cannot change it. The following description is provided for information only. You must not rely on it when you develop your message flows, because the internal implementation might change.
When the MQInput node initializes, it sets the size of the default buffer for the first MQGET to 4 KB. The MQInput node monitors the size of messages and increases or reduces the size of the buffer:
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.
When you have put an MQInput node into a message flow, you can use the Properties view to configure the node; see Configuring a message flow node. Alternatively, you can use an MQ Service to configure an MQInput node. See Configuring an MQ node by using an MQ Service. 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.
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 | mqsiapplybaroverride command property |
---|---|---|---|---|---|
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. You must predefine this WebSphere MQ queue to the queue manager that hosts the broker to which the message flow is deployed. | queueName |
The MQInput node Input Message Parsing properties are described in the following table.
<mcd><Msd>MRM</Msd><Set>DHM4UO906S001</Set><Type>receiptmsg1</Type>
<Fmt>XML</Fmt></mcd>
If you set values, and those
values differ from the values in the MQRFH2 header, and the <Msd> element
is a valid domain, the values in the MQRFH2 header take precedence.Property | M | C | Default | Description |
---|---|---|---|---|
Message domain | No | No | BLOB | The domain that is used to parse the message. If the field is blank then the default is BLOB. |
Message model | No | No | Cleared | The name or location of the message model schema file in which the message is defined. This list is populated with all available message model schema files for the Message domain that you have selected. |
Message | No | No | Cleared | The name or location of the message root within your message model schema file. This list is populated with all available messages that are defined in the Message model that you have selected. |
Physical format | No | No | Cleared | The name of the physical format of the message. If you are using the MRM or IDOC parser, select the physical format of the incoming message from the list. This list includes all the physical formats that you have defined for the selected message model. If you set the Message domain property to DataObject, you can set this property to XML or SAP ALE IDoc. Set this property to SAP ALE IDoc when you have to parse a bit stream from an external source and generate a message tree. |
The properties of the Parser Options for the MQInput node are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
Parse timing | No | No | On Demand | This property controls when an input message
is parsed. Valid values are On
Demand, Immediate,
and Complete. Parse timing is, by default, set to On Demand, which causes parsing of the message to be delayed. To cause the message to be parsed immediately, see Parsing on demand. |
Use MQRFH2C compact parser for MQRFH2 header | No | No | Cleared | This property controls whether the MQRFH2C compact parser, instead of the MQRFH2 parser, is used for MQRFH2 headers. |
Build tree using XML schema data types | No | No | Cleared | This property controls whether the XMLNSC parser creates syntax elements in the message tree with data types taken from the XML schema. You can select this property only if you set the Validate property on the Validation tab to Content or Content and Value. |
Use XMLNSC compact parser for XMLNS domain | No | 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 is displayed under XMLNSC in nodes that are connected to the output terminal when the input MQRFH2 header or the Input Message Parsing property Message domain is XMLNS. For more information, see Manipulating messages in the XMLNSC domain. |
Retain mixed content | No | 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 | No | 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 | No | 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. |
Opaque elements | No | No | Blank | This property is used to specify a list of elements in the input message that are to be opaquely parsed by the XMLNSC parser. Opaque parsing is performed only if validation is not enabled (that is, if Validate is None); entries that are specified in Opaque Elements are ignored if validation is enabled. |
The Advanced properties of the MQInput node are described in the following table. Set these properties to determine how the message is processed, such as its transactional characteristics. Many of these properties map to options on the MQGET call.
Property | M | C | Default | Description | mqsiapplybaroverride command property |
---|---|---|---|---|---|
Transaction mode | Yes | No | Yes | This property controls whether the incoming
message is received under sync point. 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. Messages arriving can be processed in order, or any thread can process any message when it is ready. When ordering is imposed, a thread processes a message only if it is the first unprocessed message available with a unique ordering value. Valid values are Default, By User ID, By Queue Order, and User Defined. This property has an effect only if the message flow property Additional instances on the Instances tab, is set to greater than zero; that is, if multiple threads read the input queue. Valid values are:
For more details about using this option, see Optimizing message flow throughput and Receiving messages in a WebSphere MQ message group. |
|
Order field location | N | N | "" | An XPath or ESQL expression property to control
which part of the message is used to impose ordering on incoming messages
when Order mode is User Defined. If the field is missing, an exception is raised, and the message is rolled back. NULL and empty values are processed separately, in parallel. |
|
Logical order | Yes | No | Selected | If you select this check box, messages are received
in logical order, as defined by WebSphere MQ.
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 7 product documentation online. For more details about using this option, see Receiving messages in a WebSphere MQ message group. |
|
All messages available | Yes | No | Cleared | 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 of the 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 7 product documentation online. |
|
Match message ID | No | No | A message ID that must match the message ID
in the MQMD of the incoming message. Enter a message identifier 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 matching message identifier that you enter is shorter than the size of the MsgId field, Match message ID 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 7 product documentation online. |
||
Match correlation ID | No | No | A correlation ID that must match the correlation
ID in the MQMD of the incoming message. Enter a message identifier
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 7 product documentation online. |
||
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. 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; typical 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 WebSphere 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 values for the Convert encoding and Convert coded character set ID properties. 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 7 product documentation online. |
|
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. Enter
the number that represents the encoding to which you want to convert
numeric data in the message body. Valid values include:
For further information about the values that you can specify for Convert encoding, see Data conversion and the Application Programming Reference section of the WebSphere MQ Version 7 product documentation online. |
||
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. Enter the value that represents the character set identifier to which you want to convert character data in the message body. If you specify an incorrect value, no conversion is done. For further information about the values that you can specify for Convert coded character set ID, see the Application Programming Reference section of the WebSphere MQ Version 7 product documentation online. |
||
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. 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 are displayed on the queue. |
|
z/OS serialization token | No | No | On z/OS only:
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. Enter
a 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 7 product documentation online. For more information about serialization and queue sharing on z/OS, see the Concepts and Planning Guide section of the WebSphere MQ Version 7 product documentation online. |
serializationToken | |
Topic | No | Yes | The default topic for the input message. You
can associate a message with a publish/subscribe topic
by using this property. You can enter any characters as the topic
name. When messages pass through the MQInput node, they take on
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 have to set a value for the Topic property
because the value can be obtained from the <psc> folder
in the MQRFH2 header; for example:
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. |
topicProperty | |
Browse Only | No | No | Cleared | This 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. If you select this option, OutputLocalEnvironment.MQ.GET.Browsed is set to true when a message is propagated to the output terminal of the MQInput node. | |
Reset browse timeout (ms) | Yes | Yes | -1 | The 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. |
The Validation properties of the MQInput node are described in the following table. Set these 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.
Property | M | C | Default | Description | mqsiapplybaroverride command property |
---|---|---|---|---|---|
Validate | No | Yes | None | This property controls whether validation takes place. Valid values are None, Content, and Content and Value. | validateMaster |
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. |
The Security properties of the MQInput node are described in the following table. Set values for these properties to control the extraction of an identity from a message (when a security profile is associated with the node). For more information about these properties, see Identity, Configuring the extraction of an identity or security token, Message flow security overview, and Setting up message flow security.
Property | M | C | Default | Description |
---|---|---|---|---|
Identity token type | No | No | None | This property specifies the type of identity
token present in the incoming message. Valid values are:
|
Identity token location | No | No | None | This property specifies where, in the message, the identity can be found. The location is specified as an ESQL field reference, an XPath expression, or a string literal. If you use a string literal, it must be enclosed in single quotation marks and must not contain a period (.), If this property is not specified, the identity is retrieved from the MQMD.UserIdentifier transport header. |
Identity password location | No | No | None | This property specifies where, in the message, the password can be found. The location is specified as an ESQL field reference, an XPath expression, or a string literal. If you use a string literal, it must be enclosed in single quotation marks and must not contain a period (.), If it is not specified, the password is not set. This property can be set only if Identity token type is set to Username + Password. |
Identity IssuedBy location | No | No | None | This property specifies a string or path expression that describes the issuer of the identity. The location is specified as an ESQL field reference, an XPath expression, or a string literal. If you use a string literal, it must be enclosed in single quotation marks and must not contain a period (.), The value specifies the Issuer that is passed to a WS-Trust v1.3 STS provider. If this property is not specified, the MQMD.PutApplName value is used. If you leave the Identity issuedBy location field blank and the MQMD.PutApplName is also blank, the string MQ is used. |
Treat security exceptions as normal exceptions | No | No | False | This property specifies whether to treat security exceptions (such as "Access Denied") as normal exceptions, and propagate them to the Failure terminal (if wired). This property is turned off by default, which ensures that security exceptions cause the message to be backed out even if the Failure terminal is wired. |
Property | M | C | Default | Description | mqsiapplybaroverride command property |
---|---|---|---|---|---|
Additional instances pool | No | Yes | Use Pool Associated with Message Flow | The pool from which additional instances are
obtained.
|
componentLevel |
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. | additionalInstances |
Property | M | C | Default | Description |
---|---|---|---|---|
Events | No | No | None | Events that you have defined for the node are
displayed on this tab. By default, no monitoring events are defined
on any node in a message flow. Use Add, Edit,
and Delete to create, change or delete monitoring
events for the node; see Configuring monitoring event sources using monitoring properties for details. You can enable and disable events that are shown here by selecting or clearing the Enabled check box. |