Local environment tree structure

The root of the local environment tree is called LocalEnvironment. This tree is always present in the input message, it is created when a message is received by the input node. Some input nodes create local environment fields, others leave it empty.

Use the local environment 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 local environment tree to define destinations (that are internal and external to the message flow) to which a message is sent. IBM® Integration Bus 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 uses only in specific situations, see Environment tree structure.)

The following figure shows an example of the local environment tree structure. The children of Destination are protocol-dependent.

In the tree structure shown, LocalEnvironment has several children:

LocalEnvironment.Variables

This subtree is optional. If you create local environment variables, 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 the variables persist until the node that created them goes out of scope.

The variables in this subtree are persistent only 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.

LocalEnvironment.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, including Email, File, FTE, HTTP, JMS, MQ, SOAP, and TCPIP.

  LocalEnvironment.Destination.CICS

  If the message flow includes a CICSRequest node, you can override the following properties with elements in this subtree:

  • Program name
  • Commarea length
  • Mirror transaction ID
  • Set EIBTRNID only
  • Message domain
  • Message set
  • Message type
  • Message format
  • Message coded character set ID
  • Message encoding

  For more information, see Local environment overrides for the CICSRequest node.

  You can also set LocalEnvironment values for CICS® channels and containers. For more information, see COMMAREA or channel data structures.

  LocalEnvironment.Destination.CORBA

  If the message flow includes a CORBARequest node, you can override its Operation name property by specifying a value in the following location:

  $LocalEnvironment/Destination/CORBA/Request/OperationName

  For more information about the operation name, see CORBARequest node.

  LocalEnvironment.Destination.Email

  If the message flow includes an EmailOutput node, then information defined in this subtree will specify or override the SMTP server connection information and attachments associated with each email sent by the node. Multiple attachments can be specified for inclusion in the email sent, including the specification of the attachment name, content, and type. See EmailOutput node.

  LocalEnvironment.Destination.File

  If the message flow includes a FileOutput node, you can override its directory and name properties with elements in this subtree. See Using local environment variables with file nodes.

  LocalEnvironment.Destination.FTE

  If the message flow includes an FTEOutput node, you can override its properties with elements in this subtree. See Using local environment variables with file nodes.

  LocalEnvironment.Destination.HTTP

  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. For more information, see Local environment overrides in the topic HTTPRequest node, and examples in Populating Destination in the local environment tree.

  LocalEnvironment.Destination.JMSDestinationList

  A JMSOutput node can be configured to send to multiple JMS Queues or to publish to multiple JMS Topics using a destination list created in the local environment by a transformation node.

  The JMSOutput node searches the local environment for data elements called DestinationData under the folder Destination.JMSDestinationList. The node sends the JMS message to each DestinationData entry found in that folder. See the example in Populating Destination in the local environment tree.

  LocalEnvironment.Destination.MQ

  If the message flow includes an MQOutput node, each element is a name element, MQ (A deprecated alternative exists, called MQDestinationList. Use MQ for all new message flows). If more than one element exists, each is processed sequentially by the node. See the example in Populating Destination in the local environment tree.

  You can configure MQOutput 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 MQOutput node cannot deliver the messages.

  If you prefer, you can configure the MQOutput 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 MQ 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, 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 information is described in Accessing the local environment tree.

  LocalEnvironment.Destination.SOAP

  You can place outbound WS-Addressing header information in the local environment to override the defaults that are generated by the SOAPReply, SOAPRequest, or SOAPAsyncRequest nodes. See WS-Addressing information in the local environment.

  If the message flow includes SOAPRequest or SOAPAsyncRequest nodes, you can override their HTTP Transport and JMS transport properties in this subtree. See SOAPRequest node, SOAPAsyncRequest node, or Local environment overrides for the SOAPRequest node.

  If the message flow includes a SOAPAsyncRequest node, you can use this subtree to pass state and correlation information to a SOAPAsyncResponse node in another message flow. See WS-Addressing with the SOAPAsyncRequest and SOAPAsyncResponse nodes.

  If the message flow includes SOAPReply, SOAPRequest, or SOAPAsyncRequest nodes, you can override their use of outbound MTOM messages in this subtree. See Using SOAP MTOM with the SOAPReply, SOAPRequest, and SOAPAsyncRequest nodes.

  LocalEnvironment.Destination.TCPIP

  If the message flow includes a TCPIPClientOutput node or a TCPIPServerOutput node, you can override its TCPIP connection with elements in this subtree. See TCPIPClientOutput node and TCPIPServerOutput node.

• 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.

LocalEnvironment.Wildcard

This subtree contains information about the wildcard characters that are stored by the FileInput node.

On the FileInput node you can specify a file name pattern that contains wildcard characters.

More details about the information that is stored in this subtree are in Using local environment variables with file nodes.

LocalEnvironment.WrittenDestination

This 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 transformation 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.

LocalEnvironment.Adapter

This subtree contains information that is stored by the WebSphere Adapters nodes.

For a WebSphere Adapters input node:

• MethodName is the name of the business method that corresponds to the Enterprise Information System (EIS) event that triggered this message delivery.

  The bindings for EIS events or business methods are created by the Adapter Connection wizard.

• Type describes the type of adapter that is being used:
  • SAP
  • Siebel
  • PeopleSoft
  • JD Edwards

For a WebSphere Adapters request node:

MethodName is the name of the business method that the request node must use.

LocalEnvironment.CD and LocalEnvironment.CD.Transfer

These subtrees contain information that is stored by the CDInput node. The LocalEnvironment.CD subtree contains information about the current record. The LocalEnvironment.CD.Transfer subtree contains information received from IBM Sterling Connect:Direct® regarding the file.

More details about the information that is stored in these subtrees are in Using local environment variables with file nodes.

LocalEnvironment.Database

This subtree contains information that is propagated from the DatabaseInput node.

The LocalEnvironment.Database.Input.Event.Usr subtree contains user-defined data associated with an event. It is initialized in the ReadEvents procedure of the ESQL module associated with the DatabaseInput node.

LocalEnvironment.Database.Input.Event.Key holds a unique key for an event. It is set in the ReadEvents procedure of the ESQL module associated with the DatabaseInput node.

LocalEnvironment.Database.Input.Event.FailureCount contains a value for the number of times an attempt to process an event has failed. This count includes all unhandled exceptions occurring either in the ESQL module or the message flow.

LocalEnvironment.DecisionServices

This subtree contains information about the decision service that is called from a DecisionService node.

The local environment shows information about your decision services, such as the number of rules that are matched by the messages that are processed by the decision service.

More details about the information that is stored in this subtree are in DecisionService node.

LocalEnvironment.File

This subtree contains information that is stored by the FileInput node.

This information describes the file, and also contains data about the current record.

More details about the information that is stored in this subtree are in Using local environment variables with file nodes.

LocalEnvironment.FTE and LocalEnvironment.FTE.Transfer

These subtrees contain information that is stored by the FTEInput node. The LocalEnvironment.FTE subtree contains information about the current record. The LocalEnvironment.FTE.Transfer subtree contains information received from WebSphere MQ File Transfer Edition regarding the file.

More details about the information that is stored in these subtrees are in Using local environment variables with file nodes.

LocalEnvironment.JMS

This subtree contains information that is stored by the JMSReceive node.

If the message flow includes a JMSReceive node, you can override its JMS connection properties with elements in this subtree.

More details about this information that is stored in this subtree are in Local environment overrides for the JMSReceive node.

LocalEnvironment.Mapping

This subtree contains information that is stored by Mapping node.

If your message flow includes a Mapping node, you can override the mapping routine that is used to transform a message instance by specifying a new mapping routine in the MappingRoutine field. You must specify the new mapping routine in the LocalEnvironment.Mapping subtree that is upstream of the Mapping node that you need to modify.

LocalEnvironment.ServiceRegistry

This subtree contains information for queries by the EndpointLookup and RegistryLookup nodes.

More details about the information that is stored in this subtree are in Dynamically defining the search criteria, EndpointLookup node output, and RegistryLookup node output.

LocalEnvironment.SOAP

This subtree contains information that is stored by SOAPInput, SOAPAsyncResponse, or SOAPRequest nodes.

More details about the information that is stored in this subtree are in WS-Addressing information in the local environment.

If the message flow includes a SOAPAsyncResponse node, you can use this subtree to receive state and correlation information passed by a SOAPAsyncRequest node in another message flow.

More details about the information that is stored in this subtree are in WS-Addressing with the SOAPAsyncRequest and SOAPAsyncResponse nodes.

LocalEnvironment.TCPIP

If the message flow includes a TCPIPClientReceive node or a TCPIPServerReceive node, you can override its TCPIP connection with elements in this subtree. See TCPIPClientReceive node and TCPIPServerReceive node.

This subtree contains information that is stored by the TCPIPClientInput, TCPIPClientReceive, TCPIPServerInput, and TCPIPServerReceive nodes.

This information describes the connection that the node is using.

More details about the information that is stored in this subtree are in TCPIPClientInput node, TCPIPClientReceive node, TCPIPServerInput node, and TCPIPServerReceive node.

When the message flow processing is complete, the local environment tree is discarded.

You can view information about samples only when you use the product documentation that is integrated with the IBM Integration Toolkit or the online product documentation. You can run samples only when you use the product documentation that is integrated with the IBM Integration Toolkit.