|
Control Structures |
Basics |
Script Literal |
|
You can use script variables in the scripts of AE in order to store values. These script variables can include numbers, strings, and date and time formats.
The script element :DEFINE can be used to declare a script variable to a particular data type.The data type determines the values that the variable should include.The script statement :SETcan be used to assign and change values within a script.
:DEFINE &FILE#, string
:SET &FILE# = "temp.txt"
You can also create script variables directly by using :SET (without using :DEFINE before). 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 in order 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 | Alphanumeric string with arbitrary length. |
| 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
The data type "float" includes positive and negative integers. Positive integers can also be used for the data type "signed".
A variable that has already been used cannot be declared again. A variable's data type cannot be changed.
Note that floating point numbers can cause imprecise results in arithmetic operations.
A script variable's name is limited to 32 alphanumeric characters, including the special characters "$", "_", "@", "ยง" and "#". German Umlauts are not allowed. The first character must not be a number. Variables within the script must always specified with a leading "&" following the variable name!
An exception to the 32 character limit is for the :PSET and :RSET script statements, which are limited to 31 alphanumeric characters.
Note that the script variable's name must be different from the predefined variable's name. AE does not recommend using '$' at the beginning of variable names (after the character '&').
Names of script variables are not case sensitive. Script variables are specified without quotation marks.
A script variable's name must not comply with the beginning of another script variable's name. In such a case, you can name the script variable properly by appending a special character. For example, the term "Enddate" is output in the activation protocol.
:SET &ACTIVITY# = "End"
:SET &ACTIVITY_DATE# = SYS_DATE()
:PRINT "&ACTIVITY#date"
Do not use "&ACTIVITY_date" and "&ACTIVITY" within one script because in this case, the latter one is not a unique name anymore. The variable name and characters that should be output can be written in one line. Therefore, the following example could either refer to "Enddate" or to "040101".
:SET &ACTIVITY = "End"
:SET &ACTIVITYdate = SYS_DATE()
:PRINT "&ACTIVITYdate"
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 the name of arrays may be up to 24 alphanumeric characters long.
: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, Automic recommends creating arrays only with the number of elements that are required in order 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")
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 not correspond to 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".
For example:
: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).
For example:
:DEFINE &NUM#, signed
:SET &NUM# = "abc123"
The assignment works correctly if the string is a number.
For example:
: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.