Agilent Developer Network White Paper Stephen J. Greer Agilent Technologies, Inc. The 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 doubleclick 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.
Agilent Developer Network White Paper 2 of 11 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 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
Agilent Developer Network White Paper 3 of 11 cs.hardwareassets.add ha... ' Error handler for duplicate hardware assets DuplicateHardwareAsset: MsgBox "Could not add HardwareAsset with the name " + Name _ 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 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
Agilent Developer Network White Paper 4 of 11 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 _ 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.
Agilent Developer Network White Paper 5 of 11 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 _ 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>
Agilent Developer Network White Paper 6 of 11 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 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 _ 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"
Agilent Developer Network White Paper 7 of 11 ' 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) ' Error handler for reading configuration store DeserializeError: MsgBox "Could not deserialize configuration store from MasterLocation" + vbcrlf _ ' Error handler for duplicate hardware assets DuplicateHardwareAsset: MsgBox "Could not add HardwareAsset with the name " + Name _ ' Error handler for getting a hardware asset
Agilent Developer Network White Paper 8 of 11 GettingHardwareAsset: MsgBox "Could not find HardwareAsset with the name " + HwAsset + vbcrlf _ ' Error handle for getting a software module GettingSoftwareModule: MsgBox "Could not find SoftwareModule with the name " + SwModule + vbcrlf _ ' Error handler for duplicate driver sessions DuplicateDriverSession: MsgBox "Could not add DriverSession with the name " + Name _ ' Error handler for getting a Session GettingSessionError: MsgBox "Could not find Session with the name " + Session + vbcrlf _ ' Error handler for duplicate Logical Names DuplicateLogicalNames: MsgBox "Could not add LogicalName with the name " + LogicalName _ ' Error handler for writing configuration store SerializeError: MsgBox "Could not serialize configuration store into MasterLocation" _ 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,
Agilent Developer Network White Paper 9 of 11 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); try{
Agilent Developer Network White Paper 10 of 11 // 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"); 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;
Agilent Developer Network White Paper 11 of 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 Product specifications and descriptions in this document subject to change without notice 2003 Agilent Technologies, Inc. All rights reserved. Published: January 2003