Data Acquisition Toolbox

getdata

Extract data, time, and event information from the data acquisition engine

Syntax

• data = getdata(obj)
  data = getdata(obj,samples)
  data = getdata(obj,'type')
  data = getdata(obj,samples,'type')
  [data,time] = getdata(...)
  [data,time,abstime] = getdata(...)
  [data,time,abstime,events] = getdata(...)
  

Arguments

obj	An analog input object.
samples	The number of samples to extract. If samples is not specified, the number of samples extracted is given by the SamplesPerTrigger property.
'type'	Specifies the format of the extracted data as double (the default) or as native.
data	An m-by-n array where m is the number of samples extracted and n is the number of channels contained by obj.
time	An m-by-1 array of relative time values where m is the number of samples extracted. Relative time is measured with respect to the first sample logged by the engine.
abstime	The absolute time of the first trigger returned as a clock vector. This value is identical to the value stored by the InitialTriggerTime property.
events	A structure containing a list of events that occurred up to the time of the getdata call.

Description

data = getdata(obj) extracts the number of samples specified by the SamplesPerTrigger property for each channel contained by obj. data is an m-by-n array where m is the number of samples extracted and n is the number of channels.

data = getdata(obj,samples) extracts the number of samples specified by samples for each channel contained by obj.

data = getdata(obj,'type') extracts data in the specified format. If type is specified as native, the data is returned in the native data format of the device. If type is specified as double (the default), the data is returned as doubles.

data = getdata(obj,samples,'type') extracts the number of samples specified by samples in the format specified by type for each channel contained by obj.

[data,time] = getdata(...) returns data as sample-time pairs. time is an m-by-1 array of relative time values where m is the number of samples returned. Relative time is measured with respect to the first sample logged by the engine.

[data,time,abstime] = getdata(...) extracts data as sample-time pairs and returns the absolute time of the trigger. The absolute time is returned as a clock vector and is identical to the value stored by the InitialTriggerTime property.

[data,time,abstime,events] = getdata(...) extracts data as sample-time pairs, returns the absolute time of the trigger, and returns a structure containing a list of events that occurred up to the getdata call. The possible events that can be returned are identical to those stored by the EventLog property.

Remarks

More About getdata

• In most circumstances, getdata returns all requested data and does not miss any samples. In the unlikely event that the engine cannot keep pace with the hardware device, it is possible that data is missed. If data is missed, the DataMissedFcn property is called and the device object is stopped.
• getdata is a blocking function because it returns execution control to the MATLAB workspace only when the requested number of samples are extracted from the engine for each channel group member.
• You can issue ^C (Control+C) while getdata is blocking. This will not stop the acquisition but will return control to MATLAB.
• The amount of data that you can extract from the engine is given by the SamplesAvailable property.

More About Extracting Data From the Engine

• Once the requested data is extracted from the engine, the SamplesAvailable property value is automatically reduced by the number of samples returned.
• If the requested number of samples is greater than the samples to be acquired, then an error is returned.
• If the requested data is not returned in the expected amount of time, an error is returned. The expected time to return data is given by the time it takes the engine to fill one data block plus the time specified by the Timeout property.
• If multiple triggers are included in a single getdata call, a NaN is inserted into the returned data and time arrays and the absolute time returned is given by the first trigger.
• MATLAB supports math operations only for the double data type. Therefore, to use math functions on native data, you must convert it to doubles.

Example

Create the analog input object ai for a National Instruments board and add hardware channels 0-3 to it.

• ai = analoginput('nidaq',1);
  addchannel(ai,0:3);
  

Configure a one second acquisition with SampleRate set to 1000 samples per second and SamplesPerTrigger set to 1000 samples per trigger.

• set(ai,'SampleRate',1000)
  set(ai,'SamplesPerTrigger',1000)
  start(ai)
  

The following getdata command blocks execution control until all sample-time pairs, the absolute time of the trigger, and any events that occurred during the getdata call are returned.

• [data,time,abstime,events] = getdata(ai);
  

data is returned as a 1000-by-4 array of doubles, time is returned as a 1000-by-1 vector of relative times, abstime is returned as a clock vector, and events is returned as a 3-by-1 structure array.

The three events returned are the start event, the trigger event, and the stop event. To return specific event information about the stop event, you must access the Type and Data fields.

• EventType = events(3).Type;
  EventData = events(3).Data;
  

See Also

Functions

flushdata, getsample, peekdata

Properties

DataMissedFcn, EventLog, SamplesAvailable, SamplesPerTrigger, Timeout

get

getsample