getdata (Data Acquisition Toolbox)

Data Acquisition Toolbox

Search Help Desk

getdata

Examples See Also

Return data, time, and event information to the MATLAB workspace for an analog input or digital I/O object.

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 existing analog input object.
`samples` (optional)	The number of samples to return. If `samples` is not specified, then the number of samples to return is given by the `SamplesPerTrigger` property.
`type` (optional)	Specifies the format of the returned data. If `type` is specified as '`native`', then data is returned in the native data format of the device. If `type` is not specified, samples are returned as doubles.
`data`	An m-by-n array containing acquired data where m is the number of samples and n is the number of channels or lines.
`time` (optional)	An m-by-1 array containing the time values for all m samples acquired. `time` = 0 corresponds to the time the first sample logged by the data acquisition engine. Time is measured continuously until the acquisition is stopped. Absolute times are available through the `TriggerTime` property.
`abstime`(optional)	The absolute time of the trigger.
`events` (optional)	A structure containing a list of events that have occurred up to the time of the `getdata` call. The possible events that can be returned are identical to those stored by the `EventLog` property.

Description

getdata is a blocking function that returns execution control to the MATLAB workspace when the requested number of samples are extracted from the data acquisition engine for each channel group member. Once the requested data is available, the SamplesAvailable property is 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 an amount of time given by the time it takes the engine to fill one data block plus the time specified by the Timeout property, then an error is returned.

data = getdata(obj) returns the number of samples specified by the SamplesPerTrigger property for each channel group member.

data = getdata(obj, samples) returns the specified number of data samples for each channel group member.

data = getdata(obj, 'native') returns data in the native format of the device for each channel group member. By default, data is returned as doubles.

[data, time] = getdata(...) returns data as sample-time pairs.

[data, time, abstime] = getdata(...) returns data as sample-time pairs and returns the absolute time of the trigger. The absolute time returned is identical to the first element of the TriggerTime vector. abstime is returned as a datenum value and can be converted to a string using datestr. Refer to "Calculating Time" for more information about absolute and relative time.

[data, time, abstime, events] = getdata(...) returns data as sample-time pairs, returns the absolute time of the trigger, and returns a structure containing a list of events that occurred during the time span of the getdata call. The possible events that can be returned are identical to those stored by the EventLog property. Refer to Chapter 7, "Property Reference" for more information about EventLog.

Note:
You can issue ^C (Control-C) while getdata is blocking. This will not stop the acquisition but will return control to MATLAB.

If getdata spans multiple triggers, a NaN is inserted into data and time between triggered sample sets thus increasing the length of data and time.

It is possible that data can be missed in the unlikely case that the engine cannot keep pace with the hardware device. You can monitor whether data is missed during the acquisition by specifying the name of an M-file for the DataMissedAction property.

Example

National Instruments

Suppose you create the analog input object ai for a National Instruments board and add hardware channels 0-3 to it. Additionally, a one second acquisition is configured with SampleRate set to 1000 and SamplesPerTrigger set to 1000. The object is then started.

ai = analoginput('nidaq', 1)
addchannel(ai, 0:3);
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 datenum value. and events is returned as a 3-by-1 structure array.

The three events stored correspond to the start event, trigger event, and stop event. For example, to return specific event information about the stop event, you must access the Type and Data subfields of events.

type = events(3).Type;
data = events(3).Data;