ncWriteMult
Purpose
Write multiple frames to a CAN or LIN Network Interface Object.
Format
| NCTYPE_STATUS | ncWriteMult(
|
Input
ObjHandle
Object handle.
DataSize
Size of the data in bytes.
DataPtr
Pointer to the data to be written to the CAN Network Interface The data consists of an array of structures, each of type NCTYPE_CAN_STRUCT.
Within each structure, FrameType indicates the frame type. The frame type determines the interpretation of the remaining fields. For a description of each frame type, refer to Frame Types section of this function reference.
The maximum number of structures you can provide to each ncWriteMult is 512. For more information, refer to Writing Large Numbers of Frames.
Output
Return Value
Status of the function call, returned as a signed 32-bit integer. Zero means the function executed successfully. Negative specifies an error, meaning the function did not perform expected behavior. Positive specifies a warning, meaning the function performed as expected, but a condition arose that might require attention. For more information, refer to ncStatusToString.
Description
You use ncWriteMult to place one or more frames into the Network Interface write queue. This function does not wait for the frames to be transmitted on the network. This function is not supported for CAN Objects.
Timestamped Transmit
In addition to supporting multiple frames, this function is preferable to ncWrite in that it supports timestamped frames. To enable timestamped transmit, use ncSetAttribute to set the NC_ATTR_TRANSMIT_MODE (Transmit Mode) attribute to Timestamped Transmit mode (1).
In Timestamped Transmit mode, NI-CAN times the transmission according to the difference in timestamps between consecutive frames. For example, if every frame provided to ncWriteMult increments by 10 milliseconds, the frames will be transmitted with a 10 millisecond gap.
If the timestamp of one frame is less than the timestamp of the preceding frame, the timeline is reset, and both frames transmit back to back. For example, if you write a frame with relative timestamp 30 ms followed by a frame with timestamp 15 ms, the two frames will be transmitted back to back. This sort of behavior can occur when you transmit a logfile of timestamped frames repeatedly, because on the second traversal of the logfile, the timestamp of the first frame will be less than the timestamp of the last frame.
The first frame that you provide to ncWriteMult always transmits immediately, regardless of its timestamp. If you need to delay transmission of first frame after start, you can write a Delay frame or Start Trigger frame as described in Frame Types section of this function reference.
Timestamped Transmit applies only to Series 1 and Series 2 interfaces.
847x CAN and LIN products do not support timestamped transmit. These products ignore the timestamp provided in the cluster for ncWriteMult. If you use ncWriteMult to write header and full frame types out of the USB LIN acting as master, then the frames will be transmitted together as closely as possible. If you use ncWriteMult to write response frame types to the LIN interface acting as slave, then the frames will be loaded into the response table as quickly as possible.
Immediate Transmit
The default value for the NC_ATTR_TRANSMIT_MODE (Transmit Mode) attribute is Immediate Transmit mode (0). You can also use ncSetAttribute to set the NC_ATTR_TRANSMIT_MODE attribute to Immediate Transmit mode.
In Immediate Transmit mode, NI-CAN ignores the timestamp in each frame, and transmits the frames as fast as possible. This behavior is equivalent to the ncWrite function, except that you can write multiple frames for transmission in quick succession.
Writing Large Numbers of Frames
Although NI-CAN provides a large write queue to store frames pending transmission, writing timestamped frames from a logfile with thousands of frames can eventually fill this queue.
When the Network Interface write queue cannot hold all frames provided, ncWriteMult returns an overflow error. When this overflow error is returned, none of the frames provided in the array referenced by DataPtr have been written. This enables your application to try the same array again at a later time.
To determine when adequate space is available in the write queue to retry ncWriteMult after an overflow, you can use ncWaitForState with the NC_ST_WRITE_MULT (Write Multiple) state. The NC_ST_WRITE_MULT state will transition from false to true when space is available for at least 512 frames. Since you must limit the array passed to ncWriteMult to 512 frames or less, the NC_ST_WRITE_MULT state indicates that a retry will succeed.
Another technique to recover from a write queue overflow is to use ncGetAttribute with the NC_ATTR_WRITE_ENTRIES_FREE (Write Entries Free) attribute. Although this technique requires you to call ncGetAttribute periodically until the desired number of frame entries is available, it avoids the need to determine a proper Timeout for ncWaitForState. When the time difference between frames varies from milliseconds to seconds, it may be difficult to determine how long to wait for entries to become available.
After writing a sequence of timestamped frames with ncWriteMult, you cannot close the Network Interface, because you must wait for the last timestamped frame to transmit onto the network. You can wait for the final transmit to complete using ncWaitForState with the NC_ST_WRITE_SUCCESS (Write Success) state. You can also use ncGetAttribute with the NC_ATTR_WRITE_PENDING (Write Entries Pending) attribute to query periodically, which provides the option of aborting the timestamped transmission by closing the Network Interface.
Frame Types
Within each structure (type NCTYPE_CAN_STRUCT) of the array referenced by DataPtr, FrameType indicates the frame type. The frame type determines the interpretation of the remaining fields. The following tables describe the fields of the structure for each value of FrameType.
To determine if your hardware supports one of the following frame types for this function, refer to Frame Types for CAN and LIN Hardware.
Structure with FrameType value NC_FRMTYPE_DATA (0): CAN Data Frame
| Field Name | Data Type | Description |
|---|---|---|
| FrameType | NCTYPE_UINT8 | Value NC_FRMTYPE_DATA (0) specifies a CAN data frame.
The CAN data frame transfers data on the network. |
| ArbitrationId | NCTYPE_CAN_ARBID | Specifies the arbitration ID to transmit in the CAN data frame. A standard ID (11-bit) is specified by default. In order to specify an extended ID (29-bit), OR in the bit mask NC_FL_CAN_ARBID_XTD (20000000 hex). |
| DataLength | NCTYPE_UINT8 | Specifies the number of bytes in the Data array to transmit in the CAN data frame. |
| Data | Array of 8, NCTYPE_UINT8 | Data bytes to transmit in the CAN data frame. |
| Timestamp | NCTYPE_ABS_TIME | If the NC_ATTR_TRANSMIT_MODE (Transmit Mode) attribute is Immediate Transmit (default), this field is ignored, and CAN frames transmit as quickly as possible.
If the NC_ATTR_TRANSMIT_MODE attribute is Timestamped Transmit (1), this field specifies a timestamp. The timestamp is used to time transmission of CAN frames as described in Timestamped Transmit. The timestamp data type NCTYPE_ABS_TIME is a 64-bit unsigned integer in 100 nanosecond increments. The format of the time is absolute (time and date) or relative (zero based) depending on the NC_ATTR_TIMESTAMP_FORMAT (Timestamp Format) attribute. Refer to ncSetAttribute for more information on timestamps. |
Structure with FrameType value NC_FRMTYPE_REMOTE (1): CAN Remote Frame
| Field Name | Data Type | Description |
|---|---|---|
| FrameType | NCTYPE_UINT8 | Value NC_FRMTYPE_REMOTE (1) specifies a CAN remote frame.
The CAN remote frame requests data for its arbitration ID. |
| ArbitrationId | NCTYPE_CAN_ARBID | Specifies the arbitration ID to transmit in the CAN data frame. A standard ID (11-bit) is specified by default. In order to specify an extended ID (29-bit), OR in the bit mask NC_FL_CAN_ARBID_XTD (20000000 hex). |
| DataLength | NCTYPE_UINT8 | Specifies the number of bytes requested. The value is transmitted in the CAN remote frame, but with no data. |
| Data | Array of 8, NCTYPE_UINT8 | Ignored. No data bytes are contained in a CAN remote frame. |
| Timestamp | NCTYPE_ABS_TIME | If the NC_ATTR_TRANSMIT_MODE (Transmit Mode) attribute is Immediate Transmit (default), this field is ignored, and CAN frames transmit as quickly as possible.
If the NC_ATTR_TRANSMIT_MODE attribute is Timestamped Transmit (1), this field specifies a timestamp. The timestamp is used to time transmission of CAN frames as described in Timestamped Transmit. The timestamp data type NCTYPE_ABS_TIME is a 64-bit unsigned integer in 100 nanosecond increments. The format of the time is absolute (time and date) or relative (zero based) depending on the NC_ATTR_TIMESTAMP_FORMAT (Timestamp Format) attribute. Refer to ncSetAttribute for more information on timestamps. |
Structure with FrameType value NC_FRMTYPE_START_TRIG (4): Start Trigger Frame
| Field Name | Data Type | Description |
|---|---|---|
| FrameType | NCTYPE_UINT8 | Value NC_FRMTYPE_START_TRIG (4) specifies a start trigger frame.
When you use ncWriteMult to write frames from a logfile for timestamped transmit, you can write the start trigger frame as the first frame. The start trigger frame reproduces the delay from start of communication to the first CAN frame. For example, if you write a start trigger frame followed by a CAN data frame with relative timestamp 20 ms, NI-CAN will delay 20 ms before transmitting the CAN data frame. If you write the CAN data frame without the start trigger frame, NI-CAN will transmit the CAN data frame immediately. |
| ArbitrationId | NCTYPE_CAN_ARBID | Value 0 is required. |
| DataLength | NCTYPE_UINT8 | Value 1 is required. |
| Data | Array of 8, NCTYPE_UINT8 | The single data byte in the array specifies the Timestamp Format NC_ATTR_TIMESTAMP_FORMAT (defined in ncSetAttribute) used for all subsequent CAN frames. The value is 0 for absolute timestamps, and 1 for relative timestamps. In order for NI-CAN to delay the proper time for the start trigger, this timestamp format must match the format used in all subsequent frames provided to ncWriteMult. |
| Timestamp | NCTYPE_ABS_TIME | Absolute timestamp of the start trigger. Within a logfile, this timestamp indicates the date and time at which CAN communication started.
The timestamp data type NCTYPE_ABS_TIME is a 64-bit unsigned integer in 100 nanosecond increments. The format of this timestamp is always absolute, even when Data byte 0 specifies relative timestamp format. This absolute timestamp provides data/time information even when the CAN frames of a logfile use the relative format. When Data byte 0 specifies absolute format (0), the difference between this timestamp and the absolute timestamp of the subsequent CAN frame is used as the delay for transmit of that CAN frame. When Data byte 0 specifies relative format (1), this timestamp is ignored by NI-CAN, and the relative timestamp of the subsequent CAN frame is used as the transmit delay. |
Structure with FrameType value NC_FRMTYPE_DELAY (5): Delay Frame
| Field Name | Data Type | Description |
|---|---|---|
| FrameType | NCTYPE_UINT8 | Value NC_FRMTYPE_DELAY (5) specifies a delay frame.
Use the delay frame to insert an additional delay between any two timestamped frames. For example, if you write a CAN frame with relative timestamp 20 ms, followed by a delay frame of 30 ms, followed by a CAN frame with timestamp 55 ms, NI-CAN will transmit the CAN frames 65 ms apart. |
| ArbitrationId | NCTYPE_CAN_ARBID | Value 0 is required. |
| DataLength | NCTYPE_UINT8 | Value 0 is required. |
| Data | Array of 8, NCTYPE_UINT8 | Ignored. |
| Timestamp | NCTYPE_ABS_TIME | Specifies the delay to insert (not a timestamp).
The delay is a 64-bit unsigned integer in 100 nanosecond increments. For example, a delay of 10 ms would be specified as the number 100000 in the low 32 bits of Timestamp. The maximum delay supported is 180.0 seconds (3 minutes). |
FrameType Value NC_FRMTYPE_LIN_RESPONSE_ENTRY (16) LIN Response Entry
| Field Name | Data Type | Description |
|---|---|---|
| FrameType | NCTYPE_UINT8 | Value 16 represents a response entry frame for LIN communication.The behavior resulting from writing a response type to the LIN interface depends upon whether the LIN Sleep attribute is set to TRUE or FALSE (the LIN interface is asleep or awake, respectively). If the NC_ATTR_LIN_SLEEP attribute is set to FALSE: A response entry frame is issued when it is desired to configure the LIN interface slave task to subscribe to or publish data, in response to a particular header ID received from a master task. Each response entry frame indicates the ID of the header for which it is to respond, whether the response is to publish data or subscribe to data, and if it is to publish data, the data length code (DLC) and data values. The DLC determines whether the response will be to subscribe (DLC = 0), or publish (DLC = data length), in response to a header containing the ID of the response frame. Sixty-four response entry frames (one for each of the sixty-four LIN IDs) may be written to the response queue in the LIN interface. When the Network Interface is created or reset, the interface is reset to act as a slave and to respond as subscriber to data for all LIN IDs. If the NC_ATTR_LIN_SLEEP attribute is set to TRUE: A response entry frame is issued when the LIN interface has been acting as a slave (processing master headers), has been put asleep, and is desired to be used to wake the bus and initiate the transmission of headers by the master. When the response entry type is written to the LIN interface, two things occur. First, the response queue is loaded with the ID, DLC, and data (if DLC is non-zero meaning the response is to publish), of the response entry frame. Next the interface transmits a wakeup break on the bus. Per the LIN specification, it either waits until the master acknowledges the wakeup break by writing a header within the specified time, or re-transmits the wakeup break if it does not. When the master responds with a header, the LIN interface sets the LIN Sleep attribute to FALSE, and responds to the ID contained in the header in the manner (publish or subscribe) specified for that ID in the response queue. |
| ArbitrationId | NCTYPE_CAN_ARBID | Zero to sixty-three. |
| DataLength | NCTYPE_UINT8 | Zero if the response is to subscribe to data. Actual length of Data if the response is to publish data. |
| Data | Array of 8, NCTYPE_UINT8 | Ignored if DataLength is zero. Data to publish if DataLength is non-zero. |
| Timestamp | NCTYPE_ABS_TIME | Ignored. |
FrameType Value NC_FRMTYPE_LIN_HEADER (17) LIN Header
| Field Name | Data Type | Description |
|---|---|---|
| FrameType | NCTYPE_UINT8 |
Value 17 represents a header frame for LIN communication. The behavior resulting from writing a header type to the LIN interface depends upon whether the NC_ATTR_LIN_SLEEP attribute is set to TRUE or FALSE (the LIN interface is asleep or awake, respectively). If the NC_ATTR_LIN_SLEEP attribute is set to FALSE: A header frame is issued when it is desired to use the LIN interface as a master, querying a slave task to publish data. Issuing a header frame causes the LIN interface to write a break-sync-id sequence to the LIN bus, with the expectation that a slave task will publish data in response. Once a header frame is issued, the LIN interface will behave as a master until the next time it is started. If the NC_ATTR_LIN_SLEEP attribute is set to TRUE: A header frame is issued when the LIN interface has been acting as a master (transmitting header and full IsResponse types), has been put asleep, and is desired to be used to wake the LIN bus and query a slave task to publish data. Issuing a header frame causes the LIN interface to write a wakeup break followed by break-sync-id sequence to the LIN bus, with the expectation that all slaves will wake up and a slave task will publish data in response. The LIN interface also sets the NC_ATTR_LIN_SLEEP attribute to FALSE. |
| ArbitrationId | NCTYPE_CAN_ARBID | Zero to sixty-three. |
| DataLength | NCTYPE_UINT8 | One to eight if the NC_ATTR_ENABLE_DLC_CHECK attribute is set to 1 (TRUE). If the NC_ATTR_ENABLE_DLC_CHECK attribute is set to 0 (FALSE), the data length is ignored. |
| Data | Array of 8, NCTYPE_UINT8 | Ignored. |
| Timestamp | NCTYPE_ABS_TIME | Ignored. |
FrameType Value NC_FRMTYPE_LIN_FULL (18) LIN Full
| Field Name | Data Type | Description |
|---|---|---|
| FrameType | NCTYPE_UINT8 | Value 18 represents a full frame for LIN communication. The behavior resulting from writing a full type to the LIN interface depends upon whether the NC_ATTR_LIN_SLEEP attribute is set to TRUE or FALSE (the LIN interface is asleep or awake, respectively). If the NC_ATTR_LIN_SLEEP attribute is set to FALSE: A full frame is issued when it is desired to use the LIN interface as a master, publishing data to an external slave. Issuing a full frame causes the LIN interface slave task response queue to be updated, the master task to write a header to the LIN bus, then the LIN interface slave task to publish a response, with the expectation that one or more external slaves will subscribe to the data. Once a full frame is issued, the LIN interface will behave as a master until the next time it is started. If the NC_ATTR_LIN_SLEEP attribute is set to TRUE: A full frame is issued when the LIN interface has been acting as a master (transmitting header and full IsResponse types), has been put asleep, and is desired to be used to wake the LIN bus and publish data to one or more external slaves. Issuing a full frame causes the LIN interface slave task response queue to be updated, the master task to write a wakeup break followed by a header to the LIN bus, then the LIN interface slave task to publish a response, with the expectation that all slaves will wake up and one or more external slaves will subscribe to the published data. The LIN interface also sets the NC_ATTR_LIN_SLEEP attribute to FALSE. |
| ArbitrationId | NCTYPE_CAN_ARBID | Zero to sixty-three. |
| DataLength | NCTYPE_UINT8 | One to eight. |
| Data | Array of 8, NCTYPE_UINT8 | Data to publish. |
| Timestamp | NCTYPE_ABS_TIME | Ignored. |