Variable descriptors (see Section 39.16.25) allow you to define commonly-used information once and refer to them symbolically throughout your application descriptors.
Substitution for a variable or parameter VP is attempted whenever the symbol
${VP} is encountered, subject to the limitations and rules described below. Substitution is case-sensitive, and a fatal error occurs if
VP is not defined.
In this case, a variable cannot supply the value of register-process because that attribute expects a boolean value, not a string.
You can prevent substitution by escaping a variable reference with an additional leading
$ character. For example, in order to assign the literal string
${abc} to a variable, you must escape it as shown below:
The extra $ symbol is only meaningful when immediately preceding a variable reference, therefore text such as
US$$55 is not modified. Each occurrence of the characters
$$ preceding a variable reference is replaced with a single
$ character, and that character does not initiate a variable reference. Consider these examples:
IceGrid defines a set of read-only variables to hold information that may be of use to descriptors. The names of these variables are reserved and cannot be used as variable or parameter names.
Table 39.23 describes the purpose of each variable and defines the context in which it is valid.
The availability of a variable is easily determined in some cases, but may not be readily apparent in others. For example, the following example represents a valid use of the
${node} variable:
Although the server template descriptor is defined as a child of an application descriptor, its variables are not evaluated until it is instantiated. Since a template
instance is always enclosed within a node, it is able to use the
${node} variable.
Descriptors may only define variables at the application and node levels. Each node introduces a new scope, such that defining a variable at the node level overrides (but does not modify) the value of an application variable with the same name. Similarly, a template parameter overrides the value of a variable with the same name in an enclosing scope. A descriptor may refer to a variable defined in any enclosing scope, but its value is determined by the nearest scope.
Figure 39.9 illustrates these concepts.
In this diagram, the variable x is defined at the application level with the value
1. In
nodeA,
x is overridden with the value
2, whereas
x remains unchanged in
nodeB. Within the context of
nodeA,
x continues to have the value
2 in a server instance definition. However, when
x is used as the name of a template parameter, the node’s definition of
x is overridden and
x has the value
3 in the template’s scope.
To resolve a variable reference ${var}, IceGrid searches for a definition of
var using the following order of precedence:
Template parameters are not visible in nested template instances. This situation can only occur when an IceBox server template instantiates a service template, as shown in the following example:
The service template incorrectly refers to id, which is a parameter of the server template.
A variable definition can be overridden in an inner scope, but the inner definition does not modify the outer variable. If a variable is defined multiple times in the same scope (which is only relevant in XML definitions), the most recent definition is used for all references to that variable. Consider the following example:
When descriptors such as these are created, IceGrid validates their variable references but does not perform substitution until the descriptor is acted upon (such as when a node is generating a configuration file for a server). As a result, the value of
y in the above example is
2 because that is the most recent definition of
x.
Variable scoping semantics.
In this diagram, the variable x is defined at the application level with the value 1. In nodeA, x is overridden with the value 2, whereas x remains unchanged in nodeB. Within the context of nodeA, x continues to have the value 2 in a server instance definition. However, when x is used as the name of a template parameter, the node’s definition of x is overridden and x has the value 3 in the template’s scope.