Simple Substitution Variable References

The input source can contain any number of simple substitution variable references. A simple substitution variable has the following syntax:

:[variable]

variable is one of the following:

• Local variable name. You can reference local variable names in plan steps and in steps that are in a component's install, uninstall, snapshot, and control service blocks.

• Parameter name. You can reference parameters in plan steps and in steps that are in a component's install, uninstall, snapshot, and control service blocks.

• Predefined component variable name. You can only use predefined component variable names in input sources that are associated with a component, but not with a plan.

  Predefined component variable names are always resolved relative to the actual component that is (or is being) installed, even if the variable reference occurs in a base component. From an accessibility standpoint, predefined component variables are treated as PUBLIC variables.

  See Predefined Component Variable Names for a list of names.

• Dynamic component variable name. A component can reference both locally declared and inherited variables. The value that will be substituted for the reference is either the override value of the associated variable settings source or the variable's default value. The value that is used is expanded before it is substituted.

  A dynamic component variable name is declared or inherited by the component associated with the target component. In this case, the value to be substituted for the variable reference is either the associated override variable settings value or the default value defined by the component. The value of this variable is expanded before it is substituted.

Predefined Component Variable Names

These predefined component variable names refer to the associated component attributes of the generation context:

• sys.name – Component name

• sys.description – Component description

• sys.label – Label of the component

• sys.softwareVendor – Software vendor that wrote the application that is modeled by the component

• sys.author – Creator of the component

• sys.path – Path of the component

  The sys.path variable is like the path attribute of the component, but it includes a trailing slash (/). sys.path can be directly combined with the sys.name variable to create the full name of the component.

  :[sys.path]:[sys.name]

• sys.rsrcInstallPath – Location where the component resource is installed

  The sys.rsrcInstallPath variable is in the file format of the remote agent on which the component is, or is being, installed. You can only use this variable for simple components. Since the value of this variable might require other dynamic component variables to be computed, you cannot use sys.rsrcInstallPath in a component variable default value or variable settings override value. This variable also cannot be used as the value of the <component> installPath attribute or in the <resourceRef>/<installSpec> element attributes. These restrictions prevent the possibility of circular references.

• sys.targetRefName – Name of the associated component targeting host

  The sys.targetRefName variable is only defined for targetable components. The component targeting host is defined by the resolved value of the hostName attribute of the targetable component's <targetRef> element. It cannot appear as a simple substitution variable in a component variable value because component variables might be used to compute the sys.targetRefName value. This variable is most often used with the <retarget> step to install or manipulate components that are in a targetable component.

Predefined component variables are always resolved relative to the actual component that is, or is being, installed even if the variable reference occurs in a base component. Predefined component variables are treated as PUBLIC variables.

Escape Sequences for Substitution Variables

If you want to include :[ in input source, you must escape it by using :[[ instead. The configuration generator replaces occurrences of :[[ with :[.

For example, to literally include the text :[box] without the provisioning system substituting a value for box, use :[[box].

When the input source is an attribute of a component that is authored in XML, the value is subject to the following rules for XML-based escape sequences:

• To get the quote character (""), use the &quot; sequence.

• To get the apostrophe character ('), use the &apos; sequence.

• To get the less-than character (<), use the &lt; sequence.

• To get the greater-than character (>), use the &gt; sequence.

• To get the ampersand character (&), use the &amp; sequence.

These escape rules do not apply to override values input via the provisioning system's browser interface, configuration resource files, or input to the configuration generation CLI commands.

Substitution Variable Expansion

When a substitution variable reference is replaced by a variable setting value, the value is recursively expanded before being substituted. This expansion is necessary because the value itself might contain references to simple substitution variables. To prevent the substitution of values, escape input sources with :[[.

You can only use host and external component substitution references in default or override substitution values, parameter default values, and local variable default values. Such references are not permitted in other input sources.

Simple Substitution Variable Reference Expansion

The syntax for a simple substitution variable reference in a variable setting value is the same as for input sources:

:[varname]

In this case, the variable name that is referenced must be a variable that has been declared before the variable that contains the reference. This restriction prevents circular references.

For derived components, variables that are inherited from the base component are first expanded in the order of declaration in the parent. Then, local non-override variables are expanded in the order of declaration. Local variables that override inherited variables are expanded in place of the inherited variable in the same order that the inherited variable would have been expanded. Therefore, override variables can only refer to other inherited and override variables that have already been declared. For example, base component A declares variables x and y. Then derived component B declares variables z and y. The order of evaluation of variables in component B is x, which is inherited from component A, then y, which is overridden by component B, and finally z, which is local to component B.

Example 6–1 Using Simple Substitution Variables

The following table shows examples of substitution variables, as well as their expanded and unexpanded values.