ValidateAttrForChannel

IVI Library

previous page next page

Ivi_ValidateAttrForChannel

Usage

ViStatus Ivi_ValidateAttrForChannel(ViSession vi, ViChar channelName[ ], ViAttr attributeID);

Purpose

This function checks whether you can use an attribute on a particular channel. If either the AttributeID or Channel Name parameter is invalid for the session, Ivi_ValidateAttrForChannel returns an error. Otherwise, it checks for the following cases in which the combination of the AttributeID and Channel Name is invalid:

The channel name is VI_NULL or the empty string and the attribute is channel-based. An attribute is channel-based if its IVI_VAL_MULTI_CHANNEL flag is set. In this case, the function returns the IVI_ERROR_REPEATED_CAPABILITY_NAME_REQUIRED error code.

The channel name refers to a specific channel and the attribute is not channel-based. In this case, the function returns the IVI_ERROR_REPEATED_CAPABILITY_NAME_NOT_ALLOWED error code.

The channel name refers to a specific channel, the attribute is channel-based, but the instrument driver calls Ivi_RestrictAttrToChannels to exclude the channel from using the attribute. In this case, the function returns the IVI_ERROR_ATTR_NOT_VALID_FOR_REPEATED_CAPABILITY error code.

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 as valid for a particular channel. You can pass one of the following types of values: VI_NULL or an emptry string A specific driver channel string, which is one that the specific instrument driver specifies as valid using Ivi_BuildChannelTable or Ivi_AddToChannelTable. A virtual channel name that the end-user specifies in the IVI configuration file.
attributeID	ViAttr	Pass the ID of an attribute for this parameter. The include file for a specific instrument driver defines constant names for all of the user-accessible attributes that apply to the driver. This includes attributes that the IVI engine defines, attributes that the instrument class defines, and attributes that are specific to the particular instrument. Each defined constant name begins with PREFIX_ATTR_, where PREFIX is the specific instrument prefix. For each IVI engine attribute, the specific driver include file uses the same constant name that appears in ivi.h, except that the specific instrument prefix replaces the IVI prefix. For example, ivi.h defines IVI_ATTR_CACHE, and the Fluke 45 include file, fl45.h, defines the following constant name: #define FL45_ATTR_CACHE IVI_ATTR_CACHE For each instrument class attribute, the specific driver include file uses the same constant name that appears in the instrument class include file, except that the specific instrument prefix replaces the class prefix. For example, the DMM class include file, ividmm.h, defines IVIDMM_ATTR_RANGE, and fl45.h defines the following constant name: #define FL45_ATTR_RANGE IVIDMM_ATTR_RANGE For each specific instrument attribute, the specific driver include file defines a constant name and assigns a value that is an offset from IVI_SPECIFIC_PUBLIC_ATTR_BASE. For example, fl45.h defines the following constant name: #define FL45_ATTR_HOLD_THRESHOLD \ (IVI_SPECIFIC_PUBLIC_ATTR_BASE + 3L) For each attribute that is private to an instrument driver, the instrument driver source file defines a constant name and assigns a value that is an offset from IVI_SPECIFIC_PRIVATE_ATTR_BASE. For example, hp34401a.c defines the following constant name: #define HP34401A_ATTR_TRIGGER_TYPE \ (IVI_SPECIFIC_PRIVATE_ATTR_BASE + 1L)

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 as valid for a particular channel.

You can pass one of the following types of values:

VI_NULL or an emptry string
A specific driver channel string, which is one that the specific instrument driver specifies as valid using Ivi_BuildChannelTable or Ivi_AddToChannelTable.
A virtual channel name that the end-user specifies in the IVI configuration file.

attributeID

ViAttr

Pass the ID of an attribute for this parameter.

The include file for a specific instrument driver defines constant names for all of the user-accessible attributes that apply to the driver. This includes attributes that the IVI engine defines, attributes that the instrument class defines, and attributes that are specific to the particular instrument. Each defined constant name begins with PREFIX_ATTR_, where PREFIX is the specific instrument prefix.

For each IVI engine attribute, the specific driver include file uses the same constant name that appears in ivi.h, except that the specific instrument prefix replaces the IVI prefix. For example, ivi.h defines IVI_ATTR_CACHE, and the Fluke 45 include file, fl45.h, defines the following constant name:

#define FL45_ATTR_CACHE IVI_ATTR_CACHE

For each instrument class attribute, the specific driver include file uses the same constant name that appears in the instrument class include file, except that the specific instrument prefix replaces the class prefix. For example, the DMM class include file, ividmm.h, defines IVIDMM_ATTR_RANGE, and fl45.h defines the following constant name:

#define FL45_ATTR_RANGE IVIDMM_ATTR_RANGE

For each specific instrument attribute, the specific driver include file defines a constant name and assigns a value that is an offset from IVI_SPECIFIC_PUBLIC_ATTR_BASE. For example, fl45.h defines the following constant name:

#define FL45_ATTR_HOLD_THRESHOLD \ (IVI_SPECIFIC_PUBLIC_ATTR_BASE + 3L)

For each attribute that is private to an instrument driver, the instrument driver source file defines a constant name and assigns a value that is an offset from IVI_SPECIFIC_PRIVATE_ATTR_BASE. For example, hp34401a.c defines the following constant name:

#define HP34401A_ATTR_TRIGGER_TYPE \ (IVI_SPECIFIC_PRIVATE_ATTR_BASE + 1L)

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.