Environment tree structure

The environment tree is a part of the logical message tree in which you can store information while the message passes through the message flow.

The root of the environment tree is called Environment. This tree is always present in the input message; an empty environment tree is created when a message is received and parsed by the input node. You can use this tree as you choose, and create both its content and structure.

IBM® Integration Bus uses fields in the Environment tree in only two situations. (Contrast this with the local environment tree structure, which the integration node uses in many situations):

  • If you have requested data collection for message flow accounting and statistics, and have indicated that accounting origin basic support is required, the integration node checks for the existence of the field Environment.Broker.AccountingOrigin. If the field exists, the integration node uses its value to set the accounting origin for the current data record. For further information about the use of this field, see Setting message flow accounting and statistics accounting origin.
  • If you have activated a message flow to emit monitoring events the integration node stores correlation attributes in the Environment tree. For further information, see Correlation and monitoring events

The environment tree differs from the local environment tree in that a single instance of it is maintained throughout the message flow. If you include a Compute node, a Mapping node, or a JavaCompute node in your message flow, you do not have to specify whether you want the environment tree to be included in the output message. The environment tree is included automatically, and the entire contents of the input environment tree are retained in the output environment tree, subject to any modifications that you make in the node. Any changes that you make are available to subsequent nodes in the message flow, and to previous nodes if the message flows back (for example, to a FlowOrder or TryCatch node).

If you want to create your own information, create it in the environment tree in a subtree called Variables.

The following figure shown an example of an environment tree:

An Environment tree, with a Variables subtree that contains five children. The fifth child also contains children.

You could use the following ESQL statements to create the content shown above.

SET Environment.Variables = 
      ROW('granary' AS bread, 'riesling' AS wine, 'stilton' AS cheese);
SET Environment.Variables.Colors[] = 
      LIST{'yellow', 'green', 'blue', 'red', 'black'};
SET Environment.Variables.Country[] = LIST{ROW('UK' AS name, 'pound' AS currency),
   	 ROW('USA' AS name, 'dollar' AS currency)};

When the message flow processing is complete, the Environment tree is discarded.