ncReadObj.vi

Purpose

Read single frame from a CAN Object.

Format

Input

ObjHandle in is the object handle from the previous NI-CAN VI. The handle originates from the ncOpen VI.

Error in describes error conditions occurring before the VI executes. If an error has already occurred, the VI returns the value of the Error in cluster in Error out. status is True if an error occurred. If status is True, the VI does not perform any operations. code is the error code number identifying an error. A value of 0 means success. A negative value means error: VI did not execute the intended operation. A positive value means warning: VI executed intended operation, but an informational warning is returned. For a description of the code, wire the error cluster to a LabVIEW error-handling VI, such as the Simple Error Handler. source identifies the VI where the error occurred.

Output

	ObjHandle out is the object handle for the next NI-CAN VI.
	Data array returns 8 data bytes. The actual number of valid data bytes depends on the CAN Object configuration specified in ncConfigCANObj. If the CAN Object Communication Type specifies Transmit, data frames are transmitted, not received, so the ncReadObj VI has no effect. If the CAN Object Communication Type specifies Receive, Data always contains Data Length valid bytes, where Data Length was configured using ncConfigCANObj.
	Timestamp returns the absolute timestamp when the frame was placed into the read queue. The value matches the absolute timestamp format used within LabVIEW itself. LabVIEW time is a DBL representing the number of seconds elapsed since 12:00 a.m., Friday, January 1, 1904, Coordinated Universal Time (UTC). You can wire this Timestamp to LabVIEW time functions such as Seconds To Date/Time. You also can display the time in a numeric indicator of type DBL by using Format & Precision to select Time & Date format. Note  If you use Time & Date format, LabVIEW limits the Seconds Precision to 3, which shows only milliseconds. The NI-CAN timestamp provides microsecond precision. If you need to view microsecond precision, change the timestamp to decimal format, with six digits of precision.
	Error out describes error conditions. If the Error in cluster indicated an error, the Error out cluster contains the same information. Otherwise, Error out describes the error status of this VI. status is True if an error occurred. code is the error code number identifying an error. A value of 0 means success. A negative value means error: VI did not execute the intended operation. A positive value means warning: VI executed intended operation, but an informational warning is returned. For a description of the code, wire the error cluster to a LabVIEW error-handling VI, such as the Simple Error Handler. source identifies the VI where the error occurred.

Description

The ncReadObj VI is useful when you need to process one frame at a time. In order to read multiple frames at a time, such as for high-bandwidth networks, use the ncReadObjMult VI.

Since NI-CAN handles the read queue in the background, this VI does not wait for a new frame to arrive. To ensure that a new frame is available before calling ncReadObj, first wait for the Read Available state using ncWaitForState.vi.

When you call ncReadObj for an empty read queue (Read Available state false), the frame from the previous call to ncReadObj is returned again, along with the warning CanWarnOldData (status=F, code=3FF62009 hex).

When a frame arrives for a full read queue, NI-CAN discards the new frame, and the next call to ncReadObj returns the error CanErrOverflowRead (status=T, code= BFF62028 hex). If you detect this overflow, switch to using ncReadObjMult to read in a relatively tight loop (few milliseconds each read).

If you only need to obtain the most recent frame received for the CAN Object, you can set Read Queue Length to zero. When the read queue uses a zero length, only the most recent frame is stored, and overflow errors do not occur.

You can use the Network Interface and CAN Objects simultaneously. When a CAN frame arrives from the network, NI-CAN first checks the ArbitrationId for an open CAN Object. If no CAN Object applies, NI-CAN checks the comparators and masks of the Network Interface (including the Series 2 Filter Mode attributes). If the frame passes that filter, NI-CAN places the frame into the read queue of the Network Interface.