How the message tree is populated

The message tree is initially populated by the input node of the message flow.

When the input node receives the input message, it creates the Properties tree (the first subtree of the message tree) and populates this with the node properties that you have configured in the message flow. It then examines the contents of the input message bit stream and creates the remainder of the message tree to reflect those contents. This process depends to some extent on the input node itself, which is governed by the transport across which the message is received:

WebSphere MQ Enterprise Transport, and WebSphere MQ Telemetry Transport protocols
If your application communicates with the broker across these protocols, and your message flow includes the corresponding MQInput, or SCADAInput node, all messages that are received must start with a Message Queue Message Descriptor (MQMD) header. If a valid MQMD is not present at the start of the message, the message is rejected and no further processing takes place.

The input node first invokes the MQMD parser and creates the subtree for that header.

A message can have zero or more additional headers following the MQMD, and these are chained together, with the Format field of one header defining the format of the following header, up to and including the last header, which defines the format of the message body. If there is an MQRFH and MQRFH2 header in the chain, the name/value data in either of these two headers can also contain information about the format of the following data. If the value specified in Format is a recognized parser, this always takes precedence over the name/value data.

The broker invokes the appropriate parser to interpret each header, following the chain in the message. Each header is parsed independently. The fields within a single header are parsed in an order that is governed by the parser. You cannot predict or rely on the order chosen, but the order in which fields are parsed does not affect the order in which the fields appear within the header.

The broker ensures that the integrity of the headers that precede a message body is maintained. The format of each part of the message is defined, either by the Format field in the immediately preceding header (if the following part is a recognized WebSphere MQ format) or by the values set in the MQRFH or MQRFH2 header:

  • The format of the first header is known, because this must be MQMD.
  • The format of any subsequent header in the message is set in the Format field in the preceding header.
  • The format of the body corresponds to the message domain and the parser that must be invoked for the message body (for example, XML). This information is set either in the MQRFH or MQRFH2 header, or in the message domain property of the input node that receives the message.

This process is repeated as many times as required by the number of headers that precede the message body. You do not have to populate these fields yourself; the broker handles this sequence for you.

The broker completes this process to ensure that Format fields in headers correctly identify each part of the message. If the broker does not do this, WebSphere MQ might be unable to deliver the message. Because the message body parser is not a recognized WebSphere MQ header format, the broker replaces this value in the last header's Format field with the value MQFMT_NONE. The original value in that field is stored in the Domain field within the MQRFH or MQRFH2 header to retain the information about the contents of the message body. If there is no MQRFH or MQRFH2, the information is stored in the Properties tree.

For example, if the MQRFH2 header immediately precedes the message body and its Format field is set to XML, indicating that the message body must be parsed by the generic XML parser, the MQRFH2 Domain field is set to XML, and its Format field reset to MQFMT_NONE.

These actions might result in information explicitly stored by an ESQL expression being replaced by the broker.

When all the headers have been parsed, and the corresponding subtrees created within the message tree, the input node associates the specified parser with the message body. You must specify the parser that is to be associated with the message body content. You can do this either in a header in the message, for example the <mcd> folder within the MQRFH2 header (generally recommended), or in the input node properties (recommended if the message does not include headers). The input node makes the association as described below:

  • If the message has an MQRFH or MQRFH2 header, the domain that is identified in the header (either in Format or the name/value data) determines the parser that is associated with this message.

    The SCADAInput node creates WebSphere MQ format messages with MQRFH2 headers from the input messages that the listener receives on the TCP/IP port.

  • If the message does not have an MQRFH or MQRFH2 header, or the header does not identify the domain, but the properties of the input node, stored in the Properties tree, indicate the domain of the message, the parser specified by the input node property is used. You can specify a user-defined parser.
  • If the message domain cannot be identified by header values or by properties of the input node, the message is handled as a binary object (BLOB). The BLOB parser is associated with the message. A BLOB can be interpreted as a string of hexadecimal characters, and can be modified or examined in the message flow by specifying the location of the subset of the string.

The message body is not parsed for performance reasons; it is possible that the configuration of the message flow does not require the message body to be parsed. The body is parsed only when a reference is made to its contents during the message flow.

For example, the message body is parsed when you refer to Root.XML.Field (or InputRoot.XML.Field in the Compute node) or Root.MRM.Field. Depending on paths taken in the message flow, this parse could take place at different points. This parse when first needed approach is also referred to as partial parsing, and in normal processing does not affect the logic of a message flow. However, there are some implications for error handling scenarios, as described in Handling errors in message flows.

If you want a message flow to accept messages from more than one message domain, you can include an MQRFH2 header in your message from which the input nodes extract the message domain and related message definition information (set, type, and format).

If you set up the message headers or the input node properties to identify a user-defined parser, the way in which it interprets the message and constructs the logical tree might differ from that described here.

WebSphere MQ Multicast Transport, WebSphere MQ Real-time Transport, and WebSphere MQ Web Services Transport protocols
If your application communicates with the broker across these supported protocols, and your message flow includes the corresponding Real-timeInput, HTTPInput, or HTTPRequest nodes, messages that are received are not required to include a particular header. Your applications can include the MQRFH2 header to provide message-related information, for example about publications and subscriptions. If recognized headers are included, the input node invokes the appropriate parsers to interpret the headers and to build the relevant parts of the message tree, as described for the other supported protocols.

If there are no headers, or these headers do not specify the parser for the message body, you must set the input node properties to define the message body parser. If you do not do so, the message is treated as a BLOB. You can specify a user-defined parser.

The specified parser is associated with the message body by the input node (in the same way as it is for theWebSphere MQ Enterprise Transport, WebSphere MQ Mobile Transport, and WebSphere MQ Telemetry Transport protocols) and the message body is not parsed.

If you set up the message headers or the input node properties to identify a user-defined parser, the way in which it interprets the message and constructs the logical tree might differ from that described here.

All other protocols
If you want your message flow to accept messages from a transport protocol for which WebSphere Message Broker does not provide built-in support, or you want it to provide some specific processing on receipt of a message, use either the Java or the C language programming interface to create a new user-defined input node.

This interface does not automatically generate a Properties subtree for a message (this subtree is discussed in Message tree structure). It is not a requirement for a message to have a Properties subtree, although you might find it useful to create one to provide a consistent message tree structure regardless of input node. If you want to create a Properties subtree within the message tree, and you are using a user-defined input node, you must do this yourself.

If you need to process messages that do not conform to any of the defined message domains, you can use the C language programming interface to create a new user-defined parser.

Refer to the node interface to understand how it uses parsers, and whether you can configure it to modify its behavior. If the node uses a user-defined parser, the tree structure created for the message might differ slightly from that created for built-in parsers. A user-defined input node can parse an input message completely, or it can participate in partial parsing in which the message body is parsed only when it is required.

You can also create your own output and message processing nodes in C or Java.

Related concepts
Logical tree structure
Message tree structure
Environment tree structure
LocalEnvironment tree structure
ExceptionList tree structure
Partial parsing
Correlation names
Related tasks
Handling errors in message flows
Developing message flows
Related reference
Built-in nodes
User-defined nodes
MQRFH2 header