Target Substitution Variable References

You can use target substitution variables to obtain values directly from a particular host.

Target substitution variable references use the following syntax:

:[target:varname]
:[target(host-redirect):varname]

A variable name that begins with target refers to the logical host on which a plan is currently being run.

varname represents an attribute value that is specified in the target host's definition for the application that you install. Two types of host variables can be referenced: predefined and dynamic. See Predefined Host Variable Names and Dynamic Host Variable Names.

If you also specify host-redirect, the value for varname is retrieved from that particular host. That host can be a host other than the host on which the plan is currently being run. You can also specify another substitution variable for hostname that, when expanded, resolves to the name of a host. The syntax for host-redirect is described in Host Redirects.

Predefined Host Substitution Shorthands

You can use these predefined host substitution shorthands anywhere that a host substitution reference can be used:

• :[/] – Expands to the operating system-specific file separator, which is based on the root physical host of the current target host

  • UNIX systems – :[/] expands to /

  • Microsoft Windows systems – :[/] expands to \

• :[:] – Expands to the operating system-specific path separator, which is based on the root physical host of the current target host

  • UNIX systems – :[:] expands to :

  • Microsoft Windows systems – :[:] expands to ;

Host Redirects

Target host substitution variable references and external component substitution variable references can optionally include a host redirect. This means that the host on which the variable or component lookup occurs is the specified host rather than the current target. host-redirect has one of the following forms:

• parent-ref

• hostname

• hostname/parent-ref

hostname is either the name of a host or a substitution variable reference that, when expanded, resolves to the name of a host.

parent-ref is one of the following:

• / – The root parent host of the specified host, or the current target host if hostname is omitted

• A series of one or more slash-separated ..s – The nth parent of the specified host, or current target host if hostname is omitted, where n is the number of ..s that appear

The parent-ref operators are used primarily for virtual hosts, but they can also be used for physical hosts. Applying either operator to a physical host is a no-op.

Example 6–3 Using Target Substitution Variable References

• This example shows how to look up variable var1 on host myHost:

  :[target(myHost):var1]

• This example shows how to look up variable var1 on the host specified by substitution variable hostName:

  :[target(:[hostName]):var1]

• This example shows how to look up variable var1 on the logical host on which the plan is currently running:

  :[target:var1]

Predefined Host Variable Names

These predefined host variable names refer to the associated attribute of the referenced host:

• sys.hostName – Target host name

• sys.description – Target host description

• sys.hostType – Host type of the target host

• sys.ipAddress – IP address of the remote agent on the target host

• sys.portNumber – Port number of the remote agent on the target host

• sys.raHomeDir – Absolute path of the remote agent home directory on the target host

• sys.raDataDir – Absolute path of the remote agent data directory on the target host

• sys.raTmpDir – Absolute path of the remote agent temporary directory on the target host

• sys.raConfigDir – Absolute path of the remote agent configuration directory on the target host

Example 6–4 Using Host Substitution Variable References

The following are examples of host substitution variable references and their values:

• :[target:sys.ipAddress] – IP address of the current host

• :[target:var1] – Dynamic variable var1 of the current host

• :[target(host1):var1] – Dynamic variable var1 of host host1

• :[target(:[hostNameVar]):var1] – Dynamic variable var1 of the host whose name is the value of the hostNameVar substitution reference

• :[target(/):var1] – Dynamic variable var1 of the root parent host of the current host

• :[target(host1//):var1] – Dynamic variable var1 of the root parent host of the host named host1

• :[target(../..):var1] – Dynamic variable var1 of the second parent host of the current host

• :[target(host1/../..):var1] – Dynamic variable var1 of the second parent host of the host named host1

Dynamic Host Variable Names

A dynamic host variable name is any attribute name that is declared by the host type of the referenced host. In this case, the value to be substituted for the variable reference is the corresponding value of the attribute that is defined by the referenced host. The value must be expanded prior to substitution, if applicable.