Inherent IVI Attributes
Inherent IVI attributes are attributes that the IVI Engine defines for all IVI sessions. The following table shows the IVI attributes in their defined constants.
Inherent IVI Attributes
| Attribute | Defined Constant |
|---|---|
| Cache | IVI_ATTR_CACHE |
| Channel Count | IVI_ATTR_CHANNEL_COUNT |
| Check Status Callback | IVI_ATTR_CHECK_STATUS_CALLBACK |
| Driver Setup | IVI_ATTR_DRIVER_SETUP |
| Class Group Capabilities | IVI_ATTR_GROUP_CAPABILITIES |
| Instrument Firmware Revision | IVI_ATTR_INSTRUMENT_FIRMWARE_REVISION |
| Instrument Manufacturer | IVI_ATTR_INSTRUMENT_MANUFACTURER |
| Instrument Model | IVI_ATTR_INSTRUMENT_MODEL |
| Interchange Check | IVI_ATTR_INTERCHANGE_CHECK |
| I/O Resource Descriptor | IVI_ATTR_IO_RESOURCE_DESCRIPTOR |
| Logical Name | IVI_ATTR_LOGICAL_NAME |
| Operation Complete Callback | IVI_ATTR_OPC_CALLBACK |
| Query Instrument Status | IVI_ATTR_QUERY_INSTRUMENT_STATUS |
| Range Check | IVI_ATTR_RANGE_CHECK |
| Record Value Coercions | IVI_ATTR_RECORD_COERCIONS |
| Simulate | IVI_ATTR_SIMULATE |
| Class Specification Major Version | IVI_ATTR_SPECIFIC_DRIVER_CLASS_SPEC_MAJOR_ VERSION |
| Class Specification Minor Version | IVI_ATTR_SPECIFIC_DRIVER_CLASS_SPEC_MINOR_ VERSION |
| Specific Driver Description | IVI_ATTR_SPECIFIC_DRIVER_DESCRIPTION |
| Specific Driver Prefix | IVI_ATTR_SPECIFIC_DRIVER_PREFIX |
| Specific Driver Revision | IVI_ATTR_SPECIFIC_DRIVER_REVISION |
| Specific Driver Vendor | IVI_ATTR_SPECIFIC_DRIVER_VENDOR |
| Supported Instrument Models | IVI_ATTR_SUPPORTED_INSTRUMENT_MODELS |
| System | IVI_ATTR_SYSTEM_IO_SESSION |
| Timeout | IVI_ATTR_SYSTEM_IO_TIMEOUT |
| VISA Resource Manager Session | IVI_ATTR_VISA_RM_SESSION |
Inherent Attribute Reference
This section contains detailed descriptions of the inherent IVI attributes. The attributes are arranged alphabetically. The description of each attribute indicates restrictions on its use. Specific instrument driver include files must not export any inherent attributes that are marked as hidden from the user.
IVI_ATTR_CACHE
Data Type: ViBoolean
Restrictions: None
Specifies whether to cache the value of attributes. When the user enables caching, the IVI Engine keeps track of the current instrument settings so that it can avoid sending redundant commands to the instrument. Caching can significantly increase execution speed.
The user specifies the value of IVI_ATTR_CACHE. For a particular attribute, however, the driver can override the value of IVI_ATTR_CACHE by setting the IVI_VAL_NEVER_CACHE or IVI_VAL_ALWAYS_CACHE flag for the attribute.
The default value is VI_TRUE. If the user opens an instrument session by passing a logical name, the user can override the default value by using MAX to specify a value. Instrument drivers provide a Prefix_InitWithOptions function that users can call to override both the default value and any value specified in MAX.
IVI_ATTR_CHANNEL_COUNT
Data Type: ViInt32
Restrictions: Read-only
Indicates the number of channels that the specific instrument driver supports.
For each attribute for which the IVI_VAL_MULTI_CHANNEL flag attribute is set, the IVI Engine maintains a separate cache value for each channel.
IVI_ATTR_CHECK_STATUS_CALLBACK
Data Type: ViAddr
Restrictions: Hidden from user
Specifies the check status callback for the session. The check status callback queries the instrument status.
If the user enables the IVI_ATTR_QUERY_INSTR_STATUS attribute, the specific driver calls the check status callback at the end of each user-callable function that interacts with the instrument. The IVI Engine invokes the check status callback when the user calls one of the Prefix_SetAttribute or Prefix_GetAttribute functions that the driver provides.
The default value is VI_NULL. Leave the value as VI_NULL if you do not want a check status callback.
IVI_ATTR_DRIVER_SETUP
Data Type: ViString
Restrictions: Read-only, hidden from user
Some cases exist where the user must specify instrument driver options at initialization time. An example is when a user specifies a particular instrument model from among a family of instruments that the driver supports. Specification of driver options at initialization time is useful when using simulation. The user can specify driver-specific options through the DriverSetup keyword in the optionsString parameter to the Prefix_InitWithOptions function. If the user opens an instrument session by passing a logical name, the user also can specify the options in MAX.
The default value is an empty string.
IVI_ATTR_GROUP_CAPABILITIES
Data Type: ViString
Restrictions: Not writable by user
A comma-separated string that identifies the instrument class and the class-extension groups that the specific instrument driver implements.
IVI_ATTR_INSTRUMENT_FIRMWARE_REVISION
Data Type: ViString
Restrictions: Read-only
Returns an instrument specific string that contains the firmware revision information of the physical instrument. The IVI specific driver returns the value it queries from the instrument as the value of this attribute.
In some cases, it is not possible for the specific driver to query the firmware revision of the instrument. This can occur when IVI_ATTR_SIMULATE is set to True or if the instrument is not capable of returning the firmware revision. For these cases, the specific driver returns defined strings for this attribute. If IVI_ATTR_SIMULATE is set to True, the specific driver returns Not available while simulating as the value of this attribute. If the instrument is not capable of returning the firmware version and IVI_ATTR_SIMULATE is set to False, the specific driver returns Cannot query from instrument as the value of this attribute.
The string that this attribute returns does not have a predefined maximum length.
IVI_ATTR_INSTRUMENT_MANUFACTURER
Data Type: ViString
Restrictions: Read-only
Returns the name of the manufacturer of the instrument. The IVI specific driver returns the value it queries from the instrument as the value of this attribute.
In some cases, it is not possible for the IVI specific driver to query the manufacturer of the instrument. This can occur when IVI_ATTR_SIMULATE is set to True or if the instrument is not capable of returning the manufacturer's name. For these cases, the specific driver returns the defined strings for this attribute.
The string that this attribute returns contains a maximum of 256 bytes including the NUL byte.
IVI_ATTR_INSTRUMENT_MODEL
Data Type: ViString
Restrictions: Read-only
Returns the model number or name of the physical instrument. The IVI specific driver returns the value it queries from the instrument as the value of this attribute.
In some cases, it is not possible for the IVI specific driver to query the model number of the instrument. This can occur when IVI_ATTR_SIMULATE is set to True or if the instrument is not capable of returning the model number. For these cases, the specific driver returns defined strings for these attribute.
The string that this attribute returns contains a maximum of 256 bytes including the NUL byte.
IVI_ATTR_INTERCHANGE_CHECK
Data Type: ViBoolean
Restrictions: None
Specifies whether the class driver performs interchangeability checking. Each instrument class specification defines the rules for interchangeability checking for that class.
The user specifies the value of IVI_ATTR_INTERCHANGE_CHECK.
The default value is VI_TRUE. If the user opens an instrument session by passing a logical name, the user can override the default value by using MAX to specify a value. Instrument drivers provide a Prefix_InitWithOptions function that users can call to override both the default value and any value specified in MAX.
If the user opens an instrument session through a specific driver, the IVI Engine generates an error when you attempt to set or get this attribute.
IVI_ATTR_IO_RESOURCE_DESCRIPTOR
Data Type: ViString
Restrictions: Read-only
If the end-user opens the IVI session through a class driver, this attribute indicates the resource descriptor the class driver uses to identify the physical device to the specific driver. If the end-user opens an instrument session through a specific driver, the IVI engine generates an IVI_ERROR_NOT_CREATED_BY_CLASS error whenever you attempt to set or get this attribute.
IVI_ATTR_LOGICAL_NAME
Data Type: ViString
Restrictions: Read-only
When opening an IVI session through a class driver, the user passes a logical name to the class driver initialization function. The configuration store file must contain an entry for the logical name. The logical name entry refers to a driver session. The driver session specifies a physical device and a specific instrument driver. By assigning the name of a different driver session to the logical name in MAX, the user can swap one instrument for another without changing source code or recompiling or relinking the application program. This attribute indicates the logical name the user specified when opening the current IVI session.
IVI_ATTR_OPC_CALLBACK
Data Type: ViAddr
Restrictions: Hidden from user
Specifies the operation complete callback for the session. The operation complete callback waits until all pending instrument operations are complete.
If the IVI_VAL_WAIT_FOR_OPC_AFTER_WRITES flag is set for the attribute, the IVI Engine invokes the operation complete callback after invoking the write callback.
If the IVI_VAL_WAIT_FOR_OPC_BEFORE_READS flag is set for the attribute, the IVI Engine invokes the operation complete callback before invoking the read callback.
The default value is VI_NULL. Leave the value as VI_NULL if you do not want an operation complete callback.
IVI_ATTR_OPC_TIMEOUT
Data Type: ViInt32
Restrictions: Hidden from user
The driver uses this attribute internally to set the timeout for the OPC callback.
IVI_ATTR_QUERY_INSTRUMENT_STATUS
Data Type: ViBoolean
Restrictions: None
Specifies whether the instrument driver queries the instrument status after each user operation. The driver does so by calling the check status callback at the end of each user-callable function that interacts with the instrument. The IVI Engine also invokes the check status callback when the user calls one of the Prefix_SetAttribute or Prefix_GetAttribute functions that the instrument driver provides. Querying the instrument status is very useful for debugging. After validating the program, the user can set this attribute to VI_FALSE to disable status checking and maximize performance.
The user specifies the value of IVI_ATTR_QUERY_INSTRUMENT_STATUS. The driver, however, can prevent the IVI Engine from invoking the check status callback on a particular attribute by setting the IVI_VAL_DONT_CHECK_STATUS flag for the attribute.
The default value is VI_FALSE. If the user opens an instrument session by passing a logical name, the user can override the default value by using MAX to specify a value. Instrument drivers provide a Prefix_InitWithOptions function that users can call to override both the default value and any value specified in MAX.
The Ivi_QueryInstrStatus function provides convenient access to the value of this attribute.
IVI_ATTR_RANGE_CHECK
Data Type: ViBoolean
Restrictions: None
Specifies whether to validate attribute values and function parameters. If enabled, the instrument driver validates the parameter values that users pass to driver functions, and the IVI Engine validates values that the driver or users pass to SetAttribute functions. The IVI Engine uses the range table, range table callback, or check callback for each attribute to validate its values. Range checking parameters is useful for debugging. After validating the program, the user can set this attribute to VI_FALSE to disable range checking and maximize performance.
The user specifies the value of IVI_ATTR_RANGE_CHECK.
The default value is VI_TRUE. If the user opens an instrument session by passing a logical name, the user can override the default value by using MAX to specify a value. Instrument drivers provide a Prefix_InitWithOptions function that users can call to override both the default value and any value specified in MAX.
The Ivi_RangeChecking function provides convenient access to the value of this attribute.
IVI_ATTR_RECORD_COERCIONS
Data Type: ViBoolean
Restrictions: None
Specifies whether the IVI Engine keeps a list of the value coercions it makes for ViInt32, ViInt64, and ViReal64 attributes.
If the driver provides a coerced range table, a range table callback that returns a coerced range table, or a coerce callback for an attribute, the IVI Engine can coerce the values you specify for the attribute to canonical values the instrument accepts.
If the IVI_ATTR_RECORD_COERCIONS attribute is enabled, the IVI Engine maintains a record of each coercion. The user calls the Prefix_GetNextCoercionRecord function in the specific driver to extract and delete the oldest coercion record from the list.
The user specifies the value of IVI_ATTR_RECORD_COERCIONS.
The default value is VI_FALSE. If the user opens an instrument session by passing a logical name, the user can override the default value by using MAX to specify a value. Instrument drivers provide a Prefix_InitWithOptions function that users can call to override both the default value and any value specified in MAX.
IVI_ATTR_RESOURCE_DESCRIPTOR
Data Type: ViString
Restrictions: Read-only
If the user opens the IVI session through a class driver, this attribute indicates the resource descriptor the class driver uses to identify the physical device to the specific driver.
If the user opens an instrument session through a specific driver, the IVI Engine generates an IVI_ERROR_NOT_CREATED_BY_CLASS error when you attempt to set or get this attribute.
IVI_ATTR_SIMULATE
Data Type: ViBoolean
Restrictions: None
Specifies whether to simulate instrument driver I/O operations. If simulation is enabled, specific instrument driver functions perform range checking and call Ivi_GetAttribute and Ivi_SetAttribute functions, but they do not perform instrument I/O. The IVI Engine does not invoke the read and write callbacks for attributes, except when the IVI_VAL_USE_CALLBACKS_FOR_SIMULATION flag is set for an attribute.
For output parameters that represent instrument data, the instrument driver functions return hardcoded values. If the user opens the session through a class driver, the class driver loads a special simulation driver to generate output data in a more sophisticated manner unless the user sets the IVI_ATTR_USE_SPECIFIC_SIMULATION attribute to VI_TRUE.
The user sets the value of IVI_ATTR_SIMULATE.
The default value is VI_FALSE. If the user opens an instrument session by passing a logical name, the user can override the default value by using MAX to specify a value. Instrument drivers provide a Prefix_InitWithOptions function that users can call to override both the default value and any value specified in MAX. If the user initializes a driver session with simulation enabled, attempting to set this attribute to VI_TRUE returns an error.
The Ivi_Simulating function provides convenient access to the value of this attribute.
IVI_ATTR_SPECIFIC_DRIVER_CLASS_SPEC_MAJOR_VERSION
Data Type: ViInt32
Restrictions: Read-only
Returns the major version number of the class specification in accordance with which the IVI specific driver was developed. The value is a positive integer value.
If the IVI specific driver is not compliant with a class specification, the specific driver returns zero as the value of this attribute.
IVI_ATTR_SPECIFIC_DRIVER_CLASS_SPEC_MINOR_VERSION
Data Type: ViInt32
Restrictions: Read-only
Returns the minor version number of the class specification in accordance with which the IVI specific driver was developed. The value is a non-negative integer value.
If the IVI specific driver is not compliant with a class specification, the specific driver returns zero as the value of this attribute.
IVI_ATTR_SPECIFIC_DRIVER_DESCRIPTION
Data Type: ViString
Restrictions: Read-only
Returns a brief description of the IVI specific driver.
The string that this attribute returns contains a maximum of 256 bytes including the NUL byte.
IVI_ATTR_SPECIFIC_DRIVER_REVISION
Data Type: ViString
Restrictions: Read-only
Returns version information about the IVI specific driver. The Instrument Driver Wizard generates a read callback from this attribute. The read callback provides the proper format for the revision string.
The string that this attribute returns contains a maximum of 256 bytes including the NUL byte.
IVI_ATTR_SPECIFIC_DRIVER_VENDOR
Data Type: ViString
Restrictions: Read-only
Returns the name of the vendor that supplies the IVI specific driver.
The string that this attribute returns contains a maximum of 256 bytes including the NUL byte.
IVI_ATTR_SPECIFIC_PREFIX
Data Type: ViString
Restrictions: Read-only
The prefix for the specific instrument driver. The maximum character length for the prefix is eight characters.
The name of each user-callable function in the specific driver begins with this prefix. For example, if the Fluke 45 driver has a user-callable function named FL45_init, FL45 is the prefix for that driver.
IVI_ATTR_SUPPORTED_INSTRUMENT_MODELS
Data Type: ViString
Restrictions: Read-only
Returns a comma-separated list of names of instrument models with which the IVI specific driver is compatible. The string has no white space except possibly embedded in the instrument model names. An example of a string that this attribute might return is TKTDS3012, TKTDS3014, TKTDS3016.
It is not necessary for the string to include the abbreviation for the manufacturer if it is the same for all models. In the example above, it is valid for the attribute to return the string TDS3012, TDS3014, TDS3016.
The string that this attribute returns does not have a predefined maximum length.
IVI_ATTR_SYSTEM_IO_SESSION
Data Type: ViSession
Restrictions: Not writable by user
Specifies the I/O session that the specific driver uses to communicate with the instrument.
If a specific driver uses VISA instrument I/O, the driver passes the value of the IVI_ATTR_VISA_RM_SESSION attribute to the viOpen function and sets the IVI_ATTR_SYSTEM_IO_SESSION attribute to the VISA session handle that viOpen returns.
The IVI Engine passes the value of IVI_ATTR_SYSTEM_IO_SESSION to the read and write callbacks the specific driver installs for its attributes. The Ivi_IOSession function provides convenient access to the value of this attribute.
IVI_ATTR_SYSTEM_IO_TIMEOUT
Data Type: ViInt32
Restrictions: None
Specifies the I/O timeout.
IVI_ATTR_USE_SPECIFIC_SIMULATION
Data Type: ViBoolean
Restrictions: Hidden from user
Specifies whether to simulate instrument driver I/O operations in the specific or class driver. This attribute affects instrument driver operation only when the IVI_ATTR_SIMULATE is set to VI_TRUE and when the specific driver is being used through a class driver. The default value is VI_TRUE. If the user initializes a driver session with simulation enabled, attempting to set the this attribute to VI_TRUE returns an error.
IVI_ATTR_VISA_RM_SESSION
Data Type: ViSession
Restrictions: Read-only, hidden from user
If a specific driver uses VISA instrument I/O, it passes the value of this attribute to the viOpen function during initialization. The viOpen function returns an instrument I/O session, which the driver stores in the IVI_ATTR_SYSTEM_IO_SESSION attribute.