nctRead
Purpose
Reads samples from a CAN task initialized with Mode of nctModeInput. Samples are obtained from received CAN messages. For an overview of nctRead, refer to the Read section of Using the Channel API.
Format
| nctTypeStatus | nctRead(
|
Inputs
TaskRef
Task reference from the previous NI-CAN function. The task reference is originally returned from nctInitStart, nctInitialize, or nctCreateMessage.
The Mode initialized for the task must be NctModeInput.
NumberOfSamplesToRead
Specifies the number of samples to read for the task. For single-sample input, pass 1 to this parameter.
If the initialized SampleRate is zero, you must pass NumberOfSamplesToRead no greater than 1. SampleRate of zero means nctRead immediately returns a single sample from the most recent message(s) received.
Outputs
StartTime
Returns the time of the first CAN sample in SampleArray.
This parameter is optional. If you pass NULL for the StartTime parameter, the nctRead function proceeds normally.
If the initialized SampleRate 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 nctTypeTimestamp data type. The nctTypeTimestamp 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 nctTypeTimestamp 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 SampleArray.
This parameter is optional. If you pass NULL for the DeltaTime parameter, the nctRead function proceeds normally.
If the initialized SampleRate is greater than zero, the DeltaTime is determined by the sample timing.
If the initialized SampleRate is zero, the DeltaTime is zero, because the most recent sample is returned regardless of timing.
DeltaTime uses the nctTypeTimestamp 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 SampleRate s as slow as 0.4 Hz are still limited to a 32-bit 100 ns count.
SampleArray
Returns 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 nctInitStart with ChannelList of mych1,mych2,mych3, then call nctRead with NumberOfSamplesToRead of 10, SampleArray must be allocated as:
f64 SampleArray[3][10];
The order of channel entries in SampleArray is the same as the order in the original ChannelList.
If you need to determine the number of channels in the task after initialization, get the nctPropNumChannels property for the task reference.
If no message has been received since you started the task, the default value of the channel (nctPropChanDefaultValue) is returned in all entries of SampleArray.
NumberOfSamplesReturned
Indicates the number of samples returned for each channel in SampleArray. 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 ncStatusToString function of the Frame API to obtain a descriptive string for the return value. The ncStatusToString and ncGetHardwareInfo functions are the only Frame API functions that can be called within a Channel API application.
Description
When using Mode of nctModeInput, you can specify channels in ChannelList that span multiple messages.
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 nctRead 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 CAN channel over time, such as for comparison with other CAN or DAQ input channels. To avoid internal waiting, you can use nctGetProperty to obtain the nctPropSamplesPending property, and pass that as the NumberOfSamplesToRead parameter to nctRead.
If the initialized SampleRate is zero, nctRead 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 nctRead to determine whether a new message has been received since the previous call to nctRead (or nctStart). If no message has been received, the warning code CanWarnOldData 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 SampleArray.