Data Acquisition Toolbox

Recording and Retrieving Event Information

While the analog input object is running, certain information is automatically recorded in the EventLog property for some of the event types listed in the preceding section. EventLog is a structure that contains two fields: Type and Data. The Type field contains the event type. The Data field contains event-specific information. Events are recorded in the order in which they occur. The first EventLog entry reflects the first event recorded, the second EventLog entry reflects the second event recorded, and so on.

The event types recorded in EventLog for analog input objects, as well as the values for the Type and Data fields, are given below.

Table 5-12: Analog Input Event Information Stored in EventLog  

Event Type	Type Field Value	Data Field Value
Data missed	DataMissed	RelSample
Input overrange	OverRange	RelSample
		Channel
		OverRange
Run-time error	Error	AbsTime
		RelSample
		String
Start	Start	AbsTime
		RelSample
Stop	Stop	AbsTime
		RelSample
Trigger	Trigger	AbsTime
		RelSample
		Channel
		Trigger

Samples acquired events and timer events are not stored in EventLog.

Note    Unless a run-time error occurs, EventLog records a start event, trigger event, and stop event for each data acquisition session.

The Data field values are described below.

The AbsTime Field.   AbsTime is used by the run-time error, start, stop, and trigger events to indicate the absolute time the event occurred. The absolute time is returned using the MATLAB clock format.

day-month-year hour:minute:second

The Channel Field.   Channel is used by the input overrange event and the trigger event. For the input overrange event, Channel indicates the index number of the input channel that experienced an overrange signal. For the trigger event, Channel indicates the index number for each input channel serving as a trigger source.

The OverRange Field.   OverRange is used by the input overrange event, and can be On or Off. If OverRange is On, then the input channel experienced an overrange signal. If OverRange is Off, then the input channel no longer experienced an overrange signal.

The RelSample Field.   RelSample is used by all events stored in EventLog to indicate the sample number that was acquired when the event occurred. RelSample is 0 for the start event and for the first trigger event regardless of the trigger type. RelSample is NaN for any event that occurs before the first trigger executes.

The String Field.   String is used by the run-time error event to store the descriptive message that is generated when a run-time error occurs. This message is also displayed at the MATLAB command line.

The Trigger Field.   Trigger is used by the trigger event to indicate the trigger number. For example, if three trigger events occur, then Trigger is 3 for the third trigger event. The total number of triggers executed is given by the TriggersExecuted property.

Example: Retrieving Event Information

Suppose you want to examine the events logged for the example given by Example: Voice Activation Using a Software Trigger. You can do this by accessing the EventLog property.

• events = AIVoice.EventLog
  events = 
  3x1 struct array with fields:
      Type
      Data
  

By examining the contents of the Type field, you can list the events that occurred while AIVoice was running.

• {events.Type}
  ans = 
      'Start'    'Trigger'    'Stop'
  

To display information about the trigger event, you must access the Data field, which stores the absolute time the trigger occurred, the number of samples acquired when the trigger occurred, the index of the trigger channel, and the trigger number.

• trigdata = events(2).Data
  trigdata = 
        AbsTime: [1999 4 15 18 12 5.8615]
      RelSample: 0
        Channel: 1
        Trigger: 1
  

You can display a summary of the event log with the showdaqevents function. For example, to display a summary of the second event contained by the structure events:

• showdaqevents(events,2)
     2 Trigger#1           ( 18:12:05, 0 )      Channel: 1
  

Alternatively, you can display event summary information via the Workspace browser by right-clicking the device object and selecting Explore -> Show DAQ Events from the context menu.

Event Types

Creating and Executing Callback Functions