nctInitStart
Purpose
Initializes a task for the specified channel list, then starts communication.
Format
| nctTypeStatus | nctInitStart(
|
Inputs
ChannelList
Comma-separated list of channel names to initialize as a task.
You can type in the channel list as a string constant, or you can obtain the list from MAX or another CAN database by using the nctGetNames function. Channel names are case sensitive.
You can initialize the same ChannelList with different Interface, Mode, or SampleRate, because each task reference is unique.
If you are using mode dependent channels, and each channel name is not unique, you will need to use a special syntax described in the Mode Dependent Channel Syntax section at the end of the function description.
The following paragraphs describe the syntax of each channel name. Brackets indicate optional fields.
[filepath::][message.]channel
filepath is the path to a CAN database file from which to import the channel (signal) configurations. The filepath must use Windows directory syntax, and must be followed by a double-colon.
If filepath is not included, the channel configuration is obtained from MAX. The MAX CAN channels are in the MAX CAN Channels listing within Data Neighborhood.
Once you specify a filepath, it will continue to be applied to subsequent names in the channel list until you specify a new filepath. After using filepath for a CAN database file, you can revert to using MAX by specifying an empty filepath (double colon only).
If you are using mode dependent channels, and each channel name is not unique, you will need to use a special syntax described in the Mode Dependent Channel Syntax section at the end of the function description.
message refers to the message in which the channel is contained. The message name must be followed by a decimal point.
If the channel name occurs in multiple messages, you must specify the message name to identify the channel uniquely. Within MAX, channels with the same name in multiple messages are shown with a yellow exclamation point.
If the channel name is unique across all channels, the message name is not required.
The following examples demonstrate the channel list syntax:
List of channels from MAX, each channel name unique across all messages.
myChan1,myChan2,myChan3
List of channels from a CANdb file, each channel name unique across all messages.
C:\MyCandb\MyChannels.DBC::myChan1
myChan2,myChan3
List of channels from MAX, with one channel duplicated across two messages. MyChan2 and MyChan3 must be unique across all messages.
myMessage1.myChan1,myChan2,
myMessage2.myChan1,myChan3
List of two channels from a CANdb file, then two channels from MAX.
C:\MyCandb\MoreChannels.DBC::myChan1,
myChan2,::myChan3,myChan4
Interface
Specifies the CAN interface to use for this task.
The interface input uses an enumeration in which value 0 selects CAN0, value 1 selects CAN1, and so on.
If you pass the special value -1 to Interface, this function uses the default interface as defined in the Message/Channel configuration properties. If the default interface in MAX is All, or if one or more channels in ChannelList specifies a filepath, the Interface is a required input to this function.
The Channel API and Frame API cannot use the same CAN network interface simultaneously. If the CAN network interface is already initialized in the Frame API, this function returns an error.
The special interface values 256 and 257 refer to virtual interfaces. For more information on usage of virtual interfaces, refer to Frame to Channel Conversion.
Mode
Specifies the I/O mode for the task. For an overview of the I/O modes, including figures, refer to the Channel API Basic Programming Model.
nctModeInput
Input channel data from received CAN messages. Use the nctRead function to obtain input samples as single-point, array, or waveform. Each periodic message uses the sample values from the most recent nctWrite.
Use this input mode to read waveforms of timed samples, such as for comparison with NI-DAQ or NI-DAQmx waveforms. You also can use this input mode to read a single point from the most recent message, such as for control or simulation.
For this mode, the channels in ChannelList can be contained in multiple messages.
nctModeOutput
Output channel data to CAN messages for transmit. Use the nctWrite function to write output samples as single-point, array, or waveform.
For this mode, there are restrictions on using channels in ChannelList that are contained in multiple messages. Refer to nctWrite for more information.
nctModeOutputRecent
Output channel data to CAN messages for transmit. This mode is used with sample rate greater than zero (periodic transmit). Use nctWrite to provide a single sample per channel. Each periodic message uses the sample values from the most recent nctWrite.
For this mode, there are restrictions on using channels in channel list that are contained in multiple messages. Refer to nctWrite for more information.
nctModeTimestampedInput
Input channel data from received CAN messages. Use the nctRead function to obtain input samples as an array of sample/timestamp pairs (refer to nctReadTimestamped).
For this mode, the channels in ChannelList must be contained in a single message.
Use this input mode to read samples with timestamps that indicate when each message is received from the network.
If nctModeTimestampedInput mode is used, the task cannot be started with nctInitStart because the Value for invalid data must be set up through nctSetProperty before calling nctStart. Use the sequence nctInitialize, nctSetProperty (nctPropNoValue), and nctStart instead.
SampleRate
Specifies the timing to use for samples of the task. The sample rate is specified in Hertz (samples per second). A sample rate of zero means to sample immediately.
For Mode of NctModeInput, SampleRate of zero means nctRead returns a single point from the most recent message received, and greater than zero means nctRead returns samples timed at the specified rate.
For Mode of NctModeOutput, SampleRate of zero means CAN messages transmit immediately when nctWrite is called, and greater than zero means CAN messages are transmitted periodically at the specified rate.
For Mode of NctModeTimestampedInput, SampleRate is ignored.
When the Interface specifies a virtual interface (256 or 257), and Mode is nctModeOutput or nctModeOutputRecent, this SampleRate must be zero (greater than zero not supported).
Outputs
TaskRef
Use TaskRef with all subsequent functions to reference the running task. Because nctInitStart starts communication, you can pass this task reference to nctRead or nctWrite.
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 code for this function simply calls nctInitialize followed by nctStart. This provides an easy way to start a list of channels.
The following list describes the scenarios for which nctInitStart cannot be used:
- If you need to set properties for the channels, use nctInitialize, then nctSetProperty, then nctStart. The nctInitStartfunction starts communication, and most channel properties cannot be changed after the task is started.
- If you need to synchronize tasks for multiple NI-CAN, NI-DAQ, or NI-DAQmx cards, use nctInitialize, then nctConnectTerminals to synchronize, the nctStart to start communication.
- If you need to create channel configurations entirely within the application, without using MAX or a CAN database file, use nctCreateMessage, then nctStart. The nctInitStart function accepts only channel names defined in MAX or a CAN database file.
Mode Dependent Channel Syntax
If you are using mode dependent channels, and each channel name is not unique, you will need to use a special syntax described in this section. For the large majority of channels, you can use the simple syntax described previously for channel list. The brackets [] define optional parameters:
[message name.[[multiplexer.]mode_value.]]channel.
- message refers to the message in which the channel is contained. The message name must be followed by a decimal point. If the channel name is not unique within MAX or the database file, you must specify the message name to identify the channel uniquely.
Within MAX, channels with the same name are shown with a yellow exclamation point. This feature can be changed in the CAN Channels»Options dialog box.
If the channel name is unique across all channels, the message name is not required.
- multiplexer refers to the multiplexer name in MAX or the CAN database. The message name must be followed by a decimal point. It applies only to mode dependent messages and must be omitted for normal CAN channels. If more than one multiplexer is defined for the message and the channel name is not unique within the CAN message, you must specify the multiplexer name to identify the channel uniquely.
- mode_value refers to the multiplexer mode in MAX or the CAN database. The message name must be followed by a decimal point. It applies only to mode dependent messages and must be omitted for normal CAN channels. If the channel name is not unique within the multiplexer, you must specify the mode to identify the channel uniquely.
- channel refers to the channel (signal) name in MAX or the CAN database.
You cannot use the same channel name for a normal CAN channel and a mode dependent CAN channel within the same CAN message.
If the name of a channel is unique within MAX or the database, it can be referenced by the channel API using its channel name.
For more information on mode dependent channels, refer to Mode Dependent Channels.