ncReadObjMult.vi

Purpose

Read multiple frames 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.
	RequestedDataBufSize specifies the maximum number of frames desired. For most applications, this will be the same as the configured Read Queue Length in order to empty the read queue with each call to ncReadObjMult.
	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.
	ActualDataSize (Frames) specifies the number of frames returned in Data. This number is less than or equal to RequestedDataBufSize.
	Data returns an array of clusters. Each cluster in the array uses the typedef CanDataTimed.ctl with the following elements: 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 Data is ignored. For this Communication Type, the ncReadObjMult 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.
	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

Since NI-CAN handles the read queue in the background, this VI does not wait for new frames to arrive. To ensure that new frames are available before calling ncReadObjMult, first wait for the Read Available state or Read Multiple state using ncWaitForState.vi.

When you call ncReadObjMult for an empty read queue (Read Available state false), Error out returns success (status=F, code=0), and ActualDataSize (Frames) returns 0.

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

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.