STR_SUBSTITUTE_VAR, STR_SUB_VAR

Script function: Replaces script variable names by their values.

Syntax

STR_SUB[STITUTE]_VAR (Variables)

Syntax	Description/Format
Variables	Script variable or string that includes one or several variable names. Format: script literal or script variable

Return code
String with the script variable's values.

Comments

The script variable STR_SUB_VAR can be used to replace one or several script variable names that are stored as a string in a different script variable by the actual variable value. The following examples illustrate this behavior.

The script element GET_PROCESS_LINE includes a parameter that is also called STR_SUB[STITUTE]_VAR. It makes the same replacements in data sequence lines.

Examples

The following example stores a script variable's name (&VAR#) in a different variable (&VAR_NOSUB#) by using the & character twice.

If &VAR_NOSUB# is output, the name of the script variable &VAR# is written to the activation protocol. The script element STR_SUB_VAR serves to replace this name by the variable's value.

:SET &VAR# = "script variable"
:SET &VAR_NOSUB# = "&&VAR# = &VAR#"
:PRINT &VAR_NOSUB#
:SET &VAR_SUB# = STR_SUB_VAR(&VAR_NOSUB#)
:PRINT &VAR_SUB#

Output in the activation protocol:

2011-05-06 10:34:04 - U0020408 &VAR# = script variable
2011-05-06 10:34:04 - U0020408 script variable = script variable

The second example retrieves a value from the Variable object VARA.SUB which includes the names of two script variables. These two script variables are created and set.

Only the script variable names are written to the report if the Variable object's value is directly output. They are not replaced by their values.

The script element STR_SUB_VAR is used to replace the names of the two script variables by their values.

:SET &VARA# = GET_VAR(VARA.SUB, "SUBVAR")
:SET &VAR1# = "Hello"
:SET &VAR2# = "World"
:PRINT "Content without replacements: &VARA#"
:SET &VARA_SUB_VAR# = STR_SUB_VAR(&VARA#)
:PRINT "Content with replacements: &VARA_SUB_VAR#"

Output without and with STR_SUB_VAR:

2011-05-06 10:34:04 - U0020408 Content without replacements: &VAR1# &VAR2#
2011-05-06 10:34:04 - U0020408 Content with replacements: Hello World

The Script Optimizer

Executable objects have a Process page (and sometimes a Pre Process page) where you add Automic script. Let's call this "custom" script. At the execution time of an object, the Automation Engine inserts an internal part into the script right before the custom scripts. This internal part mainly contains :SET commands in order to set the Predefined Variables to the appropriate values. For example, the internal part contains the following:

:SET_SVAL &$CLIENT# = SYS_ACT_CLIENT()

:SET_SVAL &$PHYS_DATE_DAY_OF_YEAR# = SYS_DATE_PHYSICAL("LLL")

Setting the whole set of predefined variables ends up in a lot of :SET_SVAL commands, which would be a significant loss of performance at script execution. So before script execution, the "Script Optimizer" removes all :SET_SVAL except those which set predefined variables being used in the "custom" script. If the "custom" script dynamically uses predefined variables, for example, by reading the name of the predefined value with get_var() than the optimizer would not see that and remove the corresponding :SET_SVAL. The dynamically used predefined variables would not be resolved.

Example

In this example references the static variable VARA.STR_SUB_VAR shown below.

Given custom script:

:set &value# = get_var('VARA.STR_SUB_VAR','1')

:set &value# = str_sub_var(&value#)

:print 'the value is &value#'

The resulting output is:

U00020408 the value is &$PHYS_DATE_DAY_OF_YEAR#

Reason is that the Script Optimizer removes the :SET_SVAL &$PHYS_DATE_DAY_OF_YEAR# = SYS_DATE_PHYSICAL("LLL") statement from the INTERNAL part because '&$PHYS_DATE_DAY_OF_YEAR#' was not found in the custom script.

To solve this, simply use the Predefined Variables in the custom script. For example:

:set &x# = &$PHYS_DATE_DAY_OF_YEAR#

:set &value# = get_var('VARA.STR_SUB_VAR','1')

:set &value# = str_sub_var(&value#)

:print 'the value is &value#'

The resulting output is:

U00020408 the value is 047