Message tree

The message tree is a part of the logical tree (message assembly) in which the internal representation of the message body is stored.

The root of a message tree is called Root. The message tree is always present, and is passed from node to node in a single instance of a message flow.

The message tree includes all the headers that are present in the message, in addition to the message body. The tree also includes the Properties subtree, if that is created by the parser. If a supplied parser has created the message tree, the element that represents the Properties subtree is followed by zero or more headers.

If the message has been received across the IBM® MQ Enterprise Transport or IBM MQ Mobile Transport, the first header (the second element) must be the MQMD. Any additional headers that are included in the message appear in the tree in the same order as in the message. The last element beneath the root of the message tree is always the message body.

If a user-defined parser has created the message tree, the Properties tree, if present, is followed by the message body.

The message tree structure is shown in the following section. If the input message is not an IBM MQ message, the headers that are shown might not be present. If the parser that created this tree is a user-defined parser, the Properties tree might not be present.

Message tree structure created by an input node and parser for a message received across a transport that uses IBM MQ.

The Body tree is a structure of child elements that represents the message content (data), and reflects the logical structure of that content. The Body tree is created by a body parser (either a supplied parser or a user-defined parser)

Each element in the parsed tree is one of three types:

Name element: A name element has a string associated with it, which is the name of the element. An example of a name element is XMLElement. A name element also has a second string associated with it, which is the namespace of the element; this string might be empty.
Value element: A value element has a value associated with it. An example of a value element is XMLContent.
Name-value element: A name-value element is an optimization of the case where a name element contains only a value element and nothing else. The element contains both a name and a value. An example of a name-value element is XMLAttribute.

Properties folder

The Properties folder is the first element of the message tree and holds information about the characteristics of the message.

The root of the Properties folder is called Properties. It is the first element under Root. All message trees that are generated by the built-in parsers include a Properties folder for the message. If you create your own user-defined parser, you can choose whether the parser creates a Properties folder. However, for consistency, you should include this action in the user-defined parser.

The Properties folder contains a set of standard properties that you can manipulate in the message flow nodes in the same way as any other property. Some of these fields map to fields in the supported IBM MQ headers, if present, and are passed to the appropriate parser when a message is delivered from one node to another.

For example, the MQRFH2 header contains information about the message model, message name, and message physical format. These values are stored in the Properties folder as MessageSet, MessageType, and MessageFormat. To access these values using ESQL or Java™ in the message processing nodes, refer to these values in the Properties folder; do not refer directly to the fields in the headers from which they are derived.

The Properties parser ensures that the values in the header fields match the values in the Properties folder on input to, and output from, every node. For any field, if only one header is changed (the Properties header or a specific message header), that value is used. If both the Properties header and the specific message header are changed, the value from the Properties folder is used.

When the message flow processing is complete, the Properties folder is discarded.