Accessing the local environment tree

The local environment tree has its own correlation name, LocalEnvironment, and you must use this name in all ESQL statements that refer to or set the content of this tree.

About this task

The local environment tree is used by the integration node, and you can refer to and modify this information. You can also extend the tree to contain information that you create yourself. You can create subtrees of this tree that you can use as a scratchpad or working area.

The message flow sets up information in two subtrees, Destination and WrittenDestination, below the LocalEnvironment root. You can refer to the content of both of these subtrees, and you can write to the Destination tree to influence the way in which the message flow processes your message. However, if you write to the Destination tree, follow the defined structure to ensure that the tree remains valid.

The WrittenDestination subtree contains the addresses to which the message has been written. Its name is fixed and it is created by the message flow when a message is propagated through the Out terminal of a request, output, or reply node. The subtree includes transport-specific information (for example, if the output message has been put to a WebSphere® MQ queue, it includes the queue manager and queue names). You can use one of the following methods to obtain information about the details of a message after it has been sent by the nodes:
  • Connect a Compute node to the Out terminal.
  • Configure a user exit to process an output message callback event, as described in Exploiting user exits.
The topic for each node that supports WrittenDestination information contains details about the data that it contains.

If you want the local environment tree to be included in the output message that is propagated by the Compute node, you must set the Compute node property Compute mode to a value that includes the local environment (for example, All). If you do not, the local environment tree is not copied to the output message.

The information that you insert into DestinationData or Defaults depends on the characteristic of the corresponding node property:

  • If a node property is represented by a check box (for example, New Message ID), set the Defaults or DestinationData element to Yes (equivalent to selecting the check box) or No (equivalent to clearing the check box).
  • If a node property is represented by a drop-down list (for example, Transaction Mode), set the Defaults or DestinationData element to the appropriate character string (for example Automatic).
  • If a node property is represented by a text entry field (for example, Queue Manager Name), set the Defaults or DestinationData element to the character string that you would enter in this field.

If necessary, configure the sending node to indicate where the destination information is. For example, for the output node MQOutput, set Destination Mode:

  • If you set Destination Mode to Queue Name, the output message is sent to the queue identified in the output node properties Queue Name and Queue Manager Name. Destination is not referenced by the node.
  • If you set Destination Mode to Destination List, the node extracts the destination information from the Destination subtree. If you use this value you can send a single message to multiple destinations, if you configure Destination and a single output node correctly. The node checks the node properties only if a value is not available in Destination (as described above).
  • If you set Destination Mode to Reply To Queue, the message is sent to the reply-to queue identified in the MQMD in this message (field ReplyToQ). Destination is not referenced by the node.

To find more information about ESQL procedures that perform typical updates to the local environment, see Populating Destination in the local environment tree. Review the ESQL statements in these procedures to see how to modify the local environment. You can use these procedures unchanged, or modify them for your own requirements.

To find more information about how to extend the contents of this tree for your own purposes, see Using scratchpad areas in the local environment.