Ivi_BuildChannelTable
Usage
ViStatus Ivi_BuildChannelTable (ViSession vi, ViChar defaultChannelsStringsList[ ], ViBoolean allowUnknownChannelStrings, Ivi_ValidateChannelStringFunc chanStringValidationFunction);
Purpose
This function creates the initial channel table for an IVI session. A channel table consists of the channel strings that are valid for the instrument session. When you create attributes with the Ivi_AddAttribute functions, you set the IVI_VAL_MULTI_CHANNEL flag for attributes that have different values for each channel. You use this function to specify the set of channels.
You must call Ivi_BuildChannelTable in your PREFIX_IviInit function. If you call it again at a later point, it discards the old channel table and builds a new one. To add channel strings to an existing channel table, call Ivi_AddToChannelTable. To restrict an attribute to a subset of channels, call Ivi_RestrictAttrToChannels.
The IVI engine maintains the channel table for the session. If the user defines any virtual channel names in the configuration store, the IVI engine associates the virtual names with the entries in the table.
Parameters
| Name | Type | Description |
|---|---|---|
| vi | ViSession |
The ViSession handle that you obtain from Ivi_SpecificDriverNew. The handle identifies a particular IVI session. |
| DefaultChannelsStringsList | ViChar[ ] |
Pass a single string containing a list of the strings that represent the channels of the instrument. Separate the channel strings with commas. You can include spaces after the commas. For example, pass "1,2" if the instrument has two channels and your driver accepts "1" or "2" as the channel string. |
| allowUnknownChannelStrings | ViBoolean |
Set this control to VI_TRUE if you want to allow users to pass channel strings that are not in the channel table to your instrument driver functions. If you pass VI_TRUE for this parameter, you must pass a non-NULL value for the Chan String Validation Function parameter. In drivers for typical instruments, pass VI_FALSE for this parameter. |
| chanStringValidationFunction | Ivi_ValidateChannelStringFunc |
The ivi.h include file defines the Ivi_ValidateChannelStringFunc typedef for this prototype. If the channel string is not a valid channel name, your callback function must return VI_FALSE in the *isValid parameter. If the channel string represents a valid channel, the callback function must return VI_TRUE in the *isValid parameter. The IVI engine then adds this channel string to the channel table after the callback function returns. If the application initializes the session through an IVI class driver, the IVI engine automatically applies the default setup on the new channel. You can add the channel string to the channel table inside the callback function explicitly. You must do this if you want to exclude the channel from one or more attributes. Call Ivi_AddToChannelTable, and then call Ivi_RestrictAttrToChannels for every attribute you want to exclude from using the new channel. You can then call Ivi_ApplyDefaultSetup function. If you do not call Ivi_ApplyDefaultSetup, the IVI engine does it for you. If you pass VI_FALSE for the Allow Unknown Channel Strings parameter, pass VI_NULL for this parameter. |
Return Value
Contains the status code that the function call returns. IVI engine functions can return error and warning values from several sets of status codes. Some status codes are unique to the IVI engine. Other status codes are the same codes that VISA Library functions return. Still others are error or warning values that functions in specific instrument drivers return. Each set of status codes has its own numeric range.
Regardless of the source of the status code, 0 always indicates success, a positive value indicates a warning, and a negative value indicates an error.