Automation Engine Script Guide > Ordered by Function > Script Structure and Processing > :DEFINE

:DEFINE

Script Statement: Declares a script variable with a particular data type.

Syntax

:D[EFINE] Script variable, data type, [Array size]

Syntax	Description/Format
Script variable	The name of the script variable that is newly created including a data type. 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! Format: script variable
Data type	The data type of the declared variable. Allowed values: "unsigned", "string", "float" or "signed" unsigned: positive integers without signs signed: integers with signs float: floating point number string: string, text
Array size	Should the script variable be generated as an array, you can use this parameter to define its size. Format: number without inverted commas Allowed values: 1 to 99999

Syntax

Description/Format

Script variable

The name of the script variable that is newly created including a data type.

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!

Format: script variable

Data type

The data type of the declared variable.

Allowed values: "unsigned", "string", "float" or "signed"

unsigned: positive integers without signs
signed: integers with signs
float: floating point number
string: string, text

Array size

Should the script variable be generated as an array, you can use this parameter to define its size.
Format: number without inverted commas

Allowed values:
1 to 99999

Comments

Script variables can also be directly created using the script element :SET. This is only possible for the data types "string" or "unsigned". In this case, the data type is automatically retrieved via the specified value. A scripting error occurs if a floating point number or a negative number has been specified.

You cannot declare variables that have already been used. This applies to script and object variables including the definitions made in the Variables & Prompts tab.

Directly assigning the value of a different data type is only possible for script variables that have been created using :SET and only with positive integers and strings.

If you assign a value to a script variable that lies outside of the range of its data type, the value will be converted to the target data type automatically.

Using the script element :DEFINE without a data type or with a data type that is invalid results in a scripting error.

It is possible to redefine variables with :DEFINE that are already defined by :SET.

The following value ranges are available for the different data types:

Data Type	Value Range
unsigned	0 to +9 999 999 999 999 999
signed	-9 999 999 999 999 999 to +9 999 999 999 999 999
string	Alphanumeric string with arbitrary length.
float	-9 999 999 999 999 999.9999999999999999 to +9 999 999 999 999 999.9999999999999999

The following value ranges are different for Sun Solaris operating system. They are:

Data Type	Value Range
unsigned	0 to +9 999 999 999 999 998
signed	-9 999 999 999 999 998 to +9 999 999 999 999 998
float	-9 999 999 999 999 998.9999999999999999 to +9 999 999 999 999 998.9999999999999999

Use the parameter Array size to have the script variable generated as an array with a defined length. The size must not exceed the value 99999. Please pay attention to the peculiarities in handling script arrays. No square brackets [] are required for the array declaration.

Use the script statement :FILL to fill script arrays with several different values.

Examples

Declaration of several variables with different data types and subsequent value assignment:

:DEFINE &a#, unsigned
:DEFINE &b#, signed
:DEFINE &c#, float
:DEFINE &d#, string
:SET &a# = 12
:SET &b# = -5
:SET &c# = 0.50
:SET &d# = "string"

The following example converts the data type of the variable's value automatically:

:DEFINE &unsigned#, unsigned
:DEFINE &string#, signed
:SET &unsigned# = 12
:SET &string# = &unsigned#

The following example shows a valid assignment because the variable "&unsigned#" is converted to the correct data type via the function CONVERT:

:DEFINE &unsigned#, unsigned
:DEFINE &string#, signed
:SET &unsigned# = 12
:SET &string# = CONVERT(string,&unsigned#)

A direct value assignment with the data types "unsigned" and "string" is possible if a script variable is created using the script element :SET.

:SET &setvar#= 12
:SET &setvar2#="string"
:SET &setvar# = &setvar2#

The last example shows how to create and fill an array.

:DEFINE &array#, unsigned, 5
:FILL &array#[] = GET_VAR(VARA1, ARRAY)

The following example rounds the result of the arithmetic operation 3.0 - 0.1 into a string, using the script function FORMAT while taking a common arithmetical error Epsilon = 0.0000005 and one decimal place into account.

:DEFINE &SCRIPT_VERSION_ORIG#, float
:DEFINE &SCRIPT_VERSION_ORIG1#, float
:DEFINE &EPSILON#, float

:SET &SCRIPT_VERSION_ORIG# = 3.0
:SET &EPSILON# = 0.0000005
:P &SCRIPT_VERSION_ORIG#
:SET &SCRIPT_VERSION_ORIG# = &SCRIPT_VERSION_ORIG# - 0.1
:P BEFORE FORMAT: &SCRIPT_VERSION_ORIG#
:SET &SCRIPT_VERSION_ORIG# = &SCRIPT_VERSION_ORIG# + &EPSILON#
:SET &SCRIPT_VERSION_ORIG# = FORMAT(&SCRIPT_VERSION_ORIG#, "0.0")
:P AFTER FORMAT: &SCRIPT_VERSION_ORIG#

Details concerning the problem of representing floating-point numbers you find in the chapter "Floating-point numbers in the Automation Engine".