You can use script variables in the scripts of the Automation Engine to store values. These script variables can include numbers, strings, and date and time formats. You can also use the script element :DEFINE to redefine a script variable that has already been set by a :SET.
:DEFINE &FILE#, string
:SET &FILE# = "temp.txt"
You can also create script variables directly by using :SET without using :DEFINE. In this case, the variable does not have a specific data type and can only store strings and positive integers.
For example:
:SET &VAR# = 10
:SET &VAR# = "string"
A script variable's validity ends when the script has been processed.
Four data types with different value ranges are available for script variables. Use the script statement :DEFINE to determine the data type in the variable declaration.
| Data type | Description | Value range |
|---|---|---|
| unsigned | Positive integers without algebraic signs | 0 to +9 999 999 999 999 999 |
| signed | Integers with algebraic signs | -9 999 999 999 999 999 to +9 999 999 999 999 999 |
| string | String |
String of any length, all characters that correspond to the Latin1 codepage can be used. Tip: Be careful when you copy & paste contents from browsers or other tools. They might use a different type of encoding that does not work. |
| float | Floating point numbers with algebraic signs | -9 999 999 999 999 999.9999999999999999 to +9 999 999 999 999 999.9999999999999999 |
First declare the variable, and then assign the corresponding value.
:DEFINE &STRING#, string
:DEFINE &SIGNED#, signed
:DEFINE &UNSIGNED#, unsigned
:DEFINE &FLOAT#, float
:SET &STRING#= "1234abc"
:SET &SIGNED#= -5
:SET &UNSIGNED#= 24
:SET &FLOAT#= -0.50
Data type "float" includes positive and negative integers. Positive integers can also be used for the data type "signed".
Important!
- A variable that has already been used cannot be declared again. A variable's data type cannot be changed.
- Floating point numbers can cause imprecise results in arithmetic operations.
You must always use an ampersand symbol (&) that precedes the script variable's name, and it is recommended that you use a hash (#) symbol to signal the end of the variable's name.
The length of a script variable's name is limited to 32 characters. All characters of the alphabet, the numbers 0-9, and the following special characters can be used:"$", "_", "@", "ยง" and "#". German Umlauts are not allowed. The first character after the leading "&", which is not part of the 32-character limit, must neither be a number nor a "$" symbol.
Notes:
- The "$" symbol cannot be used for script variables because it is used as the first character of predefined variables. For details, see List of Predefined Variables for System and Object Values
- An exception to the 32 character limit applies for :PSET and :RSET. Here, the limit is 31 alphanumeric characters.
- Script variable names are not case sensitive and you specify script variables without quotation marks.
It is recommended that the beginning of your script variable's name is not identical to the beginning of another script variable's name. If you still need such a combination of names, make sure that you append a special character to the script variable so that it becomes unique.
Correct example:
:SET &ACTIVITY# = "End"
:SET &ACTIVITY_DATE# = SYS_DATE()
:PRINT "&ACTIVITY#date"
The activation protocol shows the term "Enddate" when this script has been executed:
Incorrect example:
:SET &ACTIVITY = "End"
:SET &ACTIVITYdate = SYS_DATE()
:PRINT "&ACTIVITYdate"
You cannot use"&ACTIVITY_date" and "&ACTIVITY" within one script. "&ACTIVITY" is not a unique name and therefore, your system will display a warning when you try to save the above script.
You can create arrays in combination with script variables. In doing so, you can store several different values in one variable. The individual values can be accessed via an index. This index is specified as a number which is enclosed in [] square brackets after the variable's name. Arrays can only be created during the variable declaration by using :DEFINE . The third parameter defines the number of values (index area).
Unlike script variables, array names are limited to 24 alphanumeric characters.
:DEFINE &ARR#, unsigned, 10
:SET &ARR#[5] = 20
An array's maximum size is 99999. The index is always specified as a positive number without inverted commas. The first element is accessed with the index 1.
Note that memory is allocated for all elements when an array is created. Therefore, it is recommended that you create arrays only with the number of elements that are required to avoid performance problems.
Array fields that have not yet been initialized show the default value "" (data type: string) or 0 (numerical data types).
Several values can directly be stored in an array using the script element :FILL. No index must be specified. Doing so is useful if several columns of a Variable object should be read:
:FILL &ARR#[] = GET_VAR("VARA","JOBS")
Value Assignments
Values can be assigned to script variables by using the script element :SET . You can specify the assigned value (regardless of its data type) with or without inverted commas (script literal), or it can be the return code of a script function.
:DEFINE &NUM#, unsigned
:SET &NUM# = 1234
:SET &NUM# = "1234"
:SET &NUM# = ADD(1,2)
You can create script variables either with a certain data type by using :DEFINE or when you assign a value.
variables that are created by using :SET do not have a certain data type but can only store positive integers or strings. The attempts to assign a negative value or a positive floating-point number to a variable has the effect that the value "0" is stored in the variable. No error occurs.
The following peculiarities apply for script variables that have a data type:
If the assigned variable does comply with the script variable's data type, the system tries to correct and adjust it. A runtime error occurs if this is not possible as the following two error cases show:
Error case 1:
A negative number is assigned to a script variable of data type "unsigned":
:DEFINE &NUM#, unsigned
:SET &NUM# = -1
Error case 2:
A string that is not a number is assigned to a script variable that has a numerical data type (unsigned, signed or float):
:DEFINE &NUM#, signed
:SET &NUM# = "abc123"
The above assignment works correctly if the string is a number:
:DEFINE &NUM#, signed
:SET &NUM# = "-123"
Assigning a floating-point number to a variable although its data type does not support it (such as "signed" and "unsigned") has the effect that the decimal places are truncated and not rounded.
For example: The assignment result is -10 in this case.
:DEFINE &NUM#, signed
:SET &NUM# = -10.654
:P &NUM#
Report:
-0000000000000010
By default, numbers have a 16-digit format. Floating-point numbers (data type float) also include 16 decimal places. Zeros are inserted in places that are not used. You can use the script function FORMAT in order to remove leading or final zeros.