mcDAQReadEx

Purpose

Reads samples from a Measurement task. Samples are obtained from received CAN messages. Scaled and raw (unscaled) Measurements are acquired.

Format

Input

DAQRefNum

DAQRefNum is the task reference from the previous Measurement task function. The task reference is originally returned from mcDAQInitializeEx, and then reused by subsequent Measurement task functions.

NumberOfSamplesToRead

Specifies the number of samples to read for the task. For single-sample input, pass 1 to this parameter.

If the initialized sample rate is zero, you must pass NumberOfSamplesToRead no greater than 1. A SampleRate of zero means mcDAQReadEx immediately returns a single sample from the most recent message(s) received.

Output

StartTime

Returns the time of the first CAN sample in SampleArray (or in RawSampleArray if no scaled Measurements are defined). This parameter is optional. If you pass NULL for the StartTime parameter, the mcDAQReadEx function proceeds normally. If the initialized sample rate is greater than zero, the StartTime is determined by the sample timing. If the initialized SampleRate is zero, the StartTime is zero, because the most recent sample is returned regardless of timing.

StartTime uses the mcTypeTimestamp data type. The mcTypeTimestamp data type is a 64-bit unsigned integer 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 mcTypeTimestamp is compatible with Win32 FILETIME, you can pass it into the Win32 FileTimeToLocalFileTime function to convert it to the local time zone, 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 on Win32 time types and functions, refer to the Microsoft Win32 documentation.

DeltaTime

Returns the time between each sample in (Raw)SampleArray. This parameter is optional. If you pass NULL for the DeltaTime parameter, the mcDAQReadEx function proceeds normally. If the initialized sample rate is greater than zero, the DeltaTime is determined by the sample timing. If the initialized sample rate is zero, the DeltaTime is zero, because the most recent sample is returned regardless of timing. DeltaTime uses the mcTypeTimestamp data type. The delta time is a relative 64-bit counter of 100 ns intervals, not an absolute UTC time. Nevertheless, you can use functions like the Win32 FileTimeToSystemTime function to convert to the Win32 SYSTEMTIME type. In addition, you can use the 32-bit LowPart of DeltaTime to obtain a simple 100 ns count, because values for SampleRate as slow as 0.4 Hz are still limited to a 32-bit 100 ns count.

SampleArray

Returns a 2D array, one array for each scaled channel initialized in the task. The array of each channel must have NumberOfSamplesToRead entries allocated. The order of channel entries in SampleArray is the same as the order in the original channel list. If you need to determine the number of channels in the task after initialization, get the mcPropDAQ_NumChannels property for the task reference. If no message has been received since you started the task, 0 is returned as default value for of the channel in all entries of SampleArray.

RawSampleArray

Returns a 2D array, one array for each raw channel initialized in the task. The array of each channel must have NumberOfSamplesToRead entries allocated. The order of channel entries in RawSampleArray is the same as the order in the original channel list. If you need to determine the number of channels in the task after initialization, get the mcPropDAQ_NumRawChannels property for the task reference. If no message has been received since you started the task, 0 is returned as default value for of the channel in all entries of RawSampleArray.

NumberOfSamplesReturned

NumberOfSamplesReturned indicates the number of samples returned for each channel in SampleArray and RawSampleArray. 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

If the initialized SampleRate is greater than zero, this function returns an array of samples, each of which indicates the value of the CAN channel at a specific point in time. The mcDAQReadEx function waits for these samples to arrive in time before returning. In other words, the SampleRate specifies a virtual clock that copies the most recent value from CAN messages for each sample time. The changes in sample values from message to message enable you to view the channel over time, such as for comparison with other CAN or DAQ input channels. To avoid internal waiting, you can use mcGetProperty to obtain nctPropSamplesPending property, and pass that as the NumberOfSamplesToRead parameter to mcDAQReadEx.

If the initialized SampleRate is zero, mcDAQReadEx immediately returns a single sample from the most recent message(s) received. For this single-point read, you must pass the NumberOfSamplesToRead parameter as 1. You can use the return value of mcDAQReadEx to determine whether a new message has been received since the previous call to mcDAQReadEx (or mcDAQStartStop). If no message has been received, the warning code mcWarningOldData is returned. If a new message has been received, the success code 0 is returned. If no message has been received since you started the task, the default value of the channel (nctPropChanDefaultValue) is returned in all entries of (Raw)SampleArray.