IVI Configuration Store

(1)

IVI Configuration Store

February 2003

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.

Adding a Reference

Before using any COM server in Visual Basic, you must add a reference to it. Under the Project menu, select References. In the list of “Available References,” scroll down to “IVI Configuration Server 1.0 Type Library” and check the box.

(2)

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 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, vbExclamation

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 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.

' Add it to the global hardware asset collection On Error GoTo DuplicateHardwareAsset

(3)

cs.HardwareAssets.Add ha . . .

' Error handler for duplicate hardware assets DuplicateHardwareAsset:

MsgBox "Could not add HardwareAsset with the name " + Name _ + vbCrLf + Err.Description, vbExclamation

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:

<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 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.

The Cache, InterChangeCheck, QueryInstrStatus, RangeCheck, RecordCoercions, Simulate, and DriverSetup properties allow you to override their default values

(4)

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 " + Name _ + vbCrLf + Err.Description, vbExclamation

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:

<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.

(5)

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 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 " + LogicalName _ + vbCrLf + Err.Description, vbExclamation

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

<Description>The name used in the test program</Description> <IviDriverSession idref="p29" />

</IviLogicalName> </LogicalNames>

(6)

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:

' 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, vbExclamation

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 " + Name + vbCrLf _ + Err.Description, vbExclamation

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 IviConfigStore

On Error GoTo DeserializeError cs.Deserialize (cs.MasterLocation) On Error GoTo 0

' Create an empty Hardware Asset Dim ha As New IviHardwareAsset ' Set its properties

ha.Name = "Agilent34401"

ha.Description = "Multimeter connected to the switch" ha.IOResourceDescriptor = "GPIB::22::INSTR"

(7)

' 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 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") ' Add it to the global driver session collection

On Error GoTo DuplicateDriverSession cs.DriverSessions.Add ds

' Create the Logical Name Dim ln As New 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, vbExclamation Exit Sub

' Error handler for duplicate hardware assets DuplicateHardwareAsset:

MsgBox "Could not add HardwareAsset with the name " + Name _ + vbCrLf + Err.Description, vbExclamation

Exit Sub

(8)

GettingHardwareAsset:

MsgBox "Could not find HardwareAsset with the name " + HwAsset + vbCrLf _ + Err.Description, vbExclamation

Exit Sub

' Error handle for getting a software module GettingSoftwareModule:

MsgBox "Could not find SoftwareModule with the name " + SwModule + vbCrLf _ + Err.Description, vbExclamation

Exit Sub

' Error handler for duplicate driver sessions DuplicateDriverSession:

MsgBox "Could not add DriverSession with the name " + Name _ + vbCrLf + Err.Description, vbExclamation

Exit Sub

' Error handler for getting a Session GettingSessionError:

MsgBox "Could not find Session with the name " + Session + vbCrLf _ + Err.Description, vbExclamation

Exit Sub

' Error handler for duplicate Logical Names DuplicateLogicalNames:

MsgBox "Could not add LogicalName with the name " + LogicalName _ + vbCrLf + Err.Description, vbExclamation

Exit Sub

' Error handler for writing configuration store SerializeError:

MsgBox "Could not serialize configuration store into MasterLocation" _ + vbCrLf + Err.Description, vbExclamation

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 IviSessionFactory Dim dmm As 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,

(9)

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 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 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/ApprovedSpecs/Default.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);

(10)

// 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 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");

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);

printf("Add LogicalName failed.\n");

// Overwrite the master with the modified configuration store try{

cs->Serialize(cs->MasterLocation); } catch (_com_error e) {

printf("Serialize failed.\n");

printf("Deserialize failed.\n");

}

CoUninitialize(); return 0;

(11)

}

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

// #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, solutions and Agilent Developer Network 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