CheckAttributeViInt64

IVI Library

Ivi_CheckAttributeViInt64

Usage

ViStatus Ivi_CheckAttributeViInt64(ViSession vi, ViChar repeatedCapability[ ], ViAttr attributeID, ViInt32 optionFlags, ViInt64 attributeValue);

Purpose

This function checks the validity of a value you specify for a ViInt64 attribute. The function performs the following actions:

  1. Checks whether the attribute is writable. If not, the function returns an error.
  2. Validates the value you specify. If you provide a check callback, the function invokes the callback to validate the value. If you do not provide a check callback but you provide a range table or a range table callback, the function invokes the default IVI check callback to validate the value. If the value is invalid, the function returns an error. If the attribute has no range table or check callback, the function assumes the value is valid.

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 you specify is based on a repeated capability, pass a repeated capability identifier. You can pass one of the identifiers strings that the specific instrument driver defines, or a virtual name the end-user defines in the configuration file.

If the attribute you specify is not based on a repeated capability, 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)

optionFlags ViInt32

Use this parameter to request special behavior. In most cases, you pass 0.

You can specify individual bits to request specific behavior. Each of the following sections describes one of the bit values.

IVI_VAL_DIRECT_USER_CALL (1<<0)

Use the IVI_VAL_DIRECT_USER_CALL bit when calling this function from the source code for the PREFIX_Set/Get/CheckAttribute functions that your instrument driver exports. Do not use the bit when calling this function from any other context.

If you set this bit, this function checks the IVI_VAL_USER_READABLE or IVI_VAL_USER_WRITABLE flag. If the end-user does not have permission to access the attribute, the function returns an error.

If you set this bit, the function also checks the status of the instrument after invoking the read or write callback for the attribute, but only if the following conditions are true.

  • This is a SetAttribute or GetAttribute function.
  • The value of the IVI_ATTR_QUERY_INSTRUMENT_STATUS attribute for the session is VI_TRUE.
  • The value of the IVI_VAL_DONT_CHECK_STATUS flag for the attribute is 0.

IVI_VAL_SET_CACHE_ONLY (1<<1)

This bit applies only to calls that specific instrument drivers make to the Ivi_SetAttribute functions. Pass 1 for this bit if want to set the value in the attribute cache but you do not want to invoke the write callback for the attribute.

This is useful if one instrument I/O command sets multiple attributes in the instrument. In the write callback function that performs the instrument I/O, after the instrument I/O succeeds, call an Ivi_SetAttribute function for each of the other attributes, with set the IVI_VAL_SET_CACHE_ONLY bit set to 1 in the Option Flags parameter.

IVI_VAL_DONT_MARK_AS_SET_BY_USER (1<<2)

This bit applies only to calls that specific instrument drivers make to the Ivi_SetAttribute functions. Pass 1 for this bit if want to set an attribute value even though the user has not requested you to do so directly through a PREFIX_SetAttribute function call or indirectly through a helper function that sets multiple attributes.

This case occurs very rarely. It affects interchangeability checking in class drivers. To pass interchangeability checking, either all attributes in an extension group must be marked as "set by user" or none of them must be marked as "set by user".

attributeValue ViInt64

Pass the value which you want to verify as a valid value for the attribute given the current settings of the instrument session.

If the attribute currently showing in the Attribute ID ring control has named constants as valid values, you can bring up a list of them on this control by pressing <ENTER>. Select a value by double-clicking on it or by highlighting it and then pressing <ENTER>. Some of the values might not be valid depending on the current settings of the instrument session.

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