LocalEnvironment tree structure

The LocalEnvironment tree is a part of the logical message tree in which you can store information while the message flow processes the message.

The root of the LocalEnvironment tree is called LocalEnvironment. This tree is always present in the input message: an empty LocalEnvironment tree is created when a message is received by the input node.

Use the LocalEnvironment tree to store variables that can be referred to and updated by message processing nodes that occur later in the message flow. You can also use the LocalEnvironment tree to define destinations (that are internal and external to the message flow) to which a message is sent. WebSphere Message Broker also stores information in LocalEnvironment in some circumstances, and references it to access values that you might have set for destinations. (Contrast this to the Environment tree structure, which the broker refers to in one situation only.)

The figure below shows the LocalEnvironment tree structure. The children of Destination are protocol-dependent. The example below shows the structure for a WebSphere MQ message. If the message is parsed by another built-in parser, or by a user-defined parser, the tree structure below the Destination element has different content than that shown in the figure.


Local environment tree structure created by a supplied input node and parser

In the tree structure shown above, LocalEnvironment has three children:

Variables
This subtree is optional. If you create local environment variables, you are recommended to store them in a subtree called Variables. It provides a work area that you can use to pass information between nodes. This subtree is never inspected or modified by any supplied node.

Variables in the local environment can be changed by any subsequent message processing node, and persist until the message flow goes out of scope and the node that created it has completed its work and returns control to the previous node

The variables in this subtree are only persistent within a single instance of a message flow. If you have multiple instances of a message passing through the message flow, and need to pass information between them, you must use an external database.

Destination
This subtree consists of a number of children that indicate the transport types to which the message is directed (the Transport identifiers), or the target Label nodes that are used by a RouteToLabel node.
  • Transport information

    Transport information is used by some input and output nodes.

    If the message flow starts with an HTTPInput node, a single name element HTTP is added to Destination. The element HTTP.RequestIdentifier is created and initialized so that it can be used by an HTTPReply node. You can also create other fields in the HTTP structure for use by the HTTPRequest node, for example the URL of the service to which the request is sent. The topic for each node contains more information about the contents of Destination for the WebSphere MQ Web Services Transport protocol.

    If the message flow includes an MQOutput node, each element is a single name element, MQDestinationList. If more than one element exists, each is processed sequentially by the node.

    If you have included a user-defined output node in the message flow, the contents of Destination (if supported) are defined by that node.

    You can configure output nodes to examine the list of destinations and send the message to those destinations, by setting the property Destination Mode to Destination List. If you do so, you must create this subtree and its contents to define those destinations, giving it the name Destination. If you do not do so, the output node cannot deliver the messages.

    If you prefer, you can configure the output node to send messages to a single fixed destination, by setting the property Destination Mode to Queue Name or Reply To Queue. If you select either of these fixed options, the destination list has no effect on broker operations and you do not have to create this subtree.

    You can construct the MQ element to contain a single optional Defaults element. The Defaults element, if created, must be the first child and must contain a set of name-value elements that give default values for the message destination and its PUT options for that parent.

    You can also create a number of elements called DestinationData within MQ. Each of these can be set up with a set of name-value elements that defines a message destination and its PUT options.

    The set of elements that define a destination is described in Data types for elements in the DestinationData subtree.

    The content of each instance of DestinationData is the same as the content of Defaults for each protocol, and can be used to override the default values in Defaults. You can set up Defaults to contain values that are common to all destinations, and set only the unique values in each DestinationData subtree. If you do not set a value either in DestinationData or Defaults then the value that you have set for the corresponding node property is used. Similarly, if you specify a field name or value with the wrong spelling or case, it is ignored, and the value that you have set for the corresponding node property is used.

    The information that you insert into DestinationData depends on the characteristic of the corresponding node property: this is described in Accessing the LocalEnvironment tree.

  • Routing information

    The child of Destination is RouterList. It has a single child element called DestinationData, which has a single entry called labelName. If you are using a dynamic routing scenario involving the RouteToLabel and Label nodes, you must set up the Destination subtree with a RouterList that contains the reference labels.

WrittenDestination
This subtree contains the addresses to which the message has been written. Its name is fixed. It is created by the message flow when a message is propagated through the out terminal of an output node. It 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). If the out terminal of the output node is not connected to another node, this subtree is not created.

The topic for each output node contains more information about the contents of WrittenDestination for WebSphere MQ and WebSphere MQ Everyplace.

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

The Airline Reservations sample and the Message Routing sample demonstrate how to use the LocalEnvironment to dynamically route messages based on the destination list. The User-defined Extension sample uses the LocalEnvironment to store information that is later added to the output message that is created by the message flow.

Related concepts
Message modeling
Environment tree structure
Related tasks
Developing message flows
Creating destination lists
Accessing the LocalEnvironment tree
Using scratchpad areas in LocalEnvironment
Writing ESQL
Writing Java
Related reference
HTTPReply node
HTTPRequest node
MQeOutput node
MQOutput node
Data types for elements in the DestinationData subtree