Data Types and Variables

Data types are used to apply semantic meaning to various things in the language, such as how variables interact and how data is returned from a function. Data types are used to restrict the operations that can be performed upon those things (for example, you can’t use a real value of 2.5 as an index to an array because arrays are indexed by integer values such as 2).

Fundamental Data Types

Fundamental data types are the basic data types built into the language, from which all variables and more complex data types can be constructed. (Note that the terms “fundamental data type” and “primitive data type” are often used interchangeably in programming language documentation).

Fundamental Numeric Data Types

Two fundamental numeric data types will exist to handle numbers with different representations.

Name Description Range

real

64-bit IEEE floating-point value

-1.7976931348623158 x 10308 to 1.7976931348623158 x 10308

integer

64-bit signed integer

-9,223,372,036,854,775,808 to 9,223,372,036,854,775,807

The real data type is used to represent numbers that have a fractional component, such as 0.5. Positions, velocities, and analog input/output values usually contain fractional components, and therefore should be expressed with a real.

The integer data type is used to represent whole numbers that do not have a fractional component, such as 1024. Task indices, array indices, and digital/analog I/O channels should be expressed with an integer. The integer data type is also useful for operating on low-level bit patterns (for example, shifting a mask value such as 0x800 to the right by 3 bits).

var $myInt as integer = 0xFF
var $myReal as real = 1.23

Fundamental String Data Type

The fundamental string data type is used to represent a sequence of Unicode characters. Unicode supports a very large set of characters that are not supported in the limited set of ASCII characters, such as 安 and ☮. Unicode characters are stored as UTF-8 code points, and AeroScript automatically handles memory allocation for single-byte ASCII characters and multi-byte Unicode characters. The strings do not need to be null-terminated, and null-terminator character literals are not supported.

var $myStr as string(32) = "Hello World! ☺"

The maximum number of characters that a string can contain cannot change dynamically as the program executes. This is because the language runs in a real-time environment, where dynamic memory allocation is non-deterministic. Therefore, the capacity (maximum number of characters) in a string should be specified when declaring a string variable. The number of characters that the string actually contains can fluctuate during the execution of a program, but a string can never contain more than the specified maximum number of characters. If a capacity is not specified, a default capacity of 256 characters is used.

Fundamental Axis Data Type

The fundamental axis data type is used to represent a single axis in the system. A set of multiple axes can be represented by creating an array of axis indices.

var $myAxis as axis = X
var $myAxisGroup[] as axis = [X, Y]

Having an axis data type will allow users to have more control over their motion than they did on the A3200. For example, the axes that are used to perform PVT motion in the following program can be easily modified by changing the first program line.

var $myAxes[] as axis = [X, Y]

MovePvt($myAxes, [10, 20], [10, 10], 1)
MovePvt($myAxes, [20, 40], [10, 10], 1)
MovePvt($myAxes, [30, 60], [10, 10], 1)

The @ operator (an asperand, also known as the “at sign” or “commercial at”) can be used to convert a value into an axis. The value to convert to an axis can be an integer, a real with a whole number value such as 3.0, or a string that contains the name of an axis.

var $myAxis as axis = @0
var $myStr as string = "X"
var $axis as axis

$axis = @$myStr

Fundamental Handle Data Type

The fundamental handle data type is used to interact with some external resource (such as a file or a socket) through a well-defined interface. The following example shows a handle being used to access a file.

var $myFile as handle
var $myValue as real

$myFile = FileOpenText("data.txt", FileMode.Read)
$myValue = StringToReal(FileTextReadLine($myFile))
FileClose($myFile)

The existence of the handle data type allows the compiler to perform better type checking in order to produce an error when incorrectly using file functions or socket functions. For more information, refer to File and Directory Functions and Socket Functions. In addition, the type checking prevents the usage of the handle data type incorrectly, such as in an operation where a handle variable is added to a real variable.

Aggregate Data Types

An aggregate data type is a data type that can be referenced as a single entity, yet can consist of multiple pieces of data. Arrays and structures are the two aggregate data types that can be used in the language.

Array Data Types

Arrays are used to store multiple values of the same data type. The data type used by the array can be any existing data type. For example, you can have an array of values with the string, integer, real, or user-defined struct data types, among others. The following example shows the declaration of a 1-dimensional array of integer values and an array of AxisData (a user-defined struct) values.

// Array of 3 integers.
var $positions[3] as integer

struct AxisData
   $position as real
   $velocity as real
end

// Array of 32 user-defined AxisData structs.
var $axData[32] as AxisData

In addition to 1-dimensional array variables, arrays can also be 2-dimensional or 3-dimensional. The following example shows how you can declare a 2-dimensional array and a 3-dimensional array.

// 2-dimensional array of real values.
var $coeff[3][3]

// 3-dimensional array of real values.
var $matrix[2][3][3] as real

Each element of an array can be individually referenced by its index. Array indices are zero-based, meaning the first element in the array has an index of 0, the second element has an index of 1, and so on, up to one less than the length of the array. For example, a 1-dimensional array that was declared with 3 elements can be accessed with indices 0, 1, and 2. Attempting to access an array element with an out-of-bounds index will result in a runtime error.

var $myArray[3] as real = [5.5, 3.7, 3.1]

// Copy the value from the array at index 2 to the array at index 0.
$myArray[0] = $myArray[2]

// The following results in a runtime error because an out-of-bounds array
// index (3) was specified for $myArray, which can only be accessed through
// indices 0-2.
$myArray[3] = $myArray[0]

In the following example, an array of position values is filled by looping over an array of axes.

var $axisArray[3] as axis = [X, Y, Z]
var $posArray[3] as real
var $index as integer

for $index = 0 to 2
   $posArray[$index] = StatusGetAxisItem($axisArray[$index], AxisStatusItem.PositionCommand)
end

Structure Data Types

A structure (called a struct for short) is an aggregate data type that is user-defined. Structures are useful for grouping a common set of data together, such as a set of gains for an axis, or a set of coefficients for a filter.

Each element of a structure can be declared to be any data type that has been previously defined, including fundamental data types or another struct. An example of a user-defined structure is as follows.

struct AxisData
   $pos as real
   $vel as real
   $acc as real
   $miscData[3][3] as integer
end

Once a struct is defined, variables can be declared with their data type. In addition, they can be used to declare the type of a function argument. One thing to note is that a struct cannot be returned from a function. However, a struct can be created outside of a function and modified within the function by using the ref keyword when declaring the function argument, as shown in the following example.

struct Point
   $x as real
   $y as real
end

program
   var $p1 as Point = [5.5, 10.2]
   var $p2 as Point = [-1.5, 6.6]
   var $sum as Point

   AddPoints($p1, $p2, $sum)
end

function AddPoints($a as Point, $b as Point, ref $result as Point)
   $result.x = $a.x + $b.x
   $result.y = $a.y + $b.y
end

Refer to the Structure Variable Definition and Declaration Syntax and Structure Variable Initialization Syntax sections for more information.

Enumerated Data Types

An enumeration or enumerated data type (called an enum for short) is a data type that consists of a set of named values called enumerators. The main purpose of an enum is to perform logic using a set of names rather than using constant numeric values. An example of an enum is as follows.

enum Direction
   North = 0
   South = 1
   East  = 2
   West  = 3
end

var $direction as Direction = Direction.North

Once an enum is defined, variables can be declared with their data type. In addition, function arguments and function return types can be an enum type. The following example shows the definition of an enum along with its use in a variable and as a function return type.

enum Quadrant
   None
   One
   Two
   Three
   Four
end

program
   var $quadrant as Quadrant

    // Determine which quadrant the point (-5, -6) is in.
    // The function will return Quadrant.Three.
   $quadrant = GetQuadrant(-5, -6)
end

function GetQuadrant($x as real, $y as real) as Quadrant
   if ($x > 0)
      if ($y > 0)
         return Quadrant.One
      elseif ($y < 0)
         return Quadrant.Four
      end
   elseif ($x < 0)
      if ($y > 0)
         return Quadrant.Two
      elseif ($y < 0)
         return Quadrant.Three
      end
   end

   return Quadrant.None
end

Refer to the Enumeration Variable Definition and Declaration Syntax and Enumeration Variable Initialization Syntax sections for more information.

Variables

Variable Declaration

Variable Names

In order to use a program variable, you must first declare it with a name. The name of a variable must match the regular expression that follows.

$[A-Za-z_][A-Za-z0-9_]*
  • A variable name must start with a dollar sign ($).
  • After the dollar sign ($), it must contain a letter or underscore.
  • After the first letter or underscore, it can contain zero or more letters, numbers, or underscores.

A variable cannot share the same name as a property declared within the same scope. Refer to Properties for more information.

Some names, such as $iglobal, are reserved by the Standard Library in order to refer to controller global variables. These reserved names cannot be used for user-defined variables. See Controller Global Variables for more information.

Variable names are case-sensitive. For example, $MYVAR and $myVar refer to different variables.

Numeric, Axis, and Handle Variable Declaration Syntax

The simplest syntax for declaring a variable with a fundamental numeric data type is as follows:

var <VariableName> as <DataType>

The <DataType> can refer to either of the fundamental numeric types (integer or real), the fundamental axis type, the fundamental handle type, or some user-defined struct or enum type.

Each code example that follows shows you different values for the <VariableName> and <DataType>:

var $myInt as integer
var $myReal as real
var $myAxis as axis
var $myHandle as handle

If no <DataType> is specified, then the variable is automatically assigned a data type of real. The two variable declarations that follow are equivalent:

var $myVar
var $myVar as real

String Variable Declaration Syntax

Variables with the string data type must be declared differently than numeric variables. To declare a string variable, you must use the syntax that follows:

var <VariableName> as string(<Capacity>)

The <Capacity> value refers to the maximum number of characters that the string can contain. In order to declare a string that can hold up to 32 characters, for example, use the following code:

var $myStr as string(32)

A string variable may be declared without a size. If no size is specified, then the compiler will choose a default capacity of 256 characters for the string.

var $myStr as string

Syntax for Declaring Multiple Variables on the Same Line

Multiple variables with the same type can be declared on a single line if they are separated with a comma and are not initialized.

var $myVar, $myOtherVar, $myThirdVar as integer
var $realVal, $arr[3] as real
var $rVal, $realArr[3]
var $myStr, $myOtherStr as string(32)

However, each variable that is initialized must occupy its own line. See the Structure Variable Initialization Syntax section for more details.

var $myInt as integer = 0xBEEF  // OK.
var $a, $b as real = 3          // Causes a compiler error.

Array Variable Declaration Syntax

Array variables are declared with the following syntax, where <Size> is used to represent the number of elements within the array.

var <VariableName>[<Size>] as <Type>

The above syntax is used to declare a one-dimensional array, which users will find to be sufficient in many cases. However, two- or three-dimensional arrays can be declared simply by specifying more dimensions to the declaration.

var <VariableName>[<Size1>][<Size2>] as <Type>
var <VariableName>[<Size1>][<Size2>][<Size3>] as <Type>

Keep in mind that variables with a data type of string are declared with their own special syntax, but declaring an array of variables with these types is intuitive. The following shows some examples of variable array declarations.

// Create an array of 32 real values.
var $positions[32]

// Create a 2-dimensional array of integers.
var $matrix[3][3] as integer

// Create an array of 2 handles.
var $files[2] as handle

// Create an array of 5 strings (each containing up to 16 characters).
var $myStr[5] as string(16)

Structure Variable Definition and Declaration Syntax

Definition Syntax

Structure data types are defined with the following syntax.

struct <TypeName>
<VariableName1> as <DataType1>

<VariableName2> as <DataType2>
   // ...
end

The rules for the <TypeName> are similar to other identifiers and must obey the regular expression that follows. Other restrictions apply. See Valid Identifier Format for more information.

[A-Za-z_][A-Za-z0-9_]+

Members of a structure are declared similar to normal variable declarations. However:

  • The var keyword is omitted.
  • Members cannot be initialized in the definition.

See Valid Variable Name Format for the correct way to define the names of struct members.

An example structure data type definition is as follows:

struct MotionType
   $pos as real
   $vel as real
end

A struct must be defined at the program global scope. The program global scope exists outside of all statement blocks (such as if or repeat statements), the program block, or function blocks, if they exist. For more information about the program block, refer to the User-Defined Functions section.

Note that the elements within a structure data type can be defined with any type as long as that type has been previously defined, including other structures. Elements may also be declared as arrays. See the following for an example.

struct MotionType
   $pos as real
   $vel as real
   $acc as real
end

struct ProfileType
   $motion[32] as MotionType
   $mask as integer
end
Declaration Syntax

Structure variables use the same syntax as numeric variables. You can also declare an array of structures.

var <VariableName> as <Type>
var <VariableName>[<Size>] as <Type>
var <VariableName>[<Size1>][<Size2>] as <Type>
var <VariableName>[<Size1>][<Size2>][<Size3>] as <Type>

The following example shows both a definition and a declaration of a struct data type. The declaration shows the creation of an array of structures.

struct MyType
   $valA as integer
   $valB as integer
   $name as string
end

var $myVar[3] as MyType
Member Access Syntax

Accessing member elements in a structure data type can be done in a similar fashion to many existing languages, by using the dot operator. To keep code readable, accessing member elements of a structure requires that there is only one dollar sign ($) at the beginning of the entire expression instead of before the name of each member or sub-member element.

struct MyType2
   $iVal as integer
   $dVal as real
end

var $tval as MyType2

$tval.iVal = 1
$tval.dVal = 1.23

Note that structures can be nested. That is, a struct can be defined with a member whose data type is that of another struct, and that structure can refer to yet another struct, and so on. This means that there may be multiple levels of indirection, as seen in the following example.

struct MyType1
   $arr1[10] as integer
   $arr2[10] as integer
end

// The $data member of the following struct is a struct itself (MyType1).
struct MyType2
   $mask as integer
   $data as MyType1
end

// The $data member of the following struct is a struct itself (MyType2).
struct MyType3
   $data as MyType2
   $dval as real
end

// Declare an array of 3 structures with the type "MyType3".
var $myVar[3] as MyType3

// Store a value in a sub-struct member variable.
$myVar[2].data.data.arr1[4] = 123

Enumeration Variable Definition and Declaration Syntax

Definition

Enumerated data types are defined with the following syntax options:

enum <TypeName>
   <EnumeratorName1> = <Value1>
   <EnumeratorName1> = <Value1>
   // ...
end
enum <TypeName>
   <EnumeratorName1>
   <EnumeratorName1>
   // ...
end

When declaring an enum, either all enumerator values must be specified, or all enumerator values must be unspecified; otherwise a compilation error will occur. If none of the enumerators are given a value, the compiler will assign values to each enumerator sequentially, starting with a value of 0.

// Enum with user-assigned enumerator values.
enum Color
   Red = 1
   Green = 2
   Blue = 3
end
// Enum with compiler-assigned enumerator values.
enum Shape
  Triangle // Assigned a value of 0.
  Square   // Assigned a value of 1.
  Circle   // Assigned a value of 2.
end

The rules for the <TypeName> and <EnumeratorName> are similar to other identifiers and must obey the regular expression that follows. Other restrictions apply. See Valid Identifier Format for more information.

[A-Za-z_][A-Za-z0-9_]+

An enum must be defined at the program global scope. The program global scope exists outside of all statement blocks (such as if or repeat statements), the program block, or function blocks, if they exist. For more information about the program block, refer to the User-Defined Functions section.

Enumerator values must use the integer data type. Therefore, they can be any valid integer value, which includes negative numbers. In addition, multiple enumerator values within an enum can have the same value.

enum CardSuits
   None     = -1      // Negative enumeration values are acceptable.
   Clubs    = 1 << 0
   Diamonds = 1 << 1
   Hearts   = 1 << 2
   Spades   = 1 << 3
   MaxSuit  = 1 << 3  // This has the same value as Spades.
   Joker    = 3.5     // This causes an error because 3.5 is not an integer.
end
Declaration Syntax

Enumeration variables are declared using the same syntax as declaring a numeric variable. Also, an array of enumerators may be declared.

var <VariableName> as <Type>
var <VariableName>[<Size>] as <Type>
var <VariableName>[<Size1>][<Size2>] as <Type>
var <VariableName>[<Size1>][<Size2>][<Size3>] as <Type>

The following example shows both a definition and a declaration of an enum data type. The declaration shows the creation of an array of enumerations.

enum Level
   Low
   Medium
   High
end

var $levels[5] as Level
Enumerator Access Syntax

An enumerator may be accessed using the following syntax.

<EnumName>.<EnumeratorName>

The example that follows shows the access of an enumerator value.

enum Direction
   None
   CW
   CCW
end

var $direction as Direction

if ($iglobal[0] < 0)
   $direction = Direction.CCW
elseif ($iglobal[0] > 0)
   $direction = Direction.CW
else
   $direction = Direction.None
end

Variable Initialization Syntax

Basic Variable Initialization Syntax

When a program is downloaded to the controller, the user-defined program variables are initialized to a specific value. If an initial value is specified for a variable with an initializer, the variable will be set to that initial value.

var $myValue as real = 3.5
var $myStr as string = "Hello"
var $myAxis as axis = X

However, if no initial value is specified for a variable, then that variable will be set to a default value.

var $myDefault as integer  // Gets a value of 0.
var $myReal as real        // Gets a value of 0.0.
var $emptyStr as string    // Gets a value of "".

The default value of each variable declared with a fundamental data type is listed in the following table.

Data Type

Default Value

integer

0

real

0.0
string

"" (empty string)
axis

None (no axis)

handle

None (no handle)

There are different ways in which a variable can be initialized, depending on its data type or whether it is an array or struct. The following example shows variable initialization using constant Literals.

var $myVar as integer = 123
var $myVar2 as integer = 0xFF
var $dval1 = 6.78
var $dval2 = 1.23e-3
var $myArray[2] as integer = [1, 2]
var $myStr as string(32) = "Hello World"
var $myAxis as axis = @0

Variables can also be initialized with expressions. An expression can either be a constant expression, whose value is known at compile time, or a runtime expression, whose value is only known once the program is running. Any variable may be initialized with a constant expression. However, only variables that are declared on the program stack can be initialized with a runtime expression. Refer to the StackSize Parameter.

// Constant expressions
var $numIters as integer = 1024 / 8
var $dpos as real = 2.0 + 2.0 + 2.0
var $str as string = "Hello"
var $axis as axis = X
program
    // Runtime expressions
    var $ival as integer = $iglobal[0]
    var $dval as real = Sin(2.0)
    var $ypos as integer = $dval
    var $pos as real = StatusGetAxisItem(X, AxisStatusItem.PositionCommand)
    var $str as string = $sglobal[3]
    var $axis as axis = @$iglobal[1]
end

When you declare multiple variables on the same line, variable initializers cannot be specified. This is to eliminate any possible confusion as to which variable is actually being initialized.

// This causes a compiler error.
var $xVar, $yVar as real = 3

Array Variable Initialization Syntax

Array variables may be initialized by using the syntax shown in the following example. Note that multi-dimensional arrays can be initialized as well.

var $myArr[3] as integer = [3, 18, 46]
var $str[2] as string(8) = ["Hello", "World"]
var $myMatrix[2][3] as real = [[1.0, 4.0, 8.0], [3.0, 9.0, 27.0]]

When an array variable is initialized, the number of initializers must match the length of the array.

// This causes a compiler error because there are too many initializers.
var $myArr[3] = [1, 2, 3, 4]

If a length is not specified for an array variable, the compiler determines the size of the array from the number of specified initializers. If no size is specified for an array variable and there is no initializer, the compiler will throw an error because it is unable to determine the proper size for the array.

var $myArr[] as integer = [1, 2, 3, 4]  // Array size set to 4.
var $badArray[] as real                 // Compiler error (no initializers).

Multi-dimensional arrays can also be initialized without specifying a length for each dimension. However, each array dimension must contain the same number of initializers.

// Declares a 2x3 array.
var $myArray1[][] = [[1, 2, 3], [4, 5, 6]]

// This causes a compiler error because the second dimension does not
// contain a consistent number of initializers (2 and 3).
var $myArray2[][] = [[0x3F, 0x1C], [0xA0, 0x72, 0xCE]]

An array can be initialized with a dimension whose size is zero by specifying an empty initializer, as shown in the following examples. However, an array may not be explicitly given a size of zero.

// Declares an array with a length of 0.
var $myArray1D[] as real = []

// Declares a 2x0 array.
var $myArray2D[][] as real = [[],[]]

// Produces a compiler error because an explicit array dimension of 0 is
// disallowed.
var $invalidArray[0] as real

Most statements, such as function calls and variable assignments, occupy one line each in a program. However, variable array initializations can span multiple lines to prevent the need to specify everything on a single line, making code more readable.

var $myArr[2][10] as real = [
   [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0],
   [11.0, 12.0, 13.0, 14.0, 15.0, 16.0, 17.0, 18.0, 19.0, 20.0]
]

Structure Variable Initialization Syntax

A struct variable can be initialized similarly to how array variables are initialized. If no initializers are specified, each member of a struct is initialized with its default value, depending on its data type. However, if initializers are specified, then each member of the struct must have an initializer.

struct MyType
  $foo as integer
  $bar as real
end

var $myVar as MyType = [1, 2.345]

In a struct, member variables that are arrays can be initialized with the typical array initialization syntax.

struct MyType
   $a as axis
   $b[3] as real
end

var $myVar as MyType = [X, [2.0, 1.0, 0.5]]

Similarly, an array of structs can be initialized.

struct Point
   $x as real
   $y as real
end

// Creates an array of 3 Point structs.
var $myPoints[] as Point = [[0, 0], [10, 5], [-3, 8]]

Enumeration Variable Initialization Syntax

// An enum variable can be initialized similarly to regular numeric variables.
enum Direction
   Left
   Right
end

var $myDirection as Direction = Direction.Left
var $directions[3] as Direction = [
   Direction.Right, Direction.Right, Direction.Left
]

Variable Scope

The scope of a variable is the region of a program from which that variable can be accessed.

Controller Global Variables

The controller has a set of global array variables that are accessible from every task. These variables can be used to communicate data between tasks.

Controller Global Variable Description

$rglobal[]

Array of controller global variables with the real data type.

$iglobal[]

Array of controller global variables with the integer data type.

$sglobal[]

Array of controller global variables with the string data type. Each string has a capacity of 256 bytes.

During a controller reset, the $rglobal[] and $iglobal[] variables initialize to zero and the $sglobal[] variables initialize to an empty string ("").

During initialization, memory is reserved for a specified number of global real variables, global integer variables, and global string variables. The number of variables for each type is determined by the GlobalReals, GlobalIntegers, and GlobalStrings parameters.

The $sglobal[] variables have a capacity of 256 bytes. But the string buffer must be null-terminated, which makes 255 bytes available for AeroScript characters. Each multi-byte Unicode character that you use will also consume multiple bytes of the 255-byte buffer.

Controller Task Variables

The controller has a set of task array variables for each task. You can access these variables only from AeroScript and the APIs on the same task. Different from controller global variables, you cannot use task array variables to communicate between tasks. But you can use task array variables to communicate between iterations of a program that are running on the same task.

Controller Task Variable Description

$rtask[]

Array of controller task variables with the real data type.

$itask[]

Array of controller task variables with the integer data type.

$stask[]

Array of controller task variables with the string data type. Each string has a capacity of 256 bytes.

During a controller reset, the $rtask[] and $itask[] variables initialize to zero and the $stask[] variables initialize to an empty string (""). The number of task real variables, task integer variables, and task string variables that are initialized for a specified task is determined by the TaskReals, TaskIntegers, and TaskStrings parameters.

Similar to global variables, $stask[] variables have a capacity of 256 bytes. But the string buffer must be null-terminated, which makes 255 bytes available for AeroScript characters. Each multi-byte Unicode character that you use will also consume multiple bytes of the 255-byte buffer.

User-Defined Variables

User-Defined Variable Accessibility

User-defined variables have a much smaller scope than controller global variables, as they can only be accessed from certain areas within a program.

Variables declared outside of the program block are considered to be program global variables. These variables are accessible everywhere within the program block, as well as within each function defined in the program. Refer to the User-Defined Functions section for more information about the program block.

var $globalProgVar

program
   // $globalProgVar is accessible here.
end

function Foo()
   // $globalProgVar is accessible here.
end

Variables declared within the program block are considered to be local variables, and are only accessible within the program block.

program
  var $progVar

   // $progVar is accessible here.
end

function Foo()
   // $progVar is not accessible here.
end

Variables declared within a function body are considered to be local variables, and are only accessible within that function.

program
   // $funcVar is not accessible here.
end

function Foo()
   var $funcVar

   // $funcVar is accessible here.
end

Arguments that are declared for a function are only accessible within the function in which they were declared.

program
   // $funcArg is not accessible here.
end

function Foo($funcArg as real)
   // $funcArg is accessible here.
end

function Bar($myVal as real)
   // $funcArg is not accessible here.
end

function Baz($funcArg as real)
   // $funcArg is accessible here.
   // Note that this is a different $funcArg than the one declared for
   // the function Foo().
end

Arguments specified for a function cannot shadow variables with a larger scope. That is, the name of a function argument cannot be the same as the name of a controller global variable or a program global variable. In addition, variables declared within a function cannot shadow function arguments.

var $globalProgVar

program
   // ...
end

// The following function definition will produce a compiler error because
// the $globalProgVar name is already used by a variable with larger
// scope.
function Foo($globalProgVar as real)
   // ...
end

function Bar($funcArg as real)
   // The following variable declaration will produce a compiler error
   // because the $funcArg name is already used by a variable with larger
   // scope as a function argument.
   var $funcArg as integer
end

Variables can be declared within some conditional or iterative blocks (if, while, for, foreach, and repeat). These variables go out of scope at the end of the block in which they were declared.

if $iglobal[0] != 0
   var $localVar as real = $rglobal[0]

    if $localVar < 100.0
      // $localVar is accessible here.
   end
end

// $localVar is not accessible here since it went out of scope at the end
// of the larger if statement block.

Similar to variables declared as function arguments or variables declared within a function body, variables declared within conditional or iterative blocks cannot shadow variables declared with a larger scope.

if $iglobal[0] != 0
    var $localVar as real = $rglobal[0]

    while $localVar > 0.0
       // The following variable declaration will cause a compiler error
       // because the $localVar name is already used by a variable that
       // was declared with larger scope.
      var $localVar as integer
   end
end
User-Defined Local Variable Declaration Location

As mentioned earlier, variables can be declared outside of the program block. These variables are known as program global variables. All other variables must either be declared within the program block (assuming that it exists, see User-Defined Functions) or within a function body. Variables of this type can be declared anywhere that a statement can be placed. Variable scope rules must be followed, and variables must be declared before they are accessed in the program.

// Variables can be declared at the top of a program before any executable statements.
var $myInt as integer

Enable(X)
Home(X)

// Variables can also be declared after executable statements.
var $myReal as real
G1 X10
G1 X25
G1 X-10

// Variables can be used after they are declared.
$myReal = 3.14
$rglobal[0] = $myReal
// The following statement will cause a compiler error because $myVar is
// being used before it is declared.
$myVar = 3

var $myVar as integer

Variable Data Type Conversions

Numeric values can be converted from one type to another through assignments or by passing them as arguments to a function. The following example shows how a real can be converted to an integer. A real may be converted to an integer only if the real value can be represented by an integer. 1,180,591,620,717,411,303,424, or 270, is a whole number; however, it is too large to be able to be represented by an integer, and therefore causes a runtime error when its conversion is attempted.

var $rval as real = 3.50
var $ival as integer

// Causes a runtime error because 3.5 is not an integer.
$ival = $rval

// Okay because Trunc() produces an integer value (as a real).
$ival = Trunc($rval)

Any integer value can be converted to a real value without causing an error.

var $ival as integer
var $rval as real

$ival = 5

// Legal conversion from integer to real.
$rval = $ival

However, some very large integer values cannot be represented exactly as a real value, so some loss of precision may occur when performing such a conversion. The following is an example that shows precision loss occurring when converting a large integer value into a real.

var $ival as integer
var $rval as real

$ival = -9223372036854775808

// This conversion causes some precision loss to occur, making $rval
// contain a value of -9223372036854775800
$rval = $ival

Note that type conversions can only be used to convert from one numeric type to another numeric type. Non-numeric values cannot be converted to other types. For example, you cannot convert a string to an integer directly through an assignment (although there are API functions that will allow users to do this explicitly).

Type conversion may occur automatically when calling a function with arguments that have data types that are able to be converted to the data types that are expected by the function. For example, if a function accepts a single real argument, but an argument with the integer type is specified, the integer value will be implicitly converted to a real (and will cause an error if an invalid conversion occurs).

var $intVar as integer = 50

// Sin() expects a real but will accept an integer.
$rglobal[0] = Sin($intVar)

Similar type conversion occurs when a function expects an integer argument, but a real argument is specified. In this case, the type conversion is only allowed if the real value represents a value that can be represented by an integer as well. In the example below, the Foo() function expects an integer argument. The value 5.0 represents a valid integer, and can be passed to the function; however, the value 5.5 does not represent a valid integer, and therefore will cause a runtime error. Note that some of these errors can be caught at compilation time. Refer to Calling a Function for more details.

program
    var $rVal as real = 5.0
    $rVal = 5.0

    // This is okay because 5.0 can be converted to an integer without loss of data.
    Foo($rVal)

    $rVal = 5.5

    // This causes a runtime error because 5.5 does not represent an integer.
    Foo($rVal)
end

function Foo($arg as integer)
    // ...
end

Properties

Property Declaration

Property Names

In order to use a property, you must first declare it with a name. The name of a property must match the regular expression that follows.

$[A-Za-z_][A-Za-z0-9_]*
  • A property name must start with a dollar sign ($).
  • After the dollar sign ($), it must contain a letter or underscore.
  • After the first letter or underscore, it can contain zero or more letters, numbers, or underscores.

A property cannot share the same name as a variable declared within the same scope. Refer to Variables for more information.

Some names, such as $iglobal, $rglobal, and $sglobal, are reserved by the Standard Library in order to refer to controller global variables. These reserved names cannot be used for user-defined properties. See Controller Global Variables for more information.

Property names are case-sensitive. For example, $MYPROP and $myProp refer to different properties.

Property Declaration

The syntax for declaring a property is as follows.

property <VariableName> as <DataType>
   get
      <GetterStatements>
   end

    set
      <SetterStatements>
   end
end

The <DataType> can refer to either of the fundamental numeric types (integer or real), the fundamental axis type, the fundamental string type, the fundamental handle type, or the fundamental enum type.

A get property accessor is used to return a property value, and a set property accessor is used to set a property value. A property can be read-write (i.e., both a get and set accessor are specified), read-only (i.e., only a get accessor is specified), or write-only (i.e., only a set accessor is specified). A get accessor or a set accessor must be specified in a property. A property cannot have multiple get or set accessors.

Properties can have indices specified in their declaration. Indices act similarly to function arguments, and can be accessed within the get or set accessors.

Use the value keyword to get access to the user-specified value from within the set accessor.

Properties can be used like normal variables, with the exception that they cannot be passed as a function argument that was declared with the ref keyword.

var $myVar[10] as real

property $myProperty[$index as integer] as real
   get
     return $myVar[$index]
   end

   set
     $myVar[$index] = value
   end
end

program
   $myProperty[3] = 1.23
end

Next Topic: Expressions