You can use simple substitution variables in any input source, including configuration files. You can use external component and target substitution variables in a number of places, including <varList>/<var> default values of the <installSteps>, <uninstallSteps>, <controlService>, and <executionPlan> elements.
Simple substitution variable references of the form :[varname] can be used in any input source, including configuration files and configurable component attributes. However, host substitution references (:[target:varname]) and external component substitution references (:[component:compRef:varname]) can only be used in variable setting values.
Variable setting values include the default attribute of the <var> element and values in the variable setting overrides, but not configuration files or other configurable component attributes. This limitation ensures that all variables used in a component and in the configuration files that it references are explicitly declared and validated by the <varlist> element of the component.
Following are all substitution variables that can be used in particular input sources. The elements and attributes listed are the input source, and the sublist contains the types of variables that are permitted.
<component>/<varList>/<var>/ default attribute:
Variable settings override value:
Component substitution references, excluding sys.rsrcInstallPath and sys.targetRefName
Host substitution references
External component substitution references, excluding nested-component and dependee-component as primary components
Session variable references
<component>/<installList>/<installSteps>/<paramList>/<param>/ default attribute:
<component>/<uninstallList>/<uninstallSteps>/ <paramList>/<param>/default attribute:
<component>/<controlList>/<control>/<paramList>/<param>/default attribute:
<component>/<snapshotList>/<snapshot>/<paramList>/<param>/ default attribute:
Component substitution references
Host substitution references
External component substitution references
Session variable references
<component>/<installList>/<installSteps>/<varList>/<var>/ default attribute:
<component>/<uninstallList>/<uninstallSteps>/<varList>/<var>/ default attribute:
<component>/<controlList>/<control>/<varList>/<var>/default attribute:
<component>/<snapshotList>/<snapshot>/<varlList>/<var>/default attribute:
Local variable substitution references that have been previously declared
Parameter substitution references
Component substitution references
Host substitution references
External component substitution references
Session variable references
<component>/<installList>/<installSteps>/child steps:
<component>/<uninstallList>/<uninstallSteps>/child steps:
<component>/<controlList>/<control>/child steps:
<component>/<snapshotList>/<snapshot>/<prepare>/child steps:
<component>/<snapshotList>/<snapshot>/<capture>/child steps:
<component>/<snapshotList>/<snapshot>/<cleanup>/child steps:
Local variable substitution references
Parameter substitution references
Component substitution references
<component>/<resourceRef>/<installSpec>:
<component>/installPath attribute:
Component substitution references, excluding sys.rsrcInstallPath
<component>/<diff>/<ignore>:
<component>/<componentRef>/<argList>:
Configuration files:
Component substitution references
<component>/<targetRef>:
<component>/<targetRef>/<agent>:
Component substitution references, excluding sys.targetRefName and sys.rsrcInstallPath
<executionPlan>/<paramList>/<param>/ default attribute:
Session variable references
<executionPlan>/<varList>/<var>/ default attribute:
<executionPlan>/*/<inlineSubplan>/<varList>/<var>/ default attribute:
Session variable references
Local variable substitution references that have been previously declared
Unhidden local variable substitution references of enclosing plans
Unhidden parameter substitution references
Host substitution references for simple plans and subplans only
External component substitution references for simple plans and subplans only, but excluding container, nested, top-level, and dependee as primary component
<executionPlan>/*/child steps:
Local variable substitution references
Unhidden local variable substitution references of enclosing plans
Unhidden parameter substitution references
hostAttributes
Session variable references
The following configuration attributes of a component can include substitution variable references.
Parent Element |
Substitutable Attributes |
---|---|
<capture>/<addFile> |
displayName, path |
<component> |
installPath |
<diff>/<ignore> |
path |
<installSpec> |
name, path, permissions, user, group, deployMode, diffDeploy |
<paramList>/<param> |
default |
<targetRef> |
hostName |
<targetRef>/<agent> |
connection, ipAddr, port, params |
<varList>/<var> |
default |
The following step attributes that are in a component or a plan can include substitution variable references.
Parent Element |
Substitutable Attributes |
---|---|
<argList> |
Attributes of the <argList> element, which are free form |
<execJava> |
className, classPath |
<execNative> |
dir, userToRunAs |
<execNative>/<ouputFile> |
name |
<execNative>/<errorFile> |
name |
<execNative>/<env> |
name, value |
<execNative>/<exec> |
cmd |
<execNative>/<exec>/<arg> |
value |
<execNative>/<shell> |
cmd, <body> |
<execNative>/<successCriteria> |
outputMatches, errorMatches |
<execNative>/<inputFile> |
name |
<execNative>/<inputText> |
<body> |
<if>/<condition>/<equals> <if>/<condition>/<istrue> <if>/<condition>/<matches> |
value1, value2 value value, pattern |
<processTest> |
processNamePattern, user |
<raise> <retarget> <retarget>/<varList>/<var> |
message host default |
<sendCustomEvent> |
message |
<transform> |
input, output |
<transform>/<source> |
name |
<transform>/<stylesheet> |
<body> |
<transform>/<subst> |
match, replace |
<urlTest> |
url, pattern |
The following plan attributes can include substitution variable references.
Parent Element |
Substitutable Attribute |
---|---|
<paramList>/<param> |
default |
<varList>/<var> |
default |
The following attributes of installed component targeters can include substitution variable references.
Parent Element |
Substitutable Attributes |
---|---|
<installedComponent> |
installPath, host |
<systemType> |
installPath, host |
<targetableComponent> |
host |
<toplevelRef> |
installPath, host |
The following attributes of repository component targeters can include substitution variable references.
Parent Element |
Substitutable Attribute |
---|---|
<component> <toplevelRef> |
host host |
The following example lists the variables that are defined in a component for the Apache web server:
<varList> <var name="domainname" default=":[target:domainname]"/> <var name="name" default="apache"/> <var name="installPath" default="/opt/apache"/> <var name="execNativeShutdown" default=":[installPath]/bin/apachectlstop"/> <var name="execNativeStartUp" default=":[installPath]/bin/apachectlstart"/> </varList> |
This component specifies the following:
The domain name must be dynamically retrieved from the target host.
The default value of name is apache.
The variable called installPath has a value of /opt/apache.
The value of installPath is used in the definition of two <execNative> variables.
Although you cannot use a target substitution variable in a configuration file, you can reference a host-specific value from a configuration file. You can do this because the value of the variable that you reference can be computed as a host-specific value. For example, you might have the following variable defined in the <varList> section of the component:
<var name="box" value=":[target:room]"> |
You can then reference :[box] from a configuration file. When :[box] is substituted, it is substituted with the value of the room variable that is defined by the target host.