
Boonton55xxx IVI Driver Reference

Initializing the IVI-COM Driver

Initializing the IVI-COM driver proceeds in two steps. First, the IVI-COM driver must be instantiated and then the Initialize function is called. This topic explains these two steps along with the options available for each step.

There are two ways to instantiate the IVI-COM driver -- direct instantiation using the specific driver name, and using the COM Session Factory. If the client application is to be interchangeable, then the COM Session Factory must be used. This component exposes a CreateDriver function that accepts 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 instantiate the IVI-COM driver directly. The exact syntax for creating an instance of a COM component varies from language to language. For instance, the CreateInstance function can be used in C++ while the new operator is used in C# and Visual Basic.NET. In any event, the client application will have a direct reference to the specific driver, so the program would not be interchangeable. For many applications, this is perfectly acceptable.

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

Calling the Initialize Function

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 ResourceName 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 E_IVI_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 E_IVI_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) -- Instantiate with the COM Session Factory

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

C++

Copy Code

#import "IviDriverTypeLib.dll" no_namespace
#import "IviSessionFactory.dll" no_namespace
void main()
{
  try
  {
    // Create an instance of the driver using the session factory.
    // This code is interchangeable since no reference to the specific driver exists.
    IIviSessionFactory spFactory(__uuidof(IviSessionFactory));
    IIviDriverPtr spDriver = spFactory->CreateDriver(_T("MyLogicalName"));
    // Initialize the driver with no range checking and no state caching
    // This will also check the instrument ID to make sure it is supported
    // and reset the instrument
    spDriver->Initialize(_T("MyLogicalName"), VARIANT_TRUE, VARIANT_TRUE, _T("RangeCheck=false, Cache=false"));
    // Use the driver...
    // Close the session
    spDdriver->Close();
  }
  catch (_com_error&)
  {
  }
}

Copy Code

using System;
using System.Runtime.InteropServices;
using Ivi.Driver.Interop;
using Ivi.SessionFactory.Interop;
public class App
{
  public static void Main(string[] args)
  {
    try
    {
      // Create an instance of the driver using the session factory
      // This code is interchangeable since no reference to the specific driver exists.
      IIviSessionFactory factory = new IviSessionFactoryClass();
      IIviDriver driver = (IIviDriver)factory.CreateDriver("MyLogicalName");
      // Initialize the driver with no range checking and no state caching
      // This will also check the instrument ID to make sure it is supported
      // and reset the instrument
      driver.Initialize("MyLogicalName", true, true, "RangeCheck=false, Cache=false");
      // Use the driver...
      // Close the session
      driver.Close();
    }
    catch (Exception e)
    {
      Console.WriteLine(e.Message);
    }
  }
}

Example 2 (simulation) -- Direct Driver Instantiation

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

C++

Copy Code

#import "IviDriverTypeLib.dll" no_namespace
#import "IviSessionFactory.dll" no_namespace
#import "Boonton55xxx.dll" no_namespace
void main()
{
  try
  {
    // Instantiate the driver class directly
    IIviDriverPtr spDriver(__uuidof(Boonton55xxx)); // not interchangeable, using driver class name
    // Initialize the driver with no range checking and no state caching
    // This will also check the instrument ID to make sure it is supported
    // and reset the instrument
    spDriver->Initialize(_T("MyLogicalName"), VARIANT_TRUE, VARIANT_TRUE, _T("Simulate=true, DriverSetup= Model=55006"));
    // Use the driver ...
    // Close the session
    spDriver->Close();
  }
  catch (_com_error&)
  {
  }
}

Copy Code

using System;
using System.Runtime.InteropServices;
using Ivi.Driver.Interop;
using Ivi.SessionFactory.Interop;
using Boonton.Boonton55xxx.Interop;
public class App
{
  [STAThread]
  public static void Main(string[] args)
  {
    try
    {
      // Instantiate the driver class directly
      IIviDriver driver = new Boonton55xxxClass(); // not interchangeable, using driver class name
      // Initialize the driver with no range checking and no state caching
      // This will also check the instrument ID to make sure it is supported
      // and reset the instrument
      driver.Initialize("MyLogicalName", true, true, "Simulate=true, DriverSetup= Model=55006");
      // Use the class-compliant capabilities...
      // Close the session
      driver.Close();
    }
    catch (Exception e)
    {
      Console.WriteLine(e.Message);
    }
  }
}

Instantiating the IVI-COM Driver

Calling the Initialize Function

ResourceName

IdQuery

Reset

OptionString

DriverSetup

Example 1 (no range checking, no state caching) -- Instantiate with the COM Session Factory

Example 2 (simulation) -- Direct Driver Instantiation