Callback Functions

Callback functions are special functions that execute in the non-real-time part of the controller. For example, if the controller is running in a real-time operating system, it cannot access files directly on the PC. Thus, when the controller encounters a File access function, it pauses the AeroScript program and triggers the execution of the function in the non-real-time environment.

There is a full list of callback functions in the Callback Functions table at the end of this page.

Callback Function Execution

The steps that follow show the order in which the controller executes a callback function:

The controller pauses the AeroScript program that is currently running.
The controller generates a callback interrupt.
The communication service, which runs in the non-real-time environment, gets the callback interrupt and sends a signal to the controller that it received the callback interrupt.

IMPORTANT: If this step does not occur in a sufficient quantity of time, the controller will return a CallbackNotRegistered error. When this error occurs, there is no application registered to handle the callback.

A host application retrieves the callback data and does the applicable function.
When the callback function is completed, the host application tells the controller to continue.
The controller continues to execute the AeroScript program.

Custom Callback

Use custom callbacks to pass execution to an external process that will be handled by the .NET, C, or Python API. These APIs expose the ability to handle callbacks of a specific callback identification number.

When the custom callback function is called from AeroScript, program execution waits for any registered .NET, C, or Python callback handler to execute. These handlers read the specified input arguments and, if applicable, they do operations based on those arguments.

For Example

The handlers can pass some data as an argument to a file or send data over the network.

Execution of the AeroScript program continues when the callback handler returns in the .NET, C, or Python API. The callback handler can return doubles, integers, strings, or any combination of these values to the AeroScript program.

For information about how to use the Callback() AeroScript function with the .NET, C, or Python API, see the Handle AeroScript Callbacks section of .NET Tasks, C Tasks, or Python Tasks.

function Callback($id as integer, $integerInputs[] as integer, $realInputs[] as real, $stringInputs[] as string, ref $integerOutputs[] as integer, ref $realOutputs[] as real, ref $stringOutputs[] as string)

Triggers a custom callback to be handled by an external process. If there is not an external process connected to your controller that can handle this callback, then an error will occur. If you need to do a check, call the CallbackIsRegistered() function.

Arguments

$id The id number of the callback. This value must be between 0 and 65535.

$integerInputs An array of integers to be provided to the external callback function. The length of the integer array must not exceed 100.

$realInputs An array of reals to be provided to the external callback function. The length of the real array must not exceed 100.

$stringInputs An array of strings to be provided to the external callback function. The length of the string array must not exceed 100.

ref $integerOutputs An array of integers returned from the external callback function. The length of the integer array will not exceed 100.

ref $realOutputs An array of reals returned from the external callback function. The length of the real array will not exceed 100.

ref $stringOutputs An array of strings returned from the external callback function. The length of the string array will not exceed 100.

Before you execute the callback, you can see if it has a registered handler. To do this, use the CallbackIsRegistered() function.

function CallbackIsRegistered($id as integer) as integer

Returns if the specified custom callback is registered by an application.

Arguments

$id The id number of the custom callback.

Returns

If the custom callback is registered by an application, returns 1. Otherwise, returns 0.

Callback Functions

The table that follows includes a full list of callback functions.

Table: Callback Functions

Function Name	Description
`Callback()`	Raises a custom callback that the .NET, C, or Python API handles. See the Handle AeroScript Callbacks section of .NET Tasks, C Tasks, or Python Tasks for more information. To see if this function is registered, use the `CallbackIsRegistered()` function.
`ProgramLoad()`	Loads a program to the specified task. See Program Control for more information.
`ProgramRun()`	Runs a program on the specified task. See Program Control for more information.
`DateTimeGet()`	Gets the current time on the controller. See DateTime Functions for more information.
`DateTimeExtract*()` Functions	Extracts the specified time component from the given epoch time. See DateTime Functions for more information.
`FileOpenBinary()` / `FileOpenText()`	Opens a file for binary or text I/O. See Open and Close a Handle for more information.
`FileClose()`	Closes the specified file. See Open and Close a Handle for more information.
`FileSetByteOffset()`	Sets the current byte offset for reading and writing in the specified file. See File Position for more information.
`FileGetByteOffset()`	Gets the current byte offset for reading and writing in the specified file. See File Position for more information.
`FileIsEndOfFile()`	Returns whether the current reading offset is at the end of the file. See File Position for more information.
`FileSize()`	Returns the size of the specified file. See File Position for more information.
`FileTextReadLine()` / `FileTextReadString()`	Reads a line or string from a text file. See Text Files for more information.
`FileTextWriteString()`	Writes a string to a text file. See Text Files for more information.
`FileBinaryRead*()` Functions	Returns data from a binary file interpreted as the specified data type. See Reading Binary Files for more information.
`FileBinaryWrite*()` Functions	Converts data to a specified data type and writes it to the specified file. See Writing Binary Files for more information.
`DirectoryCount()`	Returns the number of subdirectories within the specified directory. See Directories for more information.
`DirectoryFileCopy()`	Copies the specified file. See Directories for more information.
`DirectoryFileCount()`	Returns the number of files within the specified directory. See Directories for more information.
`DirectoryFileDelete()`	Deletes the specified file. See Directories for more information.
`DirectoryFileExists()`	Returns whether the specified file exists. See Directories for more information.
`DirectoryFileGetFileName()`	Returns the name of the file with the specified index within the specified directory. See Directories for more information.
`DirectoryFileMove()`	Moves the specified file. See Directories for more information.
`DirectoryGetName()`	Returns the name of the subdirectory with the specified index within the specified directory. See Directories for more information.
`DataCollectionAddAxisSignal()` / `DataCollectionAddTaskSignal()` / `DataCollectionAddSystemSignal()`	Adds an axis, task, or system status signal to the data collection configuration. See Configure Axis Signals, Configure Task Signals, and Configure System Signals for more information.
`DataCollectionReset()`	Resets the data collection configuration. See Configure Data Collection for more information.
`DataCollectionStart()`	Starts real-time data collection. See Start and Stop Data Collection for more information.
`DataCollectionStop()`	Stops real-time data collection. See Start and Stop Data Collection for more information.
`AppDataCollectionAddAxisSignal()` / `AppDataCollectionAddTaskSignal()` / `AppDataCollectionAddSystemSignal()`	Adds an axis, task, or system status signal to the data collection configuration. See Configure Axis Signals, Configure Task Signals, and Configure System Signals for more information. To see if the function you are using is registered, use the applicable function that follows: `AppDataCollectionAddAxisSignalIsRegistered()` `AppDataCollectionAddTaskSignalIsRegistered()` `AppDataCollectionAddSystemSignalIsRegistered()` .
`AppDataCollectionAddIndustrialEthernetMappingSignal()`	Adds an Industrial Ethernet mapping signal to the application's data collection configuration. See Configure Industrial Ethernet Signals for more information. To see if this function is registered, use the `AppDataCollectionAddIndustrialEthernetMappingSignalIsRegistered()` function.
`AppDataCollectionReset()`	Resets the data collection configuration. See Configure Data Collection for more information. To see if this function is registered, use the `AppDataCollectionResetIsRegistered()` function.
`AppDataCollectionConfigure()`	Configures application data collection. See Configure the Number of Samples and Sample Time for Data Collection for more information. To see if this function is registered, use the `AppDataCollectionConfigureIsRegistered()` function.
`AppDataCollectionAutoSaveOn()` / `AppDataCollectionAutoSaveOff()`	Enables or disables the operation that automatically saves data collected through the `AppDataCollectionSnapshot()` function. See Configure Auto-Save for Snapshots for more information. To see if this function is registered, use the `AppDataCollectionAutoSaveOn()` or `AppDataCollectionAutoSaveOff()` function.
`CalibrationLoad()`	Loads and activates the specified axis calibration file or galvo power correction file. See Calibration Functions for more information.
`CalibrationUnload()`	Deactivates and unloads the calibration for the specified calibration type. See Calibration Functions for more information.
`AppIndicatorOn()`	Turns on all indicators with the specified ID. See `AppIndicatorOn()` for more information. To see if this function is registered, use the `AppIndicatorOnIsRegistered()` function.
`AppIndicatorOff()`	Turns off all indicators with the specified ID. See `AppIndicatorOff()` for more information. To see if this function is registered, use the `AppIndicatorOffIsRegistered()` function.
`AppMessageBox()`	Shows a message box that gives you information with a specified severity. See Message Box for more information. To see if this function is registered, use the `AppMessageBoxIsRegistered()` function.
`AppMessageDisplay()`	Shows the specified message. See Message Notifications for more information. To see if this function is registered, use the `AppMessageDisplayIsRegistered()` function.
`AppMessageDisplayDismiss()`	Clears all of the application message notifications. See Message Notifications for more information. To see if this function is registered, use the `AppMessageDisplayDismissIsRegistered()` function.
`AppMessageFileOpen()`	Shows a dialog box that you can use to select a file to open. See File Open for more information. To see if this function is registered, use the `AppMessageFileOpenIsRegistered()` function.
`AppMessageFileSave()`	Shows a dialog box that you can use to select a file to save. See File Save for more information. To see if this function is registered, use the `AppMessageFileSaveIsRegistered()` function.
`AppMessageInputBox()`	Shows a message box that retrieves input data. See Message Input for more information. To see if this function is registered, use the `AppMessageInputBoxIsRegistered()` function.
`AppMessageMenu()`	Shows a list of items that you can select. See Message Menu for more information. To see if this function is registered, use the `AppMessageMenuIsRegistered()` function.
`AppFrequencyResponsePerformStabilityAnalysis()`	Does a stability analysis on a saved frequency response file and returns the stability metrics. See Stability Analysis for more information. To see if this function is registered, use the `AppFrequencyResponsePerformStabilityAnalysisIsRegistered()` function.
`AppFrequencyResponseTriggerMultisinePlus()`	Triggers a MultisinePlus frequency response transmission on the specified axis. See Frequency Response for more information. To see if this function is registered, use the `AppFrequencyResponseTriggerMultisinePlusIsRegistered()` function.
`AppFrequencyResponseTriggerSinusoid()`	Triggers a Sinusoidal frequency response transmission on the specified axis. See Frequency Response for more information. To see if this function is registered, use the `AppFrequencyResponseTriggerSinusoidIsRegistered()` function.
`AppFrequencyResponseTriggerWhiteNoise()`	Triggers a White Noise frequency response transmission on the specified axis. See Frequency Response for more information. To see if this function is registered, use the `AppFrequencyResponseTriggerWhiteNoiseIsRegistered()` function.
`AppFrequencyResponseTriggerMultisine()`	Triggers a Multisine frequency response transmission on the specified axis. See Frequency Response for more information. To see if this function is registered, use the `AppFrequencyResponseTriggerMultisineIsRegistered()` function.

Related Help Pages

About the .NET API

About the C API

About the Python API