Data Acquisition Toolbox

Creating and Executing Callback Functions

When using callback functions, you should be aware of these execution rules:

• Callback functions execute in the order in which they are issued.
• All callback functions except those associated with timer events are guaranteed to execute.
• Callback function execution might be delayed if the callback involves a CPU-intensive task such as updating a figure.

You specify the callback function to be executed when a specific event type occurs by including the name of the M-file as the value for the associated callback property. You can specify the callback function as a function handle or as a string cell array element. Function handles are described in the MATLAB function_handle reference pages. Note that if you are executing a local callback function from within an M-file, then you must specify the callback as a function handle.

For example, to execute the callback function mycallback for the analog input object ai every time 1000 samples are acquired

• ai.SamplesAcquiredFcnCount = 1000;
  ai.SamplesAcquiredFcn = @mycallback;
  

Alternatively, you can specify the callback function as a cell array.

• ai.SamplesAcquiredFcn = {'mycallback'};
  

M-file callback functions require at least two input arguments. The first argument is the device object. The second argument is a variable that captures the event information given in Table 5-12, Analog Input Event Information Stored in EventLog,. This event information pertains only to the event that caused the callback function to execute. The function header for mycallback is shown below.

• function mycallback(obj,event)
  

You pass additional parameters to the callback function by including both the callback function and the parameters as elements of a cell array. For example, to pass the MATLAB variable time to mycallback:

• time = datestr(now,0);
  ai.SamplesAcquiredFcnCount = 1000;
  ai.SamplesAcquiredFcn = {@mycallback,time};
  

Alternatively, you can specify mycallback as a string in the cell array.

• ai.SamplesAcquiredFcn = {'mycallback',time};
  

The corresponding function header is

• function mycallback(obj,event,time)
  

If you pass additional parameters to the callback function, then they must be included in the function header after the two required arguments.

Note    You can also specify the callback function as a string. In this case, the callback is evaluated in the MATLAB workspace and no requirements are made on the input arguments of the callback function.

Specifying a Toolbox Function as a Callback

In addition to specifying your own callback function, you can specify the start, stop, or trigger toolbox functions as callbacks. For example, to configure ai to stop running when an overrange condition occurs:

• ai.InputOverRangeFcn = @stop;
  

Recording and Retrieving Event Information

Examples: Using Callback Properties and Functions