minute read

On this API page:

Controller Variables

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

The Basics

In the C 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 C 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. This makes them useful when you share information between tasks or between the controller and your custom application.

There are three types of global variables:

  • Global integer array ($iglobal in AeroScript)
  • Global real array ($rglobal in AeroScript)
  • Global string array ($sglobal in AeroScript)

AeroScript integers are 64-bit. They are represented in C by the int64_t data type. AeroScript reals are double-precision floating-point numbers, which are represented in C by the double data type.

In the AeroScript global string array, the strings 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

Global Variables is part of the controller runtime. Thus the Automation1 controller must be running before you do work with global variables. For more information, see the Controller page.

You can get global variables with one of the functions that follow:

Copy 
bool Automation1_Variables_GetGlobalIntegers(Automation1Controller controller, int32_t startingGlobalIntegerIndex, int64_t* integerValuesOut, int32_t integerValuesOutMaxLength);
bool Automation1_Variables_GetGlobalReals(Automation1Controller controller, int32_t startingGlobalRealIndex, double* realValuesOut, int32_t realValuesOutMaxLength);
bool Automation1_Variables_GetGlobalString(Automation1Controller controller, int32_t startingGlobalStringIndex, char* stringValueOut, int32_t stringValueMaxLength);

You can set global variables with one of the functions that follow:

Copy 
bool Automation1_Variables_SetGlobalIntegers(Automation1Controller controller, int32_t startingGlobalIntegerIndex, int64_t* integerValues, int32_t integerValuesLength);
bool Automation1_Variables_SetGlobalReals(Automation1Controller controller, int32_t startingGlobalRealIndex, double* realValues, int32_t realValuesLength);
bool Automation1_Variables_SetGlobalString(Automation1Controller controller, int32_t startingGlobalStringIndex, const char* stringValue);

Task Variables

In the C 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 int64_t 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

Task Variables is part of the controller runtime, so the Automation1 controller must be running before you do work with task variables. For more information about this property, refer to the Controller page.

You can get task variables with one of the functions that follow.

Copy 
bool Automation1_Variables_GetTaskIntegers(Automation1Controller controller, int32_t taskIndex, int32_t taskIntegerArrayStartingIndex, int64_t* integerValuesOut, int32_t integerValuesOutMaxLength);
bool Automation1_Variables_GetTaskReals(Automation1Controller controller, int32_t taskIndex, int32_t taskRealArrayStartingIndex, int64_t* realValuesOut, int32_t realValuesOutMaxLength);
bool Automation1_Variables_GetTaskString(Automation1Controller controller, int32_t taskIndex, int32_t taskStringArrayIndex, int64_t* stringValueOut, int32_t stringValueMaxLength);

You can set task variables with one of the functions that follow.

Copy 
bool Automation1_Variables_SetTaskIntegers(Automation1Controller controller, int32_t taskIndex, int32_t taskIntegerArrayStartingIndex, int64_t* integerValues, int32_t integerValuesLength);
bool Automation1_Variables_SetTaskReals(Automation1Controller controller, int32_t taskIndex, int32_t taskRealArrayStartingIndex, double* realValues, int32_t realValuesLength);
bool Automation1_Variables_SetTaskString(Automation1Controller controller, int32_t taskIndex, int32_t taskStringArrayIndex, const char* stringValue);

Industrial Ethernet Variables

In the C API, Industrial Ethernet Varaibles lets you get and set the values of Industrial Ethernet mappings on an Automation1 controller. Automation1 exposes the memory block 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 C by the int64_t data type. AeroScript reals are double-precision floating-point numbers. They are represented in C by the double data type.

How to Use

In the C API, Industrial Ethernet Variables is part of the controller runtime. Thus the Automation1 controller must be running before you do work with Industrial Ethernet mappings. For more information about this property, see the Controller page.

You can get the value of a single Industrial Ethernet mapping or get the values of a contiguous segment of an Industrial Ethernet mapping array by using the functions that follow:

Copy 
bool Automation1_Variables_GetIndustrialEthernetInteger(Automation1Controller controller, const char* industrialEthernetMappingName, int32_t* integerValueOut);
bool Automation1_Variables_GetIndustrialEthernetIntegerArray(Automation1Controller controller, const char* industrialEthernetMappingArrayName, int32_t industrialEthernetMappingStartingArrayIndex, int32_t* integerValuesOut, int32_t integerValuesOutMaxLength);
bool Automation1_Variables_GetIndustrialEthernetReal(Automation1Controller controller, const char* industrialEthernetMappingName, double* realValueOut);
bool Automation1_Variables_GetIndustrialEthernetRealArray(Automation1Controller controller, const char* industrialEthernetMappingArrayName, int32_t industrialEthernetMappingStartingArrayIndex, double* realValuesOut, int32_t realValuesOutMaxLength);

You can set the value of a single Industrial Ethernet mapping or set the values of a contiguous segment of an Industrial Ethernet mapping array by using the functions that follow:

Copy 
bool Automation1_Variables_SetIndustrialEthernetInteger(Automation1Controller controller, const char* industrialEthernetMappingName, int32_t integerValue);
bool Automation1_Variables_SetIndustrialEthernetIntegerArray(Automation1Controller controller, const char* industrialEthernetMappingArrayName, int32_t industrialEthernetMappingStartingArrayIndex, int32_t* integerValues, int32_t integerValuesLength);
bool Automation1_Variables_SetIndustrialEthernetReal(Automation1Controller controller, const char* industrialEthernetMappingName, double realValue);
bool Automation1_Variables_SetIndustrialEthernetRealArray(Automation1Controller controller, const char* industrialEthernetMappingArrayName, int32_t industrialEthernetMappingStartingArrayIndex, double* realValues, int32_t realValuesLength);

Thread Safety

The Automation1_Variables_ functions are thread safe. You can call them from two or more threads without interference.

Full Reference

For more information about the functions that are available for Global Variables, Task Variables, and Industrial Ethernet Variables, refer to the list that follows.

Functions

Gets the values of a contiguous segment of integer controller global variables ($iglobal in AeroScript), starting at the specified global integer array index and with the specified number of variables to get. The values are returned as AeroScript integer values, which are 64-bit integers. You can access these controller global variables from each task on the controller and from each API.

controller (In): The controller from which to get the variables.

startingGlobalIntegerIndex (In): The global integer array index that starts the segment of global variables to get.

integerValuesOut (Out): The out array that is populated with integer values that were retrieved from the controller. Use this argument only if the function call was successful. This argument must have memory preallocated before you pass it into this function.

integerValuesOutMaxLength (In): The maximum number of variables to get from the controller and copy to the integerValuesOut function argument. This number must not be greater than the length of the integerValuesOut array.

Returns: True if the function got the variable values successfully. False if the function did not get the variable values. See the Automation1_GetLastError() and Automation1_GetLastErrorMessage() functions for more information. You can find information about these functions in the Errors and Error Handling section of C API Guidelines.

Sets the values of a contiguous segment of integer controller global variables ($iglobal in AeroScript), starting at the specified global integer array index and with the specified number of variables to set. The values to set are AeroScript integer values, which are 64-bit integers. You can access these controller global variables from each task on the controller and from each API.

controller (In): The controller on which to set the variables.

startingGlobalIntegerIndex (In): The global integer array index that starts the segment of global variables to set.

integerValues (In): The array of AeroScript integer values (which are 64-bit long integers) to set on the controller.

integerValuesLength (In): The length of the integerValues function argument.

Returns: True if the function set the variable values successfully. False if the function did not set the variable values. See the Automation1_GetLastError() and Automation1_GetLastErrorMessage() functions for more information. You can find information about these functions in the Errors and Error Handling section of C API Guidelines.

Gets the values of a contiguous segment of real controller global variables ($rglobal in AeroScript), starting at the specified global real array index and with the specified number of variables to get. The values are returned as AeroScript real values, which are double-precision floating-point numbers. You can access these controller global variables from each task on the controller and from each API.

controller (In): The controller from which to get the variables.

startingGlobalRealIndex (In): The global real array index that starts the segment of global variables to get.

realValuesOut (Out): The out array that is populated with real values that were retrieved from the controller. Use this argument only if the function call was successful. This argument must have memory preallocated before you pass it into this function.

realValuesOutMaxLength (In): The maximum number of variables to get from the controller and copy to the realValuesOut function argument. This number must not be greater than the length of the realValuesOut array.

Returns: True if the function got the variable values successfully. False if the function did not get the variable values. See the Automation1_GetLastError() and Automation1_GetLastErrorMessage() functions for more information. You can find information about these functions in the Errors and Error Handling section of C API Guidelines.

Sets the values of a contiguous segment of real controller global variables ($rglobal in AeroScript), starting at the specified global real array index and with the specified number of variables to set. The values to set are AeroScript real values, which are double-precision floating-point numbers. You can access these controller global variables from each task on the controller and from each API.

controller (In): The controller on which to set the variables.

startingGlobalRealIndex (In): The global real array index that starts the segment of global variables to set.

realValues (In): The array of AeroScript real values, which are double-precision floating-point numbers, to set on the controller.

realValuesLength (In): The length of the realValues function argument.

Returns: True if the function set the variable values successfully. False if the function did not set the variable values. See the Automation1_GetLastError() and Automation1_GetLastErrorMessage() functions for more information. You can find information about these functions in the Errors and Error Handling section of C API Guidelines.

Gets the value of a single string controller global variable ($sglobal in AeroScript), at the specified global string array index. You can access these controller global variables from each task on the controller and from each API. Each string global variable has a capacity of 256 characters, which includes the null terminator.

controller (In): The controller from which to get the variable.

startingGlobalStringIndex (In): The global string array index of which to get the value.

stringValueOut (Out): The null-terminated string value of the specified string controller global variable. Use this argument only if the function call was successful. This argument must have memory preallocated before you pass it into this function.

stringValueMaxLength (In): The maximum number of characters to copy to the stringValueOut function argument. This number must not be greater than the length of the stringValueOut array.

Returns: True if the function got the variable value successfully. False if the function did not get the variable value. See the Automation1_GetLastError() and Automation1_GetLastErrorMessage() functions for more information. You can find information about these functions in the Errors and Error Handling section of C API Guidelines.

Sets the value of a single string controller global variable ($sglobal in AeroScript), at the specified global string array index. You can access these controller global variables from each task on the controller and from each API. Each string global variable has a capacity of 256 characters, which includes the null terminator.

controller (In): The controller on which to set the variables.

startingGlobalStringIndex (In): The global string array index for which to set the value.

stringValue (In): The null-terminated string value to set for the string controller global variable.

Returns: True if the function set the variable value successfully. False if the function did not set the variable value. See the Automation1_GetLastError() and Automation1_GetLastErrorMessage() functions for more information. You can find information about these functions in the Errors and Error Handling section of C API Guidelines.

Gets the values of a contiguous segment of integer task variables ($itask in AeroScript), starting at the specified task integer array index and with the specified number of variables to get. The values are returned as AeroScript integer values (which are 64-bit long integers). These task variables are accessible from every API and can be used to communicate data between iterations of a program running on the same task. They are not accessible from other tasks.

controller (In): The controller to get the task variables from.

taskIndex (In): The index of the task to get the integer task variables from.

taskIntegerArrayStartingIndex (In): The task integer array index that starts the segment of task variables to get.

integerValuesOut (Out): The out array that will be populated with integer values that were retrieved from the task. Only use this if the function call was successful. This argument must have memory preallocated before passing it into this function.

integerValuesOutMaxLength (In): The maximum number of variables to get from the task and to copy to the integerValuesOut function argument. This must not be greater than the length of the integerValuesOut array.

Returns: Returns true if the function successfully got the variable values, otherwise it returns false. See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information.

Sets the values of a contiguous segment of integer task variables ($itask in AeroScript), starting at the specified task integer array index and with the specified number of variables to set. The values to set are AeroScript integer values (which are 64-bit long integers). These task variables are accessible from every API and can be used to communicate data between iterations of a program running on the same task. They are not accessible from other tasks.

controller (In): The controller to set the variables on.

taskIndex (In): The index of the task on which to set the integer task variables.

taskIntegerArrayStartingIndex (In): The task integer array index that starts the segment of task variables to set.

integerValues (In): The array of AeroScript integer values (which are 64-bit long integers) to set on the task.

integerValuesLength (In): The length of the integerValues function argument.

Returns: Returns true if the function successfully set the variable values, otherwise it returns false. See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information.

Gets the values of a contiguous segment of real task variables ($rtask in AeroScript), starting at the specified task real array index and with the specified number of variables to get. The values are returned as AeroScript real values (which are double precision floating point numbers). These task variables are accessible from every API and can be used to communicate data between iterations of a program running on the same task. They are not accessible from other tasks.

controller (In): The controller to get the task variables from.

taskIndex (In): The index of the task to get the real task variables from.

taskRealArrayStartingIndex (In): The task real array index that starts the segment of task variables to get.

realValuesOut (Out): The out array that will be populated with real values that were retrieved from the task. Only use this if the function call was successful. This argument must have memory preallocated before passing it into this function.

realValuesOutMaxLength (In): The maximum number of variables to get from the task and to copy to the realValuesOut function argument. This must not be greater than the length of the realValuesOut array.

Returns: Returns true if the function successfully got the variable values, otherwise it returns false. See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information.

Sets the values of a contiguous segment of real task variables ($rtask in AeroScript), starting at the specified task real array index and with the specified number of variables to set. The values to set are AeroScript real values (which are double precision floating point numbers). These task variables are accessible from every API and can be used to communicate data between iterations of a program running on the same task. They are not accessible from other tasks.

controller (In): The controller to set the task variables on.

taskIndex (In): The index of the task on which to set the real task variables.

taskRealArrayStartingIndex (In): The task real array index that starts the segment of task variables to set.

realValues (In): The array of AeroScript real values (which are double precision floating point numbers) to set on the task.

realValuesLength (In): The length of the realValues function argument.

Returns: Returns true if the function successfully set the variable values, otherwise it returns false. See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information.

Gets the value of a single string task variable ($stask in AeroScript), at the specified task string array index. These task variables are accessible from every API and can be used to communicate data between iterations of a program running on the same task. They are not accessible from other tasks. Each string task variable has a capacity of 256 characters including the null terminator.

controller (In): The controller to get the task variable from.

taskIndex (In): The index of the task to get the string task variable from.

taskStringArrayIndex (In): The task string array index to get the value of.

stringValueOut (Out): The null-terminated string value of the specified string task variable. Only use this if the function call was successful. This argument must have memory preallocated before passing it into this function.

stringValueMaxLength (In): The maximum number of characters to copy to the stringValueOut function argument. This must not be greater than the length of the stringValueOut array.

Returns: Returns true if the function successfully got the task variable value, otherwise it returns false. See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information.

Sets the value of a single string task variable ($stask in AeroScript), at the specified task string array index. These task variables are accessible from every API and can be used to communicate data between iterations of a program running on the same task. They are not accessible from other tasks. Each string task variable has a capacity of 256 characters including the null terminator.

controller (In): The controller to set the task variables on.

The (In): index of the task on which to set the string task variable.

taskStringArrayIndex (In): The task string array index to set the value of.

stringValue (In): The null-terminated string value to set for the string task variable.

Returns: Returns true if the function successfully set the variable value, otherwise it returns false. See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information.

Gets the values of an integer Industrial Ethernet mapping.

controller (In): The controller from which to get the Industrial Ethernet mapping.

industrialEthernetMappingName (In): The name of the Industrial Ethernet mapping to get.

integerValueOut (Out): The integer value that was retrieved from the controller. Use this value only if the function call was successful. This argument must have memory preallocated before you pass it into this function.

Returns: True if the function successfully got the Industrial Ethernet mapping. False if the function did not get the Industrial Ethernet mapping. See the Automation1_GetLastError() and Automation1_GetLastErrorMessage() functions for more information. You can find information about these functions in the Errors and Error Handling section of C API Guidelines.

Gets the values of a contiguous segment of an Industrial Ethernet mapping array, starting at the specified Industrial Ethernet mapping array index and with the specified number of integers to get.

controller (In): The controller from which to get the Industrial Ethernet mapping array.

industrialEthernetMappingArrayName (In): The name of the Industrial Ethernet mapping array to get.

industrialEthernetMappingStartingArrayIndex (In): The Industrial Ethernet mapping array index that starts the segment of integers to get.

integerValuesOut (Out): The out array that will be populated with integer values that were retrieved from the controller. Use this array only if the function call was successful. This argument must have memory preallocated before you pass it into this function.

integerValuesOutMaxLength (In): The maximum number of integers to get from the Industrial Ethernet mapping array and to copy to the integerValuesOut function argument. This number must not be greater than the length of the integerValuesOut array.

Returns: True if the function successfully got the Industrial Ethernet mapping array. False if the function did not get the Industrial Ethernet mapping array. See the Automation1_GetLastError() and Automation1_GetLastErrorMessage() functions for more information. You can find information about these functions in the Errors and Error Handling section of C API Guidelines.

Sets the value of an integer Industrial Ethernet mapping.

controller (In): The controller on which to set the Industrial Ethernet mapping.

industrialEthernetMappingName (In): The name of the Industrial Ethernet mapping to set.

integerValue (In): The integer value to set on the controller.

executionTaskIndex (In): The task to use to set the Industrial Ethernet mapping.

Returns: True if the function successfully set the Industrial Ethernet mapping. False if the function did not set the Industrial Ethernet mapping. See the Automation1_GetLastError() and Automation1_GetLastErrorMessage() functions for more information. You can find information about these functions in the Errors and Error Handling section of C API Guidelines.

Sets the values of a contiguous segment of an integer Industrial Ethernet mapping array, starting at the specified Industrial Ethernet mapping array index and with the specified number of integers to set.

controller (In): The controller on which to set the Industrial Ethernet mapping array.

industrialEthernetMappingArrayName (In): The name of the Industrial Ethernet mapping array to set.

industrialEthernetMappingStartingArrayIndex (In): The Industrial Ethernet mapping array index that starts the segment of integers to set.

integerValues (In): The array of integer values to set on the controller.

integerValuesLength (In): The length of the integerValues function argument.

executionTaskIndex (In): The task to use to set the Industrial Ethernet mapping array.

Returns: True if the function successfully set the Industrial Ethernet mapping array. False if the function did not set the Industrial Ethernet mapping array. See the Automation1_GetLastError() and Automation1_GetLastErrorMessage() functions for more information. You can find information about these functions in the Errors and Error Handling section of C API Guidelines.

Gets the values of an integer Industrial Ethernet mapping.

controller (In): The controller from which to get the Industrial Ethernet mapping.

industrialEthernetMappingName (In): The name of the Industrial Ethernet mapping to get.

realValueOut (Out): The real value that was retrieved from the controller. Use this value only if the function call was successful. This argument must have memory preallocated before you pass it into this function.

Returns: True if the function successfully got the Industrial Ethernet mapping. False if the function did not get the Industrial Ethernet mapping. See the Automation1_GetLastError() and Automation1_GetLastErrorMessage() functions for more information. You can find information about these functions in the Errors and Error Handling section of C API Guidelines.

Gets the values of a contiguous segment of an Industrial Ethernet mapping array, starting at the specified Industrial Ethernet mapping array index and with the specified number of reals to get.

controller (In): The controller from which to get the Industrial Ethernet mapping array.

industrialEthernetMappingArrayName (In): The name of the Industrial Ethernet mapping array to get.

industrialEthernetMappingStartingArrayIndex (In): The Industrial Ethernet mapping array index that starts the segment of reals to get.

realValuesOut (Out): The out array that will be populated with real values that were retrieved from the controller. Use this array only if the function call was successful. This argument must have memory preallocated before you pass it into this function.

realValuesOutMaxLength (In): The maximum number of reals to get from the Industrial Ethernet mapping array and to copy to the realValuesOut function argument. This number must not be greater than the length of the integerValuesOut array.

Returns: True if the function successfully got the Industrial Ethernet mapping array. False if the function did not get the Industrial Ethernet mapping array. See the Automation1_GetLastError() and Automation1_GetLastErrorMessage() functions for more information. You can find information about these functions in the Errors and Error Handling section of C API Guidelines.

Sets the value of a real Industrial Ethernet mapping.

controller (In): The controller on which to set the Industrial Ethernet mapping.

industrialEthernetMappingName (In): The name of the Industrial Ethernet mapping to set.

integerValue (In): The real value to set on the controller.

executionTaskIndex (In): The task to use to set the Industrial Ethernet mapping.

Returns: True if the function successfully set the Industrial Ethernet mapping. False if the function did not set the Industrial Ethernet mapping. See the Automation1_GetLastError() and Automation1_GetLastErrorMessage() functions for more information. You can find information about these functions in the Errors and Error Handling section of C API Guidelines.

Sets the values of a contiguous segment of a real Industrial Ethernet mapping array, starting at the specified Industrial Ethernet mapping array index and with the specified number of reals to set.

controller (In): The controller on which to set the Industrial Ethernet mapping array.

industrialEthernetMappingArrayName (In): The name of the Industrial Ethernet mapping array to set.

industrialEthernetMappingStartingArrayIndex (In): The Industrial Ethernet mapping array index that starts the segment of reals to set.

realValues (In): The array of real values to set on the controller.

realValuesLength (In): The length of the realValues function argument.

executionTaskIndex (In): The task to use to set the Industrial Ethernet mapping array.

Returns: True if the function successfully set the Industrial Ethernet mapping array. False if the function did not set the Industrial Ethernet mapping array. See the Automation1_GetLastError() and Automation1_GetLastErrorMessage() functions for more information. You can find information about these functions in the Errors and Error Handling section of C API Guidelines.