nctCreateMessageEx

Purpose

Creates a mode dependent message configuration and associated channel configurations within the application.

Format

Inputs

ConfigID

Specifies the type of structures you provide in MessageConfig and ChannelConfigList. The properties are similar to the message properties in MAX. Currently, the following values are supported.

1

In this case, the MessageConfig and ChannelConfigList parameters behave exactly as those described for the nctCreateMessage function. This mode is provided for compatibility.

2

This value allows you to define mode dependent channels. The MessageConfig parameter behaves the same way as for ConfigId = 1. The ChannelConfigList parameter must be passed an array of structures described below. For more information, refer to Mode Dependent Channels.

3

This value is reserved for internal purposes. Do not use.

All other values for this parameter return an error.

MessageConfig

Configures properties for a new message. For both ConfigId = 1 and ConfigId = 2, you provide the properties as a pointer to a C struct.

The properties are similar to the message properties in MAX:

u32 MsgArbitrationID

Configures the arbitration ID of the message.

Use the Extended property to specify whether the ID is standard (11-bit) or extended (29-bit).

u32 Extended

Configures a Boolean value that indicates whether the message arbitration ID is standard 11-bit format (0) or extended 29-bit format (1).

u32 MsgDataBytes

Configures the number of data bytes in the message. The range is 0 to 8.

NumberOfChannels

Specifies the number of channel configurations you provide in ChannelConfigList.

ChannelConfigList

Configures the list of channels for the new message. ChannelConfigList is an array of a C struct, with one C struct for each channel. The properties of each channel are similar to the channel properties in MAX. For ConfigId = 1, refer to the ChannelConfigList parameter of the nctCreateMessage function. For ConfigId = 2 use this structure:

u32 StartBit

Configures the starting bit position in the message. The range is 0 (lowest bit in first byte), to 63 (highest bit in last byte).

u32 NumBits

Configures the number of bits in the message. The range is 1 to 64.

u32 DataType

Configures the data type of the channel in the message. Values are nctDataSigned, nctDataUnsigned, and nctDataFloat.

u32 ByteOrder

Configures the byte order of the channel in the message. Values are nctOrderIntel (little-endian), and nctOrderMotorola (big-endian).

f64 ScalingFactor

Configures the scaling factor used to convert raw bits of the message to/from scaled floating-point units. The scaling factor is the A in the linear scaling formula AX+B, where X is the raw data, and B is the scaling offset.

f64 ScalingOffset

Configures the scaling offset used to convert raw bits of the message to/from scaled floating-point units. The scaling offset is the B in the linear scaling formula AX+B, where X is the raw data, and A is the scaling factor.

f64 MaxValue

Configures the maximum value of the channel in scaled floating-point units.

The nctRead and nctWrite functions do not coerce samples when converting to/from CAN messages. You can use this value with the user-interface functions of the development environment to set the range of front-panel controls and indicators.

f64 MinValue

Configures the minimum value of the channel in scaled floating-point units.

The nctRead and nctWrite functions do not coerce samples when converting to/from CAN messages. You can use this value with the user-interface functions of the development environment to set the range of front-panel controls and indicators.

f64 DefaultValue

Configures the default value of the channel in scaled floating-point units.

For information on how the DefaultValue is used, refer to the nctRead and nctWrite functions.

const str Unit

Configures the unit string of the channel. The string is no more than 64 characters in length.

You can use this value to display units (such as volts or RPM) along with the samples of the channel.

u32 NumModeChannels

Configures whether to use a mode channel for this channel. The range is 0 to 1. For 0, this channel is valid in each frame (mode independent channel). For 1, this channel is valid only if the mode channel described in the ModeChannel struct applies (mode dependent channel). For more information, refer to Mode Dependent Channels.

struct ModeChannel

Configures the mode channel for this (data) channel. Note that the same mode channel can be specified for several channels. The structure contains following fields:

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.

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 nctReadTimestamped function to obtain input samples as an array of sample/timestamp pairs (refer to nctReadTimestamped for more information).

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.

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

To use message and channel configurations from MAX or a CAN database, use the nctInitStart or nctInitialize functions. The nctCreateMessage function provides an alternative in which you create the message and channel configurations within the application, without use of MAX or a CAN database.

nctCreateMessage returns a task reference you wire to nctStart to start communication for the message and its channels.