Accessing the LocalEnvironment tree

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

The LocalEnvironment tree is used by the broker, 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 within this tree that you can use as a scratchpad or working area.

This topic describes how to refer to the information that is set up by the broker. Using scratchpad areas in LocalEnvironment describes how to extend the contents of this tree for your own purposes.

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, and can write to them to influence the way in which the message flow processes your message. However, if you write to these areas, ensure that you follow the defined structure to ensure that the tree remains valid. For more details of their content, see LocalEnvironment tree.

If you want the LocalEnvironment tree to be included in the output message that is propagated by the Compute node, ensure that you copy this tree by setting the Compute node property Compute mode to a value that includes LocalEnvironment (for example, All). If you do not, the LocalEnvironment tree is not included in the output message.

For example, to check if WebSphere MQ destinations are present in the Destination subtree:
DECLARE cursor REFERENCE TO LocalEnvironment.Destination.MQ;

IF LASTMOVE(cursor) THEN
To update the Destination subtree to change the name of a WebSphere MQ queue to which the message is written on output, code the following (this uses the reference cursor, declared in the above example):
SET cursor.DestinationData.queueManagerName = 'myNewQManagerName';
SET cursor.DestinationData.queueName = 'myNewQueueName';
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.
You must configure the output node to indicate where the destination information is for the output message:
  • 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. This means that you can send a single message to multiple destinations, if you configure Destination and a single output node correctly. The node only checks the node properties 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.

For information about the full list of elements in the Defaults and DestinationData subtrees, see Data types for elements in the DestinationData subtree.

For another example of how you can use LocalEnvironment to modify the behavior of a message flow, refer to the XML_PassengerQuery message flow in the Airline sample program. The Compute node in this message flow writes a list of destinations in the RouterList subtree of Destination that are used as labels by a later RouteToLabel node that propagates the message to the corresponding Label node.

Related concepts
Message flows
LocalEnvironment tree
ESQL
Message modeling

Related tasks
Designing a message flow
Creating destination lists
Defining message flow content
Managing ESQL files

Related reference
Compute node
Database node
Filter node
Data types for elements in the DestinationData subtree
ESQL
DECLARE statement
LASTMOVE function
SET statement