Working with variables in scripts

What a script variable is

• A script variable is a temporary storage used during script execution.
• Variables are written in the form “#A#”, “#B#”, “#C#”, etc.
• Script variables are not database columns – they exist only for the duration of the script execution.
• Each variable always has exactly one data type.

Supported variable data types:

• String – text string
• Integer – integer number
• Long – large integer number
• Double – decimal number
• Date – date

Database null value

• The script uses the database value “null”.
• The value “null” means that the variable has no defined value.
• A newly declared variable that has not been assigned a value always has the value “null”.
• The value “null” can be assigned explicitly using the variable “#null#”.

Variable declaration

A variable must always be declared before it is used. Declaration defines the variable’s data type.

A variable can be declared in several ways:

• Using a script command for variable declaration.
• By loading a value from a database query – the variable’s data type is automatically taken from the database column type.
• Using expressions:
  • String(text)
  • Integer(number)
  • Long(number)
  • Double(number)
  • Date(date)

Important behavior of declaration:

• If a variable already exists and is redeclared with a different type, its value is reset to “null”.

Single value vs. array of values

• A variable loaded from a database query automatically becomes an array of values.
• Each row in the query result corresponds to one element of the array.
• If the database query returns no records, the result is an array with zero elements.

Arrays of values can also be created manually using server functions:

• StringArray(value1;value2;…)
• IntegerArray(number_of_elements)
• LongArray(number_of_elements)
• DoubleArray(value1;value2;…)
• DateArray(value1;value2;…)

Assigning values

• A variable value can be assigned to another variable or to a database control.
• Assignment can be:
  • simple (a single value), or
  • based on a mathematical expression (addition, subtraction, multiplication, division).
• If a variable is an array of values, arithmetic operations are applied to all elements of the array.
• When assigning an array of values to a database control, only the first value of the array is used.
• If the array contains no elements or the value is “null”, the database value “null” is assigned to the control.

Loop

• A loop is used to sequentially process elements of an array of values.
• The number of loop iterations corresponds to the number of elements in the controlling variable.
• If the array contains no elements, the loop is not executed at all.

Variable behavior inside a loop:

• During a single iteration, the variable behaves as a single-value variable.
• After the loop finishes, the variable again behaves as an array of values.
• Elements with the value “null” are automatically skipped in the loop.
• If multiple variables were loaded using the same database query, they are iterated synchronously in the loop.
• It is recommended to use the primary key “id” as the controlling variable of the loop.

Comparing values

• Script values of two variables can be compared.
• If one of the variables is an array of values, only its first value is used for comparison.

The “contains” operator:

• When used on an array of values, it tests whether the array contains a specific value.
• When used on a text string, it tests whether the string contains a given substring.

Data type conversion

• A value’s data type can be changed by assigning it to a variable of a different data type.
• Writing a value into a variable of the target type performs the conversion.

Example of converting a number to text:

• a variable of type Integer is assigned to a variable of type String

Example of converting text to a number:

• a variable of type String is assigned to a variable of type Integer

Typical mistakes when working with variables

• A variable is used without being declared.
• The script author expects a single value, but the variable is actually an array of values.
• The value “null” is not handled in subsequent processing.
• A loop uses a controlling variable that contains “null” values.