nctGetNames

Purpose

Gets an array of CAN channel names or message names from MAX or a CAN database file.

Format

Inputs

FilePath

FilePath is an optional path to a CAN database file from which to get channel names. The file must use either .DBC or .NCD extension. Files with extension .DBC use the CANdb database format. Files with extension .NCD use the NI-CAN database format. You can generate NI-CAN database files from the Save Channels selection in MAX.

If you pass NULL or empty-string to FilePath, this function gets the channel names from MAX. The MAX CAN channels are in the MAX CAN Channels listing within Data Neighborhood.

Mode

Specifies the type of names to return.

nctGetNamesModeChannels

Return list of channel names. You can pass the returned ChannelList to nctInitStart.

nctGetNamesModeMessages

Return list of message names.

MessageName

MessageName is an optional input that filters the names for a specific message. If you pass NULL or empty-string to MessageName, this function returns all names in the database. If you pass a non empty string, the ChannelList output is limited to channels of the specified message.

This input applies to Mode of nctGetNamesModeChannels only. It is ignored for Mode of nctGetNamesModeMessages.

SizeofChannelList

Number of bytes allocated for the ChannelList output.

If all of the channel names do not fit in the allocated ChannelList, this function returns as much as possible with an error.

Use the nctGetNamesLength function to determine the proper SizeofChannelList.

Outputs

ChannelList

Returns the comma-separated list of channel names.

Each name in ChannelList uses the minimum syntax required to properly initialize:

• If a channel name is used within only one message in the database, nctGetNames returns only the channel name in the list. If a channel name is used within multiple messages, nctGetNames prepends the message name to that channel name, with a decimal point separating the message and channel name. This syntax ensures that the duplicate channel is associated to a single message in the database.

For more information on the syntax conventions for channel names, refer to nctInitStart.

To start a task for all channels returned from nctGetNames, pass ChannelList to the nctInitStart function to start a task.

You also can use ChannelList with a user-interface control such as a ring or list box. The user of the application can then select names using this control, and the selected names can be passed to nctInitStart.

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.

Note  The function nctGetNames returns the string results as an array of char (*char). VB is not able to convert this array to a string automatically. Therefore, VB users should call the wrapper function nct_GetNames.