External Substitution Variables

A variable setting value may include any number of external component substitution references. An external component substitution reference is one of the following:

:[primary-component:varname]
:[primary-component:secondary-component-list:varname]

An external component substitution reference does not include any white space.

Above, primary-component is one of the following:

	explicit-external-component
	secondary-component

And secondary-component is one of the following:

	nested-component
	toplevel-component
	dependee-component

The secondary-component-list is a sequence of one or more colon-separated secondary-components.

The varname is either a predefined substitution variable name, or a dynamic substitution variable name declared by the referenced component.

Explicit External Component Expansion

An explicit-external-component explicitly specifies a component that is expected to be installed on a particular host at a particular location, and has the component resolution semantics of the <installedComponent> installed component targeter described in Chapter 2, “Installed Component Targeter” section. It has the following syntax:

	component-target:explicit-component-reference

Above, component-target specifies the host on which the desired component is installed, and is one of the following:

component
component(host-redirect)

The first variant specifies the current target host in the generation context. The second variant refers to the ROX host named by host-redirect, as specified in the host redirects section.

Above, explicit-component-reference is a reference to a component already installed on the target host specified by component-target. explicit-component-reference minimally includes the installed component name, but may also include a version and an install path, as follows:

full-component-name
full-component-name#version
full-component-name@{path}
full-component-name#version@{path}

Above, full-component-name is an absolute or relative reference to the desired component. Relative references are expanded relative to the plan or component that contains the explicit-component-reference. And path is either an absolute path name representing the install path of the desired component, or a substitution variable reference that, when expanded, represents the absolute install path of the desired component. If the former includes the "}" character, it must be escaped using the sequence "}}".

Nested Component Expansion

A nested-component specifies the component that is referenced by a nested component reference declared by the current component, and has the component resolution semantics of the <nestedRef> installed component targeter described in Chapter 2, "Installed Component Targeter" section. It has the following syntax:

	nestedRef:component-reference-name

Above, component-reference-name is the name of a <componentRef> element with "NESTED" installMode within the current component.

A nested-component may only be used when the current component is a composite component, and may only be used as a primary-component when the external component substitution reference appears within a composite component. When used as a primary-component, it may not be used as the default value of a component variable or override variable setting, as the referenced component will not yet have been installed when the variable is evaluated.

Toplevel Component Expansion

A toplevel-component specifies the component that is referenced by a toplevel component reference declared by the current component, and has the component resolution semantics of the <toplevelRef> installed component targeter described in Chapter 2, "Installed Component Targeter" section. It has one of the following formats:

toplevelRef:component-reference-name
toplevelRef:component-reference-name@{path}
toplevelRef(host-redirect):component-reference-name
toplevelRef(host-redirect):component-reference-name@{path}

Above, component-reference-name is the name of a <componentRef> element with "TOPLEVEL" installMode within the current component.

Above, path and host-redirect are the location and host, respectively, at which the referenced component is expected to be installed. host-redirect has syntax as specified in the host redirects section.

A toplevel-component may only be used when the current component is a composite component, and may only be used as a primary-component when the external component substitution reference appears within a composite component. When used as a primary-component, it may not be used as the default value of a component variable or override variable setting unless the referenced component has already been installed.

Dependee Component Expansion

A dependee-component specifies the component on which the current component depends as a result of a dependency created by a <createDependency> step, and has the component resolution semantics of the <dependee> installed component targeter described in Chapter 2, "Installed Component Targeter" section. It has the following syntax:

	dependee:dependency-name

Above, dependency-name is the name of a dependency created by the current component.

A dependee-component may only be used as a primary-component when the external component substitution reference appears within a component. When used as a primary-component, it may not be used as the default value of a component variable or override variable setting, as the dependency will not yet have been created when the variable is evaluated.

System Service Component Expansion

A system-service-component specifies a system service component that is expected to be installed on the root physical host of the current target, and has the component resolution semantics of the <systemService> installed component targeter described in Chapter 2, "Installed Component Targeter" section. It has the following syntax:

systemService:system-service-name

System Type Component Expansion

A system-type-component specifies the component derived from a given component type that is most recently installed on a particular host at a particular location, and has the component resolution semantics of the <systemType> installed component targeter described in Chapter 2, "Installed Component Targeter" section. It has the following syntax:

systemType:component-type-name

systemType:component-type-name@{path}

systemType(host-redirect):component-type-name

systemType(host-redirect):component-type-name@{path}

Here, path is optional, and if specified, indicates the path in which the desired component is installed. The host-redirect is also optional, and indicates the host on which the desired component is installed, as described in the host redirects section.

Container Component Expansion

A container-component specifies the component that contains the current component as a nested reference. It has the following syntax:

	container

A container-component may only be used as a primary-component when the external component substitution reference appears within a component that has been installed as a nested component by another "container" component.