The DECLARE statement defines a variable, the data type of the variable and, optionally, its initial value.
Notes:
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.
Use CONSTANT to define a constant. You can declare constants within schemas, modules, routines, or compound statements (both implicit and explicit). The behavior of these cases is as follows:
A constant or variable declared within a routine overlays any parameters of the same name, and all constants and variables of the same name that are declared in a containing module or schema.
Within any one schema or module, all constants occupy a namespace. A constant declared within a module overlays any constant of the same name and type declared in the containing schema.
Constants within the DECLARE statement are always referred to by a single unqualified identifier.
At the schema level the DECLARE statement supports the declaration of constants and shared variables.
An error is reported if the use of a namespace identifier that is not equal to the name of a namespace constant is found. This applies only to explicit references to elements by name.
Use EXTERNAL to denote a user-defined property (UDP). A UDP is a user-defined constant whose initial value (optionally set by the DECLARE statement) can be modified, at design time, by the Message Flow editor, or overridden, at deployment time, by the Broker Archive editor. Its value cannot be modified by ESQL.
For an overview of UDPs, see the Related link about user-defined properties in ESQL.
When a UDP is given an initial value on the DECLARE statement, this becomes its default. However, any value that you specify in the Message Flow editor at design time, or in the BAR editor at deployment time (even a zero length string) overrides any initial value coded on the DECLARE statement.
All UDPs in a message flow must have a value, given either on the DECLARE statement or by the Message Flow or BAR editor; otherwise a deployment-time error occurs. At run time, after the UDP has been declared its value can be queried by subsequent ESQL statements, but cannot be modified.
The advantage of UDPs is that their values can be changed at deployment time. If, for example, you use the UDPs to hold configuration data, it means that you can configure a message flow for a particular machine, task, or environment at deployment time, without having to change the code at the node level.
You can declare UDPs only in modules or schemas, this means that you can use the DECLARE statement with the EXTERNAL keyword only at the MODULE or SCHEMA level. If you use a DECLARE statement with the EXTERNAL keyword within a PROCEDURE or FUNCTION, a BIP2402E exception is produced when you deploy the message flow.
Take care when specifying the data type of a UDP, because a CAST is used to change the value to the requested DataType.
DECLARE mycolour EXTERNAL CHARACTER ‘blue';
DECLARE TODAYSCOLOR EXTERNAL CHARACTER; SET COLOR = TODAYSCOLOR;where TODAYSCOLOR is a user-defined property that has a TYPE of CHARACTER and a VALUE set by the Message Flow Editor.
Use NAME to define an alias (an alternative name) by which a variable can be known.
-- The following statement gives Schema1 an alias of 'Joe'. DECLARE Schema1 NAME 'Joe'; -- The following statement produces a field called 'Joe'. SET OutputRoot.XMLNS.Data.Schema1 = 42; -- The following statement inserts a value into a table called Table1 -- in the schema called 'Joe'. INSERT INTO Database.Schema1.Table1 (Answer) VALUES 42;
DECLARE Schema1 EXTERNAL NAME; CREATE FIRSTCHILD OF OutputRoot.XMLNS.TestCase.Schema1 Domain('XMLNS') NAME 'Node1' VALUE '1'; -- If Schema1 has been given the value 'red', the result would be: <xml version="1.0"?> <TestCase> <red> <Node1>1</Node1> </red>
Use NAMESPACE to define an alias (an alternative name) by which a namespace can be known.
This example illustrates a namespace declaration, its use as a SpaceId in a path, and its use as a character constant in a namespace expression:
DECLARE prefixOne NAMESPACE 'http://www.example.com/PO1'; -- On the right hand side of the assignment a namespace constant -- is being used as such while, on the left hand side, one is -- being used as an ordinary constant (that is, in an expression). SET OutputRoot.XMLNS.{prefixOne}:{'PurchaseOrder'} = InputRoot.XMLNS.prefixOne:PurchaseOrder;
Use SHARED to define a shared variable. Shared variables are private to the flow (if declared within a schema) or node (if declared within a module), but are shared between instances of the flow (threads). No type of variable is visible beyond the flow level; for example you cannot share variables across execution groups.
You can use shared variables to implement an in-memory cache in the message flow (for further information refer to optimizing message flow response times in the related links.) Shared variables have a long lifetime and are visible to multiple messages passing through a flow (for more information about long-lived variables refer to the related links.) 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.
You cannot define a shared variable within a function or procedure.
These read-write variables are ideal for users prepared to sacrifice the persistence and transactional advantages of databases in order to obtain better performance, because they have a longer life than only one message and perform better than a database.
Because flow-shared variables can be updated by multiple instances and multiple flows, ensure that your flows or instances do not make changes to shared variables that might cause unexpected results in other flows and instances, for example if the variable is being used as a counter. You can prevent other instances seeing the intermediate stages of the data by using a BEGIN ATOMIC construct as described in the BEGIN...END statement in the related links.
Shared row variables allow a user program to make an efficient read/write copy of an input node’s message. This is generally useful and, in particular, simplifies the technique for handling large messages.
There is a restriction that subtrees cannot be copied directly from one shared row variable to another shared row variable. Subtrees can be copied indirectly by using a non-shared row variable. Scalar values extracted from one shared row variable (using the FIELDVALUE function) can be copied to another shared row variable.
DECLARE SHARED tempmessage ROW InputRoot.XMLNS;
DECLARE temp SHARED ROW ROW(SELECT…..FROM ….. AS blarr[]);This defines temp as a shared ROW variable and constructs a ROW by means of a SELECT statement. The SELECT statement obtains the value and places it into blarr as the first layer of elements.