mcDAQReadTimestamped

Purpose

Reads timestamped scaled samples from a DAQ task initialized with the selected mode of mcDAQModeDAQListTimeStamped.

Format

Input

DAQRefNum

DAQRefNum is the task reference that links to the selected measurement task. This reference is originally returned from mcDAQInitialize or mcDAQListInitialize.

NumberOfSamplesToRead

Specifies the number of samples to read for the task.

Output

TimestampArray

Returns the time at which each corresponding sample in SampleArray was received in a CAN message. The timestamps are returned as an array of arrays (2D array), one array for each channel initialized in the task. The array of each channel must have NumberOfSamplesToRead entries allocated. For example, if you call mcDAQInitialize with MeasurementNames of myDAQ1,myDAQ2, and then call mcDAQReadTimestamped with NumberOfSamplesToRead of 20, both TimestampArray and SampleArray must be allocated as:

i64 mcTypeTimestamp TimestampArray[2][20];
double SampleArray[2][20];

The order of channel entries in TimestampArray is the same as the order in the original DAQ channel list. To determine the number of channels in the DAQ task after initialization, get the mcPropDAQ_NumChannels property for the DAQ task reference. Each timestamp in TimestampArray uses the i64 data type compatible with the Microsoft Win32 FILETIME type. This absolute time is kept in a Coordinated Universal Time (UTC) format. UTC time is loosely defined as the current date and time of day in Greenwich, England. Microsoft defines its UTC time (FILETIME) as a 64-bit counter of 100 ns intervals that have elapsed since 12:00 a.m., January 1, 1601. Because the timestamp is compatible with Win32 FILETIME, you can pass it into the Win32 FileTimeToLocalFileTime function to convert it to the local timezone, and then pass the resulting local time to the Win32 FileTimeToSystemTime function to convert to the Win32 SYSTEMTIME type. SYSTEMTIME is a struct with fields for year, month, day, and so on. For more information about Win32 time types and functions, refer to the Microsoft Win32 documentation.

SampleArray

SampleArray returns the scaled sample value(s) for each received CAN message. The samples are returned as an array of arrays (a 2D array), one array for each scaled channel initialized in the DAQ task. The array of each channel must have NumberOfSamplesToRead entries allocated. You must allocate SampleArray exactly as TimestampArray, and the order of channel entries is the same for both.

NumberOfSamplesReturned

Indicates the number of samples returned for each channel in SampleArray, and the number of timestamps returned for each channel in TimestampArray. The remaining entries are left unchanged (zero).

Return Value

The return value indicates the status of the function call as a signed 32-bit integer. Zero means the function executed successfully. A negative value specifies an error, which means the function did not perform the expected behavior. A positive value specifies a warning, which means the function performed as expected, but a condition arose that may require attention.

Use the mcStatusToString function of the ECU M&C API to obtain a descriptive string for the return value.

Description

Each returned sample corresponds to a received CAN message for the measurement channels initialized in the DAQ channel list. For each sample, mcDAQReadTimestamped returns the sample value and a timestamp that indicates when the message was received. Because the timing of samples returned by mcDAQReadTimestamped is determined by when the message is received, the initialized sample rate is not used.

The function waits until NumberOfSamplesToRead messages have been received. The number of samples returned is indicated in the NumberOfSamplesReturned output, up to a maximum of NumberOfSamplesToRead messages. If no new message has been received, NumberOfSamplesReturned is 0, and the return value indicates success. To avoid blocking a mcDAQReadTimestamped function, read the mcPropDAQ_SamplesPending property to check the number of collected sample points before calling mcDAQReadTimestamped.