SetAttrRangeTableCallback

IVI Library

Ivi_SetAttrRangeTableCallback

Usage

ViStatus Ivi_SetAttrRangeTableCallback(ViSession vi, ViAttr attributeID, RangeTable_CallbackPtr rangeTableCallback);

Purpose

This function sets the callback that the IVI engine invokes to obtain a pointer to the range table for an attribute. Although any attribute can have a range table, range tables normally are useful only for ViInt32 or ViReal64 attributes.

When you create a ViInt32 or ViReal64 attribute, you can specify a single range table for the IVI engine to use to validate values for the attribute. Normally, one range table is sufficient. If this is the case, you do not need a range table callback function. By default, the range table callback for each attribute is VI_NULL.

Sometimes, however, you want to use different range tables depending on the current settings of other attributes. In that case, call Ivi_SetAttrRangeTableCallback to install a callback for the IVI engine to invoke. In the callback, you determine which range table you want to use, and you return a pointer to it.

When you specify a non-NULL range table callback for a ViInt32 or ViReal64 attribute, the IVI engine automatically installs its default check and coerce callbacks if these callback are currently VI_NULL.

Parameters

Name	Type	Description
vi	ViSession	The ViSession handle that you obtain from Ivi_SpecificDriverNew. The handle identifies a particular IVI session.
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)
rangeTableCallback	RangeTable_CallbackPtr	Specify the range table callback function you want the IVI engine to invoke to obtain a range table for the attribute. The function must have the following prototype: ViStatus _VI_FUNC Callback(ViSession vi,ViConstString repCapName, ViAttr attributeId, IviRangeTablePtr *rangeTablePtr); If you do not want to use a range table callback function, pass VI_NULL.

Name

Type

Description

ViSession

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

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)

rangeTableCallback

RangeTable_CallbackPtr

Specify the range table callback function you want the IVI engine to invoke to obtain a range table for the attribute.

The function must have the following prototype:

ViStatus _VI_FUNC Callback(ViSession vi,ViConstString repCapName,
ViAttr attributeId,
IviRangeTablePtr *rangeTablePtr);

If you do not want to use a range table callback function, pass VI_NULL.

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.