Initializing the IVI-C Driver


Boonton55xxx IVI Driver Reference

Initializing the IVI-C Driver

There are two basic ways to initialize the IVI-C driver -- invoking the Initialize function directly on the specific driver and using an IVI-C class driver. If the client application is to be interchangeable, then the appropriate class driver must be used. Class drivers require that the first parameter passed to the Initialize function be a logical name for the driver. Instantiating the driver by name keeps the client program from having any dependencies on a specific driver and enables the application to be interchangeable.

If interchangeability is not necessary for a particular client application, it is often simpler to initialize the IVI-C driver directly. This avoids the need for obtaining an IVI-C class driver from a 3rd-party vendor (since the IVI Foundation does not develop or distribute IVI-C class drivers). When using the specific driver directly, the client application will necessarily have references to the specific driver (through the use of the "Btn55xxx" in function call names and by directly references Btn55xxx.h and Btn55xxx.lib); For many applications, this is perfectly acceptable.

The examples below in the section describing the Initialize function will present both techniques for initializing an IVI-C driver.

The IVI-defined Initialize function offers a variety of options and parameters that control fundamental aspects of the driver's behavior. It is critical to understand what options are available and how they impact driver operation.

ResourceName

The resource name parameter can be a logical name present in the IVI Configuration Store or a physical resource descriptor. If the ResourceName is a logical name, then additional options stored in the IVI Configuration Store will be loaded and processed. This allows client code to reuse driver option settings and to keep the driver code as concise as possible, by removing settings that can be stored in the IVI Configuration Store. It is important to note that any parameters or options passed directly to the Initialize function via the OptionString parameter (discussed below) override any settings found in the IVI Configuration Store.

IdQuery

If this is enabled, the driver will query the instrument model and compare it with a list of instrument models that is supported by the driver. If the model is not supported, Initialize will fail with the IVI_ERROR_ID_QUERY_FAILED error code.

Reset

If this is enabled, the driver will perform a reset of the instrument. If the reset fails, Initialize will fail with the IVI_ERROR_RESET_FAILED error code.

OptionString

The OptionString allows the user to pass optional settings to the driver. These settings override any settings that are specified in the IVI Configuration Store. If the IVI Configuration Store is not used (a resource descriptor is passed as the ResourceName instead of a logical name) then any setting that is not specified has a default value as specified by IVI.

Option Name	Description	Default
QueryInstrStatus	Specifies whether the IVI specific driver queries the instrument status at the end of each user operation. Querying the instrument status is very useful for debugging. After validating the program, the user can set this attribute to False to disable status checking and maximize performance. The user specifies this value for the entire IVI driver session.	false
Simulate	Specifies whether or not the IVI specific driver simulates instrument driver I/O operations. If simulation is enabled, the specific driver functions do not perform instrument I/O. For output parameters that represent instrument data, the specific driver functions return simulated values.	false
Cache	Specifies whether or not to cache the value of attributes. When caching is enabled, the IVI specific driver keeps track of the current instrument settings so that it can avoid sending redundant commands to the instrument.	true
InterchangeCheck	Specifies whether the IVI specific driver performs interchangeability checking. If the Interchange Check attribute is enabled, the specific driver maintains a record of each interchangeability warning that it encounters. The user calls the Get Next Interchange Warning function to extract and delete the oldest interchangeability warning from the list.	false
RangeCheck	Specifies whether the IVI specific driver validates attribute values and function parameters. If enabled, the specific driver validates the parameter values that users pass to driver functions. Validating attribute values and function parameters is useful for debugging. After validating the program, the user can set this attribute to False to disable range checking and maximize performance.	true
RecordCoercions	Specifies whether the IVI specific driver keeps a list of the value coercions it makes for ViInt32 and ViReal64 attributes. If the Record Value Coercions attribute is enabled, the specific driver maintains a record of each coercion. The user calls the Get Next Coercion Record function to extract and delete the oldest coercion record from the list.	false
DriverSetup	Specifies additional settings supported by the driver, but not defined by IVI.	""

DriverSetup

This is used to specify settings that are supported by the driver but not defined by IVI. If the Options String parameter contains an assignment for the Driver Setup attribute, the Initialize function assumes that everything following 'DriverSetup=' is part of the assignment. The following settings are supported by the Boonton55xxx driver.

Option Name	Description	Values
Model	Instrument model to use during simulation.	Any model supported by the driver
Trace	Output trace log of all driver calls to an XML file in the same directory as the application executable accessing the driver.	true, false
TraceName	If specified, an XML trace file of the specified name is created each time the driver is initialized with tracing enabled. It is not necessary to include the .xml extension with the name. If not specified, tracing generates a unique XML trace file name based on the date and time. A new file is created each time the driver is initialized with tracing enabled.	String name
TraceArray	Specifies if array parameters should be traced.	true, false
TraceSizeMax	Specifies the maximum size of the trace log file in bytes. Once the file reaches this size, tracing will be turned off automatically by the driver. The default value is 1000000.	Numeric value in bytes
TraceArraySizeMax	Specifies the maximum number of elements to trace for array parameters. The default value is 10.	Numeric value in elements
TraceSaveInterval	Specifies how often the driver should save trace data to the trace log file. The value is specified in minutes. The default value is 1.	Numeric value in minutes

Example 1 (no range checking, no state caching) -- Initializing with an IVI-C Class Driver

The following code initializes the driver with default options, except for range checking and state caching which are turned off.

C++

Copy Code

#include "IviPwrMeter.h" // Class Driver header file
void main()
{
  ViStatus status;
  ViSession session;
  ViReal64 reading;
  // Initialize the driver using the IviPwrMeter session factory.
  // This code is interchangeable since no reference to the specific driver exists.
  status = IviPwrMeter_InitWithOptions("MyLogicalName", VI_TRUE, VI_TRUE, "", &session);
  // ... call driver functions
  status = IviPwrMeter_close(session);
}

Example 2 (simulation) -- Direct Driver Access

The following code initializes the driver in simulation mode and specifies the model to simulate.

C++