| Data Acquisition Toolbox | Search Help Desk |
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. You can also specify additional parameters to be passed as input arguments to the action function. The action function and additional parameters must be specified as elements of a cell array.set(obj, 'Property, {'actionfcn', arg1, arg2 ,..., argn});
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.
arg1, arg2 ,&, argn are the optional input arguments that are passed to actionfcn. These arguments can be any data type since they are elements of a cell array.
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:
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. Data-Output Event
A data-output event is generated immediately after a predefined number of samples are output. This event executes the M-file specified for theSamplesOutputAction property every time the number of samples specified by SamplesOutputActionCount is output.
Timer Event
A time-based event is generated immediately after a predefined period of time has passed. This event executes the M-file specified for theTimerAction property every time the number of seconds specified for the TimerPeriod property passes. Time is measured relative to when the hardware device starts running.
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 thestart 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 theTriggerAction property. Under most circumstances, the M-file is not guaranteed to complete execution until sometime after the trigger occurs and Sending 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 theRuntimeErrorAction property.
Out-of-Data Event
An out-of-data event is generated immediately after an out-of-data condition is detected for any channel group member. An out-of-data condition occurs when the data stream has been interrupted before being completely output to theOutOfDataAction property.