On this API page:

Controller Variables

You are reading our Automation1 API documentation for the .NET programming language.

The Basics

In the .NET API, Controller Variables lets you get and set controller global variables, controller task variables on a task, and the values of Industrial Ethernet mappings on an Automation1 controller. Refer to the sections that follow for more information.

Global Variables

In the .NET API, Global Variables lets you get and set global variables on an Automation1 controller. You can access controller global variables from all tasks on the controller. Thus you can use them to share information between tasks or between the controller and your custom application.

There are three types of global variables. The global integer array ($iglobal in AeroScript), the global real array ($rglobal in AeroScript), and the global string array ($sglobal in AeroScript).

AeroScript integers are 64-bit. They are represented in .NET by the long data type. AeroScript reals are double-precision floating-point numbers. They are represented in .NET by the double data type.

The strings in the AeroScript global string array have a maximum length of 255 bytes. ASCII characters consume one byte. But the use of multi-byte characters, such as Unicode characters, results in multiple bytes of the string being consumed for individual characters.

How to Use

In the .NET API, Global Variables is part of the Controller.Runtime property. For all the APIs that operate under this property, the Automation1 controller must be running before you can do work with global variables. For more information about this property, see the Controller page.

You can get a single global variable with one of the methods that follow:

Copy

long globalInteger = controller.Runtime.Variables.Global.GetInteger(int globalIntegerIndex);
double globalReal = controller.Runtime.Variables.Global.GetReal(int globalRealIndex);
string globalString = controller.Runtime.Variables.Global.GetString(int globalStringIndex);

You can also get two or more global variables at the same time from the same contiguous segment in the global variable array with one of the methods that follow:

Copy

long[] globalIntegers = controller.Runtime.Variables.Global.GetIntegers(int startingGlobalIntegerIndex, int numberOfVariables);
double[] globalReals = controller.Runtime.Variables.Global.GetReals(int startingGlobalRealIndex, int numberOfVariables);
string[] globalStrings = controller.Runtime.Variables.Global.GetStrings(int startingGlobalStringIndex, int numberOfVariables);

You can set a single global variable with one of the methods that follow:

Copy

controller.Runtime.Variables.Global.SetInteger(int globalIntegerIndex, long integerValue);
controller.Runtime.Variables.Global.SetReal(int globalRealIndex, double realValue);
controller.Runtime.Variables.Global.SetString(int globalStringIndex, string stringValue);

You can also set two or more global variables at the same time for the same contiguous segment in the global variable array with one of the methods that follow:

Copy

controller.Runtime.Variables.Global.SetIntegers(int startingGlobalIntegerIndex, long[] integerValues);
controller.Runtime.Variables.Global.SetReals(int startingGlobalRealIndex, double[] realValues);
controller.Runtime.Variables.Global.SetStrings(int startingGlobalStringIndex, string[] stringValues);

Task Variables

In the .NET API, Task Variables lets you get and set task variables on a task on an Automation1 controller. You can access task variables from AeroScript and every API but only from the same task. You can use task variables to share information between iterations of a program running on the same task.

There are three types of task variables, and every task on an Automation1 controller has a set of these task variable arrays:

Task integer array ($itask in AeroScript)
Task real array ($rtask in AeroScript)
Task string array ($stask in AeroScript)

AeroScript integers are 64-bit.They are represented by the long data type. AeroScript reals are double-precision floating points. They are represented by the double data type.

The strings in an AeroScript task string array have a maximum length of 255 bytes. ASCII characters use just one byte. But, multi-byte characters, such as Unicode characters, use multiple bytes of the string.

The TaskIntegers Parameter, TaskReals Parameter, and TaskStrings Parameter specify the number of variables that are available to the task for which this parameter is set.

How to Use

In the .NET API, Task Variables is part of the Controller.Runtime property. The Automation1 controller must be running before you can do work with task variables. Refer to Controller for more information.

You can get a single task variable with one of the methods that follow:

Copy

long taskInteger = controller.Runtime.Variables.Task.GetInteger(string taskName, int taskIntegerArrayIndex);
double taskReal = controller.Runtime.Variables.Task.GetReal(string taskName, int taskRealArrayIndex);
string taskString = controller.Runtime.Variables.Task.GetString(string taskName, int taskStringArrayIndex);

You can also get more than one task variable at the same time from the same contiguous segment in the task variable array with one of the methods that follow.

Copy

long[] taskIntegerArray = controller.Runtime.Variables.Task.GetIntegers(string taskName, int taskIntegerArrayStartingIndex, int numberOfVariables);
double[] taskRealArray = controller.Runtime.Variables.Task.GetReals(string taskName, int taskRealArrayStartingIndex, int numberOfVariables);
string[] taskStringArray = controller.Runtime.Variables.Task.GetStrings(string taskName, int taskStringArrayStartingIndex, int numberOfVariables);

You can set a single task variable with one of the methods that follow.

Copy

controller.Runtime.Variables.Task.SetInteger(string taskName, int taskIntegerArrayIndex, long integerValue);
controller.Runtime.Variables.Task.SetReal(string taskName, int taskRealArrayIndex, double realValue);
controller.Runtime.Variables.Task.SetString(string taskName, int taskStringArrayIndex, string stringValue);

You can also set more than one task variable at the same time for the same contiguous segment in the task variable array with one of the methods that follow.

Copy

controller.Runtime.Variables.Task.SetIntegers(string taskName, int taskIntegerArrayStartingIndex, long[] integerValues);
controller.Runtime.Variables.Task.SetReals(string taskName, int taskRealArrayStartingIndex, double[] realValues);
controller.Runtime.Variables.Task.SetStrings(string taskName, int taskStringArrayStartingIndex, string[] stringValues);

For all of the method examples, you can specify the task on which to get or set with task name or task index.

Industrial Ethernet Variables

In the .NET API, Industrial Ethernet Variables lets you get and set the values of Industrial Ethernet mappings on an Automation1 controller. Automation1 exposes the memory blocks of Industrial Ethernet protocols, such as Modbus and EtherCAT, through Industrial Ethernet mappings. These Industrial Ethernet mappings let you map memory regions used by Industrial Ethernet protocols to arbitrary controller data types. For more information, see Modbus TCP/IP Overview and EtherCAT Overview.

Industrial Ethernet mappings can be AeroScript integers or reals. AeroScript integers are 64-bit. They are represented in .NET by the long data type. AeroScript reals are double-precision floating-point numbers. They are represented in .NET by the double data type.

How to Use

In the .NET API, Industrial Ethernet Variables is part of the Controller.Runtime property. For all the APIs that operate under this property, the Automation1 controller must be running before you can do work with Industrial Ethernet mappings. For more information about this property, see the Controller page.

You can get and set the value of a single Industrial Ethernet mapping by using the methods that follow:

Copy

long integerValue = controller.Runtime.Variables.IndustrialEthernet.GetInteger(string industrialEthernetMappingName);
double realValue = controller.Runtime.Variables.IndustrialEthernet.GetReal(string industrialEthernetMappingName);
controller.Runtime.Variables.IndustrialEthernet.SetInteger(string industrialEthernetMappingName, long value);
controller.Runtime.Variables.IndustrialEthernet.SetReal(string industrialEthernetMappingName, double value);

You can get and set the value of an index of a single Industrial Ethernet mapping array by using the methods that follow:

Copy

long integerValue = controller.Runtime.Variables.IndustrialEthernet.GetInteger(string industrialEthernetMappingName, int industrialEthernetMappingArrayIndex);
double realValue = controller.Runtime.Variables.IndustrialEthernet.GetReal(string industrialEthernetMappingName, int industrialEthernetMappingArrayIndex);
controller.Runtime.Variables.IndustrialEthernet.SetInteger(string industrialEthernetMappingName, int industrialEthernetMappingArrayIndex, long value);
controller.Runtime.Variables.IndustrialEthernet.SetReal(string industrialEthernetMappingName, int industrialEthernetMappingArrayIndex, double value);

You can also get and set a contiguous segment of values within a single Industrial Ethernet mapping array by using the methods that follow:

Copy

long[] integerValues = controller.Runtime.Variables.IndustrialEthernet.GetIntegers(string industrialEthernetMappingName, int startingIndustrialEthernetMappingArrayIndex, int numberOfVariables);
double[] realValues = controller.Runtime.Variables.IndustrialEthernet.GetReals(string industrialEthernetMappingName, int startingIndustrialEthernetMappingArrayIndex, int numberOfVariables);
controller.Runtime.Variables.IndustrialEthernet.SetIntegers(string industrialEthernetMappingName, int startingIndustrialEthernetMappingArrayIndex, long[] values);
controller.Runtime.Variables.IndustrialEthernet.SetReals(string industrialEthernetMappingName, int startingIndustrialEthernetMappingArrayIndex, double[] values);

Thread Safety

All the methods that operate under the Controller.Runtime.Variables.Global and Controller.Runtime.Variables.Task property are thread safe. You can call them from two or more threads without interference.

Full Reference

For more information about the methods that are available for Global Variables, Task Variables, and Industrial Ethernet Variables, refer to the lists that follow.

Controller.Runtime.Variables.Global Methods

Controller.Runtime.Variables.Task Methods

Controller.Runtime.Variables.IndustrialEthernet Methods