Variables and VARA Objects

Variables and VARA objects let you define placeholders for values to use in executable objects. This topic differentiates the various types of variables and VARA objects that you can find in your system. As a developer and object designer, you create variables and VARA objects and use them in executable objects. As a system administrator, you maintain Client and system variables and VARA objects.

This page includes the following:

Overview

When a task is generated, the system resolves variables and references to VARA objects to retrieve values from various sources. The values of variables and VARA objects are resolved at activation time or at runtime as defined on the Attributes page in the object definition. For more information, see Generating at Activation or at Runtime.

VARA Objects

VARA objects are entities with their own attributes like any other object in the Automation Engine. The following types of VARA objects are available:

As an administrator, you define system settings that determine what should happen when VARA objects cannot be resolved. For more information, see VARA_ERROR_ON_REPLACEMENT in UC_CLIENT_SETTINGS.

Predefined VARA Objects for System and Client Values

Your system contains predefined VARA objects in Client 0 that store system and Client values. These objects control the behavior of the system and of the Clients. The access to this type of VARA objects is typically restricted to administrators.

VARA objects that contain system-wide parameters must remain in Client 0.

VARA objects that govern the behavior of Clients and their processes can be stored in the respective Clients.

For more information, see List of VARA Objects for System and Client Values.

Note: You cannot use predefined VARA objects in Job Forms.

User-Defined VARA Objects

As a developer and object designer, you create VARA objects to store and use values. Your VARA objects can retrieve values from various sources (databases, directories, and so on) dynamically. You can also assign them static values. User-defined VARA objects are not provided with the installation. However, your system provides templates for various types of user-defined VARA objects. For more information, see VARA Objects.

Virtual Agent VARA Objects

Agent variables store Agent information and settings. As virtual VARA objects, they are available either in Client 0 or in the database. For a list of all available Agent variables, see List of Agent Variables.

Note: You cannot set values in Agent variables by script.

As an administrator, specify all Agent variables in the [VARIABLES] section of the Agent INI file. By doing so, you ensure that the variable values are set in accordance with your environment.

Example

[VARIABLES]

UC_HOST_CODE=UC_CODE

UC_HOST_JCL_VAR=NSK

UC_EX_PATH_BIN=$data01.uc4

UC_EX_PATH_CACHE=c:\AE11\agents\windows\CACHE\0100\
UC_EX_PATH_JOBREPORT=$data01.
UC_EX_JOB_MD=$data01.uc4.ucxjns1r

Use script elements such as GET_VAR to retrieve values from Agent variable.

Syntax

GET_VAR (Agent variable,Agent name)

Variables

There are various types of variables to store and pass values. Some variables are predefined and cannot be set by users, while you can freely create others. Variables are resolved when the task is generated. Unlike VARA objects, variables are stored in scripts and are not objects in their own right.

Predefined Variables for System and Object Values

Predefined system variables have always the same value across the whole Client or Automation Engine system. They can be accessed by all tasks. The following types of predefined variables are available:

You can use these predefined variables in scripts and in object definitions. In scripts, variables are resolved and replaced by values when the script is processed. In object definitions, the values of these variables are replaced after the script has been processed. You can use predefined variables to modify object attributes.

Predefined variables are displayed in blue in the script editor.

Notes:

For more information, see Variables for System and Object Values.

Script Variables

Script variables play a fundamental role when you write scripts. Create them to store and pass values in the scripts that you define on the Process pages of executable objects. You can also define some object properties with script variables.

Script variables can contain only text. Their values cannot contain multiple lines. Variables declared as arrays can contain multiple values.

You use scripts such as :SET, :PSET or :RSET to send and declare variables and to assign values to a script variable. You use :DEFINE to define the variable as an array. With GET_SCRIPT_VAR and :SET_SCRIPT_VAR you set and read the values of script variables by indirect reference.

Script variables are displayed in purple in the script editor.

Examples

A numerical value is assigned to a script variable:

:SET&NUMBER# = 1

The value of one script variable is assigned to another variable:

:SET&NR# = &NUMBER#

For more information, see:

Object Variables

Object variables retrieve values from object properties (values in its input fields), or from the runtime instance of the object (the task). You define object variables on the Variables Page of executable objects. Alternatively, use a :PSET script statement on the Process Pages. These object variables are stored in the object definition. Child tasks can inherit object variables from parent objects.

Object variables can contain multi-line text. They are displayed in purple in the script editor.

For more information, see:

PromptSet Variables

If you have defined values in a PromptSet, these values are stored as PromptSet variables. When the PromptSet is assigned to an object, these values are used during its execution. However, they can be overridden in one of the following ways:

The type of data that PromptSet variables can contain depends on the element type in the PromptSet where they have been defined. Once a PromptSet variable has been defined, its value is read-only and cannot be changed.

PromptSet variables can also be defined using :READ statements in scripts. They are displayed in purple in the script editor.

For more information, see:

Storing Variables in the Read Buffer

The read buffer temporarily stores values so that other tasks can use those values. The values that are stored in the read buffer are deleted after they have been consumed. If a process contains several tasks, the read buffer variables store their values in chronological order. Those values are also consumed in chronological order. For example, in a process with three tasks, the first time that the ACTIVATE_UC_OBJECT function is used, the values that are stored by the first task are used.

Use script statements to store values of script variables or PromptSet variables in the read buffer when you activate an object through a script with ACTIVATE_UC_OBJECT.

Your system includes predefined variables (UC_CAUSE* variables) that retrieve details of a task and temporarily store the values in the read buffer. Values are stored in the read buffer when you specify follow up or alternative actions (the execution of another object) if a condition or status is not met.

For more information, see:

Variable Names

Variables names have the following syntax:

Important! Variable names may not be sub strings of other variable names. For example, if you have a variable called &UNR you cannot define a variable called &UNR_SC because the former is a sub string of the latter. The last # symbol in the variable name helps you get around this limitation. It is not mandatory but it is good practice to use it, because it ensures that names do not overlap. Using the previous example, &UNR# is not a sub string of &UNR_SC#.

Examples:

Retrieving Values

In executable objects, retrieve values from variables and VARA objects in the following ways.

Defining Object Attributes using Values from VARA Objects

In the input field where you want to use the VARA object, enter its name in curly brackets. Optionally, specify key and column parameters to select a specific value in the VARA object.

Syntax

{ Variable object [, Key [,Column number]] }.

Example

The following expression is replaced by a value from a VARA object when the task is generated:

{MONITOR_SP1, 2, 3}

where

The Key and Column parameters are optional. If you do not specify the parameters, the system selects the value as follows, depending on the type of VARA object.

Retrieving Values from Variables and VARA Objects in Scripts

In scripts, retrieve values from variables and VARA objects in the following ways:

See also: