DefaultCompareCallbackViReal64

IVI Library

Ivi_DefaultCompareCallbackViReal64

Usage

ViStatus Ivi_DefaultCompareCallbackViReal64(ViSession vi, ViChar repeatedCapability[ ], ViAttr attributeID, ViReal64 a, ViReal64 b, ViInt32* result);

Purpose

This function performs the default compare actions for a ViReal64 attribute. The IVI engine invokes the compare callback to compare the cache values it obtains from the instrument against new values you set the attribute to. If the compare callback determines that the two values are equal, the IVI engine does not call the write callback for the attribute.

The IVI engine automatically installs this callback when you call Ivi_AddAttributeViReal64. The IVI engine installs the default compare callback rather than comparing based on strict equality because of differences between computer and instrument floating point representations.

You can install your own compare callback by calling Ivi_SetAttrCompareCallbackViReal64.

If the two values are not exactly equal, the function uses the following logic, where a and b are the values you want to compare, and d is the digits of precision you specify when you call Ivi_AddAttributeViReal64 or Ivi_SetAttrComparePrecision.

   if a == 0                   -(d-1)                  if  |b| < 10            then a == b.   else /* a != 0 */              |a-b|     -(d-1)        if  ----- < 10          then a == b            |a|             
Note  Do not call this function directly unless you are calling it from your own callback or you have already called Ivi_LockSession.

Parameters

Name Type Description
vi ViSession

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

repeatedCapability ViChar[ ]

If the attribute is repeated capability-based, specify a particular repeated capability. If the attribute you specify is not repeated capability-based, pass VI_NULL or an empty string.

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)

a ViReal64

Specify the first value to compare. Normally, this is the new value to which you are trying to set the attribute. If there is a coerce callback or coerced range table for the attribute, the IVI engine has already coerced the value.

b ViReal64

Specify the second value to compare. Normally, this is the current cache value of the attribute.

result ViInt32*

Returns the results of the comparison.

Return values:
 0 (if a == b)
 1 (if a > b)
-1 (if a < b)

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.

Related Topic

IVI Status Codes