ncWriteObj.vi

Purpose

Write a single frame to a CAN Object.

Format

Input

	ObjHandle in is the object handle from the previous NI-CAN VI. The handle originates from the ncOpen VI.
	Data array specifies the data bytes (8 maximum).
	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.

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

You use ncWriteObj to place a frame into the CAN Object write queue. Since NI-CAN handles the write queue in the background, this VI does not wait for the frame to be transmitted on the network.

Once you have written frames, if you need to wait for the final ncWriteObj to be transmitted successfully, use ncWaitForState.vi with the Write Success state. The Write Success state sets when all frames of the write queue have been successfully transmitted. The Write Success state clears whenever you call ncWriteObj.

The Write Success state does not necessarily mean that all transmission has stopped for the CAN Object. For example, when the CAN Object Communication Type is Transmit Data Periodically, the Write Success state sets when the final frame in the write queue is transmitted, but the previous frame will be transmitted again once the Period expires.

Sporadic, recoverable errors on the network are handled automatically by the CAN protocol. As such, after ncWriteObj returns successfully, NI-CAN eventually transmits the frame on the network unless there is a serious network problem. Network problems such as missing or malfunctioning devices are often reported as the warning CanWarmComm (status=F, code=3FF6200B hex).

If the write queue is full, a call to ncWriteObj returns the error CanErrOverflowWrite (status=T, code= BFF62008 hex). In many cases, this error is recoverable, so you should not exit the application when it occurs. For example, if you want to transmit thousands of frames in succession (for example, large waveform transmitted periodically), the application can check for the error CanErrOverflowWrite, and when detected, simply wait a few milliseconds for some of the frames to transmit, then call ncWriteObj again. If the second call to ncWriteObj returns an error, that can be treated as an unrecoverable error (for example, no other device is ACKing the frames).

If you need to write a sequence of frames to the CAN Object, and ensure that each frame is transmitted, configure the Write Queue Length of the CAN Object to greater than zero. If you only need to transmit the most recent frame provided with ncWriteObj, you can set the Write Queue Length to zero.

If the CAN Object Communication Type specifies Receive behavior, the ncWriteObj VI can be used to transmit a remote frame. When using ncWriteObj to transmit a remote frame, the Data input can be left unwired.