nctInitialize

Purpose

Initializes a task for the specified channel list.

Format

Inputs

ChannelList

Comma-separated list of channel names to initialize as a task.

For more information, refer to the channel list input of nctInitStart.

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 sample value that you write is transmitted in a message on the network. If you write an array or waveform, the samples are buffered for subsequent transmit.

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).

Use this input mode to read samples with timestamps that indicate when each message is received from the network.

For this mode, the channels in ChannelList must be contained in a single message.

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 task. Pass this task reference to nctStart before you read or write samples for the message.

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 nctInitialize function does not start communication. This enables you to use nctSetProperty to change the properties of the task, or nctConnectTerminals to synchronize CAN or DAQ cards. After you change properties or connections, use nctStart to start communication for the task.