CoerceChannelName

IVI Library

previous page next page

Ivi_CoerceChannelName

Usage

ViStatus Ivi_CoerceChannelName(ViSession vi, ViChar ChannelName[ ], ViConstString* ChannelString);

Purpose

If your driver supports multiple channels, you must call Ivi_CoerceChannelName in driver functions that use the channel string directly. When you call an Ivi_SetAttribute, Ivi_GetAttribute, or Ivi_CheckAttribute function. the IVI engine calls Ivi_CoerceChannelName internally before invoking the read, write, check, coerce, compare, and range table callback functions.

To be valid, Channel Name must be one of the following:

VI_NULL, in which case the function sets the Channel String parameter to VI_NULL.
An empty string, in which case the function returns the address of that empty string in the Channel String parameter.
A specific driver channel string. The specific instrument driver specifies the valid channel strings using Ivi_BuildChannelTable or Ivi_AddToChannelTable. If you pass one of these strings, the function returns the address of the channel string in the channel table that the IVI engine maintains for the session.
A virtual channel name that the end-user specifies in the configuration store. Virtual channel names are valid only if the end-user opens the session from a class driver and assigns a valid specific driver channel string to the virtual name in the configuration store. If you pass a valid virtual name to this function, the function returns the address of the corresponding specific driver channel string in the channel table that the IVI engine maintains for the session.

Parameters

Name	Type	Description
vi	ViSession	The ViSession handle that you obtain from Ivi_SpecificDriverNew. The handle identifies a particular IVI session.
ChannelName	ViChar[ ]	Pass the channel name that you want to verify and convert to a specific driver channel name string. Usually, this is the string that the end-user passes into a specific driver function. The parameter accepts VI_NULL, an empty string, a specific driver-defined channel name identifier, or a virtual channel name identifier.
ChannelString	ViConstString*	Returns a pointer to a channel string in the channel table that the IVI engine maintains for the session. Do not modify the contents of the channel string. If you pass VI_NULL in the Channel Name Identifier parameter, the function returns VI_NULL in this parameter. If you pass an empty string, the function returns the address of the empty string.

Name

Type

Description

ViSession

The ViSession handle that you obtain from Ivi_SpecificDriverNew. The handle identifies a particular IVI session.

ChannelName

ViChar[ ]

Pass the channel name that you want to verify and convert to a specific driver channel name string. Usually, this is the string that the end-user passes into a specific driver function.

The parameter accepts VI_NULL, an empty string, a specific driver-defined channel name identifier, or a virtual channel name identifier.

ChannelString

ViConstString*

Returns a pointer to a channel string in the channel table that the IVI engine maintains for the session.

Do not modify the contents of the channel string.

If you pass VI_NULL in the Channel Name Identifier parameter, the function returns VI_NULL in this parameter. If you pass an empty string, the function returns the address of the empty string.

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.