nctWrite
Purpose
Writes samples to a CAN task initialized as NctModeOutput. Samples are placed into transmitted CAN messages. For an overview of nctWrite, refer to the Write section of Using the Channel API.
Format
| nctTypeStatus | nctWrite(
|
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 NctModeOutput.
NumberOfSamplesToWrite
Specifies the number of samples to write for the task. For single-sample output, pass 1 to this parameter.
SampleArray
Provides an array of arrays (2D array), one array for each channel initialized in the task. The array of each channel must have NumberOfSamplesToWrite samples.
For example, if you call nctInitStart with ChannelList of mych1,mych2,mych3, then call nctWrite with NumberOfSamplesToWrite of 10, SampleArray must be allocated as:
f64 SampleArray[3][10];
You must provide a valid sample value in each entry of the arrays.
The order of channel entries in SampleArray is the same as the order in the original ChannelList.
To determine the number of channels in the task after initialization, get the nctPropNumChannels property for the task reference.
Outputs
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
The associated ChannelList determines the messages transmitted by nctWrite. If all channels are contained in a single message, only that message is transmitted. If a few channels are contained in one message, and the remaining channels are contained in a second message, then two messages are transmitted.
If the initialized SampleRate is greater than zero, the task transmits associated CAN messages periodically at the specified rate. The first nctWrite transmits associated messages immediately using the first sample in the array of each channel, and then begins a periodic timer at the specified rate. Each subsequent transmission of messages is based on the timer, and uses the next sample in the array of each channel. After the final sample in the array of each channel has been transmitted, subsequent behavior is determined by the nctPropBehavAfterFinalOut property. The default nctPropBehavAfterFinalOut behavior is to retransmit the final sample each period until nctWrite is called again.
If the initialized SampleRate is zero, the task transmits associated messages immediately for each entry in the array of each channel, with as little delay as possible between messages. After the message for the final sample is transmitted, no further transmissions occur until nctWrite is called again, regardless of the nctPropBehavAfterFinalOut property.
Because all channels of a message are transmitted on the network as a unit, nctWrite enforces the following rules:
- You cannot write the same message in more than one NctModeOutput task.
- You can write more than one message in a single NctModeOutput task.
- You can write a subset of channels for a message in a single NctModeOutput task. For channels that are not included in the task, the channel default value (nctPropChanDefaultValue) is transmitted in the CAN message.
For many applications, the most straightforward technique is to assign a single NctModeOutput task for each message you want to transmit. In each task, include all channels of that message in the ChannelList. This ensures you can provide new samples for the entire message with each nctWrite.