WebSphere Message Brokers
File: ak01010_
Writer: Bill Oppenheimer

Concept topic

This build: July 31, 2007 21:31:04

ESQL variables

An ESQL variable is a data field used to help process a message.

You must declare a variable and state its type before you can use it. A variable's data type is fixed; if you code ESQL that assigns a value of a different type, either an implicit cast to the data type of the target is implemented or an exception is raised (if the implicit cast is not supported).

To define a variable and give it a name, use the DECLARE statement.
Note: The names of ESQL variables are case sensitive, so it is important to make sure that you use the correct case in all places. The simplest way to guarantee this is always to define variables using upper case names.
The Message Broker Toolkit flags, with warning markers, variables that have not been defined. It is best practice to remove all these warnings before deploying a message flow.

You can assign an initial value to the variable on the DECLARE statement. If an initial value isn't specified, scalar variables are initialized with the special value NULL, while ROW variables are initialized to an empty state. Subsequently, you can change the variable's value using the SET statement.

There are three types of built-in node that can contain ESQL code and hence support the use of ESQL variables:

Variable scope, lifetime, and sharing

How widespread and for how long a particular ESQL variable is available, is described by its scope, lifetime, and sharing:

A variable's scope is a measure of the range over which it is visible. In the broker environment, the scope of variables is normally limited to the individual node.

A variable's lifetime is a measure of the time for which it retains its value. In the broker environment, the lifetime of a variable varies but is typically restricted to the life of a thread within a node.

A variable's sharing characteristics indicate whether each thread has its own copy of the variable or whether one variable is shared between many threads. In the broker environment, variables are typically not shared.

Types of variable

You can use the DECLARE statement to define three types of variable:
External
External variables (defined with the EXTERNAL keyword) are also known as user-defined properties (see User-defined properties in ESQL). They exist for the entire lifetime of a message flow and are visible to all messages passing through the flow. You can define external variables only at the module and schema level. You can modify their initial values (optionally set by the DECLARE statement) at design time, using the Message Flow editor, or at deployment time, using the BAR editor. You cannot later modify their values using ESQL.
Normal
"Normal" variables have a lifetime of just one message passing through a node. They are visible to that message only. To define a "normal" variable, omit both the EXTERNAL and SHARED keywords.
Shared
Shared variables can be used to implement an in-memory cache in the message flow (see Optimizing message flow response times). Shared variables have a long lifetime and are visible to multiple messages passing through a flow (see Long-lived variables). They exist for the lifetime of the execution group process, the lifetime of the flow or node, or the lifetime of the node’s SQL that declares the variable (whichever is the shortest). They are initialized when the first message passes through the flow or node after each broker startup.

See also the ATOMIC option of the BEGIN ... END statement. The BEGIN ATOMIC construct is useful when a number of changes need to be made to a shared variable and it is important to prevent other instances seeing the intermediate states of the data.

For information about specific types of variable, see:
Related concepts
User-defined properties in ESQL
Long-lived variables
Message flows overview
Related tasks
Developing message flows
Developing ESQL
Related reference
Built-in nodes
Compute node
Database node
Filter node
DECLARE statement
BEGIN ... END statement
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2007Copyright IBM Corporation 1999, 2007. All Rights Reserved.
This build: July 31, 2007 21:31:04

ak01010_ This topic's URL is: