Doing More With Analog Input (Data Acquisition Toolbox)

Data Acquisition Toolbox

Action Properties and Functions

When an event occurs, you can execute a related function known as an action function. Action functions are M-files that can perform essentially any task during your data acquisition session. For example, you can use action functions to process data, display data, or display a message. All events have an associated action property.

You can specify the action function to be executed when an event occurs by including the name of an M-file as the value for the associated action property.

set(obj, 'Property', 'actionfcn')

where:

Property is the action property that is automatically called when the associated event occurs.
actionfcn is the name of the M-file to be executed when the event occurs. actionfcn can be an M-file that you create or the start, stop, or trigger functions included with the toolbox.

You can also specify additional parameters to be passed as input arguments to the action function. In this case, the action function and additional parameters must be specified as elements of a cell array.

set(obj, 'Property', {'actionfcn', arg1, arg2 ,..., argn});

The additional parameters can be any data type since they are elements of a cell array.

Action functions require at least two arguments. The first argument must be a device object. The second argument is a variable that captures the event information contained by EventLog. This event information pertains only to the event that caused the action function to be executed. The action function prototype is shown below.

function actionfcn(obj, events)

If additional parameters are passed to the action function, then these arguments must be included after the two required arguments.

function actionfcn(obj, events, arg1, arg2 ,..., argn)

Note:
If additional input parameters are passed to an action function, you are not required to use varargin. Instead, you can explicitly include the parameters in the function prototype as shown above.

Example action functions are given later in this section. The analog input properties related to action functions are shown below

**Table 4-9: Action-Related Properties**
Property	Description
`DataMissedAction`	Specifies the M-file to be executed when the engine misses data
`RuntimeErrorAction`	Specifies the M-file to be executed when a runtime error occurs
`SamplesAcquiredAction`	Specifies the M-file to be executed when the number of samples specified by `SamplesAcquiredActionCount` is acquired
SamplesAcquiredActionCount	Sample-based frequency with which `SamplesAcquiredAction` is called
`StartAction`	Specifies the M-file to be executed just prior to the device and engine start
`StopAction`	Specifies the M-file to be executed just before the device and engine stop
`TimerAction`	Specifies the M-file to be executed when the time specified by `TimerPeriod` occurs
TimerPeriod	Time-based frequency with which `TimerAction` is called
`TriggerAction`	Specifies the M-file to be executed when a trigger occurs

When using action functions, you should be aware of these issues:

All action functions are executed in the order in which they are issued.
Depending on the action, all action functions except those related to timer events are quaranteed to execute.
Action function execution may be delayed if the action is CPU-intensive such as updating a figure.
Since a common application for time-based events is to display data, and displaying data is a CPU-intensive task, some of these events may not execute if your system is significantly slowed.

The relationship between events and action properties is described below for each event type.

Data-Available Event

A data-available event is generated immediately after a specified number of samples is acquired.

This event executes the M-file specified for the SamplesAcquiredAction property every time the number of samples specified by SamplesAcquiredActionCount is available. SamplesAcquiredAction should be used if you must access each sample that is acquired. For example, if you are processing all acquired data with an FFT, you can specify the M-file containing the FFT calculation with this property. Processing data this way may impact system performance.

Timer Event

A time-based event is periodically generated whenever a specified period of time has passed.

This event executes the M-file specified for the TimerAction property every time the number of seconds specified for the TimerPeriod property passes. Time is measured relative to when the hardware device starts running. The TimerAction property does not guarantee that all the data will be accessed. Therefore, you should use SamplesAcquiredAction if all acquired data must be accessed.

Note:
Since a common application for time-based events is to display data, and displaying data is a CPU-intensive task, some of these events may not execute if your system is significantly slowed.

Start and Stop Events

Start and stop events are described together since these two events occur for all data acquisition sessions. A start event is generated immediately after the start command is issued, while the stop event is generated immediately after the stop command is issued.

The start event executes the M-file specified for the StartAction property prior to starting the hardware and engine. Once this M-file has completed execution, the Running property is set to On.

The stop event executes the M-file specified for the StopAction property. Under most circumstances, the M-file is not guaranteed to complete execution until sometime after the hardware and engine stop and the Running property is set to Off.

Trigger Event

A trigger event is generated immediately after a trigger is issued.

This event executes the M-file specified for the TriggerAction property. Under most circumstances, the M-file is not guaranteed to complete execution until sometime after Logging is set to On by the engine.

Runtime Error Event

A runtime error event is generated immediately after a runtime error occurs. Runtime errors include hardware errors and timeouts. Runtime errors do not include configuration errors.

This event executes the M-file specified for the RuntimeErrorAction property.

Input Over-Range Event

An input over-range event is generated immediately after an over-range condition is detected for any channel group member. An over-range condition occurs when a signal exceeds the range specified for the InputRange property.

This event executes the M-file specified for the InputOverRangeAction property.

Note:
Over-range detection occurs only when a value is specified for InputOverRangeAction and the analog input object is running.

Data-Missed Event

A data-missed event is generated immediately after acquired data is missed. In most cases, data is missed because the engine cannot keep up with the rate of acquisition.

This event executes the M-file specified for the DataMissedAction property. By default, the stop command is issued.

[ Previous | Help Desk | Next ]