Preliminary documentation for Ice 3.7.1 Beta. Do not use in production applications. Refer to the space directory for other releases.

Variables allow you to define commonly-used information once and refer to them symbolically throughout your application descriptors.

On this page:

Syntax

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 when the application is saved to an IceGrid registry.

Where are Variables Allowed?

Substitution is performed in all string fields except the following:

  • server and service template IDs (when defining a template or when referring to a template)
  • variable names
  • template parameter names
  • node names
  • application names

Escaping a Variable

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 would use $${abc} as this variable's value.

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.

Pre-Defined Variables

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. The table below describes the purpose of each variable and defines the context in which it is valid.

NameDescription
applicationThe name of the enclosing application.
application.distribThe pathname of the enclosing application distribution directory, and an alias for ${node.datadir}/distrib/${application}.
nodeThe name of the enclosing node.
node.osThe name of the enclosing node operating system. On Unix, this is value is provided by uname. On Windows, the value is Windows.
node.hostnameThe host name of the enclosing node.
node.releaseThe operation system release of the enclosing node. On Unix, this value is provided by uname. On Windows, the value is obtained from the OSVERSIONINFO data structure.
node.versionThe operation system version of the enclosing node. On Unix, this value is provided by uname. On Windows, the value represents the current service pack level.
node.machineThe machine hardware name of the enclosing node. On Unix, this value is provided by uname. On Windows, the value is x86 or x64.
node.datadirThe absolute pathname of the enclosing node data directory.
serverThe ID of the enclosing server.
server.distribThe pathname of the enclosing server distribution directory, and an alias for ${node.datadir}/servers/${server}/distrib.
serviceThe name of the enclosing service.
session.idThe client session identifier. For sessions created with a user name and password, the value is the user ID; for sessions created from a secure connection, the value is the distinguished name associated with the connection.

The availability of a variable is easily determined in some cases, but may not be readily apparent in others. For example, you can use the ${node} variable in a property value within a server template definition, because variables in the body of a server template are evaluated when the server template is instantiated on a specific node.

Variable Substitution in IceGrid GUI

In a number of panes, you can substitute variables and template parameters by their respective value. Use View > Show Variables and View > Substitute Variables or the corresponding toolbar toggle buttons:

When variable-substitution is enabled, the descriptors are displayed read-only.

Scoping Rules

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. The diagram below illustrates these concepts:

In this diagram, the variable x is defined at the application level with the value 1. In node A, x is overridden with the value 2, whereas x remains unchanged in node B. Within the context of node A, 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.

Resolving a Reference

To resolve a variable reference ${var}, IceGrid searches for a definition of var using the following order of precedence:

  • Pre-defined variables
  • Template parameters, if applicable
  • Node variables, if applicable
  • Application variables

After the initial substitution, any remaining references are resolved recursively using the following order of precedence:

  • Pre-defined variables
  • Node variables, if applicable
  • Application variables
  • Template Parameters

Template parameters are not visible in nested template instances. This situation can only occur when an IceBox server template instantiates a service template.

Modifying a Variable

A variable definition can be overridden in an inner scope, but the inner definition does not modify the outer variable.

See Also

 


  • No labels