User-defined properties

A user-defined property (UDP) is a user-defined constant whose initial value can be modified, at design time, by the Message Flow editor, or overridden, at deployment time, by the Broker Archive editor. You can use UDPs in your ESQL or Java programs. In ESQL, for instance, you use the DECLARE statement to define a UDP to your program. You can give the UDP an initial value when it is declared, but your code cannot modify the value at run-time.

If a UDP is given an initial value when it is declared, this becomes its default. However, any value specified by the Message Flow editor at design time, or by the BAR editor at deployment time (even a zero length string) overrides any initial declared value.

Every UDP in a message flow must have a value, given either when the UDP is declared 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 program statements but not modified.

The advantage of UDPs is that their values can be changed by operational staff 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. Configuration data does not have to be accessed by, for example, plug-ins from data sources such as databases, or copied into environment trees.

Using UDPs, configuration data can be set easily and used just like normal constants. Because no external calls to user-written plug-ins or parsing of environment trees are involved, your program code is easier to write and maintain, and performs better. Also, the parsing costs of reading data out of trees are removed. The value of the user-defined property is stamped into the variable at deployment time, which makes it quick to access.

You can declare UDPs only in modules or schemas.

The following types of broker node are capable of accessing UDPs:

If you use the Message Flow editor to change the value of a user-defined property, the value of the UDP is set at the flow level and is the same for all eligible nodes contained in the flow. (An "eligible node" is a node that supports UDPs and is within the scope of the declaration that declares the UDP to your application.) For example, if you use the Message Flow editor to change the value of a user property called "timezone", that is declared in a schema called "mySchema", in a message flow called "myFlow", the UDP is available at runtime to all the nodes in myFlow that support UDPs and fall within mySchema.

Similarly, if you use the Message Flow editor to change the value of a user-defined property in a subflow, the newly-edited property is available to all the nodes in the subflow that support UDPs and are within the scope of the declaration. (It is not available to nodes in the parent flow.)
Note: The properties dialog does not show the UDP at the node level (unless the node is a subflow for which you have defined a UDP). For example, if the timezone property is available at runtime to the compute node in myFlow and you open the properties dialog of the compute node, you do not see a timezone property.
Related concepts
Message flows overview
ESQL variables
Related tasks
Developing message flows
Configuring a message flow at deployment time using UDPs
Related reference
ESQL variables
DECLARE statement
Message Flow editor