White Paper

IVI Configuration Store

November 2006
Stephen J. Greer
Agilent Technologies, Inc.

The IVI Configuration Store holds information about IVI drivers installed on the
computer and configuration information for an instrument system. If you installed
the IVI Shared Components in the default location, you can find the configuration
information in a file named IviConfigurationStore.xml in C:\Program Files\IVI\Data.
Recent versions of Microsoft Internet Explorer can display xml files. If you double-
click on the file, a copy of Internet Explorer should start and show the contents of
the file.
You can use IVI drivers successfully, accessing their capabilities, without ever using
the Configuration Store. If, however, you want to use the IVI Session Factory or use
a Logical Name instead of a Resource Descriptor you must make some entries into
the Configuration Store. A HardwareAsset allows you to assign a name to a resource
descriptor. A DriverSession collects a specific driver, through a SoftwareModule, a
HardwareAsset, and initialization information all under one name. If you have
installed one or more IVI drivers, their information appears in the SoftwareModules.
A LogicalName allows a further abstraction for a Session with its own name. By
adding these three elements to a Configuration Store you can create and reference
an IVI driver using the names in the Configuration Store.

One of the COM servers supplied with the IVI Shared Components is the IVI
Configuration Server. It provides a safe, reliable means to modify the contents of the
Configuration Store. While you could edit the xml contents in a number of editors,
accessing the file with the Configuration Server guarantees that the contents are
valid xml, adhere to the schema in IviConfigurationStore.xsd, and comply with
other IVI rules.

Since the Configuration Server is a COM server, it can be used in a number of

programming environments which support COM programming. One environment
especially well suited to COM is Microsoft Visual Basic® so code examples appear in
that language. These examples add a HardwareAsset, a DriverSession, and a
LogicalName which allow you to use the IVI Session Factory with a driver.

The following instructions were validated for Visual Basic in Visual Studio 2005.

Adding a Reference
Before using any COM server in Visual Basic, you must add a reference to it. Under
the Project menu, select Add References. Select the COM tab. In the list of “Available
References,” scroll down to “Ivi Configuration Server 1.0 Type Library”. Select to
highlight it and hit OK.
IVI Configuration Store White Paper November 2006

Creating a Configuration Server Object

You create an instance of the Configuration Server the same way as other COM
servers. This line of code creates an instance of a Configuration Store data structure
in memory which exposes all the methods and properties implemented by the
Configuration Server.

Dim cs As New Ivi.ConfigServer.Interop.IviConfigStore

Loading the Configuration Store

You could start operating on the empty copy of a Configuration Store. If, however,
you want to access data already entered into a commonly known copy, you must
first load that file into memory with the Deserialize method.

' Deserialize the master configuration store.

cs.Deserialize (cs.MasterLocation)

The MasterLocation property contains the complete path to the master file. The
Deserialize method reads the file into memory while validating its contents. If
something is wrong with the contents, the Configuration Server throws an error. You
can trap the error with code like:
On Error GoTo DeserializeError
cs.Deserialize (cs.MasterLocation)
On Error GoTo 0
. . .

' Error handler for reading configuration store

DeserializeError:
MsgBox ("Could not deserialize configuration store from MasterLocation" +
vbCrLf + Err.Description, MsgBoxStyle.Exclamation)

Adding a HardwareAsset
One of the objects you can add is a HardwareAsset. It contains address information
about an actual instrument in the system. This code creates the object and sets its
properties:

' Create an empty Hardware Asset

Dim ha As New Ivi.ConfigServer.Interop.IviHardwareAsset
' Set its properties
ha.Name = “Agilent34401”
ha.Description = “Multimeter connected to the switch”
ha.IOResourceDescriptor = “GPIB::22::INSTR”

The Name property will be referenced in a DriverSession object so it should be

relatively short and easy to remember. You cannot use the same name for multiple
HardwareAssets. The Description property can be any string which describes this
particular instrument. The IOResourceDescriptor is used by the driver when it calls
the VISA Open routine. This string must be a syntactically valid VISA resource
descriptor though its validity is not checked until you call the driver’s Initialize
routine.

The next step is to add this object to the Configuration Store loaded into memory.

2 of 11
IVI Configuration Store White Paper November 2006

' Add it to the global hardware asset collection

On Error GoTo DuplicateHardwareAsset
cs.HardwareAssets.Add ha
. . .

' Error handler for duplicate hardware assets

DuplicateHardwareAsset:
MsgBox ("Could not add HardwareAsset with the name " + ha.Name _
+ vbCrLf + Err.Description, MsgBoxStyle.Exclamation)

Since HardwareAsset names must be unique, the Configuration Server will throw an
error if you try to add one with the same name as one already in the HardwareAssets
collection. If the Add method succeeds, this HardwareAsset would appear in the xml
as:

<HardwareAssets>
<IviHardwareAsset id="p28">
<Name>Agilent34401</Name>
<Description>Multimeter connected to the switch</Description>
<DataComponents />
<IOResourceDescriptor>GPIB::22::INSTR</IOResourceDescriptor>
</IviHardwareAsset>
</HardwareAssets>

The id number will probably be different as it is assigned by the Configuration

Server.

Adding a DriverSession
Another object you can add is a DriverSession. It contains information used by the
IVI Session Factory to create an instance of an IVI-COM driver. Data in a
DriverSession object is also used by the Initialize function. You could create an
instance and set its properties using:

' Create the Session and fill in the DriverSession object properties
Dim ds As New Ivi.ConfigServer.Interop.IviDriverSession
ds.Name = “Agilent34401”
ds.Description = “DriverSession for the system multimeter”
ds.Cache = True
ds.InterchangeCheck = False
ds.QueryInstrStatus = False
ds.RangeCheck = True
ds.RecordCoercions = False
ds.Simulate = False
ds.DriverSetup = “”

' Add the HardwareAsset reference to the Session

On Error GoTo GettingHardwareAsset
Set ds.HardwareAsset = cs.HardwareAssets.Item(“Agilent34401”)

' Add the SoftwareModule reference to the Session.

On Error GoTo GettingSoftwareModule
Set ds.SoftwareModule = cs.SoftwareModules.Item(“Agilent34401”)

The Name and Description properties are similar in function to those in a

HardwareAsset. Notice that this DriverSession’s name is the same as the one used
for the HardwareAsset. While this name must be unique among the DriverSessions,
it can be the same as a name used in other collections.

3 of 11
IVI Configuration Store White Paper November 2006

The Cache, InterChangeCheck, QueryInstrStatus, RangeCheck, RecordCoercions,

Simulate, and DriverSetup properties allow you to override their default values
without having to explicitly set them in the OptionString parameter to Initialize. In
this example, they are set to the default values.

The HardwareAsset property must be set to a HardwaredAsset which already exists

in the HardwareAssets collection. Here we use the name of the HardwareAsset
created earlier. If a HardwareAsset of that name cannot be found, the Configuration
Server throws an error.

As with the HardwareAsset property, the SoftwareModule property must reference a

SoftwareModule already present in the SoftwareModules collection. An IVI driver’s
installation is required to add a SoftwareModule to the Configuration Store which
contains information about the IVI driver. You should never add nor edit a
SoftwareModule, but you need to know their names in order to set the
SoftwareModule property in a DriverSession.

The next step is to add this object to the Configuration Store loaded into memory.

' Add it to the global driver session collection

On Error GoTo DuplicateDriverSession
cs.DriverSessions.Add ds
. . .

' Error handler for duplicate driver sessions

DuplicateDriverSession:
MsgBox ("Could not add DriverSession with the name " + ds.Name _
+ vbCrLf + Err.Description, MsgBoxStyle.Exclamation)

As with HardwareAssets, DriverSession names must be unique or the Configuration

Server throws an error if you try to add one with the same name as one already in
the DriverSessions collection. If the Add method succeeds, this DriverSession would
appear in the xml as:

<DriverSessions>
<IviDriverSession id="p30">
<Name>Agilent34401</Name>
<Description>DriverSession for the system multimeter</Description>
<DataComponents />
<IviHardwareAsset idref="p28" />
<IviSoftwareModuleRef idref="p8" />
<VirtualNames />
<SoftwareModuleName>Agilent34401</SoftwareModuleName>
<Cache>1</Cache>
<DriverSetup />
<InterchangeCheck>0</InterchangeCheck>
<QueryInstrStatus>0</QueryInstrStatus>
<RangeCheck>1</RangeCheck>
<RecordCoercions>0</RecordCoercions>
<Simulate>0</Simulate>
</IviDriverSession>
</DriverSession>

The id number will probably be different as it is assigned by the Configuration

Server. The idref values for IviHardwareAsset and IviSoftwareModuleRef match id
entries already existing in the Configuration Store. The Configuration Store uses 1
for true and 0 for false.

4 of 11
IVI Configuration Store White Paper November 2006

Adding a LogicalName
The final object we’ll add is a LogicalName. It allows an additional level of abstraction
from an actual instrument. While a DriverSession must contain information about a
specific instrument in the system, a LogicalName does not. A LogicalName can be
easily re-configured to reference a different DriverSession and thus a different
physical instrument.

You could create an instance and set its properties using:

' Create the Logical Name

Dim ln As New Ivi.ConfigServer.Interop.IviLogicalName
' Set its properties
ln.Name = “DMM”
ln.Description = “The name used in the test program”

On Error GoTo GettingSessionError

Set ln.Session = cs.Sessions.Item(“Agilent34401”)

The Name and Description properties are again similar to those in a HardwareAsset
or DriverSession. The Name must be unique among all the LogicalNames.

A LogicalName must reference a Session already in the Configuration Store. As we

retrieved a HardwareAsset for a DriverSession, here we get a reference to a Session
using the name of the Session. If a Session of that name does not exist, the
Configuration Server throws an error. The DriverSession class derives from the
Session class and thus is a more specific form of a Session and can be used
wherever a Session is required.

We next add this LogicalName object to the Configuration Store with:

' Add it to the global logical name collection

On Error GoTo DuplicateLogicalNames
cs.LogicalNames.Add ln
. . .

' Error handler for duplicate Logical Names

DuplicateLogicalNames:
MsgBox ("Could not add LogicalName with the name " + ln.Name _
+ vbCrLf + Err.Description, MsgBoxStyle.Exclamation)

If the Add succeeds, the LogicalName entry would appear in the xml as:

<LogicalNames>
<IviLogicalName id="p32">
<Name>DMM</Name>
<Description>The name used in the test program</Description>
<IviDriverSession idref="p29" />
</IviLogicalName>
</LogicalNames>

Saving the Configuration Store

We are finished changing the contents of the Configuration Store and now we should
save it so drivers and other programs can access the new information. Writing to a
file is accomplished with the Serialize method in code like:

5 of 11
IVI Configuration Store White Paper November 2006

' Overwrite the master with the modified configuration store

On Error GoTo SerializeError
cs.Serialize (cs.MasterLocation)

This code writes to the path contained in the MasterLocation property and thus
overwrites the file we read earlier. As with any write operation to a file, something
can go wrong which causes the Configuration Server to throw an error. You can
handle the error with code like:

' Error handler for writing configuration store

SerializeError:
MsgBox ("Could not serialize configuration store into MasterLocation" +
vbCrLf + Err.Description, MsgBoxStyle.Exclamation)

Removing Objects
Sometime you will need to remove an object. The objects we added can be deleted
by using the Remove method on the various collections. To remove the LogicalName
added by this example you could use:

' Remove a LogicalName from the global collection

On Error GoTo RemoveError
cs.LogicalNames.Remove “DMM”
. . .

' Error handler for removing LogicalName

RemoveError:
MsgBox ("Could not remove LogicalName with name " + ln.Name + vbCrLf _
+ Err.Description, MsgBoxStyle.Exclamation)

If you attempt to remove an object which does not exist, the Configuration Server
will throw an error. A HardwareAsset or DriverSession can be removed using similar
code.

Complete Program
The various code snippets can be combined into a complete subroutine. A more
elegant program would not hard code the values for the properties, but extract them
from user entered data.

Private Sub ModifyConfigurationStore()

' Deserialize the master configuration store.
Dim cs As New Ivi.ConfigServer.Interop.IviConfigStore
On Error GoTo DeserializeError
cs.Deserialize (cs.MasterLocation)
On Error GoTo 0

' Create an empty Hardware Asset

Dim ha As New Ivi.ConfigServer.Interop.IviHardwareAsset
' Set its properties
ha.Name = "Agilent34401"
ha.Description = "Multimeter connected to the switch"
ha.IOResourceDescriptor = "GPIB::22::INSTR"

' Add it to the global hardware asset collection

On Error GoTo DuplicateHardwareAsset
cs.HardwareAssets.Add ha

' Create the Session and fill in the DriverSession object properties
Dim ds As New Ivi.ConfigServer.Interop.IviDriverSession

6 of 11
IVI Configuration Store White Paper November 2006

ds.Name = "Agilent34401"
ds.Description = "DriverSession for the system multimeter"
ds.Cache = True
ds.InterchangeCheck = False
ds.QueryInstrStatus = False
ds.RangeCheck = True
ds.RecordCoercions = False
ds.Simulate = False
ds.DriverSetup = ""

' Add the HardwareAsset reference to the Session

On Error GoTo GettingHardwareAsset
Set ds.HardwareAsset = cs.HardwareAssets.Item("Agilent34401")

' Add the SoftwareModule reference to the Session.

On Error GoTo GettingSoftwareModule
Set ds.SoftwareModule = cs.SoftwareModules.Item("Agilent34401")

' Add it to the global driver session collection

On Error GoTo DuplicateDriverSession
cs.DriverSessions.Add ds

' Create the Logical Name

Dim ln As New Ivi.ConfigServer.Interop.IviLogicalName
' Set its properties
ln.Name = "DMM"
ln.Description = "The name used in the test program"

On Error GoTo GettingSessionError

Set ln.Session = cs.Sessions.Item("Agilent34401")

' Add it to the global logical name collection

On Error GoTo DuplicateLogicalNames
cs.LogicalNames.Add ln

' Overwrite the master with the modified configuration store

On Error GoTo SerializeError
cs.Serialize (cs.MasterLocation)

Exit Sub

' Error handler for reading configuration store

DeserializeError:
MsgBox ("Could not deserialize configuration store from MasterLocation" +
vbCrLf _
+ Err.Description, MsgBoxStyle.Exclamation)
Exit Sub

' Error handler for duplicate hardware assets

DuplicateHardwareAsset:
MsgBox ("Could not add HardwareAsset with the name " + ha.Name _
+ vbCrLf + Err.Description, MsgBoxStyle.Exclamation)
Exit Sub

' Error handler for getting a hardware asset

GettingHardwareAsset:
MsgBox ("Could not find HardwareAsset with the name " + ds.HardwareAsset.Name
+ vbCrLf _
+ Err.Description, MsgBoxStyle.Exclamation)
Exit Sub

' Error handle for getting a software module

GettingSoftwareModule:

7 of 11
IVI Configuration Store White Paper November 2006

MsgBox ("Could not find SoftwareModule with the name " +

ds.SoftwareModule.Name + vbCrLf _
+ Err.Description, MsgBoxStyle.Exclamation)
Exit Sub

' Error handler for duplicate driver sessions

DuplicateDriverSession:
MsgBox ("Could not add DriverSession with the name " + ds.Name _
+ vbCrLf + Err.Description, MsgBoxStyle.Exclamation)
Exit Sub

' Error handler for getting a Session

GettingSessionError:
MsgBox ("Could not find Session with the name " + ln.Session.Name + vbCrLf _
+ Err.Description, MsgBoxStyle.Exclamation)
Exit Sub

' Error handler for duplicate Logical Names

DuplicateLogicalNames:
MsgBox ("Could not add LogicalName with the name " + ln.Name _
+ vbCrLf + Err.Description, MsgBoxStyle.Exclamation)
Exit Sub

' Error handler for writing configuration store

SerializeError:
MsgBox ("Could not serialize configuration store into MasterLocation" _
+ vbCrLf + Err.Description, MsgBoxStyle.Exclamation)
Exit Sub
End Sub

Using Configuration Store Information

The IVI Foundation supplies a shared component, IVI Session Factory, which reads
information from the Configuration Store and uses that information to create an
instance of an IVI-COM driver.

To use the Session Factory in Visual Basic you add a reference to “IviSessionFactory
1.0 Type Library” as we added a reference to the Configuration Server. You also
need a reference to any IVI Instrument Class used in the program. In this example,
we need a reference to “IviDmm 3.0 Type Library”. Assuming the Configuration
Store contains the information from this example, we can use the Session Factory
with this code:

Dim factory As New Ivi.SessionFactory.Interop.IviSessionFactory

Dim dmm As Ivi.Dmm.Interop.IIviDmm
Set dmm = factory.CreateDriver("DMM")
dmm.Initialize "DMM", False, False, ""

The CreateDriver method looks up the name “DMM” in the LogicalNames collection.
If it finds one, it uses the DriverSession referenced by the LogicalName. If the name
does not exist in LogicalNames, it next searches the DriverSessions collection for the
name. If the name is found, that DriverSession is used. If the name is not found in
either collection, the Session Factory throws an error. The SoftwareModule,
referenced by the DriverSession contains a property, ProgID, which the Session
Factory uses to create an instance of the Agilent34401 IVI-COM driver.

The same name is passed as a parameter to the Initialize method. The driver is
required to also look up “DMM” in the Configuration Store to retrieve information for

8 of 11
IVI Configuration Store White Paper November 2006

this particular instance of the driver. It uses the referenced HardwareAsset to get an
address for the instrument.

Notice that “Agilent34401” does not appear anywhere in the code. All the information
needed to create and initialize the driver is contained in the Configuration Store.

Additional Considerations
The Configuration Store and Server have additional capabilities beyond those
illustrated in these examples. Those capabilities include:

1. Editing existing objects without creating a new object.

2. Mapping of VirtualNames in a DriverSession to PhysicalNames in a

SoftwareModule.

3. Creating and setting DataComponents which can appear in nearly every

object.

4. Using a Configuration Store other than the one in the Master Location.

While these topics are beyond the scope of this paper, you can consult the IVI
specification, “IVI-3.5: Configuration Server Specification,” available from
http://www.ivifoundation.org/Downloads/Specifications.htm for more details.

Configuration Server and C++

If you prefer programming in Microsoft Visual C++®, the following program adds the
same information to the Configuration Store as the Visual Basic program. It uses the
powerful COM programming technique of smart pointers. For the compiler to find
IviConfigServer.dll, you must add the path to the file, typically C:\Program
Files\Ivi\Bin, to your Include path.

#include "stdafx.h"
#import "IviConfigServer.dll"
using namespace IVICONFIGSERVERLib;

int main(int argc, char* argv[])

{
HRESULT hr;
hr = CoInitializeEx(NULL,COINIT_APARTMENTTHREADED );
if(FAILED(hr))
exit(1);
{
IIviConfigStorePtr cs(__uuidof(IviConfigStore));
try{
// Deserialize the master configuration store.
cs->Deserialize(cs->MasterLocation);
try{
// Create an empty Hardware Asset
IIviHardwareAssetPtr ha(__uuidof(IviHardwareAsset));
//Set its properties
ha->Name = _bstr_t("Agilent34401");
ha->Description = _bstr_t("Multimeter connected to the switch");
ha->IOResourceDescriptor = _bstr_t("GPIB::22::INSTR");
// Add it to the global hardware asset collection

9 of 11
IVI Configuration Store White Paper November 2006

cs->HardwareAssets->Add(ha);
} catch (_com_error e) {
printf("Add HardwareAsset failed.\n");
printf("Error description is: %s\n",(char*)e.Description());
}
try{
// Create an empty DriverSession
IIviDriverSessionPtr ds(__uuidof(IviDriverSession));
// Set its properties
ds->Name = _bstr_t("Agilent34401");
ds->Description = _bstr_t("DriverSession for the system multimeter");
ds->Cache = true;
ds->InterchangeCheck = false;
ds->QueryInstrStatus = false;
ds->RangeCheck = true;
ds->RecordCoercions = false;
ds->Simulate = false;
ds->DriverSetup = _bstr_t("");
// Add the HardwareAsset reference to the Session
ds->HardwareAsset = cs->HardwareAssets->Item["Agilent34401"];
// Add the SoftwareModule reference to the Session.
ds->SoftwareModule = cs->SoftwareModules->Item["Agilent34401"];
// Add it to the global driver session collection
cs->DriverSessions->Add(ds);
} catch (_com_error e) {
printf("Add DriverSession failed.\n");
printf("Error description is: %s\n",(char*)e.Description());
}
try{
// Create the Logical Name
IIviLogicalNamePtr ln(__uuidof(IviLogicalName));
// Set its properties
ln->Name = _bstr_t("DMM");
ln->Description = _bstr_t("The name used in the test program");
ln->Session = cs->Sessions->Item["Agilent34401"];
// Add it to the global logical name collection
cs->LogicalNames->Add(ln);
} catch (_com_error e) {
printf("Add LogicalName failed.\n");
printf("Error description is: %s\n",(char*)e.Description());
}
// Overwrite the master with the modified configuration store
try{
cs->Serialize(cs->MasterLocation);
} catch (_com_error e) {
printf("Serialize failed.\n");
printf("Error description is: %s\n",(char*)e.Description());
}
} catch (_com_error e) {
printf("Deserialize failed.\n");
printf("Error description is: %s\n",(char*)e.Description());
}
}
CoUninitialize();
return 0;
}

The contents of stdafx.h used to compile the program were:

// stdafx.h : include file for standard system include files,

// or project specific include files that are used frequently, but
// are changed infrequently
//

10 of 11
IVI Configuration Store White Paper November 2006

#if !defined(AFX_STDAFX_H__BA321FE9_D24E_4427_9B74_648FCE4FD9DF__INCLUDED_)
#define AFX_STDAFX_H__BA321FE9_D24E_4427_9B74_648FCE4FD9DF__INCLUDED_

#if _MSC_VER > 1000

#pragma once
#endif // _MSC_VER > 1000

#define WIN32_LEAN_AND_MEAN// Exclude rarely-used stuff from Windows headers

#ifndef _WIN32_WINNT
#define _WIN32_WINNT 0x0400
#endif

#include <stdio.h>

// TODO: reference additional headers your program requires here

//{{AFX_INSERT_LOCATION}}
// Microsoft Visual C++ will insert additional declarations immediately before
the previous line.

#endif //
!defined(AFX_STDAFX_H__BA321FE9_D24E_4427_9B74_648FCE4FD9DF__INCLUDED_)

Product and company names mentioned herein are trademarks or trade names of their respective
companies.
Microsoft, Internet Explorer, Visual Basic, and Visual C++ are either registered trademarks or trademarks
of Microsoft Corporation in the United States and/or other countries.

Agilent T&M Software and Connectivity

Agilent’s Test and Measurement software and connectivity products and solutions allow you to take time out of connecting
your instrument to your computer with tools based on PC standards, so you can focus on your tasks, not on your
connections. Visit:
http://www.agilent.com/find/connectivity
Product specifications and descriptions in this document subject to change without notice
© 2006 Agilent Technologies, Inc. All rights reserved.
First Published: January 2003
Revised: November 2006

11 of 11