Variables

2.3 Variables

Variables may be created through the Var and Eval commands. A variable has a case sensitive name and a value. Variables can be referred to in anywhere where dynamic content is needed (including the Var/Eval commands themselves). T-Plan Robot Enterprise's text preprocessor will replace all occurrences of {<var_name>} with the <var_name> variable value before parsing of each command line.

A typical example:

Var PATH=/tmp
Typeline "mkdir -p {PATH}; cd {PATH}"

Avoid variable names consisting of plain numbers, e.g. 'Var 1="test"'. These variables are reserved for procedure parameters and they will be rewritten by any procedure execution without any warning.

If a variable is not defined, no replacement is performed. The following example will rather type 'cd {PATH}' than 'cd /tmp' because the variable definition is commented out:

# Var PATH=/tmp
Typeline "cd {PATH}"

The preprocessor supports nested variable references. This functionality is necessary to process multiple matches of the 'search' image comparison method where coordinates of the matches are stored as SEARCH_X<number> and it is necessary to generate the variable names dynamically in a loop. The following example illustrates such usage. Let's suppose that you are to search the remote desktop for an icon and you click onto each of the occurrences:

Compareto "search.png" method="search"
for (i=1; {i}<{_SEARCH_MATCH_COUNT}+1; i={i}+1) {
# Nested variables compose the variable name from a suffix and an index
Mouse click to=x:{_SEARCH_X{i}},y:{SEARCH_Y{i}}_
}

T-Plan Robot Enterprise also supports a concept of global and local variables which is similar to member class and local variables in object-oriented programming (OOP). The variable type is not explicitly declared but depends on where in the code it is created:

Variables created in the main script body are considered to be global and they are accessible from the moment of definition until the end of script execution.
Variables created within a structured block of code (procedure, if/else and for statements) are considered to be local and they are available only within the block of code (including any nested blocks it may contain).

A local variable cannot override a global one. This means that if you run a Var or Eval command in a block of code and the variable name matches an already existing global variable, you'll rather modify the global variable than define a local one with the same name. The following example demonstrates the principles.

# Create a global variable
Var GLOBAL=global

if (1 == 1) {

    # Create a local variable and change the value of GLOBAL to 'modified'
    Var LOCAL=local GLOBAL=modified

    if (1 > 0) {
        Var LOCAL2=local2

        # Here GLOBAL, LOCAL and LOCAL2 are available.
        # The command will type "GLOBAL=modified, LOCAL=local, LOCAL2=local2"
        Type "GLOBAL={GLOBAL}, LOCAL={LOCAL}, LOCAL2={LOCAL2}"
    }

    # Here GLOBAL and LOCAL are available and LOCAL2 doesn't exist any more.
    # The command will type "GLOBAL=modified, LOCAL=local, LOCAL2={LOCAL2}"
    Type "GLOBAL={GLOBAL}, LOCAL={LOCAL}, LOCAL2={LOCAL2}"
}

# Here GLOBAL is available and LOCAL and LOCAL2 don't exist any more.
# The command will type "GLOBAL=modified, LOCAL={LOCAL}, LOCAL2={LOCAL2}"
Type "GLOBAL={GLOBAL}, LOCAL={LOCAL}, LOCAL2={LOCAL2}"

The same rules are applied to variables defined inside scripts loaded through the Include and Run commands. T-Plan Robot Enterprise provides a set of predefined (also called explicit) variables which may be referenced from any script. They include various useful data, such as execution start date, desktop server hostname, name of the executed script etc. For a complete list of predefined variables see the Var command specification. Variable values may be overridden in script executions through CLI. See the v/-variable parameter specified in the CLI Options document. This allows to parametrize particular script executions and/or avoid exposure of sensitive information in the script code (user names, passwords ...). Setting through the CLI makes the variable 'read-only' and fixes its value for the whole time of script execution. Any Var/Eval commands modifying this variable executed in the script will be ignored and they will have no impact on its value. This applies to any variable including the explicit (predefined) ones.