Ivi-3.5 Configuration Server V1
This document was uploaded by user and they confirmed that they have the permission to share it. If you are author or own the copyright of this book, please report to us by using this DMCA report form. Report DMCA
Overview
Download & View Ivi-3.5 Configuration Server V1 as PDF for free.
More details
- Words: 32,745
- Pages: 188
IVI
Interchangeable Virtual Instruments
IVI-3.5: Configuration Server Specification
November 7, 2002 Revision 1.0
IVI-3.5: IVI Configuration Server Specification
2
IVI Foundation
Important Information The IVI Configuration Server Specification (IVI-3.5) is authored by the IVI Foundation member companies. For a vendor membership roster list, please visit the IVI Foundation web site at www.ivifoundation.org, or contact the IVI Foundation at 2515 Camino del Rio South, Suite 340, San Diego, CA 92108. The IVI Foundation wants to receive your comments on this specification. You can contact the Foundation through email at [email protected], through the web site at www.ivifoundation.org, or you can write to the IVI Foundation, 2515 Camino del Rio South, Suite 340, San Diego, CA 92108. Warranty The IVI Foundation and its member companies make no warranty of any kind with regard to this material, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The IVI Foundation and its member companies shall not be liable for errors contained herein or for incidental or consequential damages in connection with the furnishing, performance, or use of this material. Trademarks Product and company names listed are trademarks or trade names of their respective companies.
IVI Foundation
3
IVI-3.5: IVI Configuration Server Specification
1.
Overview of the IVI Configuration Server Specification.............. 12 1.1 1.2 1.3 1.4 1.5
2.
IVI Configuration Server Design.................................................... 15 2.1 2.2 2.3 2.4 2.5
2.6 2.7 2.8
2.9
3.
Introduction.....................................................................................................................................12 Typical Use Scenario of the Configuration Server .........................................................................12 1.2.1 Repeated Capabilities .......................................................................................................13 References.......................................................................................................................................13 Definitions of Terms and Acronyms...............................................................................................13 Implementation ...............................................................................................................................14
UML Design ...................................................................................................................................15 Types of Classes and Objects..........................................................................................................15 Notation ..........................................................................................................................................17 IVI Configuration Store ..................................................................................................................17 IVI Configurable Components........................................................................................................18 2.5.1 IVI Configurable Component ...........................................................................................18 2.5.2 IVI Software Module ........................................................................................................18 2.5.3 IVI Session and IVI Driver Session..................................................................................19 2.5.4 IVI Hardware Asset ..........................................................................................................19 IVI Logical Name ...........................................................................................................................19 IVI Published API...........................................................................................................................20 IVI Data Components .....................................................................................................................20 2.8.1 IVI Data Component.........................................................................................................20 2.8.2 IVI Structure .....................................................................................................................21 2.8.3 IVI Boolean ......................................................................................................................21 2.8.4 IVI Real ............................................................................................................................21 2.8.5 IVI Integer ........................................................................................................................21 2.8.6 IVI String..........................................................................................................................22 2.8.7 IVI API Reference ............................................................................................................22 Repeated Capabilities......................................................................................................................22 2.9.1 Repeated Capabilities in the Configuration Server...........................................................22 2.9.2 IVI Physical Name and IVI Physical Range.....................................................................22 2.9.3 IVI Virtual Name and IVI Virtual Range .........................................................................24
Instantiation and execution of the IVI Configuration Server ...... 25 3.1
3.2
3.3 3.4
3.5
Installing the Configuration Server .................................................................................................25 3.1.1 Packaging..........................................................................................................................25 3.1.2 Data File Installation.........................................................................................................25 3.1.3 First Installation ................................................................................................................25 3.1.4 Subsequent Installations ...................................................................................................26 Accessing the Configuration Store..................................................................................................26 3.2.1 Master Configuration Store ..............................................................................................26 3.2.2 Process Default Configuration Store ................................................................................27 3.2.3 Instantiating the Right Configuration Store From Software Modules ..............................27 3.2.4 Serializing to a Different Configuration Store..................................................................27 Adding Entries to Collections .........................................................................................................27 Installing Software Modules ...........................................................................................................27 3.4.1 Data Components In Software Modules ...........................................................................28 3.4.2 Un-installing Software Modules .......................................................................................28 3.4.3 Re-installing Software Modules .......................................................................................29 Maintaining Configuration Data .....................................................................................................29 3.5.1 Configuring Hardware Assets...........................................................................................29 3.5.2 Configuring Sessions and Driver Sessions .......................................................................30
IVI-3.5: IVI Configuration Server Specification
4
IVI Foundation
3.6
3.7 3.8 3.9
4.
Collections ...................................................................................... 34 4.1 4.2 4.3 4.4
5.
C API Special Functions Overview ................................................................................................37 C API Special Functions .................................................................................................................37 5.2.1 Clear Error ........................................................................................................................38 5.2.2 Close .................................................................................................................................39 5.2.3 Dispose Handle.................................................................................................................40 5.2.4 Get Error ...........................................................................................................................41 5.2.5 Initialize ............................................................................................................................42
IVI Configurable Components Class (Virtual) .............................. 43 6.1 6.2 6.3
7.
Collections in COM ........................................................................................................................34 Collections in C...............................................................................................................................35 Properties in C.................................................................................................................................35 Return Codes...................................................................................................................................36
C API Special Functions................................................................. 37 5.1 5.2
6.
3.5.3 Data Components In Sessions...........................................................................................30 3.5.4 Configuring Logical Names..............................................................................................31 3.5.5 Documentation Data Components ....................................................................................31 Using Configuration Data ...............................................................................................................31 3.6.1 IVI Class Drivers and the IVI Session Factory.................................................................31 3.6.2 Software Module Initialization .........................................................................................32 3.6.3 Interchanging Instruments ................................................................................................32 Additional Instances of the Configuration Store.............................................................................33 Avoiding the Configuration Server .................................................................................................33 Copying Elements ...........................................................................................................................33
IVI Configurable Components Overview .......................................................................................43 IVI Configurable Components References .....................................................................................43 6.2.1 Data Components..............................................................................................................44 IVI Configurable Components Properties.......................................................................................45 6.3.1 Description........................................................................................................................46 6.3.2 Name.................................................................................................................................47
IVI Configuration Store Class ........................................................ 48 7.1 7.2
7.3
7.4 IVI Foundation
IVI Configuration Store Overview..................................................................................................48 IVI Configuration Store References................................................................................................48 7.2.1 Driver Sessions .................................................................................................................49 7.2.2 Hardware Assets ...............................................................................................................50 7.2.3 Logical Names ..................................................................................................................51 7.2.4 Published APIs .................................................................................................................52 7.2.5 Sessions ............................................................................................................................53 7.2.6 Software Modules.............................................................................................................54 IVI Configuration Store Properties .................................................................................................55 7.3.1 Actual Location ................................................................................................................56 7.3.2 Description........................................................................................................................57 7.3.3 Master Location ................................................................................................................58 7.3.4 Name.................................................................................................................................59 7.3.5 Process Default Location ..................................................................................................60 7.3.6 Revision ............................................................................................................................61 7.3.7 Specification Major Version.............................................................................................62 7.3.8 Specification Minor Version.............................................................................................63 7.3.9 Vendor ..............................................................................................................................64 IVI Configuration Store Functions..................................................................................................65 5
IVI-3.5: IVI Configuration Server Specification
7.4.1 7.4.2 7.4.3 7.4.4
8.
IVI Hardware Asset Class............................................................... 70 8.1 8.2 8.3
9.
10.2 10.3
11.3
IVI Physical Name Overview .........................................................................................................86 IVI Physical Name References .......................................................................................................86 11.2.1 Physical Names.................................................................................................................87 11.2.2 Physical Ranges ................................................................................................................88 IVI Physical Name Properties.........................................................................................................89 11.3.1 Name.................................................................................................................................90 11.3.2 RC Name ..........................................................................................................................91
IVI Physical Range Class ............................................................... 92 12.1 12.2
13.
IVI Software Module Overview......................................................................................................77 10.1.1 Configurable Initial Settings.............................................................................................77 10.1.2 Documentation Data Components ....................................................................................77 IVI Software Module References....................................................................................................78 10.2.1 Physical Names.................................................................................................................79 10.2.2 Published APIs .................................................................................................................80 IVI Software Module Properties .....................................................................................................81 10.3.1 Module Path......................................................................................................................82 10.3.2 Prefix ................................................................................................................................83 10.3.3 ProgID ..............................................................................................................................84 10.3.4 Supported Instrument Models...........................................................................................85
IVI Physical Name Class................................................................. 86 11.1 11.2
12.
IVI Published API Overview ..........................................................................................................72 IVI Published API Properties..........................................................................................................72 9.2.1 Major Version...................................................................................................................73 9.2.2 Minor Version...................................................................................................................74 9.2.3 Name.................................................................................................................................75 9.2.4 Type ..................................................................................................................................76
IVI Software Module Class ............................................................. 77 10.1
11.
IVI Hardware Asset Overview........................................................................................................70 8.1.1 Documentation Data Components ....................................................................................70 IVI Hardware Asset References......................................................................................................70 IVI Hardware Asset Properties .......................................................................................................70 8.3.1 I/O Resource Descriptor ...................................................................................................71
IVI Published API Class.................................................................. 72 9.1 9.2
10.
Deserialize ........................................................................................................................66 Get Driver Session............................................................................................................67 Get Session .......................................................................................................................68 Serialize ............................................................................................................................69
IVI Physical Range Overview.........................................................................................................92 IVI Physical Range Properties ........................................................................................................92 12.2.1 Max...................................................................................................................................93 12.2.2 Min ...................................................................................................................................94 12.2.3 Name.................................................................................................................................95
IVI Logical Name Class................................................................... 96 13.1 13.2
IVI Logical Name Overview...........................................................................................................96 IVI Logical Name References.........................................................................................................96
IVI-3.5: IVI Configuration Server Specification
6
IVI Foundation
13.3
14.
IVI Session Class .......................................................................... 100 14.1 14.2
14.3
15.
16.3
IVI Virtual Name Overview .........................................................................................................115 IVI Virtual Name References........................................................................................................115 16.2.1 Virtual Ranges ................................................................................................................116 IVI Virtual Name Properties .........................................................................................................117 16.3.1 Map To ...........................................................................................................................118 16.3.2 Name...............................................................................................................................119
IVI Virtual Range Class................................................................. 120 17.1 17.2
18.
IVI Driver Session Overview........................................................................................................107 IVI Driver Session References......................................................................................................107 IVI Driver Session Properties .......................................................................................................107 15.3.1 Cache ..............................................................................................................................108 15.3.2 Driver Setup....................................................................................................................109 15.3.3 Interchange Check ..........................................................................................................110 15.3.4 Query Instrument Status .................................................................................................111 15.3.5 Range Check...................................................................................................................112 15.3.6 Record Value Coercions .................................................................................................113 15.3.7 Simulate ..........................................................................................................................114
IVI Virtual Name Class .................................................................. 115 16.1 16.2
17.
IVI Session Overview ...................................................................................................................100 14.1.1 Configurable Initial Settings...........................................................................................100 14.1.2 Documentation Data Components ..................................................................................101 IVI Session References .................................................................................................................101 14.2.1 Hardware Asset...............................................................................................................102 14.2.2 Software Module ............................................................................................................103 14.2.3 Virtual Names.................................................................................................................104 IVI Session Properties...................................................................................................................105 14.3.1 Software Module Name ..................................................................................................106
IVI Driver Session Class............................................................... 107 15.1 15.2 15.3
16.
13.2.1 Session ..............................................................................................................................97 IVI Logical Name Properties ..........................................................................................................98 13.3.1 Name.................................................................................................................................99
IVI Virtual Range Overview.........................................................................................................120 IVI Virtual Range Properties ........................................................................................................120 17.2.1 Max.................................................................................................................................121 17.2.2 Min .................................................................................................................................122 17.2.3 Name...............................................................................................................................123 17.2.4 Starting Physical Index ...................................................................................................124
IVI Data Component Class ........................................................... 125 18.1 18.2
IVI Foundation
IVI Data Component Overview ....................................................................................................125 IVI Data Component Properties....................................................................................................125 18.2.1 Description......................................................................................................................126 18.2.2 Help Context ID..............................................................................................................127 18.2.3 Help File Path .................................................................................................................128 18.2.4 Name...............................................................................................................................129 18.2.5 Read Only .......................................................................................................................130 18.2.6 Software Module Key.....................................................................................................131 18.2.7 Type................................................................................................................................132 7
IVI-3.5: IVI Configuration Server Specification
18.2.8
19.
IVI Structure Class ........................................................................ 134 19.1 19.2 19.3
20.
IVI Boolean Overview ..................................................................................................................143 IVI Boolean Properties..................................................................................................................143 22.2.1 Value...............................................................................................................................144
IVI String Class ............................................................................. 145 23.1 23.2
24.
IVI Real Overview ........................................................................................................................140 IVI Real Properties .......................................................................................................................140 21.2.1 Units ...............................................................................................................................141 21.2.2 Value...............................................................................................................................142
IVI Boolean Class.......................................................................... 143 22.1 22.2
23.
IVI Integer Overview ....................................................................................................................137 IVI Integer Properties....................................................................................................................137 20.2.1 Units ...............................................................................................................................138 20.2.2 Value...............................................................................................................................139
IVI Real Class ................................................................................ 140 21.1 21.2
22.
IVI Structure Overview.................................................................................................................134 IVI Structure References...............................................................................................................134 19.2.1 Data Components............................................................................................................135 IVI Structure Properties ................................................................................................................136
IVI Integer Class ............................................................................ 137 20.1 20.2
21.
Used In Session ..............................................................................................................133
IVI String Overview......................................................................................................................145 IVI String Properties .....................................................................................................................145 23.2.1 Value...............................................................................................................................146
IVI API Reference Class................................................................ 147 24.1 24.2 24.3
IVI API Reference Overview........................................................................................................147 IVI API Reference References......................................................................................................148 24.2.1 Published API .................................................................................................................149 IVI API Reference Properties .......................................................................................................150 24.3.1 Value...............................................................................................................................151
25.
Configuration Server Error and Completion Codes .................. 152
26.
Configuration Store Data Format ................................................ 154
27.
Configuration Utility Implementation Guidelines ...................... 155 27.1 27.2 27.3 27.4 27.5 27.6
General..........................................................................................................................................155 Hardware Assets ...........................................................................................................................155 Published APIs..............................................................................................................................155 Software Modules .........................................................................................................................155 Sessions.........................................................................................................................................155 Documentation Data Components ................................................................................................156
IVI-3.5: IVI Configuration Server Specification
8
IVI Foundation
28.
Limitations..................................................................................... 157 28.1 28.2
Distributed Systems ......................................................................................................................157 Concurrent Reading and Writing ..................................................................................................157
Appendix A: IVI Configuration Server IDL file..................................... 158 Appendix B: IVI-COM Driver Example.................................................. 175 Appendix C: XSD File ............................................................................ 182
IVI Foundation
9
IVI-3.5: IVI Configuration Server Specification
LIST OF FIGURES Figure 2-1 - IVI Configuration Server UML Class Diagram................................................................ 16 Figure 24-1 Typical API Reference Configuration Store Entries....................................................... 147
IVI-3.5: IVI Configuration Server Specification
10
IVI Foundation
Configuration Server Specification Revision History This section is an overview of the revision history of the IVI Configuration Server specification. Table 1-1. Ivi-3.5 Revisions
Revision Number Date of Revision
Revision Notes
Revision 0.1
??
Original draft.
Revision 0.2
May 23, 2001
Bring up to date.
Revision 0.3
July 31, 2001
First version to reflect UML diagrams for iteration 6 of the Configuration Server.
Revision 0.4
August 27, 2001
Add Section 3 and incorporate design changes
Revision 0.5
September 10, 2001
Reflect changes discussed at Sept. 2001 IVI Foundation meeting
Revision 0.6
November 1, 2001
Reflect changes made in telephone conferences after the Sept 2001 IVI meeting.
Revision 0.7
November 30, 2001
Reflect changes made in telephone conferences after the Nov. 1, 2001 WG telephone conference.
Revision 0.8
December 18, 2001
Reflects changes made through the December, 2001 IVI Meeting and immediately after.
Revision 0.9
February 7, 2002
Reflects changes made through the February 7, 2002 telephone conference. Sections 1-23 are completely reviewed, ready for C API to be added.
Revision 0.91
March 20, 2002
C API was added in previous version. General cleanup..
Revision 0.92
April 16, 2002
New section for general C functions. Return codes sections added.
Revision 1.0vc1
April 29, 2002
Version for initial two week review.
Revision 1.0vc2
May 15, 2002
Changes made from two week review.
Revision 1.0vc
June 11, 2002
Changes made after two week review.
Revision 1.0
November 7, 2002
Approved.
IVI Foundation
11
IVI-3.5: IVI Configuration Server Specification
1. Overview of the IVI Configuration Server Specification This document describes the IVI Configuration Server that is provided by the IVI Foundation. Following the introduction, the general capabilities of the system are listed. The top-level architecture design is given with a component diagram and terminologies used. Capabilities of major components in the architecture are also described. Detailed descriptions of all the interface properties and functions follow. A sample use scenario diagram is then given. Next, the requirements on clients that use the IVI Configuration Server in a system are listed.
1.1
Introduction The IVI Configuration Server is the run-time module that is responsible for providing system database services to IVI based measurement system applications. Specifically, it provides system initialization and configuration information. The IVI Configuration Server is used by several of the IVI compliant modules. For instance, the Configuration Server indicates which physical instrument and IVI driver will be used by a particular application to provide a particular measurement capability. Since a typical system intermixes instruments and drivers from multiple vendors this system configuration service needs to be accessed in a vendor independent fashion. Therefore, the IVI Configuration Server is an IVI shared component (that is, the code is owned by the IVI Foundation). The IVI Configuration Server is provided by the IVI Foundation because the architecture requires a single Configuration Server be installed on any system, therefore having a single shared implementation eliminates potential conflicts from divergent implementations. The IVI Configuration Server is a single executable and one or more XML configuration stores (databases) made up of the following basic components: • The physical database (known as the configuration store). A physical configuration store is a single XML file. APIs are available to read and write the data to arbitrary files, thus providing complex applications with the ability to directly manage system configurations. • The API (and its implementation) used to read information from the configuration store(s). The IVI modules typically use this API when they are instantiated and configured. • The API (and its implementation) to write information to the configuration store(s). This API is typically used by GUI or other applications that set up the initial configuration. • The API (and its implementation) used to bind an instance of the Configuration Server code to a particular copy of the configuration information stored on a system. This includes appropriate algorithms for gaining access to the master configuration store.
1.2
Typical Use Scenario of the Configuration Server The following example illustrates the typical operations conducted with the IVI Configuration Server. 1.
Various instrument drivers are installed on the system. As each instrument driver is installed on the system, its installation script makes entries in the configuration store that indicate the location of the driver, its ProgID, a list of instruments it supports, and the interfaces it provides to its client. This entry is known as a SoftwareModule because it describes the software module (in this case, an instrument driver) that was installed. Software module developers determine what happens at installation time, and are the primary actors at this step.
2.
A user configuring the system makes entries in the configuration store that indicate a logical name for each instrument service they will be using. Then, the user associates a specific instrument and driver with each logical name. Note that the physical instrument is primarily identified by its I/O address. The driver is entered as a reference to a SoftwareModule entry that was created by the driver installation. In addition, the user may provide information regarding the default behavior of the instrument. This step will typically be completed with the aid of a configuration utility, however a configuration utility is beyond the scope of the IVI specifications. Users determine how the software modules are configured, and are the primary actors at this step.
IVI-3.5: IVI Configuration Server Specification
12
IVI Foundation
3.
For COM software modules, when the user’s application runs, it instantiates the IVI-COM Session Factory (refer to IVI-3.6, COM Session Factory Specification). The user application then calls CreateDriver() passing it the logical name they defined in the configuration step. The factory then instantiates the software module and configures it based on the entries provided in step 2. The user is the primary actor at this step.
The benefit of this use scenario is that the user’s program is entirely de-coupled from the configuration information. It is therefore possible to modify the configuration information provided in step 2 above without ever modifying the actual program that invokes and uses the driver. The benefit is that an instrument with a class-compliant driver can replace another class-compliant driver in an existing system, with no code changes made to the user application program. This pattern of associating configuration information with a logical name, and thus allowing a system to be re-configured without code changes is known as an abstract factory pattern and has other applications within the IVI architecture. For instance, IVI-MSS role control modules make similar use of the IVI Configuration Server. The IVI Configuration Server also allows users to associate arbitrary information with software modules and logical names. This can be useful when there is additional configuration information that is needed by the application. The IVI Configuration Server defines several fields specifically for use with instrument driver sessions.
1.2.1 Repeated Capabilities In many instruments there are capabilities that are duplicated either identically or very similarly across the instrument. Such capabilities are called repeated capabilities. The IVI class-compliant APIs represent repeated capabilities by a parameter that indicates which instance of the duplicate capability this function is intended to access. The IVI C APIs include this parameter as an additional parameter to function calls. The IVI COM APIs may do the same, or may also use this parameter as an index into a repeated capability collection. The IVI Configuration Server provides a way for software modules to publish the functionality that is duplicated and the strings that the software module recognizes to access the repeated capabilities. The IVI Configuration Server also provides a way for the client to supply aliases for the physical identifiers recognized by the drivers. Since many instruments have numerous instances of repeated capabilities, the IVI Configuration Server provides a way to represent the repeated capabilities as a range of identifiers instead of a large number of individual identifiers. One repeated capability may also be related to another repeated capability in a hierarchical parent/child relationship. The child repeated capabilities in these relationships are called nested repeated capabilities. The IVI Configuration Server provides a way to model these relationships.
1.3
References Several other documents and specifications are related to this specification. These other related documents are the following:
1.4
•
IVI-3.1: Driver Architecture Specification
•
IVI-3.2: Inherent Capabilities Specification
•
IVI-3.4: API Style Guide
•
IVI-3.6: COM Session Factory Specification
Definitions of Terms and Acronyms Terms of general interest are defined in IVI-5.0: Glossary.
IVI Foundation
13
IVI-3.5: IVI Configuration Server Specification
Symmetrical Repeated Capability – A repeated capability where each instance of a repeated capability has identical capabilities to all of the other instances.
1.5
Implementation The IVI Foundation supplied implementations of the IVI Configuration Server and IVI Session Factory are available from the IVI Foundation web site. These are packaged with the other IVI Foundation shared components as part of the shared component installation package.
IVI-3.5: IVI Configuration Server Specification
14
IVI Foundation
2. IVI Configuration Server Design The IVI Configuration Server is based on an object oriented UML (Unified Modeling Language) design. The Configuration Server data is stored as an XML configuration store file that closely follows the design of the Configuration Server.
2.1
UML Design The IVI Configuration Server design is most easily understood by considering the class diagram for the API. The XML data structure closely follows the structure of the API. The UML class diagram is shown in Figure 2-1. In the diagram, a rectangle represents a class. A dotted line indicates class inheritance, with the triangle pointing to the inherited interface. Note that IviConfigComponent and IviDataComponent are both abstract base classes, and are never implemented directly by the Configuration Server. Although it is a base class, IviSession is not abstract, and is directly implemented. The dashed and solid lines are references from the class at the tail of the arrow to the class at the head of the arrow. For each reference, it is assumed that the class at the tail of the arrow contains a reference property (a property that returns a reference to another object) named by the text at the head of the arrow. Collection classes are implied by the UML diagram wherever there is a relationship (indicated by a solid line) with an ordinality of 0..* or 1..* at the head of the arrow. For example, the IviLogicalNames collection class is implied by the Logical Names relationship between IviConfigStore and IviLogicalName. The IviConfigStore class includes a reference property named “LogicalNames” which references an IviLogicalNamesCollection object, which manages a collection of zero or more references to IviLogicalName objects. The Name property uniquely identifies an object in a collection. Refer to section 4, Collections, for more information about Configuration Server collections. A heavy dashed line represents a reference to a global collection of all of the objects in a global class (refer to the next section). A solid line represents other references.
2.2
Types of Classes and Objects Every instance of an IVI Configuration Server has exactly one instance of the IviConfigStore class. This object is instantiated by users who request an instance of the IVI Configuration Server. Users can navigate to all of the other objects in the configuration store from this object. There are six “global” classes – IviLogicalName, IviHardwareAsset, IviSoftwareModule, IviPublishedAPI, IviSession, and IviDriverSession. Objects in these classes may be referenced from any object in the configuration server that implements a corresponding reference property. All of the objects of a global class are unique (by Name), except Published APIs, within the entire Configuration Server. Published APIs are differentiated by version as well as Name. For example, all of the software module objects in the configuration server have a unique Name. There are six global collections in the configuration store, one for each global class. All of the objects of a global class are part of the corresponding global collection. The global collections are referenced by the main IviConfigStore object. Although an object in a global collection may be referenced by other objects, it exists independently of those other objects. When the referencing object is deleted, the global object is not necessarily deleted. In fact, with one exception. it may only be deleted when there are no outstanding references to it in the configuration server. For example, a session may reference a hardware asset, but the hardware asset is not necessarily deleted when the session is deleted. The hardware asset may only be deleted from the global collection when there are no sessions or driver sessions that refer to it.
IVI Foundation
15
IVI-3.5: IVI Configuration Server Specification
IviConfigComponent +Name : string(idl) +Description : string(idl)
+HardwareAssets
+SoftwareModule
IviHardwareAsset
0..*
0..1
+IOResourceDescriptor : string(idl)
+HardwareAsset 0..1
IIviComponentIdentity IviSession
+Session
IviConfigStore +ActualLocation : string(idl) +Description : string(idl) +MasterLocation : string(idl) +Name : string(idl) +ProcessDefaultLocation : string(idl) +Revision : string(idl) +SpecificationMajorVersion : string(idl) +SpecificationMinorVersion : string(idl) +Vendor : string(idl)
IviSoftwareModule +ModulePath : string(idl) +Prefix : string(idl) +ProgID : string(idl) +SupportedInstrumentModels : string(idl)
+Software Module Name : string(idl)
0..1
+SoftwareModules 0..*
IviLogicalName +Name : string(idl) +LogicalNames +Description : string(idl)
+Sessions 0..*
0..*
+Deserialize() +GetDriverSession() +GetSession() +Serialize()
IviDriverSession
+DriverSessions
+Cache : boolean(idl) +DriverSetup : string(idl) +InterchangeCheck : boolean(idl) +QueryInstrStatus : boolean(idl) +RangeCheck : boolean(idl) +RecordCoercions : boolean(idl) +Simulate : boolean(idl)
0..*
+PhysicalNames 0..* +VirtualNames 0..* IviVirtualName
IviPhysicalName
+MapTo : string(idl) +Name : string(idl)
+Name : string(idl) +RCName : string(idl)
+PublishedAPIs +PublishedAPIs 0..* +Description : string(idl) +HelpContextID : long(idl) +HelpFilePath : string(idl) +Name : string(idl) +ReadOnly : boolean(idl) +SoftwareModuleKey : string(idl) +Type : string(idl) +UsedInSession : string(idl)
+VirtualRanges 0..*
IviPublishedAPI
IviDataComponent
IviReal
+PhysicalNames 0..*
0..*
+DataComponents 0..*
+Name : string(idl) +Type : string(idl) +MajorVersion : long(idl) +MinorVersion : long(idl)
IviVirtualRange +Max : long(idl) +Min : long(idl) +Name : string(idl) +StartingPhysicalIndex : long(idl)
1..*
+PublishedAPI 1
IviString +Value : string(idl)
IviInteger
IviStructure
+Units : string(idl) +Value : long(idl)
IviBoolean
IviPhysicalRange +Max : long(idl) +Min : long(idl) +Name : string(idl)
+DataComponents
+Units : string(idl) +Value : double(idl)
+Value : boolean(idl)
+PhysicalRanges 0..*
Configuration Server UML Class Diagram
IviAPIReference +Value : string(idl)
Figure 2-1 - IVI Configuration Server UML Class Diagram The “exception” to this rule is the relationship from session to software module. A software module may be deleted when there are still sessions that reference it. In this case, the session cannot reference an IVI Software Module object, but it does “remember” the name of the software module that it referenced, and if IVI-3.5: IVI Configuration Server Specification
16
IVI Foundation
a software module with the same name is ever re-added to the configuration store, a reference from the session to that software module is recreated. The other classes (including other collection classes) are “contained” classes. Contained objects in these classes are not global, and are unique and meaningful only in the context of a “containing” object that contains a reference to a collection of the “contained” objects. Contained objects do not exist independently of the containing object, and are deleted when the containing object is deleted. For example, all of the Data Component objects referenced by a software module are unique to that software module, and must be deleted when the software module is deleted. This implies that software modules cannot share Data Component objects – each software module requires a duplicate Data Component for identical configuration variables. Note that the Software Module class references a collection of Published APIs. This collection is not a global collection. It is “contained” in the software module that references it, and is deleted when the software module is deleted. However, the Published API objects that are referenced by the collection are not deleted, since they are also in the global Published API collection.
2.3
Notation In the descriptions of each class that follow, • API methods are identified as such. • API properties that do not reference another object are followed by the basic type (Boolean, string, long, or double) and an indication of whether the property is read-only (R/O), write-only (W/O), or both (R/W). If the property is a string, Optional indicates that the string may be empty. It is assumed that longs, doubles, and Booleans must always have a valid value. All strings must be legal XML strings, since the configuration store is an XML file. • API properties that reference an object are followed by the type of the object, and an indication of whether the reference is optional (0..1) or required (1). If the reference is optional, the property returns a NULL pointer if there is no reference. • API properties that reference a collection object are followed by the type of the collection, and an indication of whether the collection may be empty (0..*) or not (1..*).
2.4
IVI Configuration Store The IviConfigStore class contains the following references, properties, and methods. • Driver Sessions (Collection of IviDriverSession, 0..*) – The global collection of references to all of the IVI Driver Session objects in the configuration store. • Hardware Assets (Collection of IviHardwareAsset, 0..*) – The global collection of references to all of the IVI Hardware Asset objects in the configuration store. • Logical Names(Collection of IviLogicalName, 0..*) – The global collection of references to all of the IVI Logical Name objects in the configuration store. • Published APIs (Collection of IviPublishedAPI, 0..*) – The global collection of references to all of the IVI Published API objects in the configuration store. • Sessions (Collection of IviSession, 0..*) – The global collection of references to all of the IVI Session objects in the configuration store. • Software Modules(Collection of IviSoftwareModule, 0..*) – The global collection of references to all of the IVI Software Module objects in the configuration store. • Actual Location (String, optional, R/O) – The full pathname of the IVI configuration store file that was deserialized by the current instance of the configuration server. • Description (String, required, R/W) – The description of the configuration store. • Master Location (String, optional, R/O) – The full pathname of the master IVI configuration store file. • Name (String, required, R/O) – The name of the component – “IVI Configuration Server”. • Process Default Location (String, required, R/W) – The full pathname of the IVI configuration store file to be used by the current process. • Revision (String, required, R/O) – The revision of this version of the Configuration Server. Will match the version reported by the DLL’s file version resource. Refer to Section 5.1, IVI-COM Interface Versioning, of IVI-3.4: API Style Guide for more details. • Specification Major Version (Long, R/O) – The major version of the IVI Configuration Server specification to which this version of the Configuration Server complies.
IVI Foundation
17
IVI-3.5: IVI Configuration Server Specification
• • • • • •
2.5
Specification Minor Version (Long, R/O) – The minor version of the IVI Configuration Server specification to which this version of the Configuration Server complies. Vendor (String, required, R/O) – “IVI Foundation, Inc.” Deserialize() (method) – Deserializes an instance of a configuration store into the Configuration Server. Get Driver Session() (method) – Given a name, navigates the Configuration Server’s logical name collection and driver session collection to find the corresponding IVI Driver Session. Get Session() (method) – Given a name, navigates the Configuration Server’s logical name collection and session collection to find the corresponding IVI Session. Serialize() (method) – Serializes the configuration store data in Configuration Server memory out to a configuration store file.
IVI Configurable Components The IVI Configuration Server is organized around a series of IVI Configurable Components – classes that inherit from the IVI Configurable Component abstract base class. This class allows the addition of custom properties to any class that inherits from it, as well as the common Name and Description properties. Although it is legitimate to define additional IVI Configurable Components, the IVI Foundation only specifies the semantics of three classes derived from IVI Configurable Component. • IVI Software Module • IVI Session (and IVI Driver Session through inheritance) • IVI Hardware Asset
2.5.1 IVI Configurable Component The IVI Configurable Component class contains the following references and properties: • Data Components (Collection of IviDataComponent, 0..*) – An optional collection of references to additional properties that may be added to any configurable component by its owner. • Name (String, required) – This is a human readable name for this component. Name may be any valid string, but is used as a key or index value in collections. Therefore, Name must be unique within collections of like objects. • Description (String, optional) - This is a human readable description of this component. Description may be any valid string.
2.5.2 IVI Software Module The IVI Software Module class contains information that describes a software component installed on the system. This component only contains information relevant to the installed software module, it does not contain information that is associated with a running instance. IVI Software Module inherits from IVI Configurable Component. In addition to the properties inherited from IVI Configurable Component, the IVI Software Module class contains the following properties: • Module Path (String, required for IVI-C) – For IVI-C software modules, the full pathname or simple filename of the software module DLL. ModulePath and ProgID may both have a valid, non-empty, string value. • Prefix (String, optional) – The prefix (IVI-C) or identifier (IVI-COM ) of the software module. • ProgID(String, required for IVI-COM) – For IVI-COM software modules, the version independent ProgID of the registered software module. ModulePath and ProgID may both have a valid, non-empty, string value. • Supported Instrument Models (String, optional) - A comma separated list of supported instrument models. Required for IVI specific instrument drivers. • Published APIs (Collection of IviPublishedAPI, 0..*) – The collection of references to the IVI Published API objects implemented by the software module. • Physical Names (Collection of IviPhysicalName, 0..*) – The collection of references to the IVI Physical Identifier objects implemented by the software module. This collection describes information about the repeated capabilities names implemented by the software module. Refer to Section 2.9, Repeated Capabilities, for more information.
IVI-3.5: IVI Configuration Server Specification
18
IVI Foundation
2.5.3 IVI Session and IVI Driver Session The IVI Session class describes how an instance of IVI Software Module will be configured. The IVI Driver Session class defines an additional set of properties for use by IVI instrument drivers. The Ivi Driver Session class inherits from the Ivi Session class. IVI Session inherits from IVI Configurable Component. In addition to the properties inherited from IVI Configurable Component, the IVI Session class contains the following references: • SoftwareModule (Reference to IviSoftwareModule, 0..1) – A reference to the IVI Software Module object that is being configured by this session. • HardwareAsset (Reference to IviHardwareAsset, 0..1) – A reference to the IVI Hardware Asset object to be used by the configured software module. • VirtualNames (Collection of IviVirtualName, 0..*) – The collection of references to the IVI Virtual Name objects defined by the session. This collection describes information about the repeated capabilities names that can be used as aliases by the software module. Refer to Section 2.9, Repeated Capabilities for more information. • SoftwareModuleName (String, optional, R/O) – The name of the current or most recently referenced software module referenced by the Software Module property. In addition, the IVI Driver Session class contains the following properties. Refer to IVI-3.2, Section 5 for exact details. • Cache (Boolean) – If TRUE, drivers that support state caching will initially enable that feature. Default is FALSE. • DriverSetup (String, optional) – The content of this string is dependent on the software module associated with the driver session. The software module knows how to interpret the string. • InterchangeCheck (Boolean) – If TRUE, drivers that support interchangeability checking will initially enable that feature. Default is FALSE. • QueryInstrumentStatus (Boolean) – If TRUE, drivers will initially enable querying instrument status. Default is FALSE. • RangeCheck (Boolean) – If TRUE, drivers that support extended range checking will initially enable that feature. Default is FALSE. • RecordCoercions (Boolean) – If TRUE, drivers that support recording of coercions will initially enable that feature. Default is FALSE. • Simulate (Boolean) – If TRUE, drivers will initially enable simulation. Default is FALSE.
2.5.4 IVI Hardware Asset The IVI Hardware Asset class contains the I/O Address of a particular hardware asset. The form of this address is dependent on the underlying I/O mechanism. For IVI instrument drivers, this will commonly be a VISA Resource Descriptor string. It is valid for a session to refer to a hardware asset even if the asset is not physically at the address. However, a software module trying to use the hardware asset will be unable to establish communication with it. IVI Hardware Asset inherits from IVI Configurable Component. In addition to the properties inherited from IVI Configurable Component, the IVI Hardware Asset class contains the following property: • IOResourceDescriptor (String, optional) – The I/O Address of a particular hardware asset.
2.6
IVI Logical Name The IVI Logical Name class provides the binding between the users program and the configuration information stored in the IVI configuration store. The users program identifies which session to instantiate by passing the Name associated with a particular IVI Logical Name component to the IVI Session Factory. The IVI Session Factory instantiates a session based on the configuration in the IviSession that is referred to by the IVI Logical Name with the name specified by the user. The IVI Logical Name class contains the following reference and property: • Session (Reference to IviSession, 0..1) – A reference to an IVI Session object. • Name (String, required) – The logical name.
IVI Foundation
19
IVI-3.5: IVI Configuration Server Specification
2.7
IVI Published API A published API defines the syntax and partial semantics of a programming interface that can be used to accomplish a particular task. The semantics are specified in sufficient detail to describe the task to be done, but enough semantics are left unspecified to leave room for a reasonable variety of implementations. Published APIs defined by the IVI Foundation have names that begin with “Ivi”. For IVI drivers, examples of published APIs are the inherent interfaces (named IviDriver) and the class-compliant interfaces (named IviDmm, IviScope, etc.). The names of IVI driver published APIs are defined by the IVI Foundation. For IVI-MSS, published APIs are the defined MSS measurement interfaces. For example, a phase noise measurement API defined by the IVI Foundation might be called IviMssPhaseNoise. Published APIs defined outside of the IVI Foundation shall not have names that begin with “Ivi”. For example, a phase noise measurement API defined by a T&M company might be called “TMCoPhaseNoise”, where “TMCo” is the T&M company that developed the API. The IVI Published API class contains the following properties: • Name (String, required) – The name of the published API. • Type (String, required) – The syntactical type of the API. Predefined values are “IVI-COM” for COM interfaces that conform to IVI-3.4: Style Guide and “IVI-C” for C interfaces that conform to IVI-3.4 Style Guide. One of these values must be used for all IVI defined APIs. Other values may be used if appropriate for other types of APIs. • MajorVersion (Long) – The major version of the published API. For APIs that are defined by IVI specifications, this is the major version of the IVI specification. • MinorVersion (Long) – The minor version of the published API. For APIs that are defined by IVI specifications, this is the minor version of the IVI specification.
2.8
IVI Data Components The IVI Data Component class provides a way to attach arbitrary data to the IVI Configurable Components – hardware assets, software modules, and sessions (including driver sessions). Data components may be used for two basic purposes • Configurable Initial Settings: Data components that define and configure initial settings for additional variables known to a software module and configured by sessions that reference the software module. • Documentation: Data components that document the configurable component itself.
2.8.1 IVI Data Component IVI Data Components are the means of customizing a configuration store’s data structure. They are used to add custom properties to IVI Configurable Components. There are six data component classes, each of which inherits from IVI Data Component. IVI Data Component is an abstract base class. This class has properties that describe the data component, as well as the common Name and Description properties. The six data component classes that inherit from IviDataComponent are: • IVI Structure • IVI Boolean • IVI Real • IVI Integer • IVI String • IVI API Reference The IVI Data Component class contains the following properties: • Name (String, required) – A human readable name for this component. Name may be any valid string, but is used as a key or index value in collections. Therefore, Name must be unique within collections of DataComponents. • Description (String, optional) - A human readable description of this component. Description may be any valid string. • HelpContextID (Long) – The context ID of the help topic for this data component. IVI-3.5: IVI Configuration Server Specification
20
IVI Foundation
• •
• • •
HelpFilePath (String, optional) – The fully qualified help file pathname for the help file in which the help topic for this data component may be found. ReadOnly (Boolean) - Indicates a restriction in the client’s permission to change the value of this data component. The IVI Configuration Server attaches no significance to this property and does not enforce any protocol regarding write access to data components. This property is primarily guidance for configuration utilities. SoftwareModuleKey (String, optional) – A string that is meaningful to the software module that identifies the data component or type of data component to the software module. Type (String, optional) - Contains a string that indicates which type of IVI Data Component this is. It will accurately reflect the type of this component and will contain one of the following values, “Structure”, “Boolean”, “Real”, “Integer”, “String”, or “APIReference”. UsedInSession (String) – Indicates whether or not a data component associated with a software module must be copied (UsedInSession = “Required”), may be copied (UsedInSession = “Optional”), or may not be copied (UsedInSession = “None”) to any associated sessions. When associated with a hardware asset, UsedInSession is always “None”.
The values of some properties are determined at least partially by what type of configurable component the data component is associated with, and the purpose of the data component.
Hardware Asset Software Module Session/Driver Session
Configurable Initial Settings N/A UsedInSession = “Required”\”Optional” ReadOnly = True UsedInSession = “Required”\”Optional” ReadOnly = False
Documentation UsedInSession = “None” SoftwareModuleKey = “” UsedInSession = “None” SoftwareModuleKey = “” UsedInSession = “None” SoftwareModuleKey = “”
2.8.2 IVI Structure The IVI Structure data component references a collection of data components. This allows the creation of complex structures. In addition to the properties inherited from IVI Data Component, the IVI Structure class contains the following property: • DataComponents (Collection of IviDataComponent, 1..*) – A collection of references to the IVI DataComponents. This collection defines a child structure of data components. Using this class, hierarchies of data components can be defined.
2.8.3 IVI Boolean This class provides Boolean data in data components. In addition to the properties inherited from IVI Data Component, the IVI Boolean class contains the following property: • Value (Boolean) – Boolean data associated with this data component. Must be TRUE or FALSE.
2.8.4 IVI Real This class provides real data in data components. In addition to the properties inherited from IVI Data Component, the IVI Real class contains the following properties: • Value (Double) – Real data associated with this data component. • Units (String, optional) – Units associated with the number.
2.8.5 IVI Integer This class provides integer data in data components. IVI Foundation
21
IVI-3.5: IVI Configuration Server Specification
In addition to the properties inherited from IVI Data Component, the IVI Integer class contains the following properties: • Value (Long) – Integer data associated with this data component. • Units (String, optional) – Units associated with the number.
2.8.6 IVI String This class provides string data in data components. In addition to the properties inherited from IVI Data Component, the IVI String class contains the following property: • Value (String, optional) – String data associated with this data component.
2.8.7 IVI API Reference This class provides a way for data component structures to reference published APIs. The Name property identifies the instance of the published API known by the software module. This data component is designed for use by IVI Software Modules and IVI Sessions. In addition to the properties inherited from IVIi Data Component, the IVI String class contains the following property: • PublishedAPI (Reference to IviPublishedAPI, 1) – A reference to an IVI Published API object to be used by the configured software module. • Value(String,optional) – A logical name or session name. Value can be passed to GetSession() or GetDriverSession() in the Name parameter. A session reference is returned according to the semantics defined for GetSession() and GetDriverSession().
2.9
Repeated Capabilities Standard ways of referencing repeated capabilities in IVI software module APIs are described in several sections of IVI-3.1, Driver Architecture Specification, and Section 12, Repeated Capabilities, of the IVI3.4: API Style Guide. Most IVI instrument class APIs include some repeated capabilities.
2.9.1 Repeated Capabilities in the Configuration Server The IVI Configuration Server provides a way for software modules to publish their repeated capabilities and the physical identifiers that a client may use to access them. Software Modules use the IviPhysicalName and IviPhysicalRange classes for this purpose. The IVI Configuration Server also provides a way for clients to configure instances of software modules for the client’s use. As part of this configuration, clients specify virtual identifiers that the software module will recognize as aliases for the physical identifiers provided by the software module. Clients use the IviVirtualName and IviVirtualRange classes for this purpose.
2.9.2 IVI Physical Name and IVI Physical Range Software modules publish their repeated capabilities using the IVI Physical Name and IVI Physical Range classes. Together these classes specify • The repeated capabilities implemented by the software module. (Determined from the RCName property of IVI Physical Range objects.) • The repeated capability hierarchy implemented by the software module. (Determined from the PhysicalNameCollection referenced by the IVI Physical Name objects, which may be used recursively to represent a hierarchy.) • A set of physical identifiers recognized by the software module. There is exactly one physical identifier for each instance of a repeated capability implemented by the software module. (Determined from the Name property of, and the PhysicalRangeCollection referenced by, the IVI Physical Range objects.)
IVI-3.5: IVI Configuration Server Specification
22
IVI Foundation
An IVI Physical Name object defines one or more physical identifiers corresponding to one or more instances of a repeated capability. The IVI Physical Name class contains the following properties: • RCName (String, required) – The name of a repeated capability. All IVI Physical Names within the same collection that have the same RCName contribute to the definition of that repeated capability. • Name (String, required) – If there is no associated physical range, the physical identifier for an instance of a repeated capability of type RCName. If there are associated physical range(s), the prefix for a range of physical identifiers to which integers from the range(s) are appended. May be empty if there are associated physical ranges. To avoid conflicts with the use of the colon character as a separator, Name may not contain a colon. • PhysicalNames (Collection of IviPhysicalName, 0..*) – The collection of the IVI Physical Name objects for instances of repeated capabilities that are nested under the current physical identifier. • PhysicalRanges (Collection of IviPhysicalRange, 0..*) – The collection of integer ranges used to create a set of physical identifiers, as explained below. When the Physical Ranges property is not NULL, it references a collection of IVI Physical Range objects. A Physical Range object defines a range of integers between a minimum and maximum. The integers are appended to the Name property of the IVI Physical Name object to form a set of physical identifiers. If an IVI Physical Name object references a collection of IVI Physical Ranges, Name may be an empty string. This allows the range of names to be purely numeric. Also, since IVI Physical Name refers to a collection of IVI Physical Ranges, several non-contiguous ranges may be referenced. For example, a physical identifier “C” that references a collection of physical ranges 0-75, 100-175, and 200-275 yields a set of physical identifiers C0-C75, C100-C175, and C200-C275. When an IVI Physical Name references IVI Physical Range(s), and IVI Physical Name(s), the collection of IVI Physical Names (and therefore the implied hierarchy of repeated capabilities) referenced by the IVI Physical Name is assumed to be symmetrical – the same for every physical identifier in the set. In the above example, if the physical identifier “C” referenced a collection of physical identifiers consisting of “X”, “Y”, and “Z”, it would be assumed that every one of the channels C0-C75, C100-C175, and C200C275 had exactly the same set of child physical identifiers “X”, “Y”, and “Z”. For non-symmetrical nested repeated capabilities, Physical Ranges cannot be used. The IVI Physical Range class contains the following properties: • Name (String, required) – A value that uniquely identifies an IVI Physical Range object in a collection. There is no other significance to the Name field in this class. • Max (Long, required) – The maximum integer in the range. • Min (Long, required) – The minimum integer in the range.
2.9.2.1
Nested Repeated Capabilities The software module represents nested repeated capabilities by creating an instance of IviPhysicalName for the parent capability (in this example, the output power), which in turn references another instance of IviPhysicalName for the nested capabilities (in this example, the external trigger). The nesting of IviPhysicalNames can be arbitrarily deep.
2.9.2.2
Symmetrical and Asymmetrical Nested Capabilities Multiple instances of the same repeated capability may or may not share the same child repeated capabilities. If multiple instances of the same repeated capability share the same child repeated capabilities, the repeated capability tree is symmetrical. In this case, each IVI Physical Name object for that repeated capability references an identical collection of child IVI Physical Name objects. If multiple instances of the same repeated capability do not share the same child repeated capabilities, the repeated capability tree is asymmetrical. In this case, each (parent) IVI Physical Name object for that repeated capability will reference a collection of (child) IVI Physical Name objects that describe the specific child repeated capabilities for that object, and these collections may differ from one parent to the next.
IVI Foundation
23
IVI-3.5: IVI Configuration Server Specification
For example, if a driver models two displays, and both displays can display two traces, that part of the repeated capability hierarchy would be symmetrical. If a driver models two displays, and the first can display four traces, but the second can only display two, that part of the repeated capability hierarchy is asymmetrical.
2.9.3 IVI Virtual Name and IVI Virtual Range The IVI Virtual Name and IVI Virtual Range classes are used by the client to create aliases for physical identifiers and colon separated lists of physical identifiers that the software module can use in context to select a repeated capability. The IVI Virtual Name class contains the following properties: • MapTo (String, required) – The string that is substituted by the software module for Name whenever it is encountered in a repeated capability selector. The empty string is a legal value for this property only if the IVI Virtual Name object references a non-empty collection of IVI Virtual Range objects. • Name (String, required) – If there is no associated physical range, a virtual identifier. If there are associated physical range(s), the prefix for a range of virtual identifiers to which integers from the range(s) are appended. May be empty if there are associated virtual ranges. To avoid conflicts with the use of the colon character as a separator, Name may not contain a colon. • VirtualRanges (Collection of IviVirtualRange, 0..*) – The collection of integer ranges used to create a set of IVI Virtual Names, as explained below. An IVI Virtual Name object can also reference a collection of IVI Virtual Range objects. An IVI Virtual Range object defines a range of integers between a minimum and maximum. The integers are appended to the Name property of the IVI Virtual Name object to form a set of virtual identifiers. If an IVI Virtual Name object references a collection of IVI Virtual Ranges, Name may be an empty string. This allows the range of names to be purely numeric. Also, since IVI Virtual Name refers to a collection of IVI Virtual Ranges, several non-contiguous ranges may be referenced. For example, a virtual identifier “C” that references a collection of Virtual Ranges 0-75, 100-175, and 200-275 yields a set of virtual identifiers C0C75, C100-C175, and C200-C275. When an IVI Virtual Name has IVI Virtual Range(s), the set of virtual identifiers maps to a set of physical identifiers created by appending a series of integers to the IVI Virtual Name object’s MapTo string. The series of integers is the same size as the virtual range, but starts at the IVI Virtual Range object’s Starting Physical Index. The IviVirtualRange class contains the following properties: • Name (String, required) – A value that uniquely identifies an IVI Virtual Range object in a collection. There is no other significance to the Name filed in this class. • Max (Long, required) – The maximum integer to be appended to the virtual identifier. • Min (Long, required) – The minimum integer to be appended to the virtual identifier. • StartingVirtualIndex (Long, required) – The first integer in a range of integers to be appended to the MapTo name.
IVI-3.5: IVI Configuration Server Specification
24
IVI Foundation
3. Instantiation and execution of the IVI Configuration Server 3.1
Installing the Configuration Server The Configuration Server is installed before any IVI software modules are installed. This is enforced by the requirements for installing IVI shared components, IVI instrument drivers and IVI-MSS role control modules described in Section 6, Installation Requirements, of the IVI-3.1: Driver Architecture Specification.
3.1.1 Packaging The IVI Configuration Server installation consists of seven files. • IviConfigServer.dll – The COM server executable file. • README.txt – A file that contains misc. information about the Configuration Server installation, including standard software dependencies, additional included files, and last minute instructions. • IviConfigurationStore.xml – An empty XML configuration store file. • IviConfigurationStore.xsd – The XSL schema for the configuration store file. • IviConfigServerCapi.dll – The C API executable file • IviConfigServer.lib – Microsoft C compatible library files. • IviConfigServer.h – C header file for C API. The IVI Configuration Server implementation uses the “Microsoft XML Core Services 4.0 RTM” which is installed when the IVI Configuration Server is installed. More information on these services is available at http://msdn.microsoft.com/downloads/default.asp?url=/downloads/sample.asp?url=/msdnfiles/027/001/766/msdncompositedoc.xml. In addition, there may be other demo or test programs included – refer to the README.txt file for a complete listing of the files included in the installation.
3.1.2 Data File Installation The installation directory for the master configuration store is\Data. The value of is set by the IVI shared components installer. The master configuration store is installed as IviConfigurationStore.xml. The schema that describes the file format is stored in the same directory as IviConfigurationStore.xsd. The installation program also creates the registry key HKEY/LOCAL_MACHINE/SOFTWARE/IVI/CONFIGURATIONSERVER, MasterStore, and sets the value to \Data\IviConfigurationStore.xml. If the user renames or moves the master configuration store, the user must change the value of the registry key HKEY/LOCAL_MACHINE/SOFTWARE/IVI/CONFIGURATIONSERVER, MasterStore. To find the master configuration store, the Configuration Server looks at the location designated by the registry key.
3.1.3 First Installation When the Configuration Server is installed on a computer for the first time, there is only one entry in the master configuration store – the IviConfigStore entry. This entry carries component and version information, references collections of other Configuration Server objects. The component and version information is read only, and serves to identify the Configuration Server component and version. The collections referenced from the IviConfigStore object are empty. The collection methods and properties themselves may be executed, but will not return any configuration data until collection items (such as Software Modules, Hardware Assets, and so on) are added.
IVI Foundation
25
IVI-3.5: IVI Configuration Server Specification
3.1.4 Subsequent Installations When the Configuration Server is reinstalled on a system, it does not erase existing entries in the master configuration store. If the same version is being reinstalled, no changes will be made to the master configuration store. If a more recent version is being installed, there may be changes. A re-installation may update the values of the IviConfigStore Revision, Description, Specification Major Version, and Specification Minor Version as appropriate. A re-installation will also update or convert the data in the master configuration store to match any changes in the configuration store schema. If the re-installation cannot perform this task silently, a conversion utility will be provided by the IVI foundation as part of the new install, with suitable instructions. Reasonable care will be taken to ensure that the Configuration Server behavior is compatible from revision to revision, and the IVI Foundation strongly recommends that all software access the master configuration store through the Configuration Server.
3.2
Accessing the Configuration Store Users and software module developers should only access the configuration store through the Configuration Server software provided by the IVI Foundation. While it is possible to edit the configuration store XML file directly, it is discouraged because of the potential for introducing invalid data and relationships into the file. Furthermore, the Configuration Server is designed to be independent of the way the data is stored, and insulates users from potential changes in the data format. The Master Location property in the IviConfigStore class returns the full pathname of the master configuration store. It determines the name by reading the registry key HKEY_LOCAL_MACHINE/SOFTWARE/IVI/CONFIGURATIONSERVER, MasterStore. For the precise semantics, refer to Section 7.3.3, Master Location. Users may copy the master configuration store, modify it, and then save it to another file. Refer to Section 3.7, Additional Instances of the Configuration Store, for more details. Users may then designate such a file as the default copy of the configuration store for use in a process by assigning the full pathname of the file to the Process Default Location property in the IviConfigStore class. The Process Default Location property then returns the full pathname of this file. For the precise semantics, refer to Section 7.3.5, Process Default Location. The IVI configuration store provides mechanisms for accessing the master and process default configuration store files. Any utility, including Software Module installation programs, which modify the contents of the master configuration store should consider making a back up copy before serializing a modified version. The IVI Configuration Server tries to maintain the integrity of all configuration store files, but the consequences of a corrupt master configuration store are so severe that a back up could prove very valuable.
3.2.1 Master Configuration Store To access the master configuration store • Instantiate the IVI Configuration Server. • Call the Deserialize method, providing the location of the master configuration store as a parameter. This is obtained through the Master Location property. • Access the configuration data. To modify the master configuration store • Perform steps required to access the master configuration store • Call the Serialize method with the master configuration store filename as a parameter. When serializing to the master configuration store, care must be taken not to modify the data that is added when software modules are installed. For instance, deleting a software module entry could make it impossible to properly configure a driver session to access that software module. IVI-3.5: IVI Configuration Server Specification
26
IVI Foundation
3.2.2 Process Default Configuration Store To set the process default configuration store for the current process • Instantiate the IVI Configuration Server. • Set the value of the Process Default Location property to the full path name of the configuration store file to be used in the current process. To access the process default configuration store • Set the process default configuration store for the current process (see previous step). • Instantiate the IVI Configuration Server (if not already instantiated). • Call the Deserialize method, providing the location of the process default configuration store as a parameter. This is obtained through the Process Default Location property. • Access the configuration data. To modify the process default configuration store • Perform steps required to access the process default configuration store. • Call the Serialize method with the process default configuration store filename as a parameter.
3.2.3 Instantiating the Right Configuration Store From Software Modules Software modules first try to open the process default configuration store. If the Process Default Location property is not the null string, and Deserialize cannot open the process default configuration store, Deserialize returns an error, and the software module returns an error as well. If the Process Default Location property is the null string then the software module tries to open the master configuration store. If Deserialize cannot open the master configuration store, Deserialize returns an error, and the software module returns an error as well.
3.2.4 Serializing to a Different Configuration Store Users may wish to deserialize from one configuration store file and serialize to a different one. One basic example is copying a configuration store from one file to another. This is not part of the use model for driver installation or initialization.
3.3
Adding Entries to Collections There are six “global” collections in the Configuration Server. Global collections include all of the instances of a particular class. The six global collections are • Software Modules • Published APIs • Sessions • Driver Sessions • Hardware Assets • Logical Names When a new instance of one of the six associated classes is added using the Configuration Server, it is added first to the global collection. If a client tries to add it to another collection first, an error is returned. For example, if a software module adds a published API entry, it will add it to the global published APIs collection first, then add it to the Software Module’s published APIs collection.
3.4
Installing Software Modules The configuration store must contain data describing a user-configurable software module before the user can configure the session or driver session that uses it. Installation requirements for software modules, including the configuration store entries, are described in Section 6, Installation Requirements, of the IVI3.1: Driver Architecture Specification. A software module installation program creates the following types of entries in the master configuration store. • A software module entry (required). • A collection of references to published APIs (optional). If the published API entries do not exist, the software module installation program also adds the published API entry. The published API is added
IVI Foundation
27
IVI-3.5: IVI Configuration Server Specification
• • • •
to the global published API collection first, and then added to the software module’s published API collection. A collection of references to IVI Physical Names (optional). One or more collections of physical ranges, each associated with an IVI Physical Name (optional). A collection of references to data components, referenced by the software module (optional). Data components added when the software module is installed are called module-defined data components. A default session that uses the software module (optional).
The software module entry contains the information needed to create a running instance of the software module, as well as a couple of basic identification fields. This is required when IVI class drivers or the IVI Session Factory are used to instantiate an IVI specific driver. The collection of IVI Physical Names identifies the repeated capabilities as defined in the software module. Refer to Section 2.9.2, IVI Physical Name and IVI Physical Range for more information.
3.4.1 Data Components In Software Modules A software module’s data components may be used for two basic purposes – to define initial settings for variables known to the software module, and to document the software module itself.
3.4.1.1
Defining Initial Settings Software module data components may be used to document additional variables that are known by the software module, and that the software module will attempt to read from a configuration server session at run-time. For instance, the software module developer may define a Trace property that determines its tracing behavior, and decide that the software module will attempt to read an initial value for this variable from the configuration server. This variable is added to the data components of the software module when the software module is installed, to document the fact that the software module is capable of reading an initial value for it from the configuration server. There are several reasons to add this type of data component to a software module. • To provide additional configuration for driver operation. The IVI Foundation defines several properties for configuring driver operation (e.g. Cache, Simulate, InterchangeCheck, and so on), but a software module may need additional data. The Trace property mentioned above is an example of this type of data component. • To provide additional configuration for instrument operation. In some cases, an instrument cannot be used interchangeably with others in its class because of some state variable that is not part of the classcompliant interfaces, but which must be set correctly in order for the class-compliant interfaces to work correctly. For example, an instrument that by default returns measurements in terms of period when the class-compliant interface returns frequency could use a data component that allows the user to configure the instrument to measure frequency. Refer to Section 5.10.1.5, Applying Configurable Initial Settings, in IVI-3.1: Driver Architecture Specification. • To provide initial instrument state. In general, the IVI Foundation recommends against using the configuration server to store and restore instrument state. While it is possible, it is very complex and often redundant with other instrument functionality. These data components are added with UsedInSession = “Required” or “Optional” and ReadOnly = True. If UsedInSession = “Required”, the data component is copied by the configuration server to any session when the reference property from the session to the software module is set or changed. If UsedInSession = “Optional”, the configuration server will allow the data component to be added to the session.
3.4.1.2
Documenting the Software Module Data components may be added to the software module just to add information about the software module. The developer may choose to add these when the software module is installed. These data components are added with UsedInSession = “None” to indicate that that they are not to be copied to a session for configuration.
3.4.2 Un-installing Software Modules When deleting software modules, IVI-3.5: IVI Configuration Server Specification
28
IVI Foundation
• • • •
Delete collections for published APIs. Do not delete the published API entries. Delete collections and entries for physical names and ranges. Delete collections and entries for data components. Delete the software module entry.
To accomplish the above, use the Configuration Server to delete the software module entry. The Configuration Server will delete all of the above listed entries correctly. When software module entries are deleted, the sessions that reference them will not be automatically deleted. These sessions may be reusable at a later time, after the software module is installed again, or they may be reusable with another compatible software module.
3.4.3 Re-installing Software Modules When re-installing the same version of a software module, delete and re-add the following entries. • The software module entry. • Collections of published APIs. Do not delete the published API entries. • Collections and entries for physical names and ranges. • Collections and entries for data components. To accomplish the above, use the Configuration Server to delete the software module entry. The Configuration Server will delete all of the above listed entries correctly. Then the installation will add the correct entries as part of the re-install process. Re-installing is not a special feature. It may be implemented with an un-install followed by a normal install. If the default session already exists, do not delete and re-add it. If it does not exist, add it. When re-installing a different version of the software module, the above actions are taken. If the data components associated with the software module have been changed, the installer notifies the user that the older associated sessions are not compatible. (Note: what about silent installs? – log files, etc.)
3.5
Maintaining Configuration Data Users add configuration data to the configuration store. Users have several mechanisms available for maintaining configuration data, including using a proprietary configuration store editor and using the Configuration Server from user application code. Users may manually edit the configuration store files, but this is strongly discouraged. Users can configure several classes in the configuration store • IVI Hardware Assets • IVI Sessions and IVI Driver Sessions • IVI Data Components associated with an IVI Session or an IVI Hardware Asset • IVI Virtual Names and Ranges • IVI Logical Names and Ranges
3.5.1 Configuring Hardware Assets Configuration of hardware assets involves the following types of entries. • Hardware asset entries. These must be added to the global hardware assets collection before being referenced by a session or driver session. • A collection of references to data components, referenced by the hardware asset (optional). These collections and referenced data components are contained in the hardware asset. Hardware asset entries identify the location of the instrument on the I/O buses. Users must add hardware asset entries for each instrument that is available for use by a session. In the future, vendors may provide instruments that make appropriate Hardware Asset entries. There may be multiple entries with the same value for IO Resource Descriptor.
IVI Foundation
29
IVI-3.5: IVI Configuration Server Specification
The hardware asset entries are not contained by the session. In the configuration store, they exist independently of the session, and are not deleted automatically when the session entry is deleted. A hardware asset may not be deleted if a session or driver session refers to it.
3.5.1.1
Data Components in Hardware Assets Data components may be added to a hardware asset entry to further document the hardware asset. These data components are user-defined, since hardware assets are not added by software modules, with UsedInSession = “None”. These may be added with the hardware asset, or at a later time. Refer to Section 3.5.5.1, IVI Hardware Assets for more details. The hardware asset’s data components collection is contained by the hardware asset that references it, and the associated data component entries are also contained by the hardware asset. They are added with and deleted with the hardware asset entry.
3.5.2 Configuring Sessions and Driver Sessions Configuration of sessions and driver sessions involves the following types of entries. • An IVI Session (required). The session entry will be a driver session entry if the referenced software module is an IVI instrument driver. These must be added to the global sessions collection and driver sessions collection (if applicable) before being referenced by a logical name. • A collection of references to IVI Virtual Names (optional). These collections and referenced IVI Virtual Names are contained in the session. • One or more collections of IVI Virtual Ranges, each associated with an IVI Virtual Name (optional). These collections and referenced physical names are contained in the session. • A collection of references to IVI Data Components, referenced by the session (optional). These collections and referenced data components are contained in the session. An IVI Session entry is used to configure a running instance of a software module. IVI instrument drivers are configured using IVI Driver Session, which inherit from IVI Session. Because of the inheritance, driver sessions include all of the functionality associated with sessions, and in addition allow the configuration of seven additional properties that have special meaning to IVI instrument drivers. A session references an IVI Software Module. IVI class drivers and the IVI Session Factory both start with a reference to a session and examine the associated session to determine which software module to instantiate as described in Section 3.6.1, IVI Class Drivers and the IVI Session Factory. The information in the software module entry is sufficient to instantiate the software module – ProgID for IVI-COM, ModulePath for IVI-C. Both may be filled in if the same vendor provides both forms of the driver in the same installation, and one is a wrapper for the other. IVI Sessions may reference zero or one IVI Hardware Asset, but this may not be enough for some software modules that require more than one hardware reference. There are two possible ways to handle this situation. First, IO Resource Descriptor may be overloaded by using a syntax that allows multiple instrument locations to be entered. Second, data components for the additional addresses may be added to the software module entry, and carried over to the session where the values are configured. The session’s IVI Virtual Name, IVI Virtual Range, and IVI Data Components collections are contained by the IVI Session that references them, and the associated virtual name, range, and data component entries are also contained by the session. They are added with and deleted with the session entry.
3.5.2.1
Virtual Names The collection of IVI Virtual Names identifies the repeated capabilities as defined in the client, and maps these names to physical identifiers that are recognized by the software module. Refer to Section 2.9.3, IVI Virtual Name and IVI Virtual Range for more information.
3.5.3 Data Components In Sessions A session’s data components may be used for two basic purposes – to configure initial settings for additional variables known to the associated software module, and to document the session itself. IVI-3.5: IVI Configuration Server Specification
30
IVI Foundation
3.5.3.1
Configurable Initial Settings Software modules may use data components to allow configuration of software module variables at initialization. Refer to section 3.4.1.1, Defining Initial Settings for details. During initialization, the software module looks for these variables in the associated session that contains the configuration information. In order for this to work, the configuration server determines what additional variables are required when the reference to the session’s Software Module is set by examining the data components for the software module, and copies all data components with UsedInSession = “Required” to the session. When it does the copy, it changes ReadOnly to “False”. After the copy, clients may change the values of the session’s data components to the correct values, and may add data components from the associated software module where UsedInSession = “Optional”.
3.5.3.2
Documenting the Session Data components may be added to the session just to add information about the session. The developer may choose to add these when the session is created, or they may be added by a configuration utility, test system, or configuration server user. These data components are added with UsedInSession = “None” to indicate that that they are not copied from the software module.
3.5.4 Configuring Logical Names Configuration of logical identifiers involves the following types of entries. • IVI Logical Name entries that reference session entries.
3.5.5 Documentation Data Components Users or configuration utilities may add user-defined data components to hardware assets and sessions (including driver sessions). These are documentation data components, and there are no pre-defined uses for them – presumably the user or configuration utility that adds them knows why they are there.
3.5.5.1
IVI Hardware Assets Users may add data components with Used In Session = “None”, and Read Only = True or False. The data components are meaningful only to the particular user or configuration utility that added them.
3.5.5.2
IVI Sessions and IVI Driver Sessions Users may add data components with Used In Session = “None”, and ReadOnly = True or False. The data components are meaningful only to the particular user or configuration utility that added them.
3.6
Using Configuration Data The Configuration Server is used to instantiate and initialize IVI instrument drivers and IVI-MSS role control modules. Instantiation is useful for class API interchangeability, using either IVI class drivers or the IVI Session Factory. As part of the Initialize function, software modules read the configuration store and use the data to configure initial values.
3.6.1 IVI Class Drivers and the IVI Session Factory IVI class drivers and the IVI Session Factory both use the configuration store to identify and locate the IVI specific driver software module that they instantiate. The IVI Session Factory can be used to instantiate any kind of software module, including IVI-MSS role control modules. The user provides a logical name or a session or driver session name to the class driver or IVI Session Factory. This name is then used to lookup the associated session or driver session entry, and the software module reference is then used to find the software module entry. The ModulePath or ProgID is then retrieved and used to instantiate the software module. IVI class drivers and the IVI Session Factory need only use Get Session to look up the session and then the software module. However, class drivers may choose to use Get Driver Session to be sure that the name passed in actually resolves to a driver session. Get Session looks for the name first in the Configuration Server’s logical name collection. If it finds it there, it follows the reference to the session. If it doesn’t find the name in the logical name collection, it IVI Foundation
31
IVI-3.5: IVI Configuration Server Specification
tries to find a session with the given name. If it doesn’t find that, it returns an error. If Get Session finds the name in either place, it returns a pointer to the session. Get Driver Session works the same as Get Session, except it is restricted to Driver Sessions.
3.6.2 Software Module Initialization Once a software module is instantiated, it can use the Configuration Server as part of the initialization process. An IVI instrument driver accesses the Configuration Server from the Initialize function. It queries the Configuration Server for the following information. • Hardware Asset. The driver uses the IO Resource Descriptor to establish a connection to the instrument. • The predefined driver properties - Cache, Driver Setup, Interchange Check, Query Instrument Status, Range Check, Record Coercions, and Simulate. These are applied in the Initialize function. • Data components. A driver reads through the data components collection referenced by the session, looking for data component names that it recognizes. If it finds a data component that it doesn’t recognize, it ignores it and continues with the next data component in the collection. After reading through the collection, if it hasn’t retrieved the value of one or more required data components, it reports an error. • Virtual identifiers. A driver reads through the virtual identifiers collection and any associated virtual ranges. It stores the mappings for use when resolving repeated capability names. Refer to section 0, Multiple instances of the same repeated capability may or may not share the same child repeated capabilities. If multiple instances of the same repeated capability share the same child repeated capabilities, the repeated capability tree is symmetrical. In this case, each IVI Physical Name object for that repeated capability references an identical collection of child IVI Physical Name objects. If multiple instances of the same repeated capability do not share the same child repeated capabilities, the repeated capability tree is asymmetrical. In this case, each (parent) IVI Physical Name object for that repeated capability will reference a collection of (child) IVI Physical Name objects that describe the specific child repeated capabilities for that object, and these collections may differ from one parent to the next. For example, if a driver models two displays, and both displays can display two traces, that part of the repeated capability hierarchy would be symmetrical. If a driver models two displays, and the first can display four traces, but the second can only display two, that part of the repeated capability hierarchy is asymmetrical. • IVI Virtual Name and IVI Virtual Range for more details. For IVI-MSS role control modules, initialization happens whenever appropriate, as determined by the software module. Use of the hardware asset reference and virtual identifier, virtual range, and data component collections is analogous to the driver case. There are no pre-defined configuration variables for IVI-MSS that are analogous to the driver session properties.
3.6.3 Interchanging Instruments Several sessions may be set up for a software module, representing several different ways of configuring the module. Since sessions are identified by name, just changing the name in the source code that instantiates and configures the software module is enough to change the way it is configured. Different sessions can point to different hardware assets or different values for configuration properties. In order to avoid any source code changes, use logical names to refer to sessions. If the logical name is used in the client’s source code, the user can use a different session by changing the logical name’s Session property.
IVI-3.5: IVI Configuration Server Specification
32
IVI Foundation
3.7
Additional Instances of the Configuration Store As mentioned above, it is possible to have multiple instances of the configuration store file. There is one master configuration store file on each system, but there may be additional configuration store files. The Process Default property can be set to the full pathname of any configuration store file. The Deserialize method may be called with any full pathname. Deserialize will return an error if the file is not a legal Configuration Store file and cannot be successfully deserialized. Likewise, Serialize may be called with any full pathname, and will return an error if the file cannot be written. Software module installers create entries only in the master configuration store. To create or maintain additional configuration store files, users must copy software module entries using the Configuration Server or use a configuration utility. Users must be careful not to delete the master configuration store’s software module entries, or to make modifications that would destroy the accuracy of the software module entries. This holds not only for the software module entry itself, but also for any associated data components, physical identifiers, or ranges.
3.8
Avoiding the Configuration Server Users can avoid having to interact with the IVI Configuration Server and Store with most IVI specific instrument drivers and many other IVI software modules. In order to avoid interacting with the Configuration Server for IVI specific instrument drivers, • The application program must explicitly specify the location of the IVI-C DLL, or the ProgID of the IVI-COM class. • The Resource Name parameter of the Initialize function must be an IO resource descriptor, rather than a logical name or a session name. • The application program must use the physical identifiers defined in the driver for repeated capabilities. • Either the application program must use the software module’s defaults for configurable attributes, or the application program must set the driver’s attributes to initial values before the attributes are used in the driver. Note that adequate defaults are defined for all of the driver session properties in IVI-3.2: Inherent Capabilities Specification.
3.9
Copying Elements In general, the IVI Configuration Store does not automatically copy data from one element to another. The user is responsible for getting the information from one element and then writing it into the second element. The one exception happens when a Session’s reference to a Software Module is set. Refer to Section 3.5.3.1, Configurable Initial Settings.
IVI Foundation
33
IVI-3.5: IVI Configuration Server Specification
4. Collections The configuration store design makes extensive use of collections of objects from a single class. For instance, the Configuration Store class includes a pointer to a collection of all of the IviHardwareAsset objects in the Configuration Store. All collections are one based. The smallest legal index is one which refers to the first item in the collection. The IVI Configuration Server returns the “Not in Global Collection” error when a reference is made to an element before the element is added to the global collection. For example, a Software Module must be added to the Software Modules collection before the reference in a Session can be set to that Software Module. The same element cannot be added to two collections in the same or different configuration stores. A second separate element with identical values can be used. The only exception is that a Published API can be added to the global Published APIs collection and to the Published APIs collection in a Software Module.
4.1
Collections in COM In COM the designed collections are implemented as standard COM collections. Collection classes are indicated by appending “Collection” to the end of the class that describes the individual objects in the collection. For instance, if a collection points to objects of class IviHardwareAsset, the collection class would be named IviHardwareAssetCollection. The methods implemented by a COM collection are • Item • Count • _NewEnum • Add • Remove All of the above properties and methods have standard COM definitions. Refer to Microsoft documentation for more details. Except for the Published API collection, the Item property and Remove method take one parameter whose type is VARIANT. The contents of the VARIANT may be either the name of an item in the collection or an integer which is the one-based index of an item in the collection. For the Published API collection, the parameters for Item and Remove are described in Section 7.2.4, Published APIs. The _NewEnum property returns an IUnknown pointer. This interface can be queried for an IEnumVARIANT interface which contains the methods: • Next • Skip • Reset • Clone The VARIANT returned by Next can be queried for an interface appropriate for the collection. For example the VARIANT returned within the Hardware Asset Collection can be queried for the IviHardwareAsset interface. All of the above properties and methods have standard COM definitions. Refer to Microsoft documentation for more details. The configuration server implements the following collection classes • IviHardwareAssetCollection • IviSessionCollection • IviDriverSessionCollection • IviPublishedAPICollection
IVI-3.5: IVI Configuration Server Specification
34
IVI Foundation
• • • • • • •
4.2
IviLogicalNameCollection IviSoftwareModuleCollection IviPhysicalNameCollection IviVirtualNameCollection IviPhysicalRangeCollection IviVirtualRangeCollection IviDataComponentCollection
Collections in C In C, collections are accessed with generic functions defined for each class. These functions correspond to methods described for COM collections. • • • • •
IviConfig_GetCount IviConfig_GetItemByIndex IviConfig_GetItemByName IviConfig_AddReference IviConfig_RemoveReference
where represents the name of the collection being accessed. For example, to get the number of IviSession objects in a given IviSessionsCollection, use the function IviConfig_GetSessionCount. To access a particular object in the collection, use the IviConfig_GetSessionItemByIndex function or the IviConfig_GetSessionItemByName function. These functions appear only in the C API. They are equivalent to object creation and destruction handled by normal COM infrustructure. • •
IviConfig_Create IviConfig_Destroy
To create a new item and add it to a collection, use the IviConfig_Create function defined for that collection. To remove an item from a collection, use the IviConfig_Destroy function defined for that collection. For example, to create a new IviSession object and add it to the global IviSessions collection, use the IviConfig_CreateSession function. To delete an IviSession object from the collection, use the IviConfig_DestroySession function. Note that objects can be created and deleted only from those collections that actually own the items. To add a reference to an object to a collection that does not own the item, use the IviConfig_AddReference function. To remove the reference, use the IviConfig_RemoveReference function.
4.3
Properties in C In C, properties for the various objects are accessed using generic functions defined for each class. These function, which correspond to the get and put COM methods are: • •
IviConfig_GetProperty IviConfig_SetProperty
where represents the name of the object for which the property is being accessed and represents the data type of the property . For example, to get the value of the Revision property for an IviConfigStore object, call the IviConfig_GetConfigStorePropertyViString function. All functions that return properties of type ViString comply with the rules in Section 3.1.2.1, Additional Compliance Rules for C Functions with ViChar Array Output Parameters of IVI-3.2: Inherent Capabilities Specification.
IVI Foundation
35
IVI-3.5: IVI Configuration Server Specification
4.4
Return Codes The IVI-3.2: Inherent Capabilities Specification defines general status codes that the collection functions can return. The table below specifies additional IVI configuration server status codes for the Add function. Completion Codes
Description
Not In Global Collection
The item does not exist in the global collection.
Duplicate Entry
An entry with name already exists.
Invalid Data Component
The data component is not a valid data component.
The table below specifies additional IVI configuration server status codes for the Item and Remove functions. Completion Codes Does Not Exist
Description The item does not exist in the collection.
The table below specifies additional IVI configuration server status codes for the Remove function. Completion Codes Reference Still Exists
Description The element cannot be removed from the global collection when it is referenced in the local collections.
The table below specifies additional IVI configuration server status codes for the Get and Set IVI-C functions. Completion Codes Invalid Property ID
IVI-3.5: IVI Configuration Server Specification
Description The specified property ID is not valid for this function.
36
IVI Foundation
5. C API Special Functions 5.1
C API Special Functions Overview This section defines special functions for the IVI Configuration Server C API in addition to the functions defined for each IVI Configuration Server class. These functions are used to create an instance of the configuration server, dispose handles to IVI Configuration Server objects, and to retrieve and clear error codes and messages.
5.2
C API Special Functions The IVI Configuration Server C API defines the following functions: • Clear Error • Close • Dispose Handle • Get Error • Initialize This section describes each function.
IVI Foundation
37
IVI-3.5: IVI Configuration Server Specification
5.2.1 Clear Error Description This function clears the error description for the current thread of execution. The Configuration Server C API logs its errors to the thread-local error variables defined by IVI-3.9 C Shared Component Specification. The Get Error function retrieves and clears these thread-local variables. For more information about thread local variables, refer to IVI-3.9 C Shared Component Specification, Section 7, Thread Local Error Storage for more information. COM Method Prototype N/A
C Function Prototype ViStatus _VI_FUNC IviConfig_ClearError ();
Return Values The IVI-3.2: Inherent Capabilities Specification defines general status codes that this function can return.
IVI-3.5: IVI Configuration Server Specification
38
IVI Foundation
5.2.2 Close Description This function releases the handle to an IVI Configuration Store object. Once a handle to the IVI Configuration Store object is no longer needed, the user must call this function to release the handle. Subsequent use of this handle will return the Invalid Handle error. An application must release all IVI Configuration Store handles by calling this function before terminating. Failure to do so may result in resource or memory leaks. COM Method Prototype N/A
C Function Prototype ViStatus _VI_FUNC IviConfig_Close (IviConfigStoreHandle ConfigStoreHandle);
Return Values The IVI-3.2: Inherent Capabilities Specification defines general status codes that this function can return.
IVI Foundation
39
IVI-3.5: IVI Configuration Server Specification
5.2.3 Dispose Handle Description This function releases the handle to an IVIConfigStore object returned from one of the Get Session, Get Driver Session, Get Collection, Create, Add Reference, Get Item, or Get Reference functions. Once a handle to an item is no longer needed, the user must call this function to release the handle. Subsequent use of this handle will return the Invalid Handle error. An application must release all handles by calling this function before terminating. Failure to do so may result in resource or memory leaks. The user must not pass a handle of type IviConfigStoreHandle as the value of the Handle parameter. The user may pass a handle of any other type. If a handle of type IviConfigStoreHandle is passed as the value of the Handle parameter, this function will return the Invalid Handle error. COM Method Prototype N/A
C Function Prototype ViStatus _VI_FUNC IviConfig_DisposeHandle (IviConfigHandle Handle);
Return Values The IVI-3.2, Inherent Capabilities Specification defines general status codes that this function can return. In addition, it returns the following status codes: Completion Codes Invalid Handle
IVI-3.5: IVI Configuration Server Specification
Description The specified handle is invalid or of an incorrect type.
40
IVI Foundation
5.2.4 Get Error Description This function retrieves and clears the description of the last error that occurred for the current thread of execution. One exception exists: If the BufferSize parameter is zero, the function does not clear the error description. By passing 0 for the buffer size, the caller can ascertain the buffer size required to get the entire error description string and then call the function again with a sufficiently large buffer. The function complies with the rules in IVI-3.2, Inherent Capabilities Specification, Section 3.1.2.1, Additional Compliance Rules for C Functions with ViChar Array Output Parameters. The Configuration Server C API logs its errors to the thread-local error variables defined by IVI-3.9 C Shared Component Specification. The Clear Error function clears these thread-local variables. For more information about thread local variables, refer to Section 7, Thread Local Error Storage in IVI-3.9 C Shared Component Specification for more information. COM Method Prototype N/A
C Function Prototype ViStatus _VI_FUNC IviConfig_GetError (ViInt32 BufferSize, ViChar ErrorDescription[]);
Return Values The IVI-3.2: Inherent Capabilities Specification defines general status codes that this function can return.
IVI Foundation
41
IVI-3.5: IVI Configuration Server Specification
5.2.5 Initialize Description This function creates and returns a handle to a new instance of the IVI Configuration Store class. The user passes this handle to the C API functions defined for the IVI Configuration Store class to access its properties and to obtain handles to the IVI configuration store global collections. This function may also perform additional initialization routines required for the use of the IVI Configuration Server C API. The user must first call this function before calling any other C API function. Every subsequent call to this function will create a new instance of the IVI Configuration Store class. The user must call the Close function once and only once for each successful call to the Initialize function. Refer to Section 1.1.5 Close for more information. COM Method Prototype N/A
C Function Prototype ViStatus _VI_FUNC IviConfig_Initialize (IviConfigStoreHandle* ConfigStoreHandle);
Return Values The IVI-3.2: Inherent Capabilities Specification defines general status codes that this function can return.
IVI-3.5: IVI Configuration Server Specification
42
IVI Foundation
6. IVI Configurable Components Class (Virtual) 6.1
IVI Configurable Components Overview The IVI Configurable Components class allows developers to add properties to several of the other Configuration Server classes. This class is not implemented directly – it is a virtual base class. The following Configuration Server classes inherit from the IVI Configurable Components class: • IVI Session • IVI Driver Session (through IVI Session) • IVI Hardware Asset • IVI Software Module Each of these classes inherits Name, Description, and a reference to a collection of Data Component objects. Each object in the Data Component collection represents either a property added by the developer or a pointer to another collection of Data Component objects.
6.2
IVI Configurable Components References The IVI Configurable Components class defines the following references: • Data Components This section describes each reference.
IVI Foundation
43
IVI-3.5: IVI Configuration Server Specification
6.2.1 Data Components COM Data Type
C Data Type
IIviDataComponentCollection**
Access
IviDataComponentCollectionHandle
R/0
COM Property Name DataComponents
C Function Prototype ViStatus _VI_FUNC IviConfig_GetConfigComponentDataComponentCollection (IviConfigComponentHandle ConfigComponentHandle, IviDataComponentCollectionHandle* DataComponentCollectionHandle);
Parameters Inputs
Description
Datatype
ConfigComponentHa ndle
Handle to an IviConfigComponent object. You may pass a handle to any of the derived IviConfigComponent objects.
IviConfigCompon entHandle
Outputs
Description
Datatype
DataComponentColl ectionHandle
Handle to an IviDataComponentCollection object.
IviDataComponen tCollectionHand le
Description References a collection of DataComponents that modifies the object of which the collection is a part.
IVI-3.5: IVI Configuration Server Specification
44
IVI Foundation
6.3
IVI Configurable Components Properties The IVI Configurable Components class defines the following properties: • Description • Name This section describes the behavior and requirements of each property.
IVI Foundation
45
IVI-3.5: IVI Configuration Server Specification
6.3.1 Description COM Data Type BSTR
Access R/W
COM Property Name Description
C Constant Name IVICONFIG_VAL_CONFIG_COMPONENT_DESCRIPTION
Description The description of the associated object. The empty string is a legal value for this property.
IVI-3.5: IVI Configuration Server Specification
46
IVI Foundation
6.3.2 Name COM Data Type BSTR
Access R/W
COM Property Name Name
C Constant Name IVICONFIG_VAL_CONFIG_COMPONENT_NAME
Description The name of the associated object. The empty string is not a legal value for this property.
IVI Foundation
47
IVI-3.5: IVI Configuration Server Specification
7. IVI Configuration Store Class 7.1
IVI Configuration Store Overview The IVI Configuration Store class is the main class of the Configuration Server. There is exactly one IVI Configuration Store object in each instance of the configuration server. This object is created before any others, and there is no way to delete it. Use of the Configuration Server starts with this object. The IVI Configuration Store class allows users to find out information about the Configuration Server using a similar approach to that used in other IVI components. Information includes Revision, Specification Major Version, Specification Minor Version, and Vendor, as well as Name and Description. The IVI Configuration Store class allows users to Deserialize (load) an IVI configuration store XML file into the Configuration Server, and to Serialize updated information out to the file again. The IVI Configuration Store class provides two helper functions to help developers find Sessions and Driver Sessions in the configuration store. Sessions and Driver Sessions may be identified either by their Name or by a Logical Name that maps to their name. These functions are be used to make sure that the logic used to search for a session is correct and consistent among IVI software modules. Finally, the IVI Configuration Store class provides the means to navigate to collections of Configuration Store objects. This class includes references to collections of Logical Names, Sessions, Driver Sessions, Hardware Assets, Software Modules, and Published APIs.
7.2
IVI Configuration Store References The IVI Configuration Store class defines the following references: • Driver Sessions • Hardware Assets • Logical Names • Published APIs • Sessions • Software Modules This section describes each reference.
IVI-3.5: IVI Configuration Server Specification
48
IVI Foundation
7.2.1 Driver Sessions COM Data Type
C Data Type
IIviDriverSessionCollection**
Access
IviDriverSessionCollectionHandle
R/O
COM Property Name DriverSessions
C Function Prototype ViStatus _VI_FUNC IviConfig_GetConfigStoreDriverSessionCollection (IviConfigStoreHandle ConfigStoreHandle, IviDriverSessionCollectionHandle* DriverSessionCollectionHandle);
Parameters Inputs
Description
Datatype
ConfigStoreHandle
Handle to an IviConfigStore object.
IviConfigStoreH andle
Outputs
Description
Datatype
DriverSessionColl ectionHandle
Handle to an IviDriverSessionCollection object.
IviDriverSessio nCollectionHand le
Description References the global collection of all Driver Session objects in the configuration store.
IVI Foundation
49
IVI-3.5: IVI Configuration Server Specification
7.2.2 Hardware Assets COM Data Type
C Data Type
IIviHardwareAssetCollection**
Access
IviHardwareAssetCollectionHandle
R/O
COM Property Name HardwareAssets
C Function Prototype ViStatus _VI_FUNC IviConfig_GetConfigStoreHardwareAssetCollection (IviConfigStoreHandle ConfigStoreHandle, IviHardwareAssetCollectionHandle* HardwareAssetCollection);
Parameters Inputs
Description
Datatype
ConfigStoreHandle
Handle to an IviConfigStore object.
IviConfigStoreH andle
Outputs
Description
Datatype
HardwareAssetColl ection
Handle to an IviHardwareAssetCollection object.
IviHardwareAsse tCollectionHand le
Description References the global collection of all Hardware Asset objects in the configuration store.
IVI-3.5: IVI Configuration Server Specification
50
IVI Foundation
7.2.3 Logical Names COM Data Type
C Data Type
IIviLogicalNameCollection**
Access
IviLogicalNameCollectionHandle
R/O
COM Property Name LogicalNames
C Function Prototype ViStatus _VI_FUNC IviConfig_GetConfigStoreLogicalNameCollection (IviConfigStoreHandle ConfigStoreHandle, IviLogicalNameCollectionHandle* LogicalNameCollectionHandle);
Parameters Inputs
Description
Datatype
ConfigStoreHandle
Handle to an IviConfigStore object.
IviConfigStoreH andle
Outputs
Description
Datatype
LogicalNameCollec tionHandle
Handle to an IviLogicalNameCollection object.
IviLogicalNameC ollectionHandle
Description References the global collection of all Logical Name objects in the configuration store.
IVI Foundation
51
IVI-3.5: IVI Configuration Server Specification
7.2.4 Published APIs COM Data Type
C Data Type
IIviPublishedAPICollection**
Access
IviPublishedAPIsCollectionHandle
R/O
COM Property Name PublishedAPIs
C Function Prototype ViStatus _VI_FUNC IviConfig_GetConfigStorePublishedAPICollection (IviConfigStoreHandle ConfigStoreHandle, IviPublishedAPICollectionHandle* PublishedAPICollection);
Parameters Inputs
Description
Datatype
ConfigStoreHandle
Handle to an IviConfigStore object.
IviConfigStoreH andle
Outputs
Description
Datatype
PublishedAPIColle ction
Handle to an IviPublishedAPICollection object.
IviPublishedAPI CollectionHandl e
Description References the global collection of all Published API objects in the configuration store. The Item property and Remove method for this collection require parameters different from the other collections. Item( [in] VARIANT varIndex, [in] long MajorVersion, [in] long MinorVersion, [in] BSTR Type, [out, retval]IIviPublishedAPI**pVal) Remove( [in] VARIANT varIndex, [in] long MajorVersion, [in] long MinorVersion, [in] BSTR Type, [out, retval]IIviPublishedAPI**pVal)
If the parameter, varIndex, is an integer, the remaining parameters are ignored as a numeric index completely identifies the item to be retrieved or removed.
IVI-3.5: IVI Configuration Server Specification
52
IVI Foundation
7.2.5 Sessions COM Data Type
C Data Type
IIviSessionCollection**
IviSessionCollectionHandle
Access R/O
COM Property Name Sessions
C Function Prototype ViStatus _VI_FUNC IviConfig_GetConfigStoreSessionCollection (IviConfigStoreHandle ConfigStoreHandle, IviSessionCollectionHandle* SessionCollectionHandle);
Parameters Inputs
Description
Datatype
ConfigStoreHandle
Handle to an IviConfigStore object.
IviConfigStoreH andle
Outputs
Description
Datatype
SessionCollection Handle
Handle to an IviSessionCollection object.
IviSessionColle ctionHandle
Description References the global collection of all IVI Session objects in the configuration store. The collection of all sessions includes all driver sessions.
IVI Foundation
53
IVI-3.5: IVI Configuration Server Specification
7.2.6 Software Modules COM Data Type
C Data Type
IIviSoftwareModuleCollection**
Access
IviSoftwareModuleCollectionHandle
R/O
COM Property Name SoftwareModules
C Function Prototype ViStatus _VI_FUNC IviConfig_GetConfigStoreSoftwareModuleCollection (IviConfigStoreHandle ConfigStoreHandle, IviSoftwareModuleCollectionHandle* SoftwareModuleCollection);
Parameters Inputs
Description
Datatype
ConfigStoreHandle
Handle to an IviConfigStore object.
IviConfigStoreH andle
Outputs
Description
Datatype
SoftwareModuleCol lection
Handle to an IviSoftwareModuleCollection object.
IviSoftwareModu leCollectionHan dle
Description References the global collection of all Software Module objects in the configuration store.
IVI-3.5: IVI Configuration Server Specification
54
IVI Foundation
7.3
IVI Configuration Store Properties The IVI Configuration Store class defines the following properties: • Actual Location • Description • Master Location • Name • Process Default Location • Revision • Specification Major Version • Specification Minor Version • Vendor This section describes the behavior and requirements of each property.
IVI Foundation
55
IVI-3.5: IVI Configuration Server Specification
7.3.1 Actual Location COM Data Type
Access
BSTR
R/O
COM Property Name ActualLocation
C Constant Name IVICONFIG_VAL_CONFIG_STORE_ACTUAL_LOCATION
Description Returns the full pathname of the configuration store file that was successfully deserialized by the current instance of the configuration server. If no configuration store file has been successfully deserialized by the current instance of the configuration server, the property returns the empty string.
IVI-3.5: IVI Configuration Server Specification
56
IVI Foundation
7.3.2 Description COM Data Type BSTR
Access R/W
COM Property Name Description
C Constant Name IVICONFIG_VAL_CONFIG_STORE_DESCRIPTION
Description The description of the Configuration Server component. In a newly created object, this string is “The IVI Configuration Server allows access to and modification of an IVI configuration store.”
IVI Foundation
57
IVI-3.5: IVI Configuration Server Specification
7.3.3 Master Location COM Data Type
Access
BSTR
R/O
COM Property Name MasterLocation
C Constant Name IVICONFIG_VAL_CONFIG_STORE_MASTER_LOCATION
Description Specifies the full pathname of the master configuration store. This includes the file name, which is always IviConfigurationStore.xml. The configuration server checks to see if the registry key HKEY_LOCAL_MACHINE\SOFTWARE\IVI\CONFIGURATIONSERVER, MasterStore exists. If it does exist, then the value of Master Location shall be the value of this key. If it does not exist, the configuration server shall return the Master Not Found error. Return Values The IVI-3.2: Inherent Capabilities Specification defines general status codes that this function can return. The table below specifies additional IVI configuration server status codes for this function. Completion Codes Master Not Found
IVI-3.5: IVI Configuration Server Specification
Description The registry key does not exist or the file can not be found.
58
IVI Foundation
7.3.4 Name COM Data Type BSTR
Access R/O
COM Property Name Name
C Constant Name IVICONFIG_VAL_CONFIG_STORE_NAME
Description The name of the Configuration Server. This string shall be “IVI Configuration Server”.
IVI Foundation
59
IVI-3.5: IVI Configuration Server Specification
7.3.5 Process Default Location COM Data Type BSTR
Access R/W
COM Property Name ProcessDefaultLocation
C Constant Name IVICONFIG_VAL_CONFIG_STORE_PROC_DEFAULT_LOCATION
Description Specifies the full pathname of the default configuration store for the process in which this property is used. If a non-empty string is assigned to this property by code executed in the process, the property shall return that string when accessed in the same process. The empty string is a legal value for this property. Refer to Section 3.2.3, Instantiating the Right Configuration Store From Software Modules, for more information.
IVI-3.5: IVI Configuration Server Specification
60
IVI Foundation
7.3.6 Revision COM Data Type BSTR
Access R/O
COM Property Name Revision
C Constant Name IVICONFIG_VAL_CONFIG_STORE_REVISION
Description This string shall be the current revision of the Configuration Server. The format of the revision string or a revision string is defined in Section 5.18, File Versioning, of the IVI-3.1: Driver Architecture Specification.
IVI Foundation
61
IVI-3.5: IVI Configuration Server Specification
7.3.7 Specification Major Version COM Data Type Long
Access R/O
COM Property Name SpecificationMajorVersion
C Constant Name IVICONFIG_VAL_CONFIG_STORE_SPEC_MAJOR_VERSION
Description This property shall be the major version of the Configuration Server specification supported by the Configuration Server component. The rules related to Specification Major Version are defined in Section 5.18, File Versioning, of the IVI-3.1: Driver Architecture Specification.
IVI-3.5: IVI Configuration Server Specification
62
IVI Foundation
7.3.8 Specification Minor Version COM Data Type Long
Access R/O
COM Property Name SpecificationMinorVersion
C Constant Name IVICONFIG_VAL_CONFIG_STORE_SPEC_MINOR_VERSION
Description This property shall be the minor version of the Configuration Server specification supported by the Configuration Server component. The rules related to Specification Minor Version are defined in Section 5.18, File Versioning, of the IVI-3.1: Driver Architecture Specification.
IVI Foundation
63
IVI-3.5: IVI Configuration Server Specification
7.3.9 Vendor COM Data Type BSTR
Access R/O
COM Property Name Vendor
C Constant Name IVICONFIG_VAL_CONFIG_STORE_VENDOR
Description The vendor of the Configuration Server component. This string shall be “IVI Foundation, Inc.”.
IVI-3.5: IVI Configuration Server Specification
64
IVI Foundation
7.4
IVI Configuration Store Functions The IVI Configuration Store class defines the following functions: • Deserialize • Get Driver Session • Get Session • Serialize This section describes the behavior and requirements of each function.
IVI Foundation
65
IVI-3.5: IVI Configuration Server Specification
7.4.1 Deserialize Description Reads a configuration store file from a data source location, parses the data, and creates the corresponding Configuration Server classes in memory. Deserialize opens the configuration file specified by the Location parameter. The location parameter must be the full pathname of the configuration store file to be opened. If the file is found, but cannot be successfully deserialized, Deseriailize shall return a Deserialized Failed error and the Configuration Server is returned to its initial state. Deserialize may only be run successfully once per instance of the Configuration Server. If Deserialize is called after being previously called successfully it shall return a Already Deserialized error. Multiple copies of the Configuration Server can be accessed by accessing multiple instances of the Configuration Server. COM Method Prototype Deserialize([in] BSTR Location);
C Function Prototype ViStatus _VI_FUNC IviConfig_Deserialize (IviConfigStoreHandle ConfigStoreHandle, ViConstString Location);
Return Values The IVI-3.2: Inherent Capabilities Specification defines general status codes that this function can return. The table below specifies additional IVI configuration server status codes for this function. Completion Codes
Description
Deserialize Failed
The specified Configuration Store file could not be deserialized.
Already Deserialized
A deserialize was attempted after a previous de-serialize had already succeeded.
IVI-3.5: IVI Configuration Server Specification
66
IVI Foundation
7.4.2 Get Driver Session Description Returns a reference to a driver session, given a name that identifies the session. Name may be either the Name of the Driver Session object, or a logical name that refers to the Driver Session object. To find the Driver Session object, Get Driver Session first searches the global Logical Names collection to see if Name is defined in that collection. If Name is found in the collection, Get Driver Session examines the referenced Session. If the Session is a Driver Session, then the Driver Session reference is returned in the DriverSession parameter. If Name is not found in the Logical Names collection, or if the Session referenced by the Logical Name is not a Driver Session, Get Driver Session searches the global Driver Session collection to see if Name is defined in the Driver Session collection. If Name is found in the Driver Session collection, then the Driver Session reference is returned in the DriverSession parameter. If Name is not found in the Logical Names or the Driver Session collections, Get Driver Session shall return a NULL pointer for the DriverSession parameter and shall return a Session Not Found error. Note that if both collections have an item that matches Name, the item found by following the Logical Name reference is returned. COM Method Prototype GetDriverSession([in] BSTR Name, [in,out] IIviDriverSession** DriverSession);
C Function Prototype ViStatus _VI_FUNC IviConfig_GetDriverSession (IviConfigStoreHandle ConfigStoreHandle, ViConstString Name, IviDriverSessionHandle* DriverSessionHandle);
Return Values The IVI-3.2: Inherent Capabilities Specification defines general status codes that this function can return. The table below specifies additional IVI configuration server status codes for this function. Completion Codes Session Not Found
IVI Foundation
Description The session name or logical name could not be resolved to a driver session.
67
IVI-3.5: IVI Configuration Server Specification
7.4.3 Get Session Description Returns a reference to a session, given a name that identifies the session. Name may be either the Name of the Session object, or a logical name that refers to the Session object. To find the Session object, Get Session first searches the global Logical Names collection to see if Name is defined in that collection. If Name is found in the Logical Names collection, then the Session reference is returned in the Session parameter. If Name is not found in the collection, Get Session searches the global Sessions collection to see if Name is defined in the Sessions collection. If Name is found in the collection, then the Session reference is returned in the Session parameter. If Name is not found in the Logical Names or the Sessions collections, Get Session returns a NULL pointer for the Session parameter and returns a Session Not Found error. Note that if both collections have an item that matches Name, the item found by following the Logical Name reference is returned. COM Method Prototype GetSession([in] BSTR Name, [in,out] IIviSession** Session);
C Function Prototype ViStatus _VI_FUNC IviConfig_GetSession (IviConfigStoreHandle ConfigStoreHandle, ViConstString Name, IviSessionHandle* SessionHandle);
Return Values The IVI-3.2: Inherent Capabilities Specification defines general status codes that this function can return. The table below specifies additional IVI configuration server status codes for this function. Completion Codes Session Not Found
IVI-3.5: IVI Configuration Server Specification
Description The session name or logical name could not be resolved to a session.
68
IVI Foundation
7.4.4 Serialize Description Serializes a configuration store from the Configuration Server to a data source location. The Serialize method creates the configuration file specified by the Location parameter. The location parameter must be the full pathname of the configuration store file to be written. If the folders specified in the pathname do not exist, this function will create them. If the file is found, but cannot be successfully serialized, Serialize shall return a Serialize Failed error. COM Method Prototype Serialize([in] BSTR Location)
C Function Prototype ViStatus _VI_FUNC IviConfig_Serialize (IviConfigStoreHandle ConfigStoreHandle, ViConstString Location);
Return Values The IVI-3.2: Inherent Capabilities Specification defines general status codes that this function can return. The table below specifies additional IVI configuration server status codes for this function. Completion Codes Serialize Failed
IVI Foundation
Description The specified Configuration Store file could not be serialized.
69
IVI-3.5: IVI Configuration Server Specification
8. IVI Hardware Asset Class 8.1
IVI Hardware Asset Overview The IVI Hardware Asset class identifies the physical assets available to a system. Hardware assets are identified by their I/O Resource Descriptor, which generally speaking will be unique for a given instrument on a given PC. The Data Components objects referenced by a hardware asset serve to document the hardware asset.
8.1.1 Documentation Data Components Data components that document the hardware asset may be added to the hardware asset’s data components collection at any time. These data components shall have Software Module Key equal to the empty string and Used In Session equal to “None” since they are not used to configure a software module.
8.2
IVI Hardware Asset References The IVI Hardware Asset class inherits the following references from IVI Configurable Component (Section6, IVI Configurable Components Class (Virtual)): • Data Components
8.3
IVI Hardware Asset Properties The IVI Hardware Asset class defines the following properties: • I/O Resource Descriptor The IVI Hardware Asset class inherits the following properties from IVI Configurable Component (Section6, IVI Configurable Components Class (Virtual)): • Description • Name This section describes the behavior and requirements of each property.
IVI-3.5: IVI Configuration Server Specification
70
IVI Foundation
8.3.1 I/O Resource Descriptor COM Data Type
Access
BSTR
R/W
COM Property Name IOResourceDescriptor
C Constant Name IVICONFIG_VAL_HARDWARE_ASSET_IO_DESCRIPTOR
Description I/O Resource Descriptor stores a string that specifies the address of the hardware asset that can be recognized by I/O used by a software module that will access the hardware. For a complete description of the I/O Resource Descriptor property, refer to Section 5.17, Function Compliance Rules and Section 6.14, Initialize, of the IVI-3.2: Inherent Capabilities Specification. The empty string is a legal value for this property.
IVI Foundation
71
IVI-3.5: IVI Configuration Server Specification
9. IVI Published API Class 9.1
IVI Published API Overview Published APIs are APIs that are supported across several products, and as such are published independently of any one component that implements them. Published APIs may be standard APIs published by the IVI Foundation, such as the IviDriver API for IVI driver inherent capabilities (refer to IVI3.2: Inherent Capabilities Specification) or the instrument class specification APIs. Published APIs may also be IVI-MSS roles or IVI Signal Interface APIs. Published APIs may also be vendor-defined APIs that span multiple components. Published APIs are identified by name. The name is a logical description of the API. For instance, the IVIC IviDriver API consists of function prototypes, attribute ID constants, and so on, while the IVI-COM IviDriver API consists of IDL enumerations and interface definitions. In both cases, the name of the published API is “IviDriver”. Published APIs are not necessarily tied to any particular revision of an API. Suppose that the IviDriver API is revised, so that both version 1 and version 2 are implemented in different drivers. In both cases, the name of the published API is “IviDriver”. Published API names are specified by the document that specifies the API. The Type field identifies the syntax of the API. “IVI-C” and “IVI-COM” are predefined values that shall be used for IVI defined APIs. There will be separate Published API entries in the configuration server for the IVI-C IviDriver API and the IVI-COM IviDriver API. The Version fields identify revisions of the API specification which are reflected in the API. Multiple revisions of a specific API (identified by Name and Type) may be stored in the configuration store. Together, the Name, Type, and Version properties identify a unique entry in the global Published API collection. This uniqueness is enforced by the configuration server. However, the properties appear individually in the API.
9.2
IVI Published API Properties The IVI Published API class defines the following properties: • Major Version • Minor Version • Name • Type This section describes the behavior and requirements of each property.
IVI-3.5: IVI Configuration Server Specification
72
IVI Foundation
9.2.1 Major Version COM Data Type long
Access R/W
COM Property Name MajorVersion
C Constant Name IVICONFIG_VAL_PUBLISHED_API_MAJOR_VERSION
Description The major version of this revision of the published API. This is determined by the person or group who publishes the API.
IVI Foundation
73
IVI-3.5: IVI Configuration Server Specification
9.2.2 Minor Version COM Data Type long
Access R/W
COM Property Name MinorVersion
C Constant Name IVICONFIG_VAL_PUBLISHED_API_MINOR_VERSION
Description The minor version of this revision of the published API. This is determined by the person or group who publishes the API.
IVI-3.5: IVI Configuration Server Specification
74
IVI Foundation
9.2.3 Name COM Data Type BSTR
Access R/W
COM Property Name Name
C Constant Name IVICONFIG_VAL_PUBLISHED_API_NAME
Description The name of a Published API. Name may refer to either: • An IVI-defined API. In this case, the first 3 characters of the string shall be “Ivi”. These API names are defined in the various IVI specifications. • An API defined outside of the IVI Foundation. In this case, the first three characters of the string shall not be “Ivi”, where “Ivi” is case insensitive. The definition of these names is specific to the person or group that defines the API. The empty string is not a legal value for this property.
IVI Foundation
75
IVI-3.5: IVI Configuration Server Specification
9.2.4 Type COM Data Type BSTR
Access R/W
COM Property Name Type
C Constant Name IVICONFIG_VAL_PUBLISHED_API_TYPE
Description The type of a Published API. Two predefined values are supported for the IVI defined interfaces, “IVI-C” and “IVI-COM”. These values shall be used for all IVI defined inherent and class APIs. Other user-defined values may be used for other types of APIs. However, if the APIs follow the style guidelines for IVI-C or IVI-COM interfaces as described in IVI-3.4: API Style Guide, it is recommended that “IVI-C” or “IVI-COM” be used as the type, respectively. The empty string is not a legal value for this property.
IVI-3.5: IVI Configuration Server Specification
76
IVI Foundation
10. IVI Software Module Class 10.1 IVI Software Module Overview The Software Module class identifies IVI software components. IVI software components include, but are not limited to, various types of IVI drivers and IVI-MSS components. A Software Module is a software component that exposes its functionality via either an ANSI C or COM API, or both. For ANSI C modules, the value of the Module Path property is the full pathname of the DLL containing the ANSI C entry points. For COM modules, the value of the ProgID property is the version independent ProgID of the software module’s COM coclass. If a single vendor supports both ANSI C and COM APIs for the Software Module object, both Module Path and ProgID have valid values. The Software Module installer is responsible for making sure one or both of these entries are not empty. If both entries are empty, the client program cannot find the Software Module’s executable code. Software Modules may expose one or more APIs that are published and implemented by one or more modules. IVI class-compliant interfaces are examples of such APIs. Refer to Section 9.1, IVI Published API Overview for a description of how Published APIs are defined and treated in the Configuration Server. If a software module implements both ANSI C and COM APIs for the same module, the associated Published API collection shall include references to both types of the APIs. Software Modules may implement repeated capabilities. Refer to Section 2.8.7. IVI API Reference for a description of how repeated capabilities are defined in the Configuration Server. If a Software Module implements repeated capabilities, if must reference a collection of IVI Physical Name objects. The IVI Physical Name objects may be structured hierarchically to reflect a hierarchy of repeated capabilities in the Software Module. Refer to Section 11.1, IVI Physical Name Overview for an overview of how IVI Physical Names may be structured hierarchically. The Data Components objects referenced by a software module are either configurable initial settings or serve to document the software module.
10.1.1 Configurable Initial Settings A configurable initial setting is an IVI Data Component object referenced by an IVI Software Module object with Used In Session equal to “Required” or “Optional”, Read Only equal to “True”, and Type equal to “Boolean”, “String”, “Integer”, “Real”, or “APIReference”. The Value property of the data component is a suitable default value for the setting when the software module is initialized, if possible. The Description property should contain a description of the configurable initial setting and its possible values. If this exceeds the practical size limit for a string, then the data component’s help properties should refer the user to a suitable form of help that fully describes the configurable initial setting and its possible values. Because the configurable initial settings are selected by the software module developer, and are recognized by the software module during initialization, configurable initial settings are only added by the software module when it is installed. Configurable initial settings from the software module are copied to sessions that reference the software module. Refer to Section 14.1.1, Configurable Initial Settings, for more details.
10.1.2 Documentation Data Components Data components that document the software module in some way may be added to the software module’s data components collection at any time. These data components shall have Used In Session equal to “None” since they are not used by the session to configure the software module.
IVI Foundation
77
IVI-3.5: IVI Configuration Server Specification
10.2 IVI Software Module References The IVI Software Module class defines the following references: • Physical Names • Published APIs The IVI Software Module class inherits the following references from IVI Configurable Component Section 6, IVI Configurable Components Class (Virtual) • Data Components This section describes each reference.
IVI-3.5: IVI Configuration Server Specification
78
IVI Foundation
10.2.1 Physical Names COM Data Type
C Data Type
IIviPhysicalNameCollection**
Access
IviPhysicalNameCollectionHandle
R/O
COM Property Name PhysicalNames
C Function Prototype ViStatus _VI_FUNC IviConfig_GetSoftwareModulePhysicalNameCollection (IviSoftwareModuleHandle SoftwareModuleHandle, IviPhysicalNameCollectionHandle* PhysicalNameCollectionHandle);
Parameters Inputs
Description
Datatype
SoftwareModuleHan dle
Handle to an IviSoftwareModule object.
IviSoftwareModu leHandle
Outputs
Description
Datatype
PhysicalNameColle ctionHandle
Handle to an IviPhysicalNameCollection object.
IviPhysicalName CollectionHandl e
Description References a collection of all the PhysicalName objects defined by the Software Module. If a Software Module implements IVI instrument class-compliant APIs that have repeated capabilities, it shall reference a collection of IVI Physical Name objects for the class-defined repeated capabilities. This information is required in order to specify virtual identifiers for IVI Sessions and Driver Sessions, and virtual identifiers are required to use repeated capabilities interchangeably. For other repeated capabilities in a Software Module, physical identifiers are optional but recommended, particularly if needed to support interchangeability. The IVI Physical Name collections may be structured hierarchically to reflect a hierarchy of repeated capabilities in the Software Module. Refer to Section 11.1, IVI Physical Name Overview for an description of how physical identifiers may be structured hierarchically.
IVI Foundation
79
IVI-3.5: IVI Configuration Server Specification
10.2.2 Published APIs COM Data Type
C Data Type
IIviPublishedAPICollection**
Access
IviPublishedAPIsCollectionHandle
R/O
COM Property Name PublishedAPIs
C Function Prototype ViStatus _VI_FUNC IviConfig_GetSoftwareModulePublishedAPIsCollection (IviSoftwareModuleHandle SoftwareModuleHandle, IviPublishedAPIsCollectionHandle* PublishedAPIsCollectionHandle);
Parameters Inputs
Description
Datatype
SoftwareModuleHan dle
Handle to an IviSoftwareModule object.
IviSoftwareModu leHandle
Outputs
Description
Datatype
PublishedAPIsColl ectionHandle
Handle to an IviPublishedAPIsCollection object.
IviPublishedAPI sCollectionHand le
Description References a collection of all the Published APIs that are implemented by the Software Module. Refer to Section 9.1, IVI Published API Overview for an overview of Published APIs. Before a Published API can be added to a Software Module’s Published API collection, it must already exist in the global Published API collection. To add a Published API to a Software Module’s Published API collection first get the Published API from the global collection and the add the returned reference to the Software Module’s collection.
IVI-3.5: IVI Configuration Server Specification
80
IVI Foundation
10.3 IVI Software Module Properties The IVI Software Module class defines the following properties: • Module Path • Prefix • ProgID • Supported Instrument Models The IVI Software Module class inherits the following properties from IVI Configurable Component Section 6, IVI Configurable Components Class (Virtual) • Description • Name This section describes the behavior and requirements of each property.
IVI Foundation
81
IVI-3.5: IVI Configuration Server Specification
10.3.1 Module Path COM Data Type BSTR
Access R/W
COM Property Name ModulePath
C Constant Name IVICONFIG_VAL_SW_MODULE_PATH
Description Returns a string that specifies the full pathname of the software module. This property may be an empty string.
IVI-3.5: IVI Configuration Server Specification
82
IVI Foundation
10.3.2 Prefix COM Data Type BSTR
Access R/W
COM Property Name Prefix
C Constant Name IVICONFIG_VAL_SW_MODULE_PREFIX
Description Prefix is a string that specifies the prefix (for IVI-C components) or the component identifier (for IVI-COM components) of the software module. This shall exactly match the value returned by the Prefix attribute or the Component Identifier attributes. Refer to Section 5.6, Class Driver Prefix, Section 5.13, Component Identifier, and Section 5.32, Specific Driver Prefix, of the IVI-3.2: Inherent Capabilities Specification, for complete details. The empty string is a legal value for this property.
IVI Foundation
83
IVI-3.5: IVI Configuration Server Specification
10.3.3 ProgID COM Data Type BSTR
Access R/W
COM Property Name ProgID
C Constant Name IVICONFIG_VAL_SW_MODULE_PROGID
Description ProgID returns a string that specifies the version-independent COM ProgID of the software module. This property may be an empty string.
IVI-3.5: IVI Configuration Server Specification
84
IVI Foundation
10.3.4 Supported Instrument Models COM Data Type
Access
BSTR
R/W
COM Property Name SupportedInstrumentModels
C Constant Name IVICONFIG_VAL_SW_MODULE_SUPPORTED_INSTR_MODELS
Description A comma-separated string that specifies the instrument models supported by the software module. This shall exactly match the value returned by the Supported Instrument Models attribute as defined in Section 5.35, Supported Instrument Models, of the IVI-3.2: Inherent Capabilities Specification.
IVI Foundation
85
IVI-3.5: IVI Configuration Server Specification
11. IVI Physical Name Class 11.1 IVI Physical Name Overview IVI Physical Name objects describe the physical identifiers supported by a software module. Physical identifiers are the names that an IVI specific instrument driver, IVI-MSS role control module, or other IVI software module gives to instances of the repeated capabilities they implement. For example, one IviScope specific instrument driver might name channels “A”, “B”, and “C” while another might name them “1”, “2”, “3’, and “4”. The RC Name property describes the type of repeated capability. In the above example, RC Name might be “Channel” – the name of the repeated capability in the IviScope specification. An IVI Physical Name object can reference a collection of IVI Physical Name objects, thereby creating a hierarchy of nested repeated capabilities. An IVI Physical Name object can reference a collection of IVI Physical Range objects, which allows an efficient way of creating a large number of physical identifiers by appending integers from the range to the Name property. For a comprehensive overview of the treatment of repeated capabilities in the Configuration Server, including the role that physical identifiers play, refer to Section 2.9, Repeated Capabilities.
11.2 IVI Physical Name References The IVI Physical Name class defines the following references: • Physical Names • Physical Ranges This section describes the behavior and requirements of each property.
IVI-3.5: IVI Configuration Server Specification
86
IVI Foundation
11.2.1 Physical Names COM Data Type
C Data Type
IIviPhysicalNameCollection**
Access
IviPhysicalNameCollectionHandle
R/O
COM Property Name PhysicalNames
C Function Prototype ViStatus _VI_FUNC IviConfig_GetPhysicalNameChildPhysicalNameCollection (IviPhysicalNameHandle PhysicalNameHandle, IviPhysicalNameCollectionHandle* ChildPhysicalNameCollectionHandle);
Parameters Inputs
Description
Datatype
PhysicalNameHandle
Handle to an IviPhysicalName object.
IviPhysicalName Handle
Outputs
Description
Datatype
ChildPhysicalNameC ollectionHandle
Handle to an IviPhysicalNameCollection object.
IviPhysicalName CollectionHandl e
Description References a collection of the IVI Physical Name objects that are hierarchically structured under this IVI Physical Name object. This collection will commonly be empty.
IVI Foundation
87
IVI-3.5: IVI Configuration Server Specification
11.2.2 Physical Ranges COM Data Type
C Data Type
IIviPhysicalRangeCollection **
Access
IviPhysicalRangeCollectionHandle
R/O
COM Property Name PhysicalRanges
C Function Prototype ViStatus _VI_FUNC IviConfig_GetPhysicalNamePhysicalRangeCollection (IviPhysicalNameHandle PhysicalNameHandle, IviPhysicalRangeCollectionHandle* PhysicalRangeCollectionHandle);
Parameters Inputs
Description
Datatype
PhysicalNameHandle
Handle to an IviPhysicalName object.
IviPhysicalName Handle
Outputs
Description
Datatype
PhysicalRangeColle ctionHandle
Handle to an IviPhysicalRangeCollection object.
IviPhysicalRang eCollectionHand le
Description References a collection of IVI Physical Range objects used to qualify the referencing IVI Physical Name object.
IVI-3.5: IVI Configuration Server Specification
88
IVI Foundation
11.3 IVI Physical Name Properties The IVI Physical Name class defines the following properties: • Name • RC Name This section describes the behavior and requirements of each property.
IVI Foundation
89
IVI-3.5: IVI Configuration Server Specification
11.3.1 Name COM Data Type BSTR
Access R/W
COM Property Name Name
C Constant Name IVICONFIG_VAL_PHYSICAL_NAME_NAME
Description The name of a specific instance of a repeated capability as defined in the software module. This is also known as the physical identifier. Name shall consist of one or more of the following characters: ‘a’-‘z’, ‘A’-‘Z’, ‘0’-‘9’, ‘!’, and ‘_’. The empty string is valid for this property only if the IVI Physical Name object references a non-empty collection of Physical Range objects.
IVI-3.5: IVI Configuration Server Specification
90
IVI Foundation
11.3.2 RC Name COM Data Type BSTR
Access R/W
COM Property Name RCName
C Constant Name IVICONFIG_VAL_PHYSICAL_NAME_RCNAME
Description The repeated capability name as defined in the software module. Each IVI Physical Name object represents an instance of the repeated capability of type RC Name. For software modules that reference Published APIs that define repeated capabilities, the RC Name shall be the repeated capability name defined by the Published API specification. The empty string is not a legal value for this property.
IVI Foundation
91
IVI-3.5: IVI Configuration Server Specification
12. IVI Physical Range Class 12.1 IVI Physical Range Overview The IVI Physical Range class allows multiple instances of a repeated capability to be defined with a minimum of effort. An IVI Physical Range object shall be referenced by exactly one IVI Physical Name object. For a comprehensive overview of the treatment of repeated capabilities in the Configuration Server, including the role that physical names play, refer to Section 2.9, Repeated Capabilities.
12.2 IVI Physical Range Properties The IVI Physical Range class defines the following properties: • Max • Min • Name This section describes the behavior and requirements of each property.
IVI-3.5: IVI Configuration Server Specification
92
IVI Foundation
12.2.1 Max COM Data Type long
Access R/W
COM Property Name Max
C Constant Name IVICONFIG_VAL_PHYSICAL_RANGE_MAX
Description The upper end of a range of integers to be appended to the Name property of the referencing IVI Physical Name object to create a set of physical repeated capability identifiers.
IVI Foundation
93
IVI-3.5: IVI Configuration Server Specification
12.2.2 Min COM Data Type long
Access R/W
COM Property Name Min
C Constant Name IVICONFIG_VAL_PHYSICAL_RANGE_MIN
Description The lower end of a range of integers to be appended to the Name property of the referencing IVI Physical Name object to create a set of physical repeated capability identifiers.
IVI-3.5: IVI Configuration Server Specification
94
IVI Foundation
12.2.3 Name COM Data Type BSTR
Access R/W
COM Property Name Name
C Constant Name IVICONFIG_VAL_PHYSICAL_RANGE_NAME
Description The name of the physical range. This name is used to uniquely identify the range in the collection, and is not used in creating the set of physical identifiers. The empty string is not a legal value for this property.
IVI Foundation
95
IVI-3.5: IVI Configuration Server Specification
13. IVI Logical Name Class 13.1 IVI Logical Name Overview Logical Names introduce an additional level of indirection when referencing IVI Sessions and IVI Driver Sessions. Logical Names allow users to define and name multiple Sessions and switch between them by referencing a Logical Name in a client program. The user changes the Logical Name reference to point to any one of the Sessions depending on the situation, without changing source code. It is impossible to tell by looking at a Logical Name object whether the reference is to a Session or a Driver Session. The Session object must be examined by the client code to determine whether or not it is a Driver Session.
13.2 IVI Logical Name References The IVI Logical Name class defines the following properties: • Session This section describes each reference.
IVI-3.5: IVI Configuration Server Specification
96
IVI Foundation
13.2.1 Session COM Data Type IIviSession**
C Data Type IviSessionHandle
Access R/W
COM Property Name Session
C Function Prototype ViStatus _VI_FUNC IviConfig_GetLogicalNameSessionReference (IviLogicalNameHandle LogicalNameHandle, IviSessionHandle* SessionHandle); ViStatus _VI_FUNC IviConfig_SetLogicalNameSessionReference (IviLogicalNameHandle LogicalNameHandle, IviSessionHandle SessionHandle);
Parameters Inputs
Description
Datatype
LogicalNameHandle
Handle to an IviLogicalNameHandle object.
IviLogicalNameH andle
SessionHandle
Handle to an IviSession object.
IviSessionHandl e
Outputs
Description
Datatype
SessionHandle
Handle to an IviSession object.
IviSessionHandl e
Description The IVI Session to which the logical name refers. The IVI Session may be an IVI Driver Session. Return Values The IVI-3.2: Inherent Capabilities Specification defines general status codes that this function can return. The table below specifies additional IVI configuration server status codes for this function. Completion Codes Not In Global Collection
IVI Foundation
Description The item does not exist in the global collection.
97
IVI-3.5: IVI Configuration Server Specification
13.3 IVI Logical Name Properties The IVI Logical Name class defines the following properties: • Name This section describes the behavior and requirements of each property.
IVI-3.5: IVI Configuration Server Specification
98
IVI Foundation
13.3.1 Name COM Data Type BSTR
Access R/W
COM Property Name Name
C Constant Name IVICONFIG_VAL_LOGICAL_NAME_NAME
Description The logical name. The empty string is not a legal value for this property.
IVI Foundation
99
IVI-3.5: IVI Configuration Server Specification
14. IVI Session Class 14.1 IVI Session Overview The IVI Session class provides the information needed to configure a software module. A software module may be referenced by several sessions. In other words, the configuration store may contain several configurations for one software module. The client specifies at run time which configuration will be used. The Software Module property refers to the specific module configured by an IVI Session object. The Hardware Asset property refers to the hardware asset that identifies the specific instrument or other physical asset that will be used by the software module. Virtual identifiers are used to assign client specific names to the physical identifiers used by the software module for repeated capabilities. Refer to Section 16.1, IVI Virtual Name Overview, for more information. The Data Components objects referenced by a session are either configurable initial settings or serve to document the session.
14.1.1 Configurable Initial Settings Configurable initial settings from the software module are copied to the configurable initial settings of the sessions that reference the software module. A configurable initial setting for a session is an IVI Data Component object referenced by an IVI Session object with Used In Session equal to “Required” or “Optional”. Read Only is set to “False”. The Value property of the data component is set to the desired initial value for the software module when it is initialized. All of the other properties are copied over unchanged from the software module referenced by the session. A session shall include all of the configurable initial settings with Used In Session equal to “Required” from the referenced software module. Clients may optionally copy configurable initial settings with Used In Session equal to “Optional” from the referenced software module. In general, the configuration server tries to preserve a session and all of its configurable initial settings, even if the referenced software module is deleted. This preserves configuration information when, for instance, a driver is reinstalled or upgraded to a new version. The configuration server employs relatively complex logic to meet this objective. •
When the session’s Software Module reference property is set for the first time, the configuration server copies all of the configurable initial settings with Used In Session equal to “Required” from the referenced software module. Users may subsequently copy configurable initial settings with Used In Session equal to “Optional” over to the session using a configuration utility.
•
When the session’s Software Module reference property is set to a null reference or the reference is changed explicitly, the configuration server deletes all of the configurable initial settings from the session. The session will not “remember” the previously referenced software module by its Name.
•
If the software module referenced by the session’s Software Module reference property is deleted, the session’s Software Module reference property is set to a null reference implicitly. However, the session will “remember” the previously referenced software module by its Name. This remembered name is returned by the Software Module Name property. The configuration server does not delete the session’s configurable settings in this case.
•
When the configuration server adds a new software module, it finds all sessions with Software Module Name identical to that of the newly added software module. For each session found, the configuration
IVI-3.5: IVI Configuration Server Specification
100
IVI Foundation
server checks to see if the session’s configurable initial settings match the newly added software module’s configurable settings. • A software module configurable setting matches a session configurable setting if the two have identical values for the Name, Type, and, where applicable, Units properties. • If a matching configurable setting is found, then the values for Description, Help Context ID, Help File Path, Software Module Key, and Used In Session are copied from the software module’s configurable setting to the matching session’s configurable setting. Read Only and Value are not changed in the session’s configurable setting. • Software module configurable settings that don’t match any session configurable settings are copied to the session if Used In Session is equal to “Required”. • Session configurable settings that don’t match any software module configurable settings are deleted from the session if Used In Session is equal to “Required”.
14.1.2 Documentation Data Components Data components that document the session in some way may be added to the session’s data components collection at any time. These data components shall have “Used In Session” equal to “None” since they are not used by the session to configure the software module.
14.2 IVI Session References The IVI Session class defines the following references: • Hardware Asset • Software Module • Virtual Names The IVI Software Module class inherits the following reference from IVI Configurable Component Section 6, IVI Configurable Components Class (Virtual) • Data Components This section describes each reference.
IVI Foundation
101
IVI-3.5: IVI Configuration Server Specification
14.2.1 Hardware Asset COM Data Type IIviHardwareAsset**
C Data Type
Access
IviHardwareAssetHandle
R/W
COM Property Name HardwareAsset
C Function Prototype ViStatus _VI_FUNC IviConfig_GetSessionHardwareAssetReference (IviSessionHandle SessionHandle, IviHardwareAssetHandle* HardwareAssetHandle); ViStatus _VI_FUNC IviConfig_SetSessionHardwareAssetReference (IviSessionHandle SessionHandle, IviHardwareAssetHandle HardwareAssetHandle);
Parameters Inputs
Description
Datatype
SessionHandle
Handle to an IviSession object.
IviSessionHandl e
Outputs
Description
Datatype
HardwareAssetHand le
Handle to an IviHardwareAsset object.
IviHardwareAsse tHandle
Description References the Hardware Asset used by the Session. Return Values The IVI-3.2: Inherent Capabilities Specification defines general status codes that this function can return. The table below specifies additional IVI configuration server status codes for this function. Completion Codes Not In Global Collection
IVI-3.5: IVI Configuration Server Specification
Description The item does not exist in the global collection.
102
IVI Foundation
14.2.2 Software Module COM Data Type IIviSoftwareModule**
C Data Type
Access
IviSoftwareModuleHandle
R/W
COM Property Name SoftwareModule
C Function Prototype ViStatus _VI_FUNC IviConfig_GetSessionSoftwareModuleReference (IviSessionHandle SessionHandle, IviSoftwareModuleHandle* SoftwareModuleHandle); ViStatus _VI_FUNC IviConfig_SetSessionSoftwareModuleReference (IviSessionHandle SessionHandle, IviSoftwareModuleHandle SoftwareModuleHandle);
Parameters Inputs
Description
Datatype
SessionHandle
Handle to an IviSession object.
IviSessionHandl e
Outputs
Description
Datatype
SoftwareModuleHan dle
Handle to an IviSoftwareModule object.
IviSoftwareModu leHandle
Description References the Software Module configured by the Session. Return Values The IVI-3.2: Inherent Capabilities Specification defines general status codes that this function can return. The table below specifies additional IVI configuration server status codes for this function. Completion Codes Not In Global Collection
IVI Foundation
Description The item does not exist in the global collection.
103
IVI-3.5: IVI Configuration Server Specification
14.2.3 Virtual Names COM Data Type
C Data Type
IIviVirtualNameCollection**
Access
IviVirtualNameCollectionHandle
R/O
COM Property Name VirtualNames
C Function Prototype ViStatus _VI_FUNC IviConfig_GetSessionVirtualNameCollection (IviSessionHandle SessionHandle, IviVirtualNameCollectionHandle* VirtualNameCollectionHandle);
Parameters Inputs
Description
Datatype
SessionHandle
Handle to an IviSession object.
IviSessionHandl e
Outputs
Description
Datatype
VirtualNameCollec tionHandle
Handle to an IviVirtualNameCollection object.
IviVirtualNameC ollectionHandle
Description References a collection of all the IVI Virtual Name objects used by the Session. Within a collection, the Name property uniquely identifies an IVI Virtual name object. IVI Virtual Name objects cannot be reused between sessions.
IVI-3.5: IVI Configuration Server Specification
104
IVI Foundation
14.3 IVI Session Properties The IVI Session class defines the following property: • Software Module Name The IVI Session class inherits the following properties from IVI Configurable Component - Section 6, IVI Configurable Components Class (Virtual) • Description • Name This section describes the behavior and requirements of each property.
IVI Foundation
105
IVI-3.5: IVI Configuration Server Specification
14.3.1 Software Module Name COM Data Type BSTR
Access R/O
COM Property Name SoftwareModuleName
C Constant Name IVICONFIG_VAL_SESSION_SOFTWARE_MODULE_NAME
Description The name of the current or most recently referenced software module referenced by the Software Module property.
IVI-3.5: IVI Configuration Server Specification
106
IVI Foundation
15. IVI Driver Session Class 15.1 IVI Driver Session Overview The IVI Driver Session class inherits from the IVI Session class, and adds several properties that may be configured for IVI instrument driver software modules. These properties are common to all IVI instrument drivers, and are defined in IVI-3.2: Inherent Capabilities Specification.
15.2 IVI Driver Session References The IVI Driver Session class inherits the following references from IVI Session - Section 14, IVI Session Class: • Hardware Asset • Software Module • Virtual Names The IVI Driver Session class inherits the following reference from IVI Configurable Component – Section 6, IVI Configurable Components Class (Virtual): • Data Components
15.3 IVI Driver Session Properties The IVI Driver Session class defines the following properties: • Cache • Driver Setup • Interchange Check • Query Instrument Status • Range Check • Record Coercions • Simulate The IVI Driver Session class inherits the following properties from IVI Configurable Component – Section 6, IVI Configurable Components Class (Virtual): • Description • Name This section describes the behavior and requirements of each property.
IVI Foundation
107
IVI-3.5: IVI Configuration Server Specification
15.3.1 Cache COM Data Type
Access
VARIANT_BOOL
R/W
COM Property Name Cache
C Constant Name IVICONFIG_VAL_DRIVER_SESSION_CACHE
Description Cache stores the Boolean value that initializes the Cache attribute in an IVI instrument specific driver. For a complete description of the Cache attribute, refer to Section 5.1, Cache, of IVI-3.2: Inherent Capabilities Specification.
IVI-3.5: IVI Configuration Server Specification
108
IVI Foundation
15.3.2 Driver Setup COM Data Type BSTR
Access R/W
COM Property Name DriverSetup
C Constant Name IVICONFIG_VAL_DRIVER_SESSION_DRIVER_SETUP
Description Driver Setup stores the string that initializes the Driver Setup attribute in an IVI instrument specific driver. For a complete description of the Driver Setup attribute, refer to Section 5.16, Driver Setup, of IVI-3.2: Inherent Capabilities Specification. The empty string is a legal value for this property.
IVI Foundation
109
IVI-3.5: IVI Configuration Server Specification
15.3.3 Interchange Check COM Data Type
Access
VARIANT_BOOL
R/W
COM Property Name InterchangeCheck
C Constant Name IVICONFIG_VAL_DRIVER_SESSION_INTERCHANGE_CHECK
Description Interchange Check stores the Boolean value that initializes the Interchange Check attribute in an IVI instrument specific driver. For a complete description of the Interchange Check attribute, refer to Section 5.22, Interchange Check, of IVI-3.2: Inherent Capabilities Specification.
IVI-3.5: IVI Configuration Server Specification
110
IVI Foundation
15.3.4 Query Instrument Status COM Data Type
Access
VARIANT_BOOL
R/W
COM Property Name QueryInstrStatus
C Constant Name IVICONFIG_VAL_DRIVER_SESSION_QUERY_INSTR_STATUS
Description Query Instrument Status stores the Boolean value that initializes the Query Instrument Status attribute in an IVI instrument specific driver. For a complete description of the Query Instrument Status attribute, refer to Section 5.24, Query Instrument Status, of IVI-3.2: Inherent Capabilities Specification.
IVI Foundation
111
IVI-3.5: IVI Configuration Server Specification
15.3.5 Range Check COM Data Type
Access
VARIANT_BOOL
R/W
COM Property Name RangeCheck
C Constant Name IVICONFIG_VAL_DRIVER_SESSION_RANGE_CHECK
Description Range Check stores the Boolean value that initializes the Range Check attribute in an IVI instrument specific driver. For a complete description of the Range Check attribute, refer to Section 5.25, Range Check, of IVI-3.2: Inherent Capabilities Specification.
IVI-3.5: IVI Configuration Server Specification
112
IVI Foundation
15.3.6 Record Value Coercions COM Data Type
Access
VARIANT_BOOL
R/W
COM Property Name RecordCoercions
C Constant Name IVICONFIG_VAL_DRIVER_SESSION_RECORD_COERCIONS
Description Record Value Coercions stores the Boolean value that initializes the Record Value Coercions attribute in an IVI instrument specific driver. For a complete description of the Record Value Coercions attribute, refer to Section 5.26, Record Value Coercions, of IVI-3.2: Inherent Capabilities Specification.
IVI Foundation
113
IVI-3.5: IVI Configuration Server Specification
15.3.7 Simulate COM Data Type
Access
VARIANT_BOOL
R/W
COM Property Name Simulate
C Constant Name IVICONFIG_VAL_DRIVER_SESSION_SIMULATE
Description Simulate stores the Boolean value that initializes the Simulate attribute in an IVI instrument specific driver. For a complete description of the Simulate attribute, refer to Section 5.27, Simulate, of IVI-3.2: Inherent Capabilities Specification.
IVI-3.5: IVI Configuration Server Specification
114
IVI Foundation
16. IVI Virtual Name Class 16.1 IVI Virtual Name Overview IVI Virtual Name objects describe virtual identifiers defined by the user for a particular session. Virtual identifiers are the names that a client program gives to instances of the repeated capabilities it accesses in software modules. For example, an IVI Scope specific instrument driver might name channels “A”, “B”, and “C” while the client programmer might choose to name them “Chan1”, “Chan2”, and “Chan3”. In this case, “A”, “B”, and “C” are physical identifiers defined by the software module and “Chan1”, “Chan2”, and “Chan3” are the corresponding virtual identifiers used by the client program. Name is the virtual identifier string. It may be qualified by referenced Virtual Ranges. MapTo is the string that is substituted for the virtual identifier. It may be qualified by referenced Virtual Ranges. An IVI Virtual Name object can reference a collection of IVI Virtual Range objects, which allows an efficient way of creating a large number of virtual identifiers by appending integers from the range to the Name property. For a comprehensive overview of the treatment of repeated capabilities in the Configuration Server, including the role that IVI Virtual Names play, refer to Section 2.9, Repeated Capabilities.
16.2 IVI Virtual Name References The IVI Virtual Name class defines the following reference: • Virtual Ranges This section describes each reference.
IVI Foundation
115
IVI-3.5: IVI Configuration Server Specification
16.2.1 Virtual Ranges COM Data Type
C Data Type
IIviVirtualRangeCollection **
Access
IviVirtualRangeCollectionHandle
R/O
COM Property Name VirtualRanges
C Function Prototype ViStatus _VI_FUNC IviConfig_GetVirtualNameVirtualRangeCollection (IviVirtualNameHandle VirtualNameHandle, IviVirtualRangeCollectionHandle* VirtualRangeCollectionHandle);
Parameters Inputs
Description
Datatype
VirtualNameHandle
Handle to an IviVirtualName object.
IviVirtualNameH andle
Outputs
Description
Datatype
VirtualRangeColle ctionHandle
Handle to an IviVirtualRangeCollection object.
IviVirtualRange CollectionHandl e
Description References a collection of IVI Virtual Range objects used to qualify the referencing IVI Virtual Name object.
IVI-3.5: IVI Configuration Server Specification
116
IVI Foundation
16.3 IVI Virtual Name Properties The IVI Virtual Name class defines the following properties: • Map To • Name This section describes the behavior and requirements of each property.
IVI Foundation
117
IVI-3.5: IVI Configuration Server Specification
16.3.1 Map To COM Data Type BSTR
Access R/W
COM Property Name MapTo C Constant Name IVICONFIG_VAL_VIRTUAL_NAME_MAPTO
Description A string used to replace the virtual identifier when the virtual identifier is used to specify repeated capability instances in a software module. When the software module encounters the associated virtual identifier in a repeated capability selector, it substitutes the Map To string for the virtual identifier. The software module is responsible for determining if the resulting string is a valid physical repeated capability selector in context. Refer to section 5.9.2, Applying Virtual Identifier Mappings, of IVI-3.1: Driver Architecture Specification for a description of how software modules resolve virtual identifiers. The empty string is a legal value for this property only if the IVI Virtual Name object references a nonempty collection of IVI Virtual Range objects.
IVI-3.5: IVI Configuration Server Specification
118
IVI Foundation
16.3.2 Name COM Data Type BSTR
Access R/W
COM Property Name Name
C Constant Name IVICONFIG_VAL_VIRTUAL_NAME_NAME
Description The virtual identifier name. When the software module encounters the virtual identifier name in a repeated capability selector, it substitutes the Map To string for the virtual identifier. The software module is responsible for determining if the resulting string is a valid physical repeated capability selector in context. Refer to section 5.9.2, Applying Virtual Identifier Mappings, of IVI-3.1: Driver Architecture Specification for a description of how software modules resolve virtual identifiers. Name shall consist of one or more of the following characters: ‘a’-‘z’, ‘A’-‘Z’, ‘0’-‘9’, ‘!’, and ‘_’. The empty string is not a legal value for this property.
IVI Foundation
119
IVI-3.5: IVI Configuration Server Specification
17. IVI Virtual Range Class 17.1 IVI Virtual Range Overview The IVI Virtual Range class allows multiple virtual identifiers to be defined with a minimum of effort. An IVI Virtual Range object shall be referenced by exactly one IVI Virtual Name object. For a comprehensive overview of the treatment of repeated capabilities in the Configuration Server, including the role that virtual names play, refer to Section 2.9, Repeated Capabilities.
17.2 IVI Virtual Range Properties The IVI Virtual Range class defines the following properties: • Max • Min • Name • Starting Physical Index This section describes the behavior and requirements of each property.
IVI-3.5: IVI Configuration Server Specification
120
IVI Foundation
17.2.1 Max COM Data Type long
Access R/W
COM Property Name Max
C Constant Name IVICONFIG_VAL_VIRTUAL_RANGE_MAX
Description The upper bound of a range of integers to be appended to the Name property of the referencing IVI Virtual Name object to create a set of virtual repeated capability identifiers.
IVI Foundation
121
IVI-3.5: IVI Configuration Server Specification
17.2.2 Min COM Data Type long
Access R/W
COM Property Name Min
C Constant Name IVICONFIG_VAL_VIRTUAL_RANGE_MIN
Description The lower bound of a range of integers to be appended to the Name property of the referencing IVI Virtual Name object to create a set of virtual repeated capability identifiers.
IVI-3.5: IVI Configuration Server Specification
122
IVI Foundation
17.2.3 Name COM Data Type BSTR
Access R/W
COM Property Name Name
C Constant Name IVICONFIG_VAL_VIRTUAL_RANGE_NAME
Description The name of the IVI Virtual Range. This name is used to uniquely identify the range in the collection, and is not used in creating the set of virtual identifiers. The empty string is not a legal value for this property.
IVI Foundation
123
IVI-3.5: IVI Configuration Server Specification
17.2.4 Starting Physical Index COM Data Type long
Access R/W
COM Property Name StartingPhysicalIndex
C Constant Name IVICONFIG_VAL_VIRTUAL_RANGE_START_PHYSICAL_INDEX
Description When a range of integers is appended to the Name property of the referencing IVI Virtual Name object to create a set of virtual repeated capability identifiers, Starting Physical Index is added to each integer in the range, and the result is appended to the Map To property to obtain the corresponding set of physical identifiers.
IVI-3.5: IVI Configuration Server Specification
124
IVI Foundation
18. IVI Data Component Class 18.1 IVI Data Component Overview The IVI Data Component class is used to extend the set of properties that can be supported by other Configuration Server classes. This class is not implemented directly – it is a virtual base class. The following Configuration Server classes inherit from the IVI Data Component class: • IVI API Reference • IVI Boolean • IVI Integer • IVI Real • IVI String • IVI Structure Each of these classes inherits Name, Description, ReadOnly, Used In Session, and Type properties from IVI Data Component class. All IVI Configuration Server classes that inherit from the IVI Configurable Component class include a reference to a collection of IVI Data Components. In addition, the IVI Structure class also contains a reference to a collection of Data Components, allowing the hierarchical definition of a data components structure.
18.2 IVI Data Component Properties The IVI Data Component class defines the following properties: • Description • Help Context ID • Help File Path • Name • Read Only • Software Module Key • Type • Used In Session This section describes the behavior and requirements of each property.
IVI Foundation
125
IVI-3.5: IVI Configuration Server Specification
18.2.1 Description COM Data Type BSTR
Access R/W
COM Property Name Description
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_DESCRIPTION
Description A description of the IVI Data Component. The empty string is a legal value for this property.
IVI-3.5: IVI Configuration Server Specification
126
IVI Foundation
18.2.2 Help Context ID COM Data Type long
Access R/W
COM Property Name HelpContextID
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_HELP_CONTEXT_ID
Description The help context ID for the data component. The default value for this property shall be 0. The value of this property is not meaningful if the Help File property does not contain a valid help file pathname. If the Help File property does contain a valid help file pathname, Help Context ID shall return the help context ID for the topic in the help file that provides the help for the data component. The configuration server does not verify the content of this property. The person or tool that maintains the field is responsible for its validity.
IVI Foundation
127
IVI-3.5: IVI Configuration Server Specification
18.2.3 Help File Path COM Data Type BSTR
Access R/W
COM Property Name HelpFilePath
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_HELP_FILE_PATH
Description The fully qualified pathname of the help file that provides the help for the data component. The default value for this property shall be the empty string. If Help File Path is not the empty string, it shall contain the fully qualified pathname of a help file that conforms to one of the standard formats for Windows help. If Help File Path is not the empty string, Help Context ID shall return the help context ID for the topic in the help file that provides the help for the data component. The configuration server does not verify the content of this property. The person or tool that maintains the field is responsible for its validity.
IVI-3.5: IVI Configuration Server Specification
128
IVI Foundation
18.2.4 Name COM Data Type BSTR
Access R/W
COM Property Name Name
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_NAME
Description The name of the IVI Data Component. The empty string is not a legal value for this property.
IVI Foundation
129
IVI-3.5: IVI Configuration Server Specification
18.2.5 Read Only COM Data Type
Access
VARIANT_BOOL
R/W
COM Property Name ReadOnly
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_READ_ONLY
Description Indicates whether the value of the data component may be changed in a configuration store GUI. If True, a Configuration Utility must not allow the user to modify the contents of the data component object. If False, the associated data component objects may be read or written.
IVI-3.5: IVI Configuration Server Specification
130
IVI Foundation
18.2.6 Software Module Key COM Data Type BSTR
Access R/W
COM Property Name SoftwareModuleKey
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_SW_MODULE_KEY
Description A string that the software module uses to identify the internal software element that the data component applies to. If Used In Session is “None”, the value of this property shall be the empty string. If Used In Session is “Required” or “Optional”, the value of this property shall not be the empty string.
IVI Foundation
131
IVI-3.5: IVI Configuration Server Specification
18.2.7 Type COM Data Type BSTR
Access R/O
COM Property Name Type
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_TYPE
Description A string denoting the data type of the associated data element. Valid values for this field are “Structure”, “Integer”, “Real”, “Boolean”, “String”, and “APIReference”.
IVI-3.5: IVI Configuration Server Specification
132
IVI Foundation
18.2.8 Used In Session COM Data Type BSTR
Access R/W
COM Property Name UsedInSession
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_USED_IN_SESSION
Description This property determines whether a data component associated with a software module is used in a session that references the software module. The possible values are “Required”, “Optional”, and “None”. The values are case insensitive. For data components associated with software modules and sessions, Used In Session shall be “Required”, “Optional”, or “None”. For data components associated with hardware assets, Used In Session shall be “None”. If the value is “Required”, the data component must be present as part of a session’s data components, with a valid value, for the associated software module to operate correctly. If the value is “Optional”, the data component may be present as part of a session’s data components, but is not required for the associated software module to operate correctly. This allows the user to choose whether to override the driver’s default value. If the value is “None”, the data component is ignored by the software module. Its presence and value have no effect on the operation of the software module. The configuration server shall enforce the valid values for this field. If an invalid value is entered manually, the configuration server shall return an Invalid Value error.
IVI Foundation
133
IVI-3.5: IVI Configuration Server Specification
19. IVI Structure Class 19.1 IVI Structure Overview The IVI Structure class allows one collection of IVI Data Components to reference another collection of IVI Data Components. This allows data components to be structured hierarchically.
19.2 IVI Structure References The IVI Structure class defines the following reference: • DataComponents This section describes the reference.
IVI-3.5: IVI Configuration Server Specification
134
IVI Foundation
19.2.1 Data Components COM Data Type
C Data Type
IIviDataComponentCollection**
IviDataComponentCollectionHandle
Access R/O
COM Property Name DataComponents
C Function Prototype ViStatus _VI_FUNC IviConfig_GetStructureDataComponentCollection (IviDataComponentHandle StructureHandle, IviDataComponentCollectionHandle* DataComponentCollectionHandle);
Parameters Inputs
Description
Datatype
StructureHandle
Handle to an IviDataComponent object.
IviDataComponen tHandle
Outputs
Description
Datatype
DataComponentColl ectionHandle
Handle to an IviDataComponentCollection object.
IviDataComponen tCollectionHand le
Description References a collection of IVI Data Component objects. Circular references or a circular series of references are not allowed.
IVI Foundation
135
IVI-3.5: IVI Configuration Server Specification
19.3 IVI Structure Properties The following properties are inherited from IVI Data Component - Section 18, IVI Data Component Class • Description • Help Context ID • Help File Path • Name • Read Only • Software Module Key • Type • Used In Session In an IVI Structure object, Type shall be set to “Structure”.
IVI-3.5: IVI Configuration Server Specification
136
IVI Foundation
20. IVI Integer Class 20.1 IVI Integer Overview The IVI Integer class defines a 32-bit integer data type for use in the IVI configuration server. This includes an integer value and other type information. An IVI Integer object cannot exist independently of an IVI Data Components collection.
20.2 IVI Integer Properties The IVI Integer class defines the following properties: • Units • Value The following properties are inherited from IVI Data Component - Section 18, IVI Data Component Class • Description • Help Context ID • Help File Path • Name • Read Only • Software Module Key • Type • Used In Session In an IVI Integer object, type shall be set to “Integer”. This section describes the behavior and requirements of each property.
IVI Foundation
137
IVI-3.5: IVI Configuration Server Specification
20.2.1 Units COM Data Type BSTR
Access R/W
COM Property Name Units
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_UNITS
Description A string that specifies the units to be applied to Value. The empty string is a legal value for this property.
IVI-3.5: IVI Configuration Server Specification
138
IVI Foundation
20.2.2 Value COM Data Type long
Access R/W
COM Property Name Value
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_VALUE
Description The integer value of the data component.
IVI Foundation
139
IVI-3.5: IVI Configuration Server Specification
21. IVI Real Class 21.1 IVI Real Overview The IVI Real class defines a 64-bit real data type for use in the IVI configuration server. This includes a real value and other type information. An IVI Real object cannot exist independently of an IVI Data Components collection.
21.2 IVI Real Properties The IVI Real class defines the following properties: • Units • Value The following properties are inherited from IVI Data Component - Section 18, IVI Data Component Class • Description • Help Context ID • Help File Path • Name • Read Only • Software Module Key • Type • Used In Session In an IVI Real object, type shall be set to “Real”. This section describes the behavior and requirements of each property.
IVI-3.5: IVI Configuration Server Specification
140
IVI Foundation
21.2.1 Units COM Data Type BSTR
Access R/W
COM Property Name Units
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_UNITS
Description A string that specifies the units to be applied to Value. The empty string is a legal value for this property.
IVI Foundation
141
IVI-3.5: IVI Configuration Server Specification
21.2.2 Value COM Data Type double
Access R/W
COM Property Name Value
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_VALUE
Description The real value of the data component.
IVI-3.5: IVI Configuration Server Specification
142
IVI Foundation
22. IVI Boolean Class 22.1 IVI Boolean Overview The IVI Boolean class defines a Boolean data type for use in the IVI configuration server. This includes a Boolean value and other type information. An IVI Boolean object cannot exist independently of an IVI Data Components collection.
22.2 IVI Boolean Properties The IVI Boolean class defines the following properties: • Value The following properties are inherited from IVI Data Component - Section 18, IVI Data Component Class • Description • Help Context ID • Help File Path • Name • Read Only • Software Module Key • Type • Used In Session In an IVI Boolean object, type shall be set to “Boolean”. This section describes the behavior and requirements of each property.
IVI Foundation
143
IVI-3.5: IVI Configuration Server Specification
22.2.1 Value COM Data Type
Access
VARIANT_BOOL
R/W
COM Property Name Value
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_VALUE
Description The Boolean value of the data component.
IVI-3.5: IVI Configuration Server Specification
144
IVI Foundation
23. IVI String Class 23.1 IVI String Overview The IVI String class defines a string data type for use in the IVI configuration server. This includes a string value and other type information. An IVI String object cannot exist independently of an IVI Data Components collection.
23.2 IVI String Properties The IVI String class defines the following properties: • Value The following properties are inherited from IVI Data Component - Section 18, IVI Data Component Class • Description • Help Context ID • Help File Path • Name • Read Only • Software Module Key • Type • Used In Session In an IVI String object, Type shall be set to “String”. This section describes the behavior and requirements of each property.
IVI Foundation
145
IVI-3.5: IVI Configuration Server Specification
23.2.1 Value COM Data Type BSTR
Access R/W
COM Property Name Value
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_VALUE
Description The string value of the data component. The empty string is a legal value for this property.
IVI-3.5: IVI Configuration Server Specification
146
IVI Foundation
24. IVI API Reference Class 24.1 IVI API Reference Overview The IVI API Reference class defines a reference to a Published API data type for use in the Configuration Server. An IVI API Reference object cannot exist independently of an IVI Data Components collection. All API references are configurable initial settings for either a software module or a session. An IVI Software Module uses IVI API Reference objects to describe the published APIs that it uses (not the ones that it implements). A software module (the “using” software module) “uses” an API when it makes API calls to another software module (the “used” software module) that implements the API. When an IVI API Reference object is created at install time in a software module’s data components collection, the value of the Published API reference is set and may not be subsequently changed.
PI
When an IVI Session includes an IVI API Reference object, it associates the Published API with a session or driver session. This session configures the “used” software module chosen to implement the published API. The Value property is a session name or logical name. Get Session and Get Driver Session may be used to resolve the name to a session. Refer to Section 7.4.3, Get Session and Section 7.4.2, Get Driver Session for more details.
lish
A PI R e feren ce
Pu b
D a ta C o m p o n e n ts
P u b lish e d A PI
dA P
I
S o ft w a r e M o d u le
e dA
T y p ic a l S o f t w a r e M o d u le E n tr ie s
D a ta C o m p o n e n ts
A PI R e feren ce
Pu b
U sin g S ession
lish e
T y p ic a l S e s s io n C o n f ig u r a tio n
P u b lish e d A PI
V a lu e P u b lis h e d A P Is
U sin g S o ft w a r e M o d u le
U sed S ession
U sed S o ft w a r e M o d u le
Figure 24-1 Typical API Reference Configuration Store Entries Figure 24-1 shows two typical uses of the API reference data component. The first shows the set of configuration store entries for a software module that uses an API reference. The second shows the set of configuration store entries for a session that configures the software module. While an API Reference may be used by IVI Drivers, the typical use is for IVI-MSS components. Attempts to add an IVI API Reference object will fail with an Invalid Data Component error if one of the following conditions is true: • The data components collection to which is being added is referenced by an IVI Hardware Asset object. • Its Used In Session property is “None”.
IVI Foundation
147
IVI-3.5: IVI Configuration Server Specification
24.2 IVI API Reference References The IVI API Reference class defines the following reference: • Published API This section describes the reference.
IVI-3.5: IVI Configuration Server Specification
148
IVI Foundation
24.2.1 Published API COM Data Type IIviPublishedAPI*
C Data Type
Access
IviPublishedAPIHandle
R/W
COM Property Name PublishedAPI
C Function Prototype ViStatus _VI_FUNC IviConfig_GetAPIReferencePublishedAPIReference (IviDataComponentHandle ApiReferenceHandle, IviPublishedAPIsHandle* PublishedAPIsHandle); ViStatus _VI_FUNC IviConfig_SetAPIReferencePublishedAPIReference (IviDataComponentHandle ApiReferenceHandle, IviPublishedAPIsHandle PublishedAPIsHandle);
Parameters Inputs
Description
Datatype
APIReferenceHandl e
Handle to an IviDataComponent object.
IviDataComponen tHandle
Outputs
Description
Datatype
PublishedAPIHandl e
Handle to an IviPublishedAPI object.
IviPublishedAPI sHandle
Description The Published API property references a published API to be associated with the client role identified by the Name property. The Value property designates a session name that implements the published API.
IVI Foundation
149
IVI-3.5: IVI Configuration Server Specification
24.3 IVI API Reference Properties The IVI API Reference class defines the following properties: • Value The following properties are inherited from IVI Data Component - Section 18, IVI Data Component Class • Description • Help Context ID • Help File Path • Name • Read Only • Software Module Key • Type • Used In Session In an IVI API Reference object, Type shall be set to “APIReference”. This section describes the behavior and requirements of each property.
IVI-3.5: IVI Configuration Server Specification
150
IVI Foundation
24.3.1 Value COM Data Type BSTR
Access R/W
COM Property Name Value
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_VALUE
Description A logical name or session name. Value can be passed to GetSession() or GetDrverSession() in the Name parameter. A session reference is returned according to the semantics defined for GetSession() and GetDriverSession(). The empty string is a legal value for this property.
IVI Foundation
151
IVI-3.5: IVI Configuration Server Specification
25. Configuration Server Error and Completion Codes The Configuration Server specification defines the following error codes in addition to the generic IVI error codes defined in IVI-3.2: Inherent Capabilities.
Table 25-1 Configuration Server Completion Codes Error Name
Description Language
Deserialize Failed
Already Deserialized
Serialize Failed
Session Not Found
Not In Global Collection
Duplicate Entry
Master Not Found
Does Not Exist
Invalid Data Component
Invalid Handle
Identifier
Value(hex)
The specified configuration store file could not be deserialized. C
IVICONFIG_ERROR_DESERIALIZE_FAILED
0xBFFA1200
COM
E_IVICONFIG_DESERIALIZE_FAILED
0x80041200
A deserialize was attempted after a previous deserialize had already succeeded. C
IVICONFIG_ERROR_ALREADY_DESERIALIZED
0xBFFA1201
COM
E_IVICONFIG_ALREADY_DESERIALIZED
0x80041201
The specified configuration store file could not be serialized. C
IVICONFIG_ERROR_SERIALIZE_FAILED
0xBFFA1202
COM
E_IVICONFIG_SERIALIZE_FAILED
0x80041202
The session name or logical name could not be resolved to a session or driver session. C
IVICONFIG_ERROR_SESSION_NOT_FOUND
0xBFFA1203
COM
E_IVICONFIG_SESSION_NOT_FOUND
0x80041203
The item does not exist in the global collection. C
IVICONFIG_ERROR_NOT_IN_GLOBAL
0xBFFA1204
COM
E_IVICONFIG_NOT_IN_GLOBAL
0x80041204
An entry with name already exists in the collection. C
IVICONFIG_ERROR_ALREADY_EXIST
0xBFFA1205
COM
E_IVICONFIG_ALREADY_EXIST
0x80041205
The registry entry for the master configuration store does not exist or the file could not be found. C
IVICONFIG_ERROR_MASTER_NOT_FOUND
0xBFFA1206
COM
E_IVICONFIG_MASTER_NOT_FOUND
0x80041206
The item does not exist in the collection. C
IVICONFIG_ERROR_NOT_EXIST
0xBFFA1207
COM
E_IVICONFIG_NOT_EXIST
0x80041207
The data component is not a valid data component. C
IVICONFIG_ERROR_INVALID_DATA_COMPONENT
0xBFFA1208
COM
E_IVICONFIG_INVALID_DATA_COMPONENT
0x80041208
The specified handle is invalid or of an incorrect type. C
IVICONFIG_ERROR_INVALID_HANDLE
COM
N/A
IVI-3.5: IVI Configuration Server Specification
152
0xBFFA1220
IVI Foundation
The specified property ID is not valid for this function.
Invalid Property ID
Reference Still Exists
C
IVICONFIG_ERROR_INVALID_PROPERTY_ID
COM
N/A
0xBFFA1221
The element cannot be removed from the global collection when it is referenced in the local collections. C
IVICONFIG_ERROR_LOCAL_REFERENCE_EXIST
0xBFFA1209
COM
E_IVICONFIG_LOCAL_REFERENCE_EXIST
0x80041209
Table 25-2 defines the format of the message string associated with the error. In C, this string is returned by the Error Message function. In COM, this string is the description contained in the ErrorInfo object.
Table 25-2. Configuration Server Error Message Strings Name
Message String
Deserialize Failed
“IviConfigServer.IviConfigStore.1: Deserialize failed. %1”
Already Deserialized
“IviConfigServer.IviConfigStore.1: A previous deserialize has already succeeded.”
Serialize Failed
“IviConfigServer.IviConfigStore.1: Serialize failed. %1”
Session Not Found
“IviConfigServer.IviConfigStore.1: Get%1 failed. Name %2 could not be resolved to a %1.”
Not In Global Collection
“IviConfigServer.IviConfigStore.1: %1 failed. %2 does not exist in the global collection or the object is not the same as in the global collection.”
Duplicate Entry
“IviConfigServer.IviConfigStore.1: %1 failed. %2 already exists in the collection.”
Master Not Found
“IviConfigServer.IviConfigStore.1: get_MasterLocation failed. The registry key does not exist or the file can not be found.”
Does Not Exist
“IviConfigServer.IviConfigStore.1: %1 failed. %2 does not exist in the collection.”
Invalid Data Component
“IviConfigServer.IviConfigStore.1: : %1 failed. The data component is not a valid data component. %2”
Invalid Handle
“IviConfigServer: %1: The specified handle is either invalid or is of an incorrect type.”
Invalid Property ID
“IviConfigStore: %1: The specified property ID is not a valid ID for this function.”
Reference Still Exists
“IviConfigStore: %1: %2 failed. The element cannot be removed from the global collection when it is referenced in the local collections.”
IVI Foundation
153
IVI-3.5: IVI Configuration Server Specification
26. Configuration Store Data Format Configuration Store data is stored in an XML file. The format is specified by a schema file, IviConfigurationStore.xsd which is installed in the same directory as the master configuration store file.
IVI-3.5: IVI Configuration Server Specification
154
IVI Foundation
27. Configuration Utility Implementation Guidelines Configuration utilities facilitate the process of “manually” editing of the configuration store. They are not specified by the IVI Foundation, and so discussion of implementation is confined to these guidelines. Users will prefer using a configuration utility to either manually editing the configuration store XML file using a text editor, or using the configuration server API to edit the configuration store as needed, since this requires programming. To provide this ease of use, configuration utilities may use a graphical user interface designed to perform the tasks that users must perform to review configuration store content and configure IVI instrument drivers and/or IVI-MSS role control modules. Vendors may choose to tailor the functionality of a configuration utility to particular business needs, or to develop a broadly applicable utility that performs many general configuration server tasks.
27.1 General Configuration utilities should always use the configuration server to make any modifications to any configuration store. Configuration utilities should preserve the data integrity of the configuration store as described in this specification. While the configuration server API handles quite a bit of the data integrity as described in this specification, some items must be handled by the configuration utility and those are described in the following guidelines.
27.2 Hardware Assets The configuration utility should allow users to add, modify, and delete hardware assets. The configuration utility should not limit the format of the IO Resource Descriptor so as to limit future potential formats for I/O addresses.
27.3 Published APIs The installation of a Software Module may add a Published API to the global collection. Configuration utilities may also add Published APIs, but they should be very careful about modifying or deleting them.
27.4 Software Modules Configuration utilities should not add or delete software modules to the master configuration store. Software modules are added to the configuration store when they are installed, and are deleted when they are uninstalled. Configuration utilities should not modify any of the data referenced directly or indirectly by software modules. The only exception is that they may add, modify, and delete documentation data components referenced by the software module. Configuration utilities may copy software modules to, and delete software modules from “slave” configuration stores. When they do, all of the referenced data should also be copied or deleted.
27.5 Sessions The configuration utility should allow users to add, modify, and delete sessions. Configuration utilities should be able to configure the configurable initial settings of a session accurately. That means modifying the Value property. Users should not be able to modify the following properties in a configurable initial setting: Description, Help Context ID, Help File Path, Name, Read Only, Software Module Key, Type, Used In Session or Units.
IVI Foundation
155
IVI-3.5: IVI Configuration Server Specification
27.6 Documentation Data Components Configuration utilities should add, modify, or delete documentation data components for a hardware asset, software module, or session accurately. In general, users may modify any property of documentation data components.
IVI-3.5: IVI Configuration Server Specification
156
IVI Foundation
28. Limitations 28.1 Distributed Systems Remote access to the Configuration Server has not been validated to work. Specifying this support will introduce new issues related to DCOM security and system configuration.
28.2 Concurrent Reading and Writing The Configuration Server does not support multiple concurrent writers or concurrent readers and writers. It does support multiple concurrent readers.
IVI Foundation
157
IVI-3.5: IVI Configuration Server Specification
Appendix A: IVI Configuration Server IDL file /************************************************************************* IviConfigServer.idl This source file was developed by and is the property of Agilent Technologies. Use and distribution of this file is governed by US Copyright law and the IVI Consortium Shared Open-Source Component Licensing agreement. Copyright 2002, Agilent Technologies *************************************************************************/ // This file will be processed by the MIDL tool to // produce the type library (IviConfigServer.tlb) and marshalling code. import "oaidl.idl"; import "ocidl.idl"; [ uuid(C6F576F5-7394-458E-B38A-C20C668585E7), version(1.0), helpstring("Ivi Configuration Server 1.0 Type Library") ] library IVICONFIGSERVERLib { importlib("stdole32.tlb"); importlib("stdole2.tlb"); typedef [ public, v1_enum, helpstring("Ivi Configuration Server Error Enum") ] enum IviConfigServerErrorEnum { E_IVICONFIG_DESERIALIZE_FAILED = 0x80041200, E_IVICONFIG_ALREADY_DESERIALIZED = 0x80041201, E_IVICONFIG_SERIALIZE_FAILED = 0x80041202, E_IVICONFIG_SESSION_NOT_FOUND = 0x80041203, E_IVICONFIG_NOT_IN_GLOBAL = 0x80041204, E_IVICONFIG_ALREADY_EXIST = 0x80041205, E_IVICONFIG_MASTER_NOT_FOUND = 0x80041206, E_IVICONFIG_NOT_EXIST = 0x80041207, E_IVICONFIG_INVALID_DATA_COMPONENT = 0x80041208, E_IVICONFIG_LOCAL_REFERENCE_EXIST = 0x80041209 } IviConfigServerErrorEnum; interface interface interface interface interface interface interface interface interface interface interface interface interface
IIviLogicalNameCollection; IIviSessionCollection; IIviPublishedAPICollection; IIviHardwareAssetCollection; IIviSoftwareModuleCollection; IIviDriverSessionCollection; IIviConfigComponent; IIviConfigStore; IIviSoftwareModule; IIviPhysicalName; IIviLogicalName; IIviHardwareAsset; IIviSession;
IVI-3.5: IVI Configuration Server Specification
158
IVI Foundation
interface interface interface interface interface interface interface interface interface interface interface interface interface interface interface interface interface interface interface
IIviPublishedAPI; IIviVirtualName; IIviVirtualNameCollection; IIviDataComponentCollection; IIviDriverSession; IIviPhysicalNameCollection; IIviPublishedAPI; IIviPublishedAPICollection; IIviVirtualRange; IIviPhysicalRange; IIviVirtualRangeCollection; IIviPhysicalRangeCollection; IIviDataComponent; IIviStructure; IIviAPIReference; IIviReal; IIviInteger; IIviString; IIviBoolean;
[ uuid(EBC90D48-10D2-4E40-AE35-C993E127B815), helpstring("IviConfigStore Class") ] coclass IviConfigStore { [default] interface IIviConfigStore; }; [ uuid(CB1A5E7B-AEE1-4967-B8B8-F490CACAC91E), helpstring("IIviConfigStore Interface"), dual, object, pointer_default(unique) ] interface IIviConfigStore : IDispatch { [id(0), propget] HRESULT Name([out,retval] BSTR* pVal); [id(1), propget] HRESULT Description([out,retval] BSTR* pVal); [id(1), propput] HRESULT Description([in] BSTR newVal); [propget, helpstring("property Vendor"), id(2)] HRESULT Vendor([out, retval] BSTR *pVal); [propget, helpstring("property Revision"), id(3)] HRESULT Revision([out, retval] BSTR *pVal); [id(4), propget] HRESULT SpecificationMajorVersion([out,retval] long* pVal); [id(5), propget] HRESULT SpecificationMinorVersion ([out,retval] long* pVal); [id(6), propget] HRESULT HardwareAssets([out,retval] IIviHardwareAssetCollection** pVal); [id(7), propget] HRESULT DriverSessions([out,retval] IIviDriverSessionCollection** pVal); [id(8), propget] HRESULT LogicalNames([out,retval] IIviLogicalNameCollection** pVal); [id(9), propget] HRESULT Sessions([out,retval] IIviSessionCollection** pVal); [id(10), propget] HRESULT PublishedAPIs([out,retval] IIviPublishedAPICollection** pVal); [id(11), propget] HRESULT SoftwareModules([out,retval] IIviSoftwareModuleCollection** pVal); [id(12)] IVI Foundation
159
IVI-3.5: IVI Configuration Server Specification
HRESULT Deserialize([in] BSTR DataStoreFileSpec); [id(13)] HRESULT Serialize([in] BSTR DataStoreFileSpec); [id(14)] HRESULT GetDriverSession(BSTR LogicalName, [out, retval] IIviDriverSession **pVal); [id(15)] HRESULT GetSession(BSTR LogicalName, [out, retval] IIviSession **pVal); [propget, id(16), helpstring("property MasterLocation")] HRESULT MasterLocation([out, retval] BSTR *pVal); [propget, id(17), helpstring("property ProcessDefaultLocation")] HRESULT ProcessDefaultLocation([out, retval] BSTR *pVal); [propput, id(17), helpstring("property ProcessDefaultLocation")] HRESULT ProcessDefaultLocation([in] BSTR newVal); [propget, id(18), helpstring("property ActualLocation")] HRESULT ActualLocation([out, retval] BSTR *pVal); }; [ uuid(6BC6718E-EEF2-4630-9E0B-C767DD27C49B), helpstring("IviSoftwareModule Class") ] coclass IviSoftwareModule { [default] interface IIviSoftwareModule; }; [ uuid(F0172C7A-620C-44BC-AA10-288901808128), helpstring("IIviSoftwareModule Interface"), dual, object, pointer_default(unique) ] interface IIviSoftwareModule : IDispatch { [id(0), propget] HRESULT Name([out,retval] BSTR* pRetVal); [id(0), propput] HRESULT Name([in] BSTR newVal); [id(1), propget] HRESULT Description([out,retval] BSTR* pRetVal); [id(1), propput] HRESULT Description([in] BSTR newVal); [id(2), propget] HRESULT ProgID([out,retval] BSTR* pRetVal); [id(2), propput] HRESULT ProgID([in] BSTR newVal); [id(3), propget, helpstring("property ModulePath")] HRESULT ModulePath([out,retval] BSTR* pRetVal); [id(3), propput, helpstring("property ModulePath")] HRESULT ModulePath([in] BSTR newVal); [id(4), propget] HRESULT Prefix([out,retval] BSTR* pRetVal); [id(4), propput] HRESULT Prefix([in] BSTR newVal); [id(5), propget] HRESULT SupportedInstrumentModels([out,retval] BSTR* pRetVal); [id(5), propput] HRESULT SupportedInstrumentModels([in] BSTR newVal); [id(7), propget] HRESULT DataComponents([out,retval] IIviDataComponentCollection** pRetVal); [id(8), propget] HRESULT PublishedAPIs([out,retval] IIviPublishedAPICollection** pRetVal);
IVI-3.5: IVI Configuration Server Specification
160
IVI Foundation
[propget, helpstring("property PhysicalNames"), id(9)] HRESULT PhysicalNames([out, retval] IIviPhysicalNameCollection * *pVal); }; [
uuid(7248E7EC-E3A0-47C2-B70B-56C19BD428DC), helpstring("IviHardwareAssetCollection Class")
] coclass IviHardwareAssetCollection { [default] interface IIviHardwareAssetCollection; }; [ uuid(FA1B41A4-2667-4C67-B6C1-9945251EF37D), helpstring("IIviHardwareAssetCollection Interface"), dual, object, pointer_default(unique) ] interface IIviHardwareAssetCollection : IDispatch { [id(1)] HRESULT Add([in] IIviHardwareAsset *pVal); [id(2), propget] HRESULT Count([out, retval] long* pVal); [id(DISPID_VALUE), propget] HRESULT Item([in] VARIANT varIndex,[out, retval]IIviHardwareAsset**pVal); [id(DISPID_NEWENUM), propget] HRESULT _NewEnum([out, retval] IUnknown** ppunkEnum); [id(3)] HRESULT Remove([in] VARIANT varIndex); }; [ uuid(7EE56C3F-5EB7-40D4-81A9-ED682BFA4DB7), helpstring("IviPhysicalName Class") ] coclass IviPhysicalName { [default] interface IIviPhysicalName; };
[ uuid(838FA3E6-307A-46C4-A601-53D0986894B9), helpstring("IviLogicalName Class") ] coclass IviLogicalName { [default] interface IIviLogicalName; }; [ uuid(8224C215-B122-499C-899F-3E73D2C80551), helpstring("IviHardwareAsset Class") ] coclass IviHardwareAsset { [default] interface IIviHardwareAsset; };
IVI Foundation
161
IVI-3.5: IVI Configuration Server Specification
[ uuid(6A6B75C4-3DEE-4DEC-B281-BD5D463B25E2), helpstring("IviSession Class") ] coclass IviSession { [default] interface IIviSession; }; [ uuid(EF53811B-90B3-49D4-B85C-714BD6DC125E), helpstring("IviRoleName Class") ] coclass IviPublishedAPI { [default] interface IIviPublishedAPI; }; [ uuid(E55DF0EF-A4A3-4A5A-A241-607E88539634), helpstring("IviVirtualName Class") ] coclass IviVirtualName { [default] interface IIviVirtualName; }; [ uuid(C9A9FAE4-7B99-4DE2-B921-ABDA914C2FBD), helpstring("IIviPhysicalName Interface"), dual, object, pointer_default(unique) ] interface IIviPhysicalName : IDispatch { [id(0), propget] HRESULT Name([out,retval] BSTR* pRetVal); [id(0), propput] HRESULT Name([in] BSTR newVal); [propget, helpstring("property PhysicalNames"), id(1)] HRESULT PhysicalNames([out, retval] IIviPhysicalNameCollection **pVal); [propget, helpstring("property RCName"), id(2)] HRESULT RCName([out, retval] BSTR *pVal); [propput, helpstring("property RCName"), id(2)] HRESULT RCName([in] BSTR newVal); [propget, helpstring("property PhysicalRanges"), id(3)] HRESULT PhysicalRanges([out, retval] IIviPhysicalRangeCollection * *pVal); }; [ uuid(CFCFC60C-EA96-44E7-895C-93FB6013FE20), helpstring("IIviLogicalName Interface"), dual, object, pointer_default(unique) ] interface IIviLogicalName : IDispatch { [id(0), propget] HRESULT Name([out,retval] BSTR* pRetVal); [id(0), propput] HRESULT Name([in] BSTR newVal); IVI-3.5: IVI Configuration Server Specification
162
IVI Foundation
[id(1), HRESULT [id(1), HRESULT [id(2), HRESULT [id(2), HRESULT
propget] Description([out,retval] BSTR* pRetVal); propput] Description([in] BSTR newVal); propget] Session([out,retval] IIviSession** pRetVal); propputref] Session([in] IIviSession* newVal);
}; [ uuid(EA0DCA91-704B-48E6-99B4-9E32440571F7), helpstring("IIviPublishedAPI Interface"), dual, object, pointer_default(unique) ] interface IIviPublishedAPI : IDispatch { [id(0), propget] HRESULT Name([out,retval] BSTR* pRetVal); [id(0), propput] HRESULT Name([in] BSTR newVal); [propget, id(1), helpstring("property MajorVersion")] retval] long *pVal); [propput, id(1), helpstring("property MajorVersion")] long newVal); [propget, id(2), helpstring("property MinorVersion")] retval] long *pVal); [propput, id(2), helpstring("property MinorVersion")] long newVal); [propget, id(3), helpstring("property Type")] HRESULT *pVal); [propput, id(3), helpstring("property Type")] HRESULT
HRESULT MajorVersion([out, HRESULT MajorVersion([in] HRESULT MinorVersion([out, HRESULT MinorVersion([in] Type([out, retval] BSTR Type([in] BSTR newVal);
};
[ uuid(49E73D41-FA90-4B68-B01A-CE655AF6C238), helpstring("IIviHardwareAsset Interface"), dual, object, pointer_default(unique) ] interface IIviHardwareAsset : IDispatch { [id(1), propget] HRESULT Name([out,retval] BSTR* pRetVal); [id(1), propput] HRESULT Name([in] BSTR newVal); [id(2), propget] HRESULT Description([out,retval] BSTR* pRetVal); [id(2), propput] HRESULT Description([in] BSTR newVal); [id(3), propget] HRESULT IOResourceDescriptor([out,retval] BSTR* pRetVal); [id(3), propput] HRESULT IOResourceDescriptor([in] BSTR newVal); [id(4), propget] HRESULT DataComponents([out,retval] IIviDataComponentCollection** pRetVal); }; [ IVI Foundation
163
IVI-3.5: IVI Configuration Server Specification
uuid(B106D7AB-1D5B-4857-ADBB-22C8C5B7307C), helpstring("IIviVirtualName Interface"), dual, object, pointer_default(unique) ] interface IIviVirtualName : IDispatch { [id(0), propget] HRESULT Name([out,retval] BSTR* pRetVal); [id(0), propput] HRESULT Name([in] BSTR newVal); [propget, helpstring("property MapTo"), id(1)] HRESULT MapTo([out, retval] BSTR *pVal); [propput, helpstring("property MapTo"), id(1)] HRESULT MapTo([in] BSTR newVal); [propget, helpstring("property VirtualRanges"), id(2)] HRESULT VirtualRanges([out, retval] IIviVirtualRangeCollection * *pVal); }; [ uuid(3221CA37-4D77-46A1-936C-60A9E7D68476), helpstring("IIviSession Interface"), dual, object, pointer_default(unique) ] interface IIviSession : IDispatch { [id(0), propget] HRESULT Name([out,retval] BSTR* pRetVal); [id(0), propput] HRESULT Name([in] BSTR newVal); [id(1), propget] HRESULT Description([out,retval] BSTR* pRetVal); [id(1), propput] HRESULT Description([in] BSTR newVal); [id(2), propget] HRESULT DataComponents([out,retval] IIviDataComponentCollection** pRetVal); [id(3), propget] HRESULT HardwareAsset([out,retval] IIviHardwareAsset** pRetVal); [id(3), propputref] HRESULT HardwareAsset([in] IIviHardwareAsset* newVal); [id(4), propget] HRESULT VirtualNames([out,retval] IIviVirtualNameCollection** pRetVal); [id(5), propget] HRESULT SoftwareModule([out,retval] IIviSoftwareModule** pRetVal); [id(5), propputref] HRESULT SoftwareModule([in] IIviSoftwareModule* newVal); [id(6), propget] HRESULT SoftwareModuleName([out,retval] BSTR * name); };
[
uuid(D90E0437-D890-40F9-8044-B100CC48CCA3), helpstring("IviVirtualNameCollection Class")
] coclass IviVirtualNameCollection { [default] interface IIviVirtualNameCollection; }; [ IVI-3.5: IVI Configuration Server Specification
164
IVI Foundation
uuid(409C4FF6-25DB-4C89-867E-0D794A6EB1B3), helpstring("IIviVirtualNameCollection Interface"), dual, object, pointer_default(unique) ] interface IIviVirtualNameCollection : IDispatch { [helpstring("method Add"), id(1)] HRESULT Add([in] IIviVirtualName *pVal); [propget, id(2)] HRESULT Count([out, retval] long* pVal); [propget, id(DISPID_VALUE)] HRESULT Item([in] VARIANT varIndex,[out, retval]IIviVirtualName**pVal); [propget, id(DISPID_NEWENUM)] HRESULT _NewEnum([out, retval] IUnknown** ppunkEnum); [id(3)] HRESULT Remove([in] VARIANT varIndex); }; [ uuid(3486A6CB-52F6-44F6-8A53-FD012B221204), helpstring("IviDataComponentCollection Class") ] coclass IviDataComponentCollection { [default] interface IIviDataComponentCollection; }; [
uuid(9C8C5AF3-D308-4F0C-BB47-1B073CBA760E), helpstring("IIviDataComponentCollection Interface"), dual, object, pointer_default(unique)
] interface IIviDataComponentCollection : IDispatch { [helpstring("method Add"), id(1)] HRESULT Add([in] IIviDataComponent *); [propget, id(2)] HRESULT Count([out, retval] long* pVal); [propget, id(DISPID_VALUE)] HRESULT Item([in] VARIANT varIndex,[out, retval]IIviDataComponent**pVal); [propget, id(DISPID_NEWENUM)] HRESULT _NewEnum([out, retval] IUnknown** ppunkEnum); [id(3)] HRESULT Remove([in] VARIANT varIndex); }; [ uuid(31C4C811-A98B-4008-9DDB-2BB642D97B06), helpstring("IviRoleNameCollection Class") ] coclass IviPublishedAPICollection { [default] interface IIviPublishedAPICollection; }; [ uuid(2D4258A6-4D9F-4C9A-921B-3DAA96366C8F), helpstring("IIviPublishedAPICollection Interface"), dual, object, pointer_default(unique) IVI Foundation
165
IVI-3.5: IVI Configuration Server Specification
] interface IIviPublishedAPICollection : IDispatch { [id(1)] HRESULT Add([in] IIviPublishedAPI *pVal); [propget, id(2)] HRESULT Count([out, retval] long* pVal); [propget, id(DISPID_VALUE)] HRESULT Item([in] VARIANT varIndex, [in] long MajorVersion, [in] long MinorVersion, [in] BSTR Type, [out, retval]IIviPublishedAPI**pVal); [propget, id(DISPID_NEWENUM)] HRESULT _NewEnum([out, retval] IUnknown** ppunkEnum); [id(3)] HRESULT Remove([in] VARIANT varIndex, [in] long MajorVersion, [in] long MinorVersion, [in] BSTR Type); }; [
uuid(EDF186A7-0AE1-487B-AE60-587812FA72D6), helpstring("IviSoftwareModuleCollection Class")
] coclass IviSoftwareModuleCollection { [default] interface IIviSoftwareModuleCollection; }; [ uuid(D97EEC1E-9906-48F9-8414-6574AA9F0377), helpstring("IIviSoftwareModuleCollection Interface"), dual, object, pointer_default(unique) ] interface IIviSoftwareModuleCollection : IDispatch { [id(1)] HRESULT Add([in] IIviSoftwareModule *pVal); [propget, id(2)] HRESULT Count([out, retval] long* pVal); [propget, id(DISPID_VALUE)] HRESULT Item([in] VARIANT varIndex,[out, retval]IIviSoftwareModule**pVal); [propget, id(DISPID_NEWENUM)] HRESULT _NewEnum([out, retval] IUnknown** ppunkEnum); [id(3)] HRESULT Remove([in] VARIANT varIndex); }; [ uuid(D349355E-56C0-4D73-8A8B-CA3F7407A357), helpstring("IviDriverSession Class") ] coclass IviDriverSession { [default] interface IIviDriverSession; };
[ uuid(3FB118A4-FDB1-4CE3-84FE-1315FB026C33), helpstring("IIviDriverSession Interface"), dual, object, pointer_default(unique) IVI-3.5: IVI Configuration Server Specification
166
IVI Foundation
] interface IIviDriverSession : IIviSession { [id(7), propget] HRESULT DriverSetup([out,retval] BSTR* pVal); [id(7), propput] HRESULT DriverSetup([in] BSTR newVal); [id(8), propget] HRESULT Cache([out,retval] VARIANT_BOOL* pVal); [id(8), propput] HRESULT Cache([in] VARIANT_BOOL newVal); [id(9), propget] HRESULT InterchangeCheck([out,retval] VARIANT_BOOL* pVal); [id(9), propput] HRESULT InterchangeCheck([in] VARIANT_BOOL newVal); [id(10), propget] HRESULT QueryInstrStatus([out,retval] VARIANT_BOOL* pVal); [id(10), propput] HRESULT QueryInstrStatus([in] VARIANT_BOOL newVal); [id(11), propget] HRESULT RangeCheck([out,retval] VARIANT_BOOL* pVal); [id(11), propput] HRESULT RangeCheck([in] VARIANT_BOOL newVal); [id(12), propget] HRESULT RecordCoercions([out,retval] VARIANT_BOOL* pVal); [id(12), propput] HRESULT RecordCoercions([in] VARIANT_BOOL newVal); [id(13), propget] HRESULT Simulate([out,retval] VARIANT_BOOL* pVal); [id(13), propput] HRESULT Simulate([in] VARIANT_BOOL newVal); }; [ uuid(C8E3D0D2-B529-411E-A13E-161DA7C29454), helpstring("IviDriverSessionCollection Class") ] coclass IviDriverSessionCollection { [default] interface IIviDriverSessionCollection; }; [ uuid(9851A673-2452-4A7E-B7AA-A6EAB8A5055B), helpstring("IIviDriverSessionCollection Interface"), dual, object, pointer_default(unique) ] interface IIviDriverSessionCollection : IDispatch { [id(1)] HRESULT Add([in] IIviDriverSession *pVal); [propget, id(2)] HRESULT Count([out, retval] long* pVal); [propget, id(DISPID_VALUE)] HRESULT Item([in] VARIANT varIndex,[out, retval]IIviDriverSession**pVal); [propget, id(DISPID_NEWENUM)] HRESULT _NewEnum([out, retval] IUnknown** ppunkEnum); [id(3)] HRESULT Remove([in] VARIANT varIndex); };
IVI Foundation
167
IVI-3.5: IVI Configuration Server Specification
[ uuid(E3042EA2-1718-4216-9C06-1DDABF124BB3), helpstring("IIviDataComponent Interface"), dual, object, pointer_default(unique) ] interface IIviDataComponent : IDispatch { [propget, helpstring("property Name"), id(1)] HRESULT Name([out, retval] BSTR *pVal); [propput, helpstring("property Name"), id(1)] HRESULT Name([in] BSTR newVal); [propget, helpstring("property Description"), id(2)] HRESULT Description([out, retval] BSTR *pVal); [propput, helpstring("property Description"), id(2)] HRESULT Description([in] BSTR newVal); [propget, helpstring("property UsedInSession"), id(3)] HRESULT UsedInSession([out, retval] BSTR *pVal); [propput, helpstring("property UsedInSession"), id(3)] HRESULT UsedInSession([in] BSTR newVal); [propget, helpstring("property Type"), id(4)] HRESULT Type([out, retval] BSTR *pVal); [propget, helpstring("property ReadOnly"), id(5)] HRESULT ReadOnly([out, retval] VARIANT_BOOL *pVal); [propput, helpstring("property ReadOnly"), id(5)] HRESULT ReadOnly([in] VARIANT_BOOL newVal); [propget, helpstring("property HelpContextID"), id(6)] HRESULT HelpContextID([out, retval] long *pVal); [propput, helpstring("property HelpContextID"), id(6)] HRESULT HelpContextID([in] long newVal); [propget, helpstring("property HelpFilePath"), id(7)] HRESULT HelpFilePath([out, retval] BSTR *pVal); [propput, helpstring("property HelpFilePath"), id(7)] HRESULT HelpFilePath([in] BSTR newVal); [propget, helpstring("property SoftwareModuleKey"), id(8)] HRESULT SoftwareModuleKey([out, retval] BSTR *pVal); [propput, helpstring("property SoftwareModuleKey"), id(8)] HRESULT SoftwareModuleKey([in] BSTR newVal); }; [
uuid(ECA7E07E-0A9D-4750-92D1-CFD8F9DB2CA3), helpstring("IviLogicalNameCollection Class")
] coclass IviLogicalNameCollection { [default] interface IIviLogicalNameCollection; }; [ uuid(B7957C4F-D86B-47E7-8384-895ABBE654AB), helpstring("IIviLogicalNameCollection Interface"), dual, object, pointer_default(unique) ] interface IIviLogicalNameCollection : IDispatch { [id(1)] HRESULT Add([in] IIviLogicalName *pVal); [propget, id(2)] HRESULT Count([out, retval] long* pVal); [propget, id(DISPID_VALUE)] IVI-3.5: IVI Configuration Server Specification
168
IVI Foundation
HRESULT Item([in] VARIANT varIndex,[out, retval]IIviLogicalName**pVal); [propget, id(DISPID_NEWENUM)] HRESULT _NewEnum([out, retval] IUnknown** ppunkEnum); [id(3)] HRESULT Remove([in] VARIANT varIndex); }; [ uuid(49031FD4-9E0B-40AF-BB4E-DF9D9DAB5750), helpstring("IviSessionCollection Class") ] coclass IviSessionCollection { [default] interface IIviSessionCollection; }; [
uuid(F5F6AB1A-06D1-43E4-88BA-750F112B4B0F), helpstring("IIviSessionCollection Interface"), dual, object, pointer_default(unique)
] interface IIviSessionCollection : IDispatch { [id(1)] HRESULT Add([in] IIviSession *pVal); [propget, id(2)] HRESULT Count([out, retval] long* pVal); [propget, id(DISPID_VALUE)] HRESULT Item([in] VARIANT varIndex,[out, retval]IIviSession**pVal); [propget, id(DISPID_NEWENUM)] HRESULT _NewEnum([out, retval] IUnknown** ppunkEnum); [id(3)] HRESULT Remove([in] VARIANT varIndex); };
[ uuid(14527192-79F0-4BCE-AE03-4C534D16858B), helpstring("IviPhysicalNameCollection Class")
] coclass IviPhysicalNameCollection { [default] interface IIviPhysicalNameCollection; }; [ uuid(273B5A6E-2D37-4C1F-85BA-AF1C4F8D65E0), helpstring("IIviPhysicalNameCollection Interface"), dual, object, pointer_default(unique)
] interface IIviPhysicalNameCollection : IDispatch { [id(1)] HRESULT Add([in] IIviPhysicalName *pVal); [propget, id(2)] HRESULT Count([out, retval] long* pVal); [propget, id(DISPID_VALUE)] HRESULT Item([in] VARIANT varIndex,[out, retval]IIviPhysicalName**pVal); [propget, id(DISPID_NEWENUM)] IVI Foundation
169
IVI-3.5: IVI Configuration Server Specification
HRESULT _NewEnum([out, retval] IUnknown** ppunkEnum); [id(3)] HRESULT Remove([in] VARIANT varIndex); }; [ uuid(8F44405A-8DD1-11D5-8F8F-0060B0FC9326), helpstring("IviVirtualRange Class") ] coclass IviVirtualRange { [default] interface IIviVirtualRange; }; [ uuid(8F44405B-8DD1-11D5-8F8F-0060B0FC9326), helpstring("IIviVirtualRange Interface"), dual, object, pointer_default(unique) ] interface IIviVirtualRange : IDispatch { [propget, helpstring("property Min"), id(1)] HRESULT Min([out, retval] long *pVal); [propput, helpstring("property Min"), id(1)] HRESULT Min([in] long newVal); [propget, helpstring("property Max"), id(2)] HRESULT Max([out, retval] long *pVal); [propput, helpstring("property Max"), id(2)] HRESULT Max([in] long newVal); [propget, helpstring("property Name"), id(3)] HRESULT Name([out, retval] BSTR *pVal); [propput, helpstring("property Name"), id(3)] HRESULT Name([in] BSTR newVal); [propget, helpstring("property StartingPhysicalIndex"), id(4)] HRESULT StartingPhysicalIndex([out, retval] long *pVal); [propput, helpstring("property StartingPhysicalIndex"), id(4)] HRESULT StartingPhysicalIndex([in] long newVal); }; [ uuid(8F444069-8DD1-11D5-8F8F-0060B0FC9326), helpstring("IviPhysicalRange Class")
] coclass IviPhysicalRange { [default] interface IIviPhysicalRange; }; [
uuid(8F44406A-8DD1-11D5-8F8F-0060B0FC9326), helpstring("IIviPhysicalRange Interface"), dual, object, pointer_default(unique)
] interface IIviPhysicalRange : IDispatch { [propget, helpstring("property Max"), *pVal); [propput, helpstring("property Max"), [propget, helpstring("property Min"), *pVal); [propput, helpstring("property Min"),
IVI-3.5: IVI Configuration Server Specification
id(1)] HRESULT Max([out, retval] long id(1)] HRESULT Max([in] long newVal); id(2)] HRESULT Min([out, retval] long id(2)] HRESULT Min([in] long newVal);
170
IVI Foundation
[propget, helpstring("property Name"), id(3)] HRESULT Name([out, retval] BSTR *pVal); [propput, helpstring("property Name"), id(3)] HRESULT Name([in] BSTR newVal); }; [ uuid(8F44407A-8DD1-11D5-8F8F-0060B0FC9326), helpstring("IviVirtualRangeCollection Class") ] coclass IviVirtualRangeCollection { [default] interface IIviVirtualRangeCollection; }; [ uuid(8F444084-8DD1-11D5-8F8F-0060B0FC9326), helpstring("IviPhysicalRangeCollection Class")
] coclass IviPhysicalRangeCollection { [default] interface IIviPhysicalRangeCollection; }; [ uuid(8F444085-8DD1-11D5-8F8F-0060B0FC9326), helpstring("IIviPhysicalRangeCollection Interface"), dual, object, pointer_default(unique)
] interface IIviPhysicalRangeCollection : IDispatch { [helpstring("method Add"), id(1)] HRESULT Add([in] IIviPhysicalRange * pVal); [helpstring("method Remove"), id(2)] HRESULT Remove([in] VARIANT varIndex); [propget, helpstring("property Count"), id(3)] HRESULT Count([out, retval] long *pVal); [propget, helpstring("property Item"), id(DISPID_VALUE)] HRESULT Item([in] VARIANT varIndex, [out, retval] IIviPhysicalRange * *pVal); [propget, helpstring("property _NewEnum"), id(DISPID_NEWENUM)] HRESULT _NewEnum([out, retval] IUnknown * *pVal); }; [ uuid(8F44407B-8DD1-11D5-8F8F-0060B0FC9326), helpstring("IIviVirtualRangeCollection Interface"), dual, object, pointer_default(unique) ] interface IIviVirtualRangeCollection : IDispatch { [helpstring("method Add"), id(1)] HRESULT Add([in] IIviVirtualRange * pVal); [propget, helpstring("property Count"), id(2)] HRESULT Count([out, retval] long *pVal ); [propget, helpstring("property Item"), id(DISPID_VALUE)] HRESULT Item([in] VARIANT varIndex, [out, retval] IIviVirtualRange * *pVal); [helpstring("method Remove"), id(5)] HRESULT Remove([in] VARIANT varIndex); [propget, helpstring("property _NewEnum"), id(DISPID_NEWENUM)] HRESULT _NewEnum([out, retval] IUnknown * *pVal); }; [ uuid(52272C88-903E-11D5-8F90-0060B0FC9326), IVI Foundation
171
IVI-3.5: IVI Configuration Server Specification
helpstring("IviStructure Class") ] coclass IviStructure { [default] interface IIviStructure; }; [ uuid(52272C89-903E-11D5-8F90-0060B0FC9326), helpstring("IIviStructure Interface"), dual, object, pointer_default(unique) ] interface IIviStructure : IIviDataComponent { [propget, helpstring("property DataComponents"), id(9)] HRESULT DataComponents([out, retval] IIviDataComponentCollection * *pVal); }; [ uuid(E15B3F69-90FA-11D5-8F90-0060B0FC9326), helpstring("IviBoolean Class") ] coclass IviBoolean { [default] interface IIviBoolean; }; [
uuid(E15B3F6F-90FA-11D5-8F90-0060B0FC9326), helpstring("IviInteger Class")
] coclass IviInteger { [default] interface IIviInteger; }; [ uuid(E15B3F73-90FA-11D5-8F90-0060B0FC9326), helpstring("IviAPIReference Class") ] coclass IviAPIReference { [default] interface IIviAPIReference; }; [ uuid(E15B3F71-90FA-11D5-8F90-0060B0FC9326), helpstring("IviString Class") ] coclass IviString { [default] interface IIviString; }; [ uuid(E15B3F6D-90FA-11D5-8F90-0060B0FC9326), helpstring("IviReal Class") ] coclass IviReal { [default] interface IIviReal; }; [ IVI-3.5: IVI Configuration Server Specification
172
IVI Foundation
uuid(E15B3F72-90FA-11D5-8F90-0060B0FC9326), helpstring("IIviString Interface"), dual, object, pointer_default(unique) ] interface IIviString : IIviDataComponent { [propget, helpstring("property Value"), id(9)] HRESULT Value([out, retval] BSTR *pVal); [propput, helpstring("property Value"), id(9)] HRESULT Value([in] BSTR newVal); }; [ uuid(E15B3F6E-90FA-11D5-8F90-0060B0FC9326), helpstring("IIviReal Interface"), dual, object, pointer_default(unique) ] interface IIviReal : IIviDataComponent { [propget, helpstring("property Units"), *pVal); [propput, helpstring("property Units"), [propget, helpstring("property Value"), double *pVal); [propput, helpstring("property Value"), newVal); };
id(9)] HRESULT Units([out, retval] BSTR id(9)] HRESULT Units([in] BSTR newVal); id(10)] HRESULT Value([out, retval] id(10)] HRESULT Value([in] double
[ uuid(E15B3F74-90FA-11D5-8F90-0060B0FC9326), helpstring("IIviAPIReference Interface"), dual, object, pointer_default(unique) ] interface IIviAPIReference : IIviDataComponent { [propget, helpstring("property Value"), id(9)] HRESULT Value([out, retval] BSTR *pVal); [propput, helpstring("property Value"), id(9)] HRESULT Value([in] BSTR newVal); [propget, helpstring("property PublishedAPI"), id(10)] HRESULT PublishedAPI([out, retval] IIviPublishedAPI **pVal); [propputref, helpstring("property PublishedAPI"), id(10)] HRESULT PublishedAPI([in] IIviPublishedAPI * newVal); }; [ uuid(E15B3F6A-90FA-11D5-8F90-0060B0FC9326), helpstring("IIviBoolean Interface"), dual, object, pointer_default(unique) ] interface IIviBoolean : IIviDataComponent { [propget, helpstring("property Value"), id(9)] HRESULT Value([out, retval] VARIANT_BOOL *pVal); [propput, helpstring("property Value"), id(9)] HRESULT Value([in] VARIANT_BOOL newVal); }; IVI Foundation
173
IVI-3.5: IVI Configuration Server Specification
[ uuid(E15B3F70-90FA-11D5-8F90-0060B0FC9326), helpstring("IIviInteger Interface"), dual, object, pointer_default(unique) ] interface IIviInteger : IIviDataComponent { [propget, helpstring("property Units"), *pVal); [propput, helpstring("property Units"), [propget, helpstring("property Value"), *pVal); [propput, helpstring("property Value"), }; };
IVI-3.5: IVI Configuration Server Specification
174
id(9)] HRESULT Units([out, retval] BSTR id(9)] HRESULT Units([in] BSTR newVal); id(10)] HRESULT Value([out, retval] long id(10)] HRESULT Value([in] long newVal);
IVI Foundation
Appendix B: IVI-COM Driver Example The focus of this example is an imaginary IVI-COM instrument specific driver. The driver supports a family of oscilloscopes from GizmoTronics , Inc. The driver supports the IVI inherent interfaces and the IVI scope class-compliant interfaces. In addition to the standard IVI configuration properties, the driver can be configured from the configuration server to turn tracing on and off. The driver supports four channels that it knows as “C1” through “C4”. All examples are in Visual Basic, and may be abbreviated to emphasize configuration server use. The configuration server code that needs to be run when the driver is installed looks like this. Option Explicit Private Sub AddSoftwareModule() Dim Dim Dim Dim Dim Dim
cs As New IviConfigStore sm As IviSoftwareModule pa As IviPublishedAPI pn As IviPhysicalName pr As IviPhysicalRange dcb As IviBoolean
'// Deserialize the master configuration store. On Error GoTo DeserializeError cs.Deserialize cs.MasterLocation On Error GoTo 0 '// Delete the old version of the driver On Error Resume Next cs.SoftwareModules.Remove "gt40xx" On Error GoTo 0 '// Make sure that the Published API entries used by the software module '// exist in the global Published API collection. Set pa = New IviPublishedAPI pa.Name = "IviDriver" pa.Type = "IVI-COM" pa.MajorVersion = 2 pa.MinorVersion = 0 '// If the API is already in the collection, what follows will return '// an error, but it doesn't need to be trapped because the API '// exists in the collection, which is what we want. On Error Resume Next cs.PublishedAPIs.Add pa On Error GoTo 0 Set pa = New IviPublishedAPI pa.Name = "IviScope" pa.Type = "IVI-COM" pa.MajorVersion = 2 pa.MinorVersion = 0 '// If the API is already in the collection, what follows will return '// an error, but it doesn't need to be trapped because the API '// exists in the collection, which is what we want. IVI Foundation
175
IVI-3.5: IVI Configuration Server Specification
On Error Resume Next cs.PublishedAPIs.Add pa On Error GoTo 0 '// Create the new software module entry Set sm = New IviSoftwareModule sm.Name = "gt40xx" sm.Description = "IVI-COM Specific Instrument Driver for GT40xx family of oscilloscopes" sm.Prefix = "gt40xx" sm.ProgId = "gt40xx.gt40xx" sm.ModulePath = "" sm.SupportedInstrumentModels = "gt4000,gt4001,gt4010,gt4011,gt4012" '// Add the Published API entries to the software module sm.PublishedAPIs.Add cs.PublishedAPIs.Item("IviDriver", 2, 0, "IVI-COM") sm.PublishedAPIs.Add cs.PublishedAPIs.Item("IviScope", 2, 0, "IVI-COM") '// Add the physical name and physical range entries Set pn = New IviPhysicalName pn.Name = "C" pn.RCName = "Channel" sm.PhysicalNames.Add pn Set pr = New IviPhysicalRange pr.Name = "C Range 1" pr.Max = 4 pr.Min = 1 pn.PhysicalRanges.Add pr '// Add the data components Set dcb = New IviBoolean dcb.Name = "Trace" dcb.Description = "If True, tracing is on, if False, tracing is off" '// dcb.Type automatically set to "Boolean" by the API dcb.ReadOnly = True dcb.UsedInSession = "Required" '// Software module will default to False dcb.Value = False '// False is the default configuration value sm.DataComponents.Add dcb cs.SoftwareModules.Add sm
Exit Sub DeserializeError: '// Handle the error appropriately. End Sub
Now create a session for the driver. A logical name (“Bob”) will refer to the session. The session will refer to a hardware asset whose resource descriptor is “GPIB0::12::INSTR”. It will also provide logical names for the software modules physical names and configure the values of the trace data component. The configuration server code that needs to be run when a session is created for the driver software module follows. Bear in mind that most end-users will use a GUI to edit the configuration store, but some users may choose to write code like this – for example, as part of a test system. In any case, this example code is
IVI-3.5: IVI Configuration Server Specification
176
IVI Foundation
meant to illustrate the kinds of configuration server entries that must be made. It is not meant to be bulletproof copy and paste code. Private Sub AddDriverSession() Dim Dim Dim Dim Dim Dim Dim Dim Dim
cs As New IviConfigStore ha As IviHardwareAsset hadup As IviHardwareAsset ds As IviDriverSession vn As IviVirtualName vr As IviVirtualRange dc As IviDataComponent dcb As IviBoolean ln As IviLogicalName
'// Deserialize the master configuration store. 'On Error GoTo DeserializeError cs.Deserialize (cs.MasterLocation) On Error GoTo 0 '// Create the Hardware Asset and add it to the global hardware asset '// collection Set ha = New IviHardwareAsset ha.Name = "Scope 5" ha.Description = "GT4010 Scope, test station 5" ha.IOResourceDescriptor = "GPIB0::12::INSTR" On Error GoTo DuplicateHardwareAsset cs.HardwareAssets.Add ha On Error GoTo 0 '// Create the Session fill in the Session object properties Set ds = New IviDriverSession ds.Name = "Scope5" ds.Description = "Driver session forscope at test station 5" ds.Cache = False ds.DriverSetup = "" ds.InterchangeCheck = True ds.QueryInstrStatus = False ds.RangeCheck = False ds.RecordCoercions = False ds.Simulate = True '// Add the Hardware Asset reference to the Session Set ds.HardwareAsset = cs.HardwareAssets.Item("Scope 5") '// Create the Virtual names for the Session. The creates the following '// mappings: Analog -> C1, 1 -> C2, 2 -> C3, and 3 -> C4. Set vn = New IviVirtualName vn.Name = "Analog" vn.MapTo = "C1" ds.VirtualNames.Add vn Set vn = New IviVirtualName vn.MapTo = "C" vn.Name = "" Set vr = New IviVirtualRange vr.Name = "Virt CH 1-3" vr.Max = 3 vr.Min = 1 vr.StartingPhysicalIndex = 2 vn.VirtualRanges.Add vr ds.VirtualNames.Add vn IVI Foundation
177
IVI-3.5: IVI Configuration Server Specification
'// Add the Software Module reference to the Session. The configuration '// server will automatically copy all data components with UsedInSession '// = "Required" or "Optional" to the session's data components, and '// change the ReadOnly property to False. Set ds.SoftwareModule = cs.SoftwareModules.Item("gt40xx") '// Change the default values for Data Components for the Session, if needed Set dcb = ds.DataComponents.Item("Trace") dcb.Value = True cs.DriverSessions.Add ds '// Create the Logical Name and add it to the global logical name collection Set ln = New IviLogicalName ln.Name = "Bob" ln.Description = "Logical name for Scope at test station 5" Set ln.Session = ds On Error GoTo DuplicateLogicalNames cs.LogicalNames.Add ln On Error GoTo 0 Exit Sub '// Error handler for duplicate hardware assets DuplicateHardwareAsset: Set hadup = cs.HardwareAssets.Item("Scope 5") If ha.IOResourceDescriptor = hadup.IOResourceDescriptor _ Then Resume Next '// The hardware asset already exists - we just move forward End If '// The hardware asset "Scope 5" refers to a different IO Resource. '// Handle this error appropriately. Exit Sub '// Error handler for duplicate Logical Names DuplicateLogicalNames: '// The logical name "Bob" already exists. '// Handle this error appropriately. Exit Sub End Sub
The XML file created by this example, with extra line breaks, looks like: IVI Configuration Server The IVI Configuration Server allows access to and modification of an IVI configuration store IVI Foundation, Inc 1.3.0.3 <SpecificationMajorVersion>1 <SpecificationMinorVersion>0 <MasterLocation>C:\Program Files\IVI\Data\IviConfigurationStore.xml IVI-3.5: IVI Configuration Server Specification
178
IVI Foundation
IviDriver <MajorVersion>2 <MinorVersion>0 IVI-COM IviScope <MajorVersion>2 <MinorVersion>0 IVI-COM <SoftwareModules> gt40xx IVI-COM Specific Instrument Driver for GT40xx family of oscilloscopes Trace If True, tracing is on, if False, tracing is off 1 <UsedInSession>Required Boolean 0 <SoftwareModuleKey> 0 <ModulePath> gt40xx gt40xx.gt40xx <SupportedInstrumentModels>gt4000,gt4001,gt4010,gt4011,gt4012 C Channel C Range 1 <Max>4 <Min>1 Scope 5 GT4010 Scope, test station 5 IVI Foundation
179
IVI-3.5: IVI Configuration Server Specification
GPIB0::12::INSTR Scope5 Driver session forscope at test station 5 Trace If True, tracing is on, if False, tracing is off 0 <UsedInSession>Required Boolean 0 <SoftwareModuleKey> 1 <MapTo>C Virt CH 1-3 <Max>3 <Min>1 <StartingPhysicalIndex>2 Analog <MapTo>C1 <SoftwareModuleName>gt40xx 0 1 0 0 0 <Simulate>1 <Sessions> Bob IVI-3.5: IVI Configuration Server Specification
180
IVI Foundation
Logical name for Scope at test station 5
IVI Foundation
181
IVI-3.5: IVI Configuration Server Specification
Appendix C: XSD File The schema file, IviConfigurationStore.xsd, used by IVI Configuration Store XML files contains: <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata"> <xs:element name="IviConfigStore"> <xs:complexType> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Description" type="xs:string"/> <xs:element name="Vendor" type="xs:string"/> <xs:element name="Revision" type="xs:string"/> <xs:element name="SpecificationMajorVersion" type="xs:int"/> <xs:element name="SpecificationMinorVersion" type="xs:int"/> <xs:element name="MasterLocation" type="xs:string"/> <xs:element name="ProcessDefaultLocation" type="xs:string"/> <xs:element name="ActualLocation" type="xs:string"/> <xs:element name="PublishedAPIs"> <xs:complexType> <xs:sequence> <xs:element name="IviPublishedAPI" type="IviPublishedAPI" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="SoftwareModules" type="SoftwareModules"/> <xs:element name="HardwareAssets"> <xs:complexType> <xs:sequence> <xs:element name="IviHardwareAsset" type="IviHardwareAsset" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="DriverSessions"> <xs:complexType> <xs:sequence> <xs:element name="IviDriverSession" type="IviDriverSession" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="Sessions"> <xs:complexType> <xs:choice minOccurs="0" maxOccurs="unbounded"> <xs:element name="IviSession" type="IviSession"/> <xs:element name="IviDriverSession"> <xs:complexType> <xs:attribute name="idref" type="xs:IDREF"/> IVI-3.5: IVI Configuration Server Specification
182
IVI Foundation
<xs:element name="LogicalNames"> <xs:complexType> <xs:sequence> <xs:element name="IviLogicalName" type="IviLogicalName" minOccurs="0" maxOccurs="unbounded"/> <xs:complexType name="IviPublishedAPI"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="MajorVersion" type="xs:int"/> <xs:element name="MinorVersion" type="xs:int"/> <xs:element name="Type" type="xs:string"/> <xs:attribute name="id" type="xs:ID"/> <xs:complexType name="IviHardwareAsset"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Description" type="xs:string"/> <xs:element name="DataComponents" type="DataComponents"/> <xs:element name="IOResourceDescriptor" type="xs:string"/> <xs:attribute name="id" type="xs:ID"/> <xs:complexType name="IviDriverSession"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Description" type="xs:string"/> <xs:element name="DataComponents" type="DataComponents"/> <xs:element name="IviHardwareAsset" minOccurs="0" maxOccurs="1"> <xs:complexType> <xs:attribute name="idref" type="xs:IDREF"/> <xs:element name="IviSoftwareModuleRef" minOccurs="0" maxOccurs="1"> <xs:complexType> <xs:attribute name="idref" type="xs:IDREF"/> <xs:element name="VirtualNames" type="VirtualNames"/> <xs:element name="SoftwareModuleName" type="xs:string"/> <xs:element name="Cache" type="xs:boolean"/> <xs:element name="DriverSetup" type="xs:string"/> <xs:element name="InterchangeCheck" type="xs:boolean"/> <xs:element name="QueryInstrStatus" type="xs:boolean"/> <xs:element name="RangeCheck" type="xs:boolean"/> <xs:element name="RecordCoercions" type="xs:boolean"/> <xs:element name="Simulate" type="xs:boolean"/> <xs:attribute name="id" type="xs:ID"/> IVI Foundation
183
IVI-3.5: IVI Configuration Server Specification
<xs:complexType name="IviSession"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Description" type="xs:string"/> <xs:element name="DataComponents" type="DataComponents"/> <xs:element name="IviHardwareAsset" minOccurs="0" maxOccurs="1"> <xs:complexType> <xs:attribute name="idref" type="xs:IDREF"/> <xs:element name="IviSoftwareModuleRef" minOccurs="0" maxOccurs="1"> <xs:complexType> <xs:attribute name="idref" type="xs:IDREF"/> <xs:element name="VirtualNames" type="VirtualNames"/> <xs:element name="SoftwareModuleName" type="xs:string"/> <xs:attribute name="id" type="xs:ID"/> <xs:complexType name="IviSoftwareModule"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Description" type="xs:string"/> <xs:element name="DataComponents" type="DataComponents"/> <xs:element name="ModulePath" type="xs:string"/> <xs:element name="Prefix" type="xs:string"/> <xs:element name="ProgID" type="xs:string"/> <xs:element name="SupportedInstrumentModels" type="xs:string"/> <xs:element name="PhysicalNames" type="PhysicalNames"/> <xs:element name="PublishedAPIs" type="PublishedAPIs"/> <xs:attribute name="id" type="xs:ID"/> <xs:complexType name="IviLogicalName"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Description" type="xs:string"/> <xs:element name="IviSession" minOccurs="0" maxOccurs="1"> <xs:complexType> <xs:attribute name="idref" type="xs:IDREF"/> <xs:element name="IviDriverSession" minOccurs="0" maxOccurs="1"> <xs:complexType> <xs:attribute name="idref" type="xs:IDREF"/> <xs:attribute name="id" type="xs:ID"/> <xs:complexType name="IviVirtualName"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="MapTo" type="xs:string"/> <xs:element name="VirtualRanges"> IVI-3.5: IVI Configuration Server Specification
184
IVI Foundation
<xs:complexType> <xs:sequence> <xs:element name="IviVirtualRange" minOccurs="0" maxOccurs="unbounded"> <xs:complexType> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Max" type="xs:int"/> <xs:element name="Min" type="xs:int"/> <xs:element name="StartingPhysicalIndex" type="xs:int"/> <xs:attribute name="id" type="xs:ID"/> <xs:attribute name="id" type="xs:ID"/> <xs:complexType name="IviPhysicalName"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="RCName" type="xs:string"/> <xs:element name="PhysicalNames" type="PhysicalNames"/> <xs:element name="PhysicalRanges"> <xs:complexType> <xs:sequence> <xs:element name="IviPhysicalRange" minOccurs="0" maxOccurs="unbounded"> <xs:complexType> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Max" type="xs:int"/> <xs:element name="Min" type="xs:int"/> <xs:attribute name="id" type="xs:ID"/> <xs:attribute name="id" type="xs:ID"/> <xs:complexType name="SoftwareModules"> <xs:choice minOccurs="0" maxOccurs="unbounded"> <xs:element name="IviSoftwareModule" type="IviSoftwareModule"/> <xs:element name="IviSoftwareModuleRef"> <xs:complexType> <xs:attribute name="idref" type="xs:IDREF"/> <xs:complexType name="PublishedAPIs"> IVI Foundation
185
IVI-3.5: IVI Configuration Server Specification
<xs:sequence> <xs:element name="IviPublishedAPI" minOccurs="0" maxOccurs="unbounded"> <xs:complexType> <xs:attribute name="idref" type="xs:IDREF"/> <xs:complexType name="DataComponents"> <xs:choice minOccurs="0" maxOccurs="unbounded"> <xs:element name="IviStructure" type="IviStructure"/> <xs:element name="IviInteger" type="IviInteger"/> <xs:element name="IviString" type="IviString"/> <xs:element name="IviReal" type="IviReal"/> <xs:element name="IviBoolean" type="IviBoolean"/> <xs:element name="IviAPIReference" type="IviAPIReference"/> <xs:complexType name="PhysicalNames"> <xs:sequence> <xs:element name="IviPhysicalName" type="IviPhysicalName" minOccurs="0" maxOccurs="unbounded"/> <xs:complexType name="VirtualNames"> <xs:sequence> <xs:element name="IviVirtualName" type="IviVirtualName" minOccurs="0" maxOccurs="unbounded"/> <xs:complexType name="IviStructure"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Description" type="xs:string"/> <xs:element name="ReadOnly" type="xs:boolean"/> <xs:element name="UsedInSession" type="xs:string"/> <xs:element name="Type" type="xs:string"/> <xs:element name="HelpContextID" type="xs:int"/> <xs:element name="HelpFilePath" type="xs:string"/> <xs:element name="SoftwareModuleKey" type="xs:string"/> <xs:element name="DataComponents" type="DataComponents"/> <xs:attribute name="id" type="xs:ID"/> <xs:complexType name="IviBoolean"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Description" type="xs:string"/> <xs:element name="ReadOnly" type="xs:boolean"/> <xs:element name="UsedInSession" type="xs:string"/> <xs:element name="Type" type="xs:string"/> <xs:element name="HelpContextID" type="xs:int"/> <xs:element name="HelpFilePath" type="xs:string"/> <xs:element name="SoftwareModuleKey" type="xs:string"/> <xs:element name="Value" type="xs:boolean"/> IVI-3.5: IVI Configuration Server Specification
186
IVI Foundation
<xs:attribute name="id" type="xs:ID"/> <xs:complexType name="IviReal"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Description" type="xs:string"/> <xs:element name="ReadOnly" type="xs:boolean"/> <xs:element name="UsedInSession" type="xs:string"/> <xs:element name="Type" type="xs:string"/> <xs:element name="HelpContextID" type="xs:int"/> <xs:element name="HelpFilePath" type="xs:string"/> <xs:element name="SoftwareModuleKey" type="xs:string"/> <xs:element name="Units" type="xs:string"/> <xs:element name="Value" type="xs:double"/> <xs:attribute name="id" type="xs:ID"/> <xs:complexType name="IviString"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Description" type="xs:string"/> <xs:element name="ReadOnly" type="xs:boolean"/> <xs:element name="UsedInSession" type="xs:string"/> <xs:element name="Type" type="xs:string"/> <xs:element name="HelpContextID" type="xs:int"/> <xs:element name="HelpFilePath" type="xs:string"/> <xs:element name="SoftwareModuleKey" type="xs:string"/> <xs:element name="Value" type="xs:string"/> <xs:attribute name="id" type="xs:ID"/> <xs:complexType name="IviInteger"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Description" type="xs:string"/> <xs:element name="ReadOnly" type="xs:boolean"/> <xs:element name="UsedInSession" type="xs:string"/> <xs:element name="Type" type="xs:string"/> <xs:element name="HelpContextID" type="xs:int"/> <xs:element name="HelpFilePath" type="xs:string"/> <xs:element name="SoftwareModuleKey" type="xs:string"/> <xs:element name="Units" type="xs:string"/> <xs:element name="Value" type="xs:int"/> <xs:attribute name="id" type="xs:ID"/> <xs:complexType name="IviAPIReference"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Description" type="xs:string"/> <xs:element name="ReadOnly" type="xs:boolean"/> <xs:element name="UsedInSession" type="xs:string"/> <xs:element name="Type" type="xs:string"/> <xs:element name="HelpContextID" type="xs:int"/> <xs:element name="HelpFilePath" type="xs:string"/> <xs:element name="SoftwareModuleKey" type="xs:string"/> <xs:element name="Value" type="xs:string"/> IVI Foundation
187
IVI-3.5: IVI Configuration Server Specification
<xs:element name="IviPublishedAPI"> <xs:complexType> <xs:attribute name="idref" type="xs:IDREF"/> <xs:attribute name="id" type="xs:ID"/>
IVI-3.5: IVI Configuration Server Specification
188
IVI Foundation
Interchangeable Virtual Instruments
IVI-3.5: Configuration Server Specification
November 7, 2002 Revision 1.0
IVI-3.5: IVI Configuration Server Specification
2
IVI Foundation
Important Information The IVI Configuration Server Specification (IVI-3.5) is authored by the IVI Foundation member companies. For a vendor membership roster list, please visit the IVI Foundation web site at www.ivifoundation.org, or contact the IVI Foundation at 2515 Camino del Rio South, Suite 340, San Diego, CA 92108. The IVI Foundation wants to receive your comments on this specification. You can contact the Foundation through email at [email protected], through the web site at www.ivifoundation.org, or you can write to the IVI Foundation, 2515 Camino del Rio South, Suite 340, San Diego, CA 92108. Warranty The IVI Foundation and its member companies make no warranty of any kind with regard to this material, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The IVI Foundation and its member companies shall not be liable for errors contained herein or for incidental or consequential damages in connection with the furnishing, performance, or use of this material. Trademarks Product and company names listed are trademarks or trade names of their respective companies.
IVI Foundation
3
IVI-3.5: IVI Configuration Server Specification
1.
Overview of the IVI Configuration Server Specification.............. 12 1.1 1.2 1.3 1.4 1.5
2.
IVI Configuration Server Design.................................................... 15 2.1 2.2 2.3 2.4 2.5
2.6 2.7 2.8
2.9
3.
Introduction.....................................................................................................................................12 Typical Use Scenario of the Configuration Server .........................................................................12 1.2.1 Repeated Capabilities .......................................................................................................13 References.......................................................................................................................................13 Definitions of Terms and Acronyms...............................................................................................13 Implementation ...............................................................................................................................14
UML Design ...................................................................................................................................15 Types of Classes and Objects..........................................................................................................15 Notation ..........................................................................................................................................17 IVI Configuration Store ..................................................................................................................17 IVI Configurable Components........................................................................................................18 2.5.1 IVI Configurable Component ...........................................................................................18 2.5.2 IVI Software Module ........................................................................................................18 2.5.3 IVI Session and IVI Driver Session..................................................................................19 2.5.4 IVI Hardware Asset ..........................................................................................................19 IVI Logical Name ...........................................................................................................................19 IVI Published API...........................................................................................................................20 IVI Data Components .....................................................................................................................20 2.8.1 IVI Data Component.........................................................................................................20 2.8.2 IVI Structure .....................................................................................................................21 2.8.3 IVI Boolean ......................................................................................................................21 2.8.4 IVI Real ............................................................................................................................21 2.8.5 IVI Integer ........................................................................................................................21 2.8.6 IVI String..........................................................................................................................22 2.8.7 IVI API Reference ............................................................................................................22 Repeated Capabilities......................................................................................................................22 2.9.1 Repeated Capabilities in the Configuration Server...........................................................22 2.9.2 IVI Physical Name and IVI Physical Range.....................................................................22 2.9.3 IVI Virtual Name and IVI Virtual Range .........................................................................24
Instantiation and execution of the IVI Configuration Server ...... 25 3.1
3.2
3.3 3.4
3.5
Installing the Configuration Server .................................................................................................25 3.1.1 Packaging..........................................................................................................................25 3.1.2 Data File Installation.........................................................................................................25 3.1.3 First Installation ................................................................................................................25 3.1.4 Subsequent Installations ...................................................................................................26 Accessing the Configuration Store..................................................................................................26 3.2.1 Master Configuration Store ..............................................................................................26 3.2.2 Process Default Configuration Store ................................................................................27 3.2.3 Instantiating the Right Configuration Store From Software Modules ..............................27 3.2.4 Serializing to a Different Configuration Store..................................................................27 Adding Entries to Collections .........................................................................................................27 Installing Software Modules ...........................................................................................................27 3.4.1 Data Components In Software Modules ...........................................................................28 3.4.2 Un-installing Software Modules .......................................................................................28 3.4.3 Re-installing Software Modules .......................................................................................29 Maintaining Configuration Data .....................................................................................................29 3.5.1 Configuring Hardware Assets...........................................................................................29 3.5.2 Configuring Sessions and Driver Sessions .......................................................................30
IVI-3.5: IVI Configuration Server Specification
4
IVI Foundation
3.6
3.7 3.8 3.9
4.
Collections ...................................................................................... 34 4.1 4.2 4.3 4.4
5.
C API Special Functions Overview ................................................................................................37 C API Special Functions .................................................................................................................37 5.2.1 Clear Error ........................................................................................................................38 5.2.2 Close .................................................................................................................................39 5.2.3 Dispose Handle.................................................................................................................40 5.2.4 Get Error ...........................................................................................................................41 5.2.5 Initialize ............................................................................................................................42
IVI Configurable Components Class (Virtual) .............................. 43 6.1 6.2 6.3
7.
Collections in COM ........................................................................................................................34 Collections in C...............................................................................................................................35 Properties in C.................................................................................................................................35 Return Codes...................................................................................................................................36
C API Special Functions................................................................. 37 5.1 5.2
6.
3.5.3 Data Components In Sessions...........................................................................................30 3.5.4 Configuring Logical Names..............................................................................................31 3.5.5 Documentation Data Components ....................................................................................31 Using Configuration Data ...............................................................................................................31 3.6.1 IVI Class Drivers and the IVI Session Factory.................................................................31 3.6.2 Software Module Initialization .........................................................................................32 3.6.3 Interchanging Instruments ................................................................................................32 Additional Instances of the Configuration Store.............................................................................33 Avoiding the Configuration Server .................................................................................................33 Copying Elements ...........................................................................................................................33
IVI Configurable Components Overview .......................................................................................43 IVI Configurable Components References .....................................................................................43 6.2.1 Data Components..............................................................................................................44 IVI Configurable Components Properties.......................................................................................45 6.3.1 Description........................................................................................................................46 6.3.2 Name.................................................................................................................................47
IVI Configuration Store Class ........................................................ 48 7.1 7.2
7.3
7.4 IVI Foundation
IVI Configuration Store Overview..................................................................................................48 IVI Configuration Store References................................................................................................48 7.2.1 Driver Sessions .................................................................................................................49 7.2.2 Hardware Assets ...............................................................................................................50 7.2.3 Logical Names ..................................................................................................................51 7.2.4 Published APIs .................................................................................................................52 7.2.5 Sessions ............................................................................................................................53 7.2.6 Software Modules.............................................................................................................54 IVI Configuration Store Properties .................................................................................................55 7.3.1 Actual Location ................................................................................................................56 7.3.2 Description........................................................................................................................57 7.3.3 Master Location ................................................................................................................58 7.3.4 Name.................................................................................................................................59 7.3.5 Process Default Location ..................................................................................................60 7.3.6 Revision ............................................................................................................................61 7.3.7 Specification Major Version.............................................................................................62 7.3.8 Specification Minor Version.............................................................................................63 7.3.9 Vendor ..............................................................................................................................64 IVI Configuration Store Functions..................................................................................................65 5
IVI-3.5: IVI Configuration Server Specification
7.4.1 7.4.2 7.4.3 7.4.4
8.
IVI Hardware Asset Class............................................................... 70 8.1 8.2 8.3
9.
10.2 10.3
11.3
IVI Physical Name Overview .........................................................................................................86 IVI Physical Name References .......................................................................................................86 11.2.1 Physical Names.................................................................................................................87 11.2.2 Physical Ranges ................................................................................................................88 IVI Physical Name Properties.........................................................................................................89 11.3.1 Name.................................................................................................................................90 11.3.2 RC Name ..........................................................................................................................91
IVI Physical Range Class ............................................................... 92 12.1 12.2
13.
IVI Software Module Overview......................................................................................................77 10.1.1 Configurable Initial Settings.............................................................................................77 10.1.2 Documentation Data Components ....................................................................................77 IVI Software Module References....................................................................................................78 10.2.1 Physical Names.................................................................................................................79 10.2.2 Published APIs .................................................................................................................80 IVI Software Module Properties .....................................................................................................81 10.3.1 Module Path......................................................................................................................82 10.3.2 Prefix ................................................................................................................................83 10.3.3 ProgID ..............................................................................................................................84 10.3.4 Supported Instrument Models...........................................................................................85
IVI Physical Name Class................................................................. 86 11.1 11.2
12.
IVI Published API Overview ..........................................................................................................72 IVI Published API Properties..........................................................................................................72 9.2.1 Major Version...................................................................................................................73 9.2.2 Minor Version...................................................................................................................74 9.2.3 Name.................................................................................................................................75 9.2.4 Type ..................................................................................................................................76
IVI Software Module Class ............................................................. 77 10.1
11.
IVI Hardware Asset Overview........................................................................................................70 8.1.1 Documentation Data Components ....................................................................................70 IVI Hardware Asset References......................................................................................................70 IVI Hardware Asset Properties .......................................................................................................70 8.3.1 I/O Resource Descriptor ...................................................................................................71
IVI Published API Class.................................................................. 72 9.1 9.2
10.
Deserialize ........................................................................................................................66 Get Driver Session............................................................................................................67 Get Session .......................................................................................................................68 Serialize ............................................................................................................................69
IVI Physical Range Overview.........................................................................................................92 IVI Physical Range Properties ........................................................................................................92 12.2.1 Max...................................................................................................................................93 12.2.2 Min ...................................................................................................................................94 12.2.3 Name.................................................................................................................................95
IVI Logical Name Class................................................................... 96 13.1 13.2
IVI Logical Name Overview...........................................................................................................96 IVI Logical Name References.........................................................................................................96
IVI-3.5: IVI Configuration Server Specification
6
IVI Foundation
13.3
14.
IVI Session Class .......................................................................... 100 14.1 14.2
14.3
15.
16.3
IVI Virtual Name Overview .........................................................................................................115 IVI Virtual Name References........................................................................................................115 16.2.1 Virtual Ranges ................................................................................................................116 IVI Virtual Name Properties .........................................................................................................117 16.3.1 Map To ...........................................................................................................................118 16.3.2 Name...............................................................................................................................119
IVI Virtual Range Class................................................................. 120 17.1 17.2
18.
IVI Driver Session Overview........................................................................................................107 IVI Driver Session References......................................................................................................107 IVI Driver Session Properties .......................................................................................................107 15.3.1 Cache ..............................................................................................................................108 15.3.2 Driver Setup....................................................................................................................109 15.3.3 Interchange Check ..........................................................................................................110 15.3.4 Query Instrument Status .................................................................................................111 15.3.5 Range Check...................................................................................................................112 15.3.6 Record Value Coercions .................................................................................................113 15.3.7 Simulate ..........................................................................................................................114
IVI Virtual Name Class .................................................................. 115 16.1 16.2
17.
IVI Session Overview ...................................................................................................................100 14.1.1 Configurable Initial Settings...........................................................................................100 14.1.2 Documentation Data Components ..................................................................................101 IVI Session References .................................................................................................................101 14.2.1 Hardware Asset...............................................................................................................102 14.2.2 Software Module ............................................................................................................103 14.2.3 Virtual Names.................................................................................................................104 IVI Session Properties...................................................................................................................105 14.3.1 Software Module Name ..................................................................................................106
IVI Driver Session Class............................................................... 107 15.1 15.2 15.3
16.
13.2.1 Session ..............................................................................................................................97 IVI Logical Name Properties ..........................................................................................................98 13.3.1 Name.................................................................................................................................99
IVI Virtual Range Overview.........................................................................................................120 IVI Virtual Range Properties ........................................................................................................120 17.2.1 Max.................................................................................................................................121 17.2.2 Min .................................................................................................................................122 17.2.3 Name...............................................................................................................................123 17.2.4 Starting Physical Index ...................................................................................................124
IVI Data Component Class ........................................................... 125 18.1 18.2
IVI Foundation
IVI Data Component Overview ....................................................................................................125 IVI Data Component Properties....................................................................................................125 18.2.1 Description......................................................................................................................126 18.2.2 Help Context ID..............................................................................................................127 18.2.3 Help File Path .................................................................................................................128 18.2.4 Name...............................................................................................................................129 18.2.5 Read Only .......................................................................................................................130 18.2.6 Software Module Key.....................................................................................................131 18.2.7 Type................................................................................................................................132 7
IVI-3.5: IVI Configuration Server Specification
18.2.8
19.
IVI Structure Class ........................................................................ 134 19.1 19.2 19.3
20.
IVI Boolean Overview ..................................................................................................................143 IVI Boolean Properties..................................................................................................................143 22.2.1 Value...............................................................................................................................144
IVI String Class ............................................................................. 145 23.1 23.2
24.
IVI Real Overview ........................................................................................................................140 IVI Real Properties .......................................................................................................................140 21.2.1 Units ...............................................................................................................................141 21.2.2 Value...............................................................................................................................142
IVI Boolean Class.......................................................................... 143 22.1 22.2
23.
IVI Integer Overview ....................................................................................................................137 IVI Integer Properties....................................................................................................................137 20.2.1 Units ...............................................................................................................................138 20.2.2 Value...............................................................................................................................139
IVI Real Class ................................................................................ 140 21.1 21.2
22.
IVI Structure Overview.................................................................................................................134 IVI Structure References...............................................................................................................134 19.2.1 Data Components............................................................................................................135 IVI Structure Properties ................................................................................................................136
IVI Integer Class ............................................................................ 137 20.1 20.2
21.
Used In Session ..............................................................................................................133
IVI String Overview......................................................................................................................145 IVI String Properties .....................................................................................................................145 23.2.1 Value...............................................................................................................................146
IVI API Reference Class................................................................ 147 24.1 24.2 24.3
IVI API Reference Overview........................................................................................................147 IVI API Reference References......................................................................................................148 24.2.1 Published API .................................................................................................................149 IVI API Reference Properties .......................................................................................................150 24.3.1 Value...............................................................................................................................151
25.
Configuration Server Error and Completion Codes .................. 152
26.
Configuration Store Data Format ................................................ 154
27.
Configuration Utility Implementation Guidelines ...................... 155 27.1 27.2 27.3 27.4 27.5 27.6
General..........................................................................................................................................155 Hardware Assets ...........................................................................................................................155 Published APIs..............................................................................................................................155 Software Modules .........................................................................................................................155 Sessions.........................................................................................................................................155 Documentation Data Components ................................................................................................156
IVI-3.5: IVI Configuration Server Specification
8
IVI Foundation
28.
Limitations..................................................................................... 157 28.1 28.2
Distributed Systems ......................................................................................................................157 Concurrent Reading and Writing ..................................................................................................157
Appendix A: IVI Configuration Server IDL file..................................... 158 Appendix B: IVI-COM Driver Example.................................................. 175 Appendix C: XSD File ............................................................................ 182
IVI Foundation
9
IVI-3.5: IVI Configuration Server Specification
LIST OF FIGURES Figure 2-1 - IVI Configuration Server UML Class Diagram................................................................ 16 Figure 24-1 Typical API Reference Configuration Store Entries....................................................... 147
IVI-3.5: IVI Configuration Server Specification
10
IVI Foundation
Configuration Server Specification Revision History This section is an overview of the revision history of the IVI Configuration Server specification. Table 1-1. Ivi-3.5 Revisions
Revision Number Date of Revision
Revision Notes
Revision 0.1
??
Original draft.
Revision 0.2
May 23, 2001
Bring up to date.
Revision 0.3
July 31, 2001
First version to reflect UML diagrams for iteration 6 of the Configuration Server.
Revision 0.4
August 27, 2001
Add Section 3 and incorporate design changes
Revision 0.5
September 10, 2001
Reflect changes discussed at Sept. 2001 IVI Foundation meeting
Revision 0.6
November 1, 2001
Reflect changes made in telephone conferences after the Sept 2001 IVI meeting.
Revision 0.7
November 30, 2001
Reflect changes made in telephone conferences after the Nov. 1, 2001 WG telephone conference.
Revision 0.8
December 18, 2001
Reflects changes made through the December, 2001 IVI Meeting and immediately after.
Revision 0.9
February 7, 2002
Reflects changes made through the February 7, 2002 telephone conference. Sections 1-23 are completely reviewed, ready for C API to be added.
Revision 0.91
March 20, 2002
C API was added in previous version. General cleanup..
Revision 0.92
April 16, 2002
New section for general C functions. Return codes sections added.
Revision 1.0vc1
April 29, 2002
Version for initial two week review.
Revision 1.0vc2
May 15, 2002
Changes made from two week review.
Revision 1.0vc
June 11, 2002
Changes made after two week review.
Revision 1.0
November 7, 2002
Approved.
IVI Foundation
11
IVI-3.5: IVI Configuration Server Specification
1. Overview of the IVI Configuration Server Specification This document describes the IVI Configuration Server that is provided by the IVI Foundation. Following the introduction, the general capabilities of the system are listed. The top-level architecture design is given with a component diagram and terminologies used. Capabilities of major components in the architecture are also described. Detailed descriptions of all the interface properties and functions follow. A sample use scenario diagram is then given. Next, the requirements on clients that use the IVI Configuration Server in a system are listed.
1.1
Introduction The IVI Configuration Server is the run-time module that is responsible for providing system database services to IVI based measurement system applications. Specifically, it provides system initialization and configuration information. The IVI Configuration Server is used by several of the IVI compliant modules. For instance, the Configuration Server indicates which physical instrument and IVI driver will be used by a particular application to provide a particular measurement capability. Since a typical system intermixes instruments and drivers from multiple vendors this system configuration service needs to be accessed in a vendor independent fashion. Therefore, the IVI Configuration Server is an IVI shared component (that is, the code is owned by the IVI Foundation). The IVI Configuration Server is provided by the IVI Foundation because the architecture requires a single Configuration Server be installed on any system, therefore having a single shared implementation eliminates potential conflicts from divergent implementations. The IVI Configuration Server is a single executable and one or more XML configuration stores (databases) made up of the following basic components: • The physical database (known as the configuration store). A physical configuration store is a single XML file. APIs are available to read and write the data to arbitrary files, thus providing complex applications with the ability to directly manage system configurations. • The API (and its implementation) used to read information from the configuration store(s). The IVI modules typically use this API when they are instantiated and configured. • The API (and its implementation) to write information to the configuration store(s). This API is typically used by GUI or other applications that set up the initial configuration. • The API (and its implementation) used to bind an instance of the Configuration Server code to a particular copy of the configuration information stored on a system. This includes appropriate algorithms for gaining access to the master configuration store.
1.2
Typical Use Scenario of the Configuration Server The following example illustrates the typical operations conducted with the IVI Configuration Server. 1.
Various instrument drivers are installed on the system. As each instrument driver is installed on the system, its installation script makes entries in the configuration store that indicate the location of the driver, its ProgID, a list of instruments it supports, and the interfaces it provides to its client. This entry is known as a SoftwareModule because it describes the software module (in this case, an instrument driver) that was installed. Software module developers determine what happens at installation time, and are the primary actors at this step.
2.
A user configuring the system makes entries in the configuration store that indicate a logical name for each instrument service they will be using. Then, the user associates a specific instrument and driver with each logical name. Note that the physical instrument is primarily identified by its I/O address. The driver is entered as a reference to a SoftwareModule entry that was created by the driver installation. In addition, the user may provide information regarding the default behavior of the instrument. This step will typically be completed with the aid of a configuration utility, however a configuration utility is beyond the scope of the IVI specifications. Users determine how the software modules are configured, and are the primary actors at this step.
IVI-3.5: IVI Configuration Server Specification
12
IVI Foundation
3.
For COM software modules, when the user’s application runs, it instantiates the IVI-COM Session Factory (refer to IVI-3.6, COM Session Factory Specification). The user application then calls CreateDriver() passing it the logical name they defined in the configuration step. The factory then instantiates the software module and configures it based on the entries provided in step 2. The user is the primary actor at this step.
The benefit of this use scenario is that the user’s program is entirely de-coupled from the configuration information. It is therefore possible to modify the configuration information provided in step 2 above without ever modifying the actual program that invokes and uses the driver. The benefit is that an instrument with a class-compliant driver can replace another class-compliant driver in an existing system, with no code changes made to the user application program. This pattern of associating configuration information with a logical name, and thus allowing a system to be re-configured without code changes is known as an abstract factory pattern and has other applications within the IVI architecture. For instance, IVI-MSS role control modules make similar use of the IVI Configuration Server. The IVI Configuration Server also allows users to associate arbitrary information with software modules and logical names. This can be useful when there is additional configuration information that is needed by the application. The IVI Configuration Server defines several fields specifically for use with instrument driver sessions.
1.2.1 Repeated Capabilities In many instruments there are capabilities that are duplicated either identically or very similarly across the instrument. Such capabilities are called repeated capabilities. The IVI class-compliant APIs represent repeated capabilities by a parameter that indicates which instance of the duplicate capability this function is intended to access. The IVI C APIs include this parameter as an additional parameter to function calls. The IVI COM APIs may do the same, or may also use this parameter as an index into a repeated capability collection. The IVI Configuration Server provides a way for software modules to publish the functionality that is duplicated and the strings that the software module recognizes to access the repeated capabilities. The IVI Configuration Server also provides a way for the client to supply aliases for the physical identifiers recognized by the drivers. Since many instruments have numerous instances of repeated capabilities, the IVI Configuration Server provides a way to represent the repeated capabilities as a range of identifiers instead of a large number of individual identifiers. One repeated capability may also be related to another repeated capability in a hierarchical parent/child relationship. The child repeated capabilities in these relationships are called nested repeated capabilities. The IVI Configuration Server provides a way to model these relationships.
1.3
References Several other documents and specifications are related to this specification. These other related documents are the following:
1.4
•
IVI-3.1: Driver Architecture Specification
•
IVI-3.2: Inherent Capabilities Specification
•
IVI-3.4: API Style Guide
•
IVI-3.6: COM Session Factory Specification
Definitions of Terms and Acronyms Terms of general interest are defined in IVI-5.0: Glossary.
IVI Foundation
13
IVI-3.5: IVI Configuration Server Specification
Symmetrical Repeated Capability – A repeated capability where each instance of a repeated capability has identical capabilities to all of the other instances.
1.5
Implementation The IVI Foundation supplied implementations of the IVI Configuration Server and IVI Session Factory are available from the IVI Foundation web site. These are packaged with the other IVI Foundation shared components as part of the shared component installation package.
IVI-3.5: IVI Configuration Server Specification
14
IVI Foundation
2. IVI Configuration Server Design The IVI Configuration Server is based on an object oriented UML (Unified Modeling Language) design. The Configuration Server data is stored as an XML configuration store file that closely follows the design of the Configuration Server.
2.1
UML Design The IVI Configuration Server design is most easily understood by considering the class diagram for the API. The XML data structure closely follows the structure of the API. The UML class diagram is shown in Figure 2-1. In the diagram, a rectangle represents a class. A dotted line indicates class inheritance, with the triangle pointing to the inherited interface. Note that IviConfigComponent and IviDataComponent are both abstract base classes, and are never implemented directly by the Configuration Server. Although it is a base class, IviSession is not abstract, and is directly implemented. The dashed and solid lines are references from the class at the tail of the arrow to the class at the head of the arrow. For each reference, it is assumed that the class at the tail of the arrow contains a reference property (a property that returns a reference to another object) named by the text at the head of the arrow. Collection classes are implied by the UML diagram wherever there is a relationship (indicated by a solid line) with an ordinality of 0..* or 1..* at the head of the arrow. For example, the IviLogicalNames collection class is implied by the Logical Names relationship between IviConfigStore and IviLogicalName. The IviConfigStore class includes a reference property named “LogicalNames” which references an IviLogicalNamesCollection object, which manages a collection of zero or more references to IviLogicalName objects. The Name property uniquely identifies an object in a collection. Refer to section 4, Collections, for more information about Configuration Server collections. A heavy dashed line represents a reference to a global collection of all of the objects in a global class (refer to the next section). A solid line represents other references.
2.2
Types of Classes and Objects Every instance of an IVI Configuration Server has exactly one instance of the IviConfigStore class. This object is instantiated by users who request an instance of the IVI Configuration Server. Users can navigate to all of the other objects in the configuration store from this object. There are six “global” classes – IviLogicalName, IviHardwareAsset, IviSoftwareModule, IviPublishedAPI, IviSession, and IviDriverSession. Objects in these classes may be referenced from any object in the configuration server that implements a corresponding reference property. All of the objects of a global class are unique (by Name), except Published APIs, within the entire Configuration Server. Published APIs are differentiated by version as well as Name. For example, all of the software module objects in the configuration server have a unique Name. There are six global collections in the configuration store, one for each global class. All of the objects of a global class are part of the corresponding global collection. The global collections are referenced by the main IviConfigStore object. Although an object in a global collection may be referenced by other objects, it exists independently of those other objects. When the referencing object is deleted, the global object is not necessarily deleted. In fact, with one exception. it may only be deleted when there are no outstanding references to it in the configuration server. For example, a session may reference a hardware asset, but the hardware asset is not necessarily deleted when the session is deleted. The hardware asset may only be deleted from the global collection when there are no sessions or driver sessions that refer to it.
IVI Foundation
15
IVI-3.5: IVI Configuration Server Specification
IviConfigComponent +Name : string(idl) +Description : string(idl)
+HardwareAssets
+SoftwareModule
IviHardwareAsset
0..*
0..1
+IOResourceDescriptor : string(idl)
+HardwareAsset 0..1
IIviComponentIdentity IviSession
+Session
IviConfigStore +ActualLocation : string(idl) +Description : string(idl) +MasterLocation : string(idl) +Name : string(idl) +ProcessDefaultLocation : string(idl) +Revision : string(idl) +SpecificationMajorVersion : string(idl) +SpecificationMinorVersion : string(idl) +Vendor : string(idl)
IviSoftwareModule +ModulePath : string(idl) +Prefix : string(idl) +ProgID : string(idl) +SupportedInstrumentModels : string(idl)
+Software Module Name : string(idl)
0..1
+SoftwareModules 0..*
IviLogicalName +Name : string(idl) +LogicalNames +Description : string(idl)
+Sessions 0..*
0..*
+Deserialize() +GetDriverSession() +GetSession() +Serialize()
IviDriverSession
+DriverSessions
+Cache : boolean(idl) +DriverSetup : string(idl) +InterchangeCheck : boolean(idl) +QueryInstrStatus : boolean(idl) +RangeCheck : boolean(idl) +RecordCoercions : boolean(idl) +Simulate : boolean(idl)
0..*
+PhysicalNames 0..* +VirtualNames 0..* IviVirtualName
IviPhysicalName
+MapTo : string(idl) +Name : string(idl)
+Name : string(idl) +RCName : string(idl)
+PublishedAPIs +PublishedAPIs 0..* +Description : string(idl) +HelpContextID : long(idl) +HelpFilePath : string(idl) +Name : string(idl) +ReadOnly : boolean(idl) +SoftwareModuleKey : string(idl) +Type : string(idl) +UsedInSession : string(idl)
+VirtualRanges 0..*
IviPublishedAPI
IviDataComponent
IviReal
+PhysicalNames 0..*
0..*
+DataComponents 0..*
+Name : string(idl) +Type : string(idl) +MajorVersion : long(idl) +MinorVersion : long(idl)
IviVirtualRange +Max : long(idl) +Min : long(idl) +Name : string(idl) +StartingPhysicalIndex : long(idl)
1..*
+PublishedAPI 1
IviString +Value : string(idl)
IviInteger
IviStructure
+Units : string(idl) +Value : long(idl)
IviBoolean
IviPhysicalRange +Max : long(idl) +Min : long(idl) +Name : string(idl)
+DataComponents
+Units : string(idl) +Value : double(idl)
+Value : boolean(idl)
+PhysicalRanges 0..*
Configuration Server UML Class Diagram
IviAPIReference +Value : string(idl)
Figure 2-1 - IVI Configuration Server UML Class Diagram The “exception” to this rule is the relationship from session to software module. A software module may be deleted when there are still sessions that reference it. In this case, the session cannot reference an IVI Software Module object, but it does “remember” the name of the software module that it referenced, and if IVI-3.5: IVI Configuration Server Specification
16
IVI Foundation
a software module with the same name is ever re-added to the configuration store, a reference from the session to that software module is recreated. The other classes (including other collection classes) are “contained” classes. Contained objects in these classes are not global, and are unique and meaningful only in the context of a “containing” object that contains a reference to a collection of the “contained” objects. Contained objects do not exist independently of the containing object, and are deleted when the containing object is deleted. For example, all of the Data Component objects referenced by a software module are unique to that software module, and must be deleted when the software module is deleted. This implies that software modules cannot share Data Component objects – each software module requires a duplicate Data Component for identical configuration variables. Note that the Software Module class references a collection of Published APIs. This collection is not a global collection. It is “contained” in the software module that references it, and is deleted when the software module is deleted. However, the Published API objects that are referenced by the collection are not deleted, since they are also in the global Published API collection.
2.3
Notation In the descriptions of each class that follow, • API methods are identified as such. • API properties that do not reference another object are followed by the basic type (Boolean, string, long, or double) and an indication of whether the property is read-only (R/O), write-only (W/O), or both (R/W). If the property is a string, Optional indicates that the string may be empty. It is assumed that longs, doubles, and Booleans must always have a valid value. All strings must be legal XML strings, since the configuration store is an XML file. • API properties that reference an object are followed by the type of the object, and an indication of whether the reference is optional (0..1) or required (1). If the reference is optional, the property returns a NULL pointer if there is no reference. • API properties that reference a collection object are followed by the type of the collection, and an indication of whether the collection may be empty (0..*) or not (1..*).
2.4
IVI Configuration Store The IviConfigStore class contains the following references, properties, and methods. • Driver Sessions (Collection of IviDriverSession, 0..*) – The global collection of references to all of the IVI Driver Session objects in the configuration store. • Hardware Assets (Collection of IviHardwareAsset, 0..*) – The global collection of references to all of the IVI Hardware Asset objects in the configuration store. • Logical Names(Collection of IviLogicalName, 0..*) – The global collection of references to all of the IVI Logical Name objects in the configuration store. • Published APIs (Collection of IviPublishedAPI, 0..*) – The global collection of references to all of the IVI Published API objects in the configuration store. • Sessions (Collection of IviSession, 0..*) – The global collection of references to all of the IVI Session objects in the configuration store. • Software Modules(Collection of IviSoftwareModule, 0..*) – The global collection of references to all of the IVI Software Module objects in the configuration store. • Actual Location (String, optional, R/O) – The full pathname of the IVI configuration store file that was deserialized by the current instance of the configuration server. • Description (String, required, R/W) – The description of the configuration store. • Master Location (String, optional, R/O) – The full pathname of the master IVI configuration store file. • Name (String, required, R/O) – The name of the component – “IVI Configuration Server”. • Process Default Location (String, required, R/W) – The full pathname of the IVI configuration store file to be used by the current process. • Revision (String, required, R/O) – The revision of this version of the Configuration Server. Will match the version reported by the DLL’s file version resource. Refer to Section 5.1, IVI-COM Interface Versioning, of IVI-3.4: API Style Guide for more details. • Specification Major Version (Long, R/O) – The major version of the IVI Configuration Server specification to which this version of the Configuration Server complies.
IVI Foundation
17
IVI-3.5: IVI Configuration Server Specification
• • • • • •
2.5
Specification Minor Version (Long, R/O) – The minor version of the IVI Configuration Server specification to which this version of the Configuration Server complies. Vendor (String, required, R/O) – “IVI Foundation, Inc.” Deserialize() (method) – Deserializes an instance of a configuration store into the Configuration Server. Get Driver Session() (method) – Given a name, navigates the Configuration Server’s logical name collection and driver session collection to find the corresponding IVI Driver Session. Get Session() (method) – Given a name, navigates the Configuration Server’s logical name collection and session collection to find the corresponding IVI Session. Serialize() (method) – Serializes the configuration store data in Configuration Server memory out to a configuration store file.
IVI Configurable Components The IVI Configuration Server is organized around a series of IVI Configurable Components – classes that inherit from the IVI Configurable Component abstract base class. This class allows the addition of custom properties to any class that inherits from it, as well as the common Name and Description properties. Although it is legitimate to define additional IVI Configurable Components, the IVI Foundation only specifies the semantics of three classes derived from IVI Configurable Component. • IVI Software Module • IVI Session (and IVI Driver Session through inheritance) • IVI Hardware Asset
2.5.1 IVI Configurable Component The IVI Configurable Component class contains the following references and properties: • Data Components (Collection of IviDataComponent, 0..*) – An optional collection of references to additional properties that may be added to any configurable component by its owner. • Name (String, required) – This is a human readable name for this component. Name may be any valid string, but is used as a key or index value in collections. Therefore, Name must be unique within collections of like objects. • Description (String, optional) - This is a human readable description of this component. Description may be any valid string.
2.5.2 IVI Software Module The IVI Software Module class contains information that describes a software component installed on the system. This component only contains information relevant to the installed software module, it does not contain information that is associated with a running instance. IVI Software Module inherits from IVI Configurable Component. In addition to the properties inherited from IVI Configurable Component, the IVI Software Module class contains the following properties: • Module Path (String, required for IVI-C) – For IVI-C software modules, the full pathname or simple filename of the software module DLL. ModulePath and ProgID may both have a valid, non-empty, string value. • Prefix (String, optional) – The prefix (IVI-C) or identifier (IVI-COM ) of the software module. • ProgID(String, required for IVI-COM) – For IVI-COM software modules, the version independent ProgID of the registered software module. ModulePath and ProgID may both have a valid, non-empty, string value. • Supported Instrument Models (String, optional) - A comma separated list of supported instrument models. Required for IVI specific instrument drivers. • Published APIs (Collection of IviPublishedAPI, 0..*) – The collection of references to the IVI Published API objects implemented by the software module. • Physical Names (Collection of IviPhysicalName, 0..*) – The collection of references to the IVI Physical Identifier objects implemented by the software module. This collection describes information about the repeated capabilities names implemented by the software module. Refer to Section 2.9, Repeated Capabilities, for more information.
IVI-3.5: IVI Configuration Server Specification
18
IVI Foundation
2.5.3 IVI Session and IVI Driver Session The IVI Session class describes how an instance of IVI Software Module will be configured. The IVI Driver Session class defines an additional set of properties for use by IVI instrument drivers. The Ivi Driver Session class inherits from the Ivi Session class. IVI Session inherits from IVI Configurable Component. In addition to the properties inherited from IVI Configurable Component, the IVI Session class contains the following references: • SoftwareModule (Reference to IviSoftwareModule, 0..1) – A reference to the IVI Software Module object that is being configured by this session. • HardwareAsset (Reference to IviHardwareAsset, 0..1) – A reference to the IVI Hardware Asset object to be used by the configured software module. • VirtualNames (Collection of IviVirtualName, 0..*) – The collection of references to the IVI Virtual Name objects defined by the session. This collection describes information about the repeated capabilities names that can be used as aliases by the software module. Refer to Section 2.9, Repeated Capabilities for more information. • SoftwareModuleName (String, optional, R/O) – The name of the current or most recently referenced software module referenced by the Software Module property. In addition, the IVI Driver Session class contains the following properties. Refer to IVI-3.2, Section 5 for exact details. • Cache (Boolean) – If TRUE, drivers that support state caching will initially enable that feature. Default is FALSE. • DriverSetup (String, optional) – The content of this string is dependent on the software module associated with the driver session. The software module knows how to interpret the string. • InterchangeCheck (Boolean) – If TRUE, drivers that support interchangeability checking will initially enable that feature. Default is FALSE. • QueryInstrumentStatus (Boolean) – If TRUE, drivers will initially enable querying instrument status. Default is FALSE. • RangeCheck (Boolean) – If TRUE, drivers that support extended range checking will initially enable that feature. Default is FALSE. • RecordCoercions (Boolean) – If TRUE, drivers that support recording of coercions will initially enable that feature. Default is FALSE. • Simulate (Boolean) – If TRUE, drivers will initially enable simulation. Default is FALSE.
2.5.4 IVI Hardware Asset The IVI Hardware Asset class contains the I/O Address of a particular hardware asset. The form of this address is dependent on the underlying I/O mechanism. For IVI instrument drivers, this will commonly be a VISA Resource Descriptor string. It is valid for a session to refer to a hardware asset even if the asset is not physically at the address. However, a software module trying to use the hardware asset will be unable to establish communication with it. IVI Hardware Asset inherits from IVI Configurable Component. In addition to the properties inherited from IVI Configurable Component, the IVI Hardware Asset class contains the following property: • IOResourceDescriptor (String, optional) – The I/O Address of a particular hardware asset.
2.6
IVI Logical Name The IVI Logical Name class provides the binding between the users program and the configuration information stored in the IVI configuration store. The users program identifies which session to instantiate by passing the Name associated with a particular IVI Logical Name component to the IVI Session Factory. The IVI Session Factory instantiates a session based on the configuration in the IviSession that is referred to by the IVI Logical Name with the name specified by the user. The IVI Logical Name class contains the following reference and property: • Session (Reference to IviSession, 0..1) – A reference to an IVI Session object. • Name (String, required) – The logical name.
IVI Foundation
19
IVI-3.5: IVI Configuration Server Specification
2.7
IVI Published API A published API defines the syntax and partial semantics of a programming interface that can be used to accomplish a particular task. The semantics are specified in sufficient detail to describe the task to be done, but enough semantics are left unspecified to leave room for a reasonable variety of implementations. Published APIs defined by the IVI Foundation have names that begin with “Ivi”. For IVI drivers, examples of published APIs are the inherent interfaces (named IviDriver) and the class-compliant interfaces (named IviDmm, IviScope, etc.). The names of IVI driver published APIs are defined by the IVI Foundation. For IVI-MSS, published APIs are the defined MSS measurement interfaces. For example, a phase noise measurement API defined by the IVI Foundation might be called IviMssPhaseNoise. Published APIs defined outside of the IVI Foundation shall not have names that begin with “Ivi”. For example, a phase noise measurement API defined by a T&M company might be called “TMCoPhaseNoise”, where “TMCo” is the T&M company that developed the API. The IVI Published API class contains the following properties: • Name (String, required) – The name of the published API. • Type (String, required) – The syntactical type of the API. Predefined values are “IVI-COM” for COM interfaces that conform to IVI-3.4: Style Guide and “IVI-C” for C interfaces that conform to IVI-3.4 Style Guide. One of these values must be used for all IVI defined APIs. Other values may be used if appropriate for other types of APIs. • MajorVersion (Long) – The major version of the published API. For APIs that are defined by IVI specifications, this is the major version of the IVI specification. • MinorVersion (Long) – The minor version of the published API. For APIs that are defined by IVI specifications, this is the minor version of the IVI specification.
2.8
IVI Data Components The IVI Data Component class provides a way to attach arbitrary data to the IVI Configurable Components – hardware assets, software modules, and sessions (including driver sessions). Data components may be used for two basic purposes • Configurable Initial Settings: Data components that define and configure initial settings for additional variables known to a software module and configured by sessions that reference the software module. • Documentation: Data components that document the configurable component itself.
2.8.1 IVI Data Component IVI Data Components are the means of customizing a configuration store’s data structure. They are used to add custom properties to IVI Configurable Components. There are six data component classes, each of which inherits from IVI Data Component. IVI Data Component is an abstract base class. This class has properties that describe the data component, as well as the common Name and Description properties. The six data component classes that inherit from IviDataComponent are: • IVI Structure • IVI Boolean • IVI Real • IVI Integer • IVI String • IVI API Reference The IVI Data Component class contains the following properties: • Name (String, required) – A human readable name for this component. Name may be any valid string, but is used as a key or index value in collections. Therefore, Name must be unique within collections of DataComponents. • Description (String, optional) - A human readable description of this component. Description may be any valid string. • HelpContextID (Long) – The context ID of the help topic for this data component. IVI-3.5: IVI Configuration Server Specification
20
IVI Foundation
• •
• • •
HelpFilePath (String, optional) – The fully qualified help file pathname for the help file in which the help topic for this data component may be found. ReadOnly (Boolean) - Indicates a restriction in the client’s permission to change the value of this data component. The IVI Configuration Server attaches no significance to this property and does not enforce any protocol regarding write access to data components. This property is primarily guidance for configuration utilities. SoftwareModuleKey (String, optional) – A string that is meaningful to the software module that identifies the data component or type of data component to the software module. Type (String, optional) - Contains a string that indicates which type of IVI Data Component this is. It will accurately reflect the type of this component and will contain one of the following values, “Structure”, “Boolean”, “Real”, “Integer”, “String”, or “APIReference”. UsedInSession (String) – Indicates whether or not a data component associated with a software module must be copied (UsedInSession = “Required”), may be copied (UsedInSession = “Optional”), or may not be copied (UsedInSession = “None”) to any associated sessions. When associated with a hardware asset, UsedInSession is always “None”.
The values of some properties are determined at least partially by what type of configurable component the data component is associated with, and the purpose of the data component.
Hardware Asset Software Module Session/Driver Session
Configurable Initial Settings N/A UsedInSession = “Required”\”Optional” ReadOnly = True UsedInSession = “Required”\”Optional” ReadOnly = False
Documentation UsedInSession = “None” SoftwareModuleKey = “” UsedInSession = “None” SoftwareModuleKey = “” UsedInSession = “None” SoftwareModuleKey = “”
2.8.2 IVI Structure The IVI Structure data component references a collection of data components. This allows the creation of complex structures. In addition to the properties inherited from IVI Data Component, the IVI Structure class contains the following property: • DataComponents (Collection of IviDataComponent, 1..*) – A collection of references to the IVI DataComponents. This collection defines a child structure of data components. Using this class, hierarchies of data components can be defined.
2.8.3 IVI Boolean This class provides Boolean data in data components. In addition to the properties inherited from IVI Data Component, the IVI Boolean class contains the following property: • Value (Boolean) – Boolean data associated with this data component. Must be TRUE or FALSE.
2.8.4 IVI Real This class provides real data in data components. In addition to the properties inherited from IVI Data Component, the IVI Real class contains the following properties: • Value (Double) – Real data associated with this data component. • Units (String, optional) – Units associated with the number.
2.8.5 IVI Integer This class provides integer data in data components. IVI Foundation
21
IVI-3.5: IVI Configuration Server Specification
In addition to the properties inherited from IVI Data Component, the IVI Integer class contains the following properties: • Value (Long) – Integer data associated with this data component. • Units (String, optional) – Units associated with the number.
2.8.6 IVI String This class provides string data in data components. In addition to the properties inherited from IVI Data Component, the IVI String class contains the following property: • Value (String, optional) – String data associated with this data component.
2.8.7 IVI API Reference This class provides a way for data component structures to reference published APIs. The Name property identifies the instance of the published API known by the software module. This data component is designed for use by IVI Software Modules and IVI Sessions. In addition to the properties inherited from IVIi Data Component, the IVI String class contains the following property: • PublishedAPI (Reference to IviPublishedAPI, 1) – A reference to an IVI Published API object to be used by the configured software module. • Value(String,optional) – A logical name or session name. Value can be passed to GetSession() or GetDriverSession() in the Name parameter. A session reference is returned according to the semantics defined for GetSession() and GetDriverSession().
2.9
Repeated Capabilities Standard ways of referencing repeated capabilities in IVI software module APIs are described in several sections of IVI-3.1, Driver Architecture Specification, and Section 12, Repeated Capabilities, of the IVI3.4: API Style Guide. Most IVI instrument class APIs include some repeated capabilities.
2.9.1 Repeated Capabilities in the Configuration Server The IVI Configuration Server provides a way for software modules to publish their repeated capabilities and the physical identifiers that a client may use to access them. Software Modules use the IviPhysicalName and IviPhysicalRange classes for this purpose. The IVI Configuration Server also provides a way for clients to configure instances of software modules for the client’s use. As part of this configuration, clients specify virtual identifiers that the software module will recognize as aliases for the physical identifiers provided by the software module. Clients use the IviVirtualName and IviVirtualRange classes for this purpose.
2.9.2 IVI Physical Name and IVI Physical Range Software modules publish their repeated capabilities using the IVI Physical Name and IVI Physical Range classes. Together these classes specify • The repeated capabilities implemented by the software module. (Determined from the RCName property of IVI Physical Range objects.) • The repeated capability hierarchy implemented by the software module. (Determined from the PhysicalNameCollection referenced by the IVI Physical Name objects, which may be used recursively to represent a hierarchy.) • A set of physical identifiers recognized by the software module. There is exactly one physical identifier for each instance of a repeated capability implemented by the software module. (Determined from the Name property of, and the PhysicalRangeCollection referenced by, the IVI Physical Range objects.)
IVI-3.5: IVI Configuration Server Specification
22
IVI Foundation
An IVI Physical Name object defines one or more physical identifiers corresponding to one or more instances of a repeated capability. The IVI Physical Name class contains the following properties: • RCName (String, required) – The name of a repeated capability. All IVI Physical Names within the same collection that have the same RCName contribute to the definition of that repeated capability. • Name (String, required) – If there is no associated physical range, the physical identifier for an instance of a repeated capability of type RCName. If there are associated physical range(s), the prefix for a range of physical identifiers to which integers from the range(s) are appended. May be empty if there are associated physical ranges. To avoid conflicts with the use of the colon character as a separator, Name may not contain a colon. • PhysicalNames (Collection of IviPhysicalName, 0..*) – The collection of the IVI Physical Name objects for instances of repeated capabilities that are nested under the current physical identifier. • PhysicalRanges (Collection of IviPhysicalRange, 0..*) – The collection of integer ranges used to create a set of physical identifiers, as explained below. When the Physical Ranges property is not NULL, it references a collection of IVI Physical Range objects. A Physical Range object defines a range of integers between a minimum and maximum. The integers are appended to the Name property of the IVI Physical Name object to form a set of physical identifiers. If an IVI Physical Name object references a collection of IVI Physical Ranges, Name may be an empty string. This allows the range of names to be purely numeric. Also, since IVI Physical Name refers to a collection of IVI Physical Ranges, several non-contiguous ranges may be referenced. For example, a physical identifier “C” that references a collection of physical ranges 0-75, 100-175, and 200-275 yields a set of physical identifiers C0-C75, C100-C175, and C200-C275. When an IVI Physical Name references IVI Physical Range(s), and IVI Physical Name(s), the collection of IVI Physical Names (and therefore the implied hierarchy of repeated capabilities) referenced by the IVI Physical Name is assumed to be symmetrical – the same for every physical identifier in the set. In the above example, if the physical identifier “C” referenced a collection of physical identifiers consisting of “X”, “Y”, and “Z”, it would be assumed that every one of the channels C0-C75, C100-C175, and C200C275 had exactly the same set of child physical identifiers “X”, “Y”, and “Z”. For non-symmetrical nested repeated capabilities, Physical Ranges cannot be used. The IVI Physical Range class contains the following properties: • Name (String, required) – A value that uniquely identifies an IVI Physical Range object in a collection. There is no other significance to the Name field in this class. • Max (Long, required) – The maximum integer in the range. • Min (Long, required) – The minimum integer in the range.
2.9.2.1
Nested Repeated Capabilities The software module represents nested repeated capabilities by creating an instance of IviPhysicalName for the parent capability (in this example, the output power), which in turn references another instance of IviPhysicalName for the nested capabilities (in this example, the external trigger). The nesting of IviPhysicalNames can be arbitrarily deep.
2.9.2.2
Symmetrical and Asymmetrical Nested Capabilities Multiple instances of the same repeated capability may or may not share the same child repeated capabilities. If multiple instances of the same repeated capability share the same child repeated capabilities, the repeated capability tree is symmetrical. In this case, each IVI Physical Name object for that repeated capability references an identical collection of child IVI Physical Name objects. If multiple instances of the same repeated capability do not share the same child repeated capabilities, the repeated capability tree is asymmetrical. In this case, each (parent) IVI Physical Name object for that repeated capability will reference a collection of (child) IVI Physical Name objects that describe the specific child repeated capabilities for that object, and these collections may differ from one parent to the next.
IVI Foundation
23
IVI-3.5: IVI Configuration Server Specification
For example, if a driver models two displays, and both displays can display two traces, that part of the repeated capability hierarchy would be symmetrical. If a driver models two displays, and the first can display four traces, but the second can only display two, that part of the repeated capability hierarchy is asymmetrical.
2.9.3 IVI Virtual Name and IVI Virtual Range The IVI Virtual Name and IVI Virtual Range classes are used by the client to create aliases for physical identifiers and colon separated lists of physical identifiers that the software module can use in context to select a repeated capability. The IVI Virtual Name class contains the following properties: • MapTo (String, required) – The string that is substituted by the software module for Name whenever it is encountered in a repeated capability selector. The empty string is a legal value for this property only if the IVI Virtual Name object references a non-empty collection of IVI Virtual Range objects. • Name (String, required) – If there is no associated physical range, a virtual identifier. If there are associated physical range(s), the prefix for a range of virtual identifiers to which integers from the range(s) are appended. May be empty if there are associated virtual ranges. To avoid conflicts with the use of the colon character as a separator, Name may not contain a colon. • VirtualRanges (Collection of IviVirtualRange, 0..*) – The collection of integer ranges used to create a set of IVI Virtual Names, as explained below. An IVI Virtual Name object can also reference a collection of IVI Virtual Range objects. An IVI Virtual Range object defines a range of integers between a minimum and maximum. The integers are appended to the Name property of the IVI Virtual Name object to form a set of virtual identifiers. If an IVI Virtual Name object references a collection of IVI Virtual Ranges, Name may be an empty string. This allows the range of names to be purely numeric. Also, since IVI Virtual Name refers to a collection of IVI Virtual Ranges, several non-contiguous ranges may be referenced. For example, a virtual identifier “C” that references a collection of Virtual Ranges 0-75, 100-175, and 200-275 yields a set of virtual identifiers C0C75, C100-C175, and C200-C275. When an IVI Virtual Name has IVI Virtual Range(s), the set of virtual identifiers maps to a set of physical identifiers created by appending a series of integers to the IVI Virtual Name object’s MapTo string. The series of integers is the same size as the virtual range, but starts at the IVI Virtual Range object’s Starting Physical Index. The IviVirtualRange class contains the following properties: • Name (String, required) – A value that uniquely identifies an IVI Virtual Range object in a collection. There is no other significance to the Name filed in this class. • Max (Long, required) – The maximum integer to be appended to the virtual identifier. • Min (Long, required) – The minimum integer to be appended to the virtual identifier. • StartingVirtualIndex (Long, required) – The first integer in a range of integers to be appended to the MapTo name.
IVI-3.5: IVI Configuration Server Specification
24
IVI Foundation
3. Instantiation and execution of the IVI Configuration Server 3.1
Installing the Configuration Server The Configuration Server is installed before any IVI software modules are installed. This is enforced by the requirements for installing IVI shared components, IVI instrument drivers and IVI-MSS role control modules described in Section 6, Installation Requirements, of the IVI-3.1: Driver Architecture Specification.
3.1.1 Packaging The IVI Configuration Server installation consists of seven files. • IviConfigServer.dll – The COM server executable file. • README.txt – A file that contains misc. information about the Configuration Server installation, including standard software dependencies, additional included files, and last minute instructions. • IviConfigurationStore.xml – An empty XML configuration store file. • IviConfigurationStore.xsd – The XSL schema for the configuration store file. • IviConfigServerCapi.dll – The C API executable file • IviConfigServer.lib – Microsoft C compatible library files. • IviConfigServer.h – C header file for C API. The IVI Configuration Server implementation uses the “Microsoft XML Core Services 4.0 RTM” which is installed when the IVI Configuration Server is installed. More information on these services is available at http://msdn.microsoft.com/downloads/default.asp?url=/downloads/sample.asp?url=/msdnfiles/027/001/766/msdncompositedoc.xml. In addition, there may be other demo or test programs included – refer to the README.txt file for a complete listing of the files included in the installation.
3.1.2 Data File Installation The installation directory for the master configuration store is
3.1.3 First Installation When the Configuration Server is installed on a computer for the first time, there is only one entry in the master configuration store – the IviConfigStore entry. This entry carries component and version information, references collections of other Configuration Server objects. The component and version information is read only, and serves to identify the Configuration Server component and version. The collections referenced from the IviConfigStore object are empty. The collection methods and properties themselves may be executed, but will not return any configuration data until collection items (such as Software Modules, Hardware Assets, and so on) are added.
IVI Foundation
25
IVI-3.5: IVI Configuration Server Specification
3.1.4 Subsequent Installations When the Configuration Server is reinstalled on a system, it does not erase existing entries in the master configuration store. If the same version is being reinstalled, no changes will be made to the master configuration store. If a more recent version is being installed, there may be changes. A re-installation may update the values of the IviConfigStore Revision, Description, Specification Major Version, and Specification Minor Version as appropriate. A re-installation will also update or convert the data in the master configuration store to match any changes in the configuration store schema. If the re-installation cannot perform this task silently, a conversion utility will be provided by the IVI foundation as part of the new install, with suitable instructions. Reasonable care will be taken to ensure that the Configuration Server behavior is compatible from revision to revision, and the IVI Foundation strongly recommends that all software access the master configuration store through the Configuration Server.
3.2
Accessing the Configuration Store Users and software module developers should only access the configuration store through the Configuration Server software provided by the IVI Foundation. While it is possible to edit the configuration store XML file directly, it is discouraged because of the potential for introducing invalid data and relationships into the file. Furthermore, the Configuration Server is designed to be independent of the way the data is stored, and insulates users from potential changes in the data format. The Master Location property in the IviConfigStore class returns the full pathname of the master configuration store. It determines the name by reading the registry key HKEY_LOCAL_MACHINE/SOFTWARE/IVI/CONFIGURATIONSERVER, MasterStore. For the precise semantics, refer to Section 7.3.3, Master Location. Users may copy the master configuration store, modify it, and then save it to another file. Refer to Section 3.7, Additional Instances of the Configuration Store, for more details. Users may then designate such a file as the default copy of the configuration store for use in a process by assigning the full pathname of the file to the Process Default Location property in the IviConfigStore class. The Process Default Location property then returns the full pathname of this file. For the precise semantics, refer to Section 7.3.5, Process Default Location. The IVI configuration store provides mechanisms for accessing the master and process default configuration store files. Any utility, including Software Module installation programs, which modify the contents of the master configuration store should consider making a back up copy before serializing a modified version. The IVI Configuration Server tries to maintain the integrity of all configuration store files, but the consequences of a corrupt master configuration store are so severe that a back up could prove very valuable.
3.2.1 Master Configuration Store To access the master configuration store • Instantiate the IVI Configuration Server. • Call the Deserialize method, providing the location of the master configuration store as a parameter. This is obtained through the Master Location property. • Access the configuration data. To modify the master configuration store • Perform steps required to access the master configuration store • Call the Serialize method with the master configuration store filename as a parameter. When serializing to the master configuration store, care must be taken not to modify the data that is added when software modules are installed. For instance, deleting a software module entry could make it impossible to properly configure a driver session to access that software module. IVI-3.5: IVI Configuration Server Specification
26
IVI Foundation
3.2.2 Process Default Configuration Store To set the process default configuration store for the current process • Instantiate the IVI Configuration Server. • Set the value of the Process Default Location property to the full path name of the configuration store file to be used in the current process. To access the process default configuration store • Set the process default configuration store for the current process (see previous step). • Instantiate the IVI Configuration Server (if not already instantiated). • Call the Deserialize method, providing the location of the process default configuration store as a parameter. This is obtained through the Process Default Location property. • Access the configuration data. To modify the process default configuration store • Perform steps required to access the process default configuration store. • Call the Serialize method with the process default configuration store filename as a parameter.
3.2.3 Instantiating the Right Configuration Store From Software Modules Software modules first try to open the process default configuration store. If the Process Default Location property is not the null string, and Deserialize cannot open the process default configuration store, Deserialize returns an error, and the software module returns an error as well. If the Process Default Location property is the null string then the software module tries to open the master configuration store. If Deserialize cannot open the master configuration store, Deserialize returns an error, and the software module returns an error as well.
3.2.4 Serializing to a Different Configuration Store Users may wish to deserialize from one configuration store file and serialize to a different one. One basic example is copying a configuration store from one file to another. This is not part of the use model for driver installation or initialization.
3.3
Adding Entries to Collections There are six “global” collections in the Configuration Server. Global collections include all of the instances of a particular class. The six global collections are • Software Modules • Published APIs • Sessions • Driver Sessions • Hardware Assets • Logical Names When a new instance of one of the six associated classes is added using the Configuration Server, it is added first to the global collection. If a client tries to add it to another collection first, an error is returned. For example, if a software module adds a published API entry, it will add it to the global published APIs collection first, then add it to the Software Module’s published APIs collection.
3.4
Installing Software Modules The configuration store must contain data describing a user-configurable software module before the user can configure the session or driver session that uses it. Installation requirements for software modules, including the configuration store entries, are described in Section 6, Installation Requirements, of the IVI3.1: Driver Architecture Specification. A software module installation program creates the following types of entries in the master configuration store. • A software module entry (required). • A collection of references to published APIs (optional). If the published API entries do not exist, the software module installation program also adds the published API entry. The published API is added
IVI Foundation
27
IVI-3.5: IVI Configuration Server Specification
• • • •
to the global published API collection first, and then added to the software module’s published API collection. A collection of references to IVI Physical Names (optional). One or more collections of physical ranges, each associated with an IVI Physical Name (optional). A collection of references to data components, referenced by the software module (optional). Data components added when the software module is installed are called module-defined data components. A default session that uses the software module (optional).
The software module entry contains the information needed to create a running instance of the software module, as well as a couple of basic identification fields. This is required when IVI class drivers or the IVI Session Factory are used to instantiate an IVI specific driver. The collection of IVI Physical Names identifies the repeated capabilities as defined in the software module. Refer to Section 2.9.2, IVI Physical Name and IVI Physical Range for more information.
3.4.1 Data Components In Software Modules A software module’s data components may be used for two basic purposes – to define initial settings for variables known to the software module, and to document the software module itself.
3.4.1.1
Defining Initial Settings Software module data components may be used to document additional variables that are known by the software module, and that the software module will attempt to read from a configuration server session at run-time. For instance, the software module developer may define a Trace property that determines its tracing behavior, and decide that the software module will attempt to read an initial value for this variable from the configuration server. This variable is added to the data components of the software module when the software module is installed, to document the fact that the software module is capable of reading an initial value for it from the configuration server. There are several reasons to add this type of data component to a software module. • To provide additional configuration for driver operation. The IVI Foundation defines several properties for configuring driver operation (e.g. Cache, Simulate, InterchangeCheck, and so on), but a software module may need additional data. The Trace property mentioned above is an example of this type of data component. • To provide additional configuration for instrument operation. In some cases, an instrument cannot be used interchangeably with others in its class because of some state variable that is not part of the classcompliant interfaces, but which must be set correctly in order for the class-compliant interfaces to work correctly. For example, an instrument that by default returns measurements in terms of period when the class-compliant interface returns frequency could use a data component that allows the user to configure the instrument to measure frequency. Refer to Section 5.10.1.5, Applying Configurable Initial Settings, in IVI-3.1: Driver Architecture Specification. • To provide initial instrument state. In general, the IVI Foundation recommends against using the configuration server to store and restore instrument state. While it is possible, it is very complex and often redundant with other instrument functionality. These data components are added with UsedInSession = “Required” or “Optional” and ReadOnly = True. If UsedInSession = “Required”, the data component is copied by the configuration server to any session when the reference property from the session to the software module is set or changed. If UsedInSession = “Optional”, the configuration server will allow the data component to be added to the session.
3.4.1.2
Documenting the Software Module Data components may be added to the software module just to add information about the software module. The developer may choose to add these when the software module is installed. These data components are added with UsedInSession = “None” to indicate that that they are not to be copied to a session for configuration.
3.4.2 Un-installing Software Modules When deleting software modules, IVI-3.5: IVI Configuration Server Specification
28
IVI Foundation
• • • •
Delete collections for published APIs. Do not delete the published API entries. Delete collections and entries for physical names and ranges. Delete collections and entries for data components. Delete the software module entry.
To accomplish the above, use the Configuration Server to delete the software module entry. The Configuration Server will delete all of the above listed entries correctly. When software module entries are deleted, the sessions that reference them will not be automatically deleted. These sessions may be reusable at a later time, after the software module is installed again, or they may be reusable with another compatible software module.
3.4.3 Re-installing Software Modules When re-installing the same version of a software module, delete and re-add the following entries. • The software module entry. • Collections of published APIs. Do not delete the published API entries. • Collections and entries for physical names and ranges. • Collections and entries for data components. To accomplish the above, use the Configuration Server to delete the software module entry. The Configuration Server will delete all of the above listed entries correctly. Then the installation will add the correct entries as part of the re-install process. Re-installing is not a special feature. It may be implemented with an un-install followed by a normal install. If the default session already exists, do not delete and re-add it. If it does not exist, add it. When re-installing a different version of the software module, the above actions are taken. If the data components associated with the software module have been changed, the installer notifies the user that the older associated sessions are not compatible. (Note: what about silent installs? – log files, etc.)
3.5
Maintaining Configuration Data Users add configuration data to the configuration store. Users have several mechanisms available for maintaining configuration data, including using a proprietary configuration store editor and using the Configuration Server from user application code. Users may manually edit the configuration store files, but this is strongly discouraged. Users can configure several classes in the configuration store • IVI Hardware Assets • IVI Sessions and IVI Driver Sessions • IVI Data Components associated with an IVI Session or an IVI Hardware Asset • IVI Virtual Names and Ranges • IVI Logical Names and Ranges
3.5.1 Configuring Hardware Assets Configuration of hardware assets involves the following types of entries. • Hardware asset entries. These must be added to the global hardware assets collection before being referenced by a session or driver session. • A collection of references to data components, referenced by the hardware asset (optional). These collections and referenced data components are contained in the hardware asset. Hardware asset entries identify the location of the instrument on the I/O buses. Users must add hardware asset entries for each instrument that is available for use by a session. In the future, vendors may provide instruments that make appropriate Hardware Asset entries. There may be multiple entries with the same value for IO Resource Descriptor.
IVI Foundation
29
IVI-3.5: IVI Configuration Server Specification
The hardware asset entries are not contained by the session. In the configuration store, they exist independently of the session, and are not deleted automatically when the session entry is deleted. A hardware asset may not be deleted if a session or driver session refers to it.
3.5.1.1
Data Components in Hardware Assets Data components may be added to a hardware asset entry to further document the hardware asset. These data components are user-defined, since hardware assets are not added by software modules, with UsedInSession = “None”. These may be added with the hardware asset, or at a later time. Refer to Section 3.5.5.1, IVI Hardware Assets for more details. The hardware asset’s data components collection is contained by the hardware asset that references it, and the associated data component entries are also contained by the hardware asset. They are added with and deleted with the hardware asset entry.
3.5.2 Configuring Sessions and Driver Sessions Configuration of sessions and driver sessions involves the following types of entries. • An IVI Session (required). The session entry will be a driver session entry if the referenced software module is an IVI instrument driver. These must be added to the global sessions collection and driver sessions collection (if applicable) before being referenced by a logical name. • A collection of references to IVI Virtual Names (optional). These collections and referenced IVI Virtual Names are contained in the session. • One or more collections of IVI Virtual Ranges, each associated with an IVI Virtual Name (optional). These collections and referenced physical names are contained in the session. • A collection of references to IVI Data Components, referenced by the session (optional). These collections and referenced data components are contained in the session. An IVI Session entry is used to configure a running instance of a software module. IVI instrument drivers are configured using IVI Driver Session, which inherit from IVI Session. Because of the inheritance, driver sessions include all of the functionality associated with sessions, and in addition allow the configuration of seven additional properties that have special meaning to IVI instrument drivers. A session references an IVI Software Module. IVI class drivers and the IVI Session Factory both start with a reference to a session and examine the associated session to determine which software module to instantiate as described in Section 3.6.1, IVI Class Drivers and the IVI Session Factory. The information in the software module entry is sufficient to instantiate the software module – ProgID for IVI-COM, ModulePath for IVI-C. Both may be filled in if the same vendor provides both forms of the driver in the same installation, and one is a wrapper for the other. IVI Sessions may reference zero or one IVI Hardware Asset, but this may not be enough for some software modules that require more than one hardware reference. There are two possible ways to handle this situation. First, IO Resource Descriptor may be overloaded by using a syntax that allows multiple instrument locations to be entered. Second, data components for the additional addresses may be added to the software module entry, and carried over to the session where the values are configured. The session’s IVI Virtual Name, IVI Virtual Range, and IVI Data Components collections are contained by the IVI Session that references them, and the associated virtual name, range, and data component entries are also contained by the session. They are added with and deleted with the session entry.
3.5.2.1
Virtual Names The collection of IVI Virtual Names identifies the repeated capabilities as defined in the client, and maps these names to physical identifiers that are recognized by the software module. Refer to Section 2.9.3, IVI Virtual Name and IVI Virtual Range for more information.
3.5.3 Data Components In Sessions A session’s data components may be used for two basic purposes – to configure initial settings for additional variables known to the associated software module, and to document the session itself. IVI-3.5: IVI Configuration Server Specification
30
IVI Foundation
3.5.3.1
Configurable Initial Settings Software modules may use data components to allow configuration of software module variables at initialization. Refer to section 3.4.1.1, Defining Initial Settings for details. During initialization, the software module looks for these variables in the associated session that contains the configuration information. In order for this to work, the configuration server determines what additional variables are required when the reference to the session’s Software Module is set by examining the data components for the software module, and copies all data components with UsedInSession = “Required” to the session. When it does the copy, it changes ReadOnly to “False”. After the copy, clients may change the values of the session’s data components to the correct values, and may add data components from the associated software module where UsedInSession = “Optional”.
3.5.3.2
Documenting the Session Data components may be added to the session just to add information about the session. The developer may choose to add these when the session is created, or they may be added by a configuration utility, test system, or configuration server user. These data components are added with UsedInSession = “None” to indicate that that they are not copied from the software module.
3.5.4 Configuring Logical Names Configuration of logical identifiers involves the following types of entries. • IVI Logical Name entries that reference session entries.
3.5.5 Documentation Data Components Users or configuration utilities may add user-defined data components to hardware assets and sessions (including driver sessions). These are documentation data components, and there are no pre-defined uses for them – presumably the user or configuration utility that adds them knows why they are there.
3.5.5.1
IVI Hardware Assets Users may add data components with Used In Session = “None”, and Read Only = True or False. The data components are meaningful only to the particular user or configuration utility that added them.
3.5.5.2
IVI Sessions and IVI Driver Sessions Users may add data components with Used In Session = “None”, and ReadOnly = True or False. The data components are meaningful only to the particular user or configuration utility that added them.
3.6
Using Configuration Data The Configuration Server is used to instantiate and initialize IVI instrument drivers and IVI-MSS role control modules. Instantiation is useful for class API interchangeability, using either IVI class drivers or the IVI Session Factory. As part of the Initialize function, software modules read the configuration store and use the data to configure initial values.
3.6.1 IVI Class Drivers and the IVI Session Factory IVI class drivers and the IVI Session Factory both use the configuration store to identify and locate the IVI specific driver software module that they instantiate. The IVI Session Factory can be used to instantiate any kind of software module, including IVI-MSS role control modules. The user provides a logical name or a session or driver session name to the class driver or IVI Session Factory. This name is then used to lookup the associated session or driver session entry, and the software module reference is then used to find the software module entry. The ModulePath or ProgID is then retrieved and used to instantiate the software module. IVI class drivers and the IVI Session Factory need only use Get Session to look up the session and then the software module. However, class drivers may choose to use Get Driver Session to be sure that the name passed in actually resolves to a driver session. Get Session looks for the name first in the Configuration Server’s logical name collection. If it finds it there, it follows the reference to the session. If it doesn’t find the name in the logical name collection, it IVI Foundation
31
IVI-3.5: IVI Configuration Server Specification
tries to find a session with the given name. If it doesn’t find that, it returns an error. If Get Session finds the name in either place, it returns a pointer to the session. Get Driver Session works the same as Get Session, except it is restricted to Driver Sessions.
3.6.2 Software Module Initialization Once a software module is instantiated, it can use the Configuration Server as part of the initialization process. An IVI instrument driver accesses the Configuration Server from the Initialize function. It queries the Configuration Server for the following information. • Hardware Asset. The driver uses the IO Resource Descriptor to establish a connection to the instrument. • The predefined driver properties - Cache, Driver Setup, Interchange Check, Query Instrument Status, Range Check, Record Coercions, and Simulate. These are applied in the Initialize function. • Data components. A driver reads through the data components collection referenced by the session, looking for data component names that it recognizes. If it finds a data component that it doesn’t recognize, it ignores it and continues with the next data component in the collection. After reading through the collection, if it hasn’t retrieved the value of one or more required data components, it reports an error. • Virtual identifiers. A driver reads through the virtual identifiers collection and any associated virtual ranges. It stores the mappings for use when resolving repeated capability names. Refer to section 0, Multiple instances of the same repeated capability may or may not share the same child repeated capabilities. If multiple instances of the same repeated capability share the same child repeated capabilities, the repeated capability tree is symmetrical. In this case, each IVI Physical Name object for that repeated capability references an identical collection of child IVI Physical Name objects. If multiple instances of the same repeated capability do not share the same child repeated capabilities, the repeated capability tree is asymmetrical. In this case, each (parent) IVI Physical Name object for that repeated capability will reference a collection of (child) IVI Physical Name objects that describe the specific child repeated capabilities for that object, and these collections may differ from one parent to the next. For example, if a driver models two displays, and both displays can display two traces, that part of the repeated capability hierarchy would be symmetrical. If a driver models two displays, and the first can display four traces, but the second can only display two, that part of the repeated capability hierarchy is asymmetrical. • IVI Virtual Name and IVI Virtual Range for more details. For IVI-MSS role control modules, initialization happens whenever appropriate, as determined by the software module. Use of the hardware asset reference and virtual identifier, virtual range, and data component collections is analogous to the driver case. There are no pre-defined configuration variables for IVI-MSS that are analogous to the driver session properties.
3.6.3 Interchanging Instruments Several sessions may be set up for a software module, representing several different ways of configuring the module. Since sessions are identified by name, just changing the name in the source code that instantiates and configures the software module is enough to change the way it is configured. Different sessions can point to different hardware assets or different values for configuration properties. In order to avoid any source code changes, use logical names to refer to sessions. If the logical name is used in the client’s source code, the user can use a different session by changing the logical name’s Session property.
IVI-3.5: IVI Configuration Server Specification
32
IVI Foundation
3.7
Additional Instances of the Configuration Store As mentioned above, it is possible to have multiple instances of the configuration store file. There is one master configuration store file on each system, but there may be additional configuration store files. The Process Default property can be set to the full pathname of any configuration store file. The Deserialize method may be called with any full pathname. Deserialize will return an error if the file is not a legal Configuration Store file and cannot be successfully deserialized. Likewise, Serialize may be called with any full pathname, and will return an error if the file cannot be written. Software module installers create entries only in the master configuration store. To create or maintain additional configuration store files, users must copy software module entries using the Configuration Server or use a configuration utility. Users must be careful not to delete the master configuration store’s software module entries, or to make modifications that would destroy the accuracy of the software module entries. This holds not only for the software module entry itself, but also for any associated data components, physical identifiers, or ranges.
3.8
Avoiding the Configuration Server Users can avoid having to interact with the IVI Configuration Server and Store with most IVI specific instrument drivers and many other IVI software modules. In order to avoid interacting with the Configuration Server for IVI specific instrument drivers, • The application program must explicitly specify the location of the IVI-C DLL, or the ProgID of the IVI-COM class. • The Resource Name parameter of the Initialize function must be an IO resource descriptor, rather than a logical name or a session name. • The application program must use the physical identifiers defined in the driver for repeated capabilities. • Either the application program must use the software module’s defaults for configurable attributes, or the application program must set the driver’s attributes to initial values before the attributes are used in the driver. Note that adequate defaults are defined for all of the driver session properties in IVI-3.2: Inherent Capabilities Specification.
3.9
Copying Elements In general, the IVI Configuration Store does not automatically copy data from one element to another. The user is responsible for getting the information from one element and then writing it into the second element. The one exception happens when a Session’s reference to a Software Module is set. Refer to Section 3.5.3.1, Configurable Initial Settings.
IVI Foundation
33
IVI-3.5: IVI Configuration Server Specification
4. Collections The configuration store design makes extensive use of collections of objects from a single class. For instance, the Configuration Store class includes a pointer to a collection of all of the IviHardwareAsset objects in the Configuration Store. All collections are one based. The smallest legal index is one which refers to the first item in the collection. The IVI Configuration Server returns the “Not in Global Collection” error when a reference is made to an element before the element is added to the global collection. For example, a Software Module must be added to the Software Modules collection before the reference in a Session can be set to that Software Module. The same element cannot be added to two collections in the same or different configuration stores. A second separate element with identical values can be used. The only exception is that a Published API can be added to the global Published APIs collection and to the Published APIs collection in a Software Module.
4.1
Collections in COM In COM the designed collections are implemented as standard COM collections. Collection classes are indicated by appending “Collection” to the end of the class that describes the individual objects in the collection. For instance, if a collection points to objects of class IviHardwareAsset, the collection class would be named IviHardwareAssetCollection. The methods implemented by a COM collection are • Item • Count • _NewEnum • Add • Remove All of the above properties and methods have standard COM definitions. Refer to Microsoft documentation for more details. Except for the Published API collection, the Item property and Remove method take one parameter whose type is VARIANT. The contents of the VARIANT may be either the name of an item in the collection or an integer which is the one-based index of an item in the collection. For the Published API collection, the parameters for Item and Remove are described in Section 7.2.4, Published APIs. The _NewEnum property returns an IUnknown pointer. This interface can be queried for an IEnumVARIANT interface which contains the methods: • Next • Skip • Reset • Clone The VARIANT returned by Next can be queried for an interface appropriate for the collection. For example the VARIANT returned within the Hardware Asset Collection can be queried for the IviHardwareAsset interface. All of the above properties and methods have standard COM definitions. Refer to Microsoft documentation for more details. The configuration server implements the following collection classes • IviHardwareAssetCollection • IviSessionCollection • IviDriverSessionCollection • IviPublishedAPICollection
IVI-3.5: IVI Configuration Server Specification
34
IVI Foundation
• • • • • • •
4.2
IviLogicalNameCollection IviSoftwareModuleCollection IviPhysicalNameCollection IviVirtualNameCollection IviPhysicalRangeCollection IviVirtualRangeCollection IviDataComponentCollection
Collections in C In C, collections are accessed with generic functions defined for each class. These functions correspond to methods described for COM collections. • • • • •
IviConfig_Get
where
IviConfig_Create
To create a new item and add it to a collection, use the IviConfig_Create
4.3
Properties in C In C, properties for the various objects are accessed using generic functions defined for each class. These function, which correspond to the get and put COM methods are: • •
IviConfig_Get
where
IVI Foundation
35
IVI-3.5: IVI Configuration Server Specification
4.4
Return Codes The IVI-3.2: Inherent Capabilities Specification defines general status codes that the collection functions can return. The table below specifies additional IVI configuration server status codes for the Add function. Completion Codes
Description
Not In Global Collection
The item does not exist in the global collection.
Duplicate Entry
An entry with name already exists.
Invalid Data Component
The data component is not a valid data component.
The table below specifies additional IVI configuration server status codes for the Item and Remove functions. Completion Codes Does Not Exist
Description The item does not exist in the collection.
The table below specifies additional IVI configuration server status codes for the Remove function. Completion Codes Reference Still Exists
Description The element cannot be removed from the global collection when it is referenced in the local collections.
The table below specifies additional IVI configuration server status codes for the Get and Set IVI-C functions. Completion Codes Invalid Property ID
IVI-3.5: IVI Configuration Server Specification
Description The specified property ID is not valid for this function.
36
IVI Foundation
5. C API Special Functions 5.1
C API Special Functions Overview This section defines special functions for the IVI Configuration Server C API in addition to the functions defined for each IVI Configuration Server class. These functions are used to create an instance of the configuration server, dispose handles to IVI Configuration Server objects, and to retrieve and clear error codes and messages.
5.2
C API Special Functions The IVI Configuration Server C API defines the following functions: • Clear Error • Close • Dispose Handle • Get Error • Initialize This section describes each function.
IVI Foundation
37
IVI-3.5: IVI Configuration Server Specification
5.2.1 Clear Error Description This function clears the error description for the current thread of execution. The Configuration Server C API logs its errors to the thread-local error variables defined by IVI-3.9 C Shared Component Specification. The Get Error function retrieves and clears these thread-local variables. For more information about thread local variables, refer to IVI-3.9 C Shared Component Specification, Section 7, Thread Local Error Storage for more information. COM Method Prototype N/A
C Function Prototype ViStatus _VI_FUNC IviConfig_ClearError ();
Return Values The IVI-3.2: Inherent Capabilities Specification defines general status codes that this function can return.
IVI-3.5: IVI Configuration Server Specification
38
IVI Foundation
5.2.2 Close Description This function releases the handle to an IVI Configuration Store object. Once a handle to the IVI Configuration Store object is no longer needed, the user must call this function to release the handle. Subsequent use of this handle will return the Invalid Handle error. An application must release all IVI Configuration Store handles by calling this function before terminating. Failure to do so may result in resource or memory leaks. COM Method Prototype N/A
C Function Prototype ViStatus _VI_FUNC IviConfig_Close (IviConfigStoreHandle ConfigStoreHandle);
Return Values The IVI-3.2: Inherent Capabilities Specification defines general status codes that this function can return.
IVI Foundation
39
IVI-3.5: IVI Configuration Server Specification
5.2.3 Dispose Handle Description This function releases the handle to an IVIConfigStore object returned from one of the Get Session, Get Driver Session, Get Collection, Create, Add Reference, Get Item, or Get Reference functions. Once a handle to an item is no longer needed, the user must call this function to release the handle. Subsequent use of this handle will return the Invalid Handle error. An application must release all handles by calling this function before terminating. Failure to do so may result in resource or memory leaks. The user must not pass a handle of type IviConfigStoreHandle as the value of the Handle parameter. The user may pass a handle of any other type. If a handle of type IviConfigStoreHandle is passed as the value of the Handle parameter, this function will return the Invalid Handle error. COM Method Prototype N/A
C Function Prototype ViStatus _VI_FUNC IviConfig_DisposeHandle (IviConfigHandle Handle);
Return Values The IVI-3.2, Inherent Capabilities Specification defines general status codes that this function can return. In addition, it returns the following status codes: Completion Codes Invalid Handle
IVI-3.5: IVI Configuration Server Specification
Description The specified handle is invalid or of an incorrect type.
40
IVI Foundation
5.2.4 Get Error Description This function retrieves and clears the description of the last error that occurred for the current thread of execution. One exception exists: If the BufferSize parameter is zero, the function does not clear the error description. By passing 0 for the buffer size, the caller can ascertain the buffer size required to get the entire error description string and then call the function again with a sufficiently large buffer. The function complies with the rules in IVI-3.2, Inherent Capabilities Specification, Section 3.1.2.1, Additional Compliance Rules for C Functions with ViChar Array Output Parameters. The Configuration Server C API logs its errors to the thread-local error variables defined by IVI-3.9 C Shared Component Specification. The Clear Error function clears these thread-local variables. For more information about thread local variables, refer to Section 7, Thread Local Error Storage in IVI-3.9 C Shared Component Specification for more information. COM Method Prototype N/A
C Function Prototype ViStatus _VI_FUNC IviConfig_GetError (ViInt32 BufferSize, ViChar ErrorDescription[]);
Return Values The IVI-3.2: Inherent Capabilities Specification defines general status codes that this function can return.
IVI Foundation
41
IVI-3.5: IVI Configuration Server Specification
5.2.5 Initialize Description This function creates and returns a handle to a new instance of the IVI Configuration Store class. The user passes this handle to the C API functions defined for the IVI Configuration Store class to access its properties and to obtain handles to the IVI configuration store global collections. This function may also perform additional initialization routines required for the use of the IVI Configuration Server C API. The user must first call this function before calling any other C API function. Every subsequent call to this function will create a new instance of the IVI Configuration Store class. The user must call the Close function once and only once for each successful call to the Initialize function. Refer to Section 1.1.5 Close for more information. COM Method Prototype N/A
C Function Prototype ViStatus _VI_FUNC IviConfig_Initialize (IviConfigStoreHandle* ConfigStoreHandle);
Return Values The IVI-3.2: Inherent Capabilities Specification defines general status codes that this function can return.
IVI-3.5: IVI Configuration Server Specification
42
IVI Foundation
6. IVI Configurable Components Class (Virtual) 6.1
IVI Configurable Components Overview The IVI Configurable Components class allows developers to add properties to several of the other Configuration Server classes. This class is not implemented directly – it is a virtual base class. The following Configuration Server classes inherit from the IVI Configurable Components class: • IVI Session • IVI Driver Session (through IVI Session) • IVI Hardware Asset • IVI Software Module Each of these classes inherits Name, Description, and a reference to a collection of Data Component objects. Each object in the Data Component collection represents either a property added by the developer or a pointer to another collection of Data Component objects.
6.2
IVI Configurable Components References The IVI Configurable Components class defines the following references: • Data Components This section describes each reference.
IVI Foundation
43
IVI-3.5: IVI Configuration Server Specification
6.2.1 Data Components COM Data Type
C Data Type
IIviDataComponentCollection**
Access
IviDataComponentCollectionHandle
R/0
COM Property Name DataComponents
C Function Prototype ViStatus _VI_FUNC IviConfig_GetConfigComponentDataComponentCollection (IviConfigComponentHandle ConfigComponentHandle, IviDataComponentCollectionHandle* DataComponentCollectionHandle);
Parameters Inputs
Description
Datatype
ConfigComponentHa ndle
Handle to an IviConfigComponent object. You may pass a handle to any of the derived IviConfigComponent objects.
IviConfigCompon entHandle
Outputs
Description
Datatype
DataComponentColl ectionHandle
Handle to an IviDataComponentCollection object.
IviDataComponen tCollectionHand le
Description References a collection of DataComponents that modifies the object of which the collection is a part.
IVI-3.5: IVI Configuration Server Specification
44
IVI Foundation
6.3
IVI Configurable Components Properties The IVI Configurable Components class defines the following properties: • Description • Name This section describes the behavior and requirements of each property.
IVI Foundation
45
IVI-3.5: IVI Configuration Server Specification
6.3.1 Description COM Data Type BSTR
Access R/W
COM Property Name Description
C Constant Name IVICONFIG_VAL_CONFIG_COMPONENT_DESCRIPTION
Description The description of the associated object. The empty string is a legal value for this property.
IVI-3.5: IVI Configuration Server Specification
46
IVI Foundation
6.3.2 Name COM Data Type BSTR
Access R/W
COM Property Name Name
C Constant Name IVICONFIG_VAL_CONFIG_COMPONENT_NAME
Description The name of the associated object. The empty string is not a legal value for this property.
IVI Foundation
47
IVI-3.5: IVI Configuration Server Specification
7. IVI Configuration Store Class 7.1
IVI Configuration Store Overview The IVI Configuration Store class is the main class of the Configuration Server. There is exactly one IVI Configuration Store object in each instance of the configuration server. This object is created before any others, and there is no way to delete it. Use of the Configuration Server starts with this object. The IVI Configuration Store class allows users to find out information about the Configuration Server using a similar approach to that used in other IVI components. Information includes Revision, Specification Major Version, Specification Minor Version, and Vendor, as well as Name and Description. The IVI Configuration Store class allows users to Deserialize (load) an IVI configuration store XML file into the Configuration Server, and to Serialize updated information out to the file again. The IVI Configuration Store class provides two helper functions to help developers find Sessions and Driver Sessions in the configuration store. Sessions and Driver Sessions may be identified either by their Name or by a Logical Name that maps to their name. These functions are be used to make sure that the logic used to search for a session is correct and consistent among IVI software modules. Finally, the IVI Configuration Store class provides the means to navigate to collections of Configuration Store objects. This class includes references to collections of Logical Names, Sessions, Driver Sessions, Hardware Assets, Software Modules, and Published APIs.
7.2
IVI Configuration Store References The IVI Configuration Store class defines the following references: • Driver Sessions • Hardware Assets • Logical Names • Published APIs • Sessions • Software Modules This section describes each reference.
IVI-3.5: IVI Configuration Server Specification
48
IVI Foundation
7.2.1 Driver Sessions COM Data Type
C Data Type
IIviDriverSessionCollection**
Access
IviDriverSessionCollectionHandle
R/O
COM Property Name DriverSessions
C Function Prototype ViStatus _VI_FUNC IviConfig_GetConfigStoreDriverSessionCollection (IviConfigStoreHandle ConfigStoreHandle, IviDriverSessionCollectionHandle* DriverSessionCollectionHandle);
Parameters Inputs
Description
Datatype
ConfigStoreHandle
Handle to an IviConfigStore object.
IviConfigStoreH andle
Outputs
Description
Datatype
DriverSessionColl ectionHandle
Handle to an IviDriverSessionCollection object.
IviDriverSessio nCollectionHand le
Description References the global collection of all Driver Session objects in the configuration store.
IVI Foundation
49
IVI-3.5: IVI Configuration Server Specification
7.2.2 Hardware Assets COM Data Type
C Data Type
IIviHardwareAssetCollection**
Access
IviHardwareAssetCollectionHandle
R/O
COM Property Name HardwareAssets
C Function Prototype ViStatus _VI_FUNC IviConfig_GetConfigStoreHardwareAssetCollection (IviConfigStoreHandle ConfigStoreHandle, IviHardwareAssetCollectionHandle* HardwareAssetCollection);
Parameters Inputs
Description
Datatype
ConfigStoreHandle
Handle to an IviConfigStore object.
IviConfigStoreH andle
Outputs
Description
Datatype
HardwareAssetColl ection
Handle to an IviHardwareAssetCollection object.
IviHardwareAsse tCollectionHand le
Description References the global collection of all Hardware Asset objects in the configuration store.
IVI-3.5: IVI Configuration Server Specification
50
IVI Foundation
7.2.3 Logical Names COM Data Type
C Data Type
IIviLogicalNameCollection**
Access
IviLogicalNameCollectionHandle
R/O
COM Property Name LogicalNames
C Function Prototype ViStatus _VI_FUNC IviConfig_GetConfigStoreLogicalNameCollection (IviConfigStoreHandle ConfigStoreHandle, IviLogicalNameCollectionHandle* LogicalNameCollectionHandle);
Parameters Inputs
Description
Datatype
ConfigStoreHandle
Handle to an IviConfigStore object.
IviConfigStoreH andle
Outputs
Description
Datatype
LogicalNameCollec tionHandle
Handle to an IviLogicalNameCollection object.
IviLogicalNameC ollectionHandle
Description References the global collection of all Logical Name objects in the configuration store.
IVI Foundation
51
IVI-3.5: IVI Configuration Server Specification
7.2.4 Published APIs COM Data Type
C Data Type
IIviPublishedAPICollection**
Access
IviPublishedAPIsCollectionHandle
R/O
COM Property Name PublishedAPIs
C Function Prototype ViStatus _VI_FUNC IviConfig_GetConfigStorePublishedAPICollection (IviConfigStoreHandle ConfigStoreHandle, IviPublishedAPICollectionHandle* PublishedAPICollection);
Parameters Inputs
Description
Datatype
ConfigStoreHandle
Handle to an IviConfigStore object.
IviConfigStoreH andle
Outputs
Description
Datatype
PublishedAPIColle ction
Handle to an IviPublishedAPICollection object.
IviPublishedAPI CollectionHandl e
Description References the global collection of all Published API objects in the configuration store. The Item property and Remove method for this collection require parameters different from the other collections. Item( [in] VARIANT varIndex, [in] long MajorVersion, [in] long MinorVersion, [in] BSTR Type, [out, retval]IIviPublishedAPI**pVal) Remove( [in] VARIANT varIndex, [in] long MajorVersion, [in] long MinorVersion, [in] BSTR Type, [out, retval]IIviPublishedAPI**pVal)
If the parameter, varIndex, is an integer, the remaining parameters are ignored as a numeric index completely identifies the item to be retrieved or removed.
IVI-3.5: IVI Configuration Server Specification
52
IVI Foundation
7.2.5 Sessions COM Data Type
C Data Type
IIviSessionCollection**
IviSessionCollectionHandle
Access R/O
COM Property Name Sessions
C Function Prototype ViStatus _VI_FUNC IviConfig_GetConfigStoreSessionCollection (IviConfigStoreHandle ConfigStoreHandle, IviSessionCollectionHandle* SessionCollectionHandle);
Parameters Inputs
Description
Datatype
ConfigStoreHandle
Handle to an IviConfigStore object.
IviConfigStoreH andle
Outputs
Description
Datatype
SessionCollection Handle
Handle to an IviSessionCollection object.
IviSessionColle ctionHandle
Description References the global collection of all IVI Session objects in the configuration store. The collection of all sessions includes all driver sessions.
IVI Foundation
53
IVI-3.5: IVI Configuration Server Specification
7.2.6 Software Modules COM Data Type
C Data Type
IIviSoftwareModuleCollection**
Access
IviSoftwareModuleCollectionHandle
R/O
COM Property Name SoftwareModules
C Function Prototype ViStatus _VI_FUNC IviConfig_GetConfigStoreSoftwareModuleCollection (IviConfigStoreHandle ConfigStoreHandle, IviSoftwareModuleCollectionHandle* SoftwareModuleCollection);
Parameters Inputs
Description
Datatype
ConfigStoreHandle
Handle to an IviConfigStore object.
IviConfigStoreH andle
Outputs
Description
Datatype
SoftwareModuleCol lection
Handle to an IviSoftwareModuleCollection object.
IviSoftwareModu leCollectionHan dle
Description References the global collection of all Software Module objects in the configuration store.
IVI-3.5: IVI Configuration Server Specification
54
IVI Foundation
7.3
IVI Configuration Store Properties The IVI Configuration Store class defines the following properties: • Actual Location • Description • Master Location • Name • Process Default Location • Revision • Specification Major Version • Specification Minor Version • Vendor This section describes the behavior and requirements of each property.
IVI Foundation
55
IVI-3.5: IVI Configuration Server Specification
7.3.1 Actual Location COM Data Type
Access
BSTR
R/O
COM Property Name ActualLocation
C Constant Name IVICONFIG_VAL_CONFIG_STORE_ACTUAL_LOCATION
Description Returns the full pathname of the configuration store file that was successfully deserialized by the current instance of the configuration server. If no configuration store file has been successfully deserialized by the current instance of the configuration server, the property returns the empty string.
IVI-3.5: IVI Configuration Server Specification
56
IVI Foundation
7.3.2 Description COM Data Type BSTR
Access R/W
COM Property Name Description
C Constant Name IVICONFIG_VAL_CONFIG_STORE_DESCRIPTION
Description The description of the Configuration Server component. In a newly created object, this string is “The IVI Configuration Server allows access to and modification of an IVI configuration store.”
IVI Foundation
57
IVI-3.5: IVI Configuration Server Specification
7.3.3 Master Location COM Data Type
Access
BSTR
R/O
COM Property Name MasterLocation
C Constant Name IVICONFIG_VAL_CONFIG_STORE_MASTER_LOCATION
Description Specifies the full pathname of the master configuration store. This includes the file name, which is always IviConfigurationStore.xml. The configuration server checks to see if the registry key HKEY_LOCAL_MACHINE\SOFTWARE\IVI\CONFIGURATIONSERVER, MasterStore exists. If it does exist, then the value of Master Location shall be the value of this key. If it does not exist, the configuration server shall return the Master Not Found error. Return Values The IVI-3.2: Inherent Capabilities Specification defines general status codes that this function can return. The table below specifies additional IVI configuration server status codes for this function. Completion Codes Master Not Found
IVI-3.5: IVI Configuration Server Specification
Description The registry key does not exist or the file can not be found.
58
IVI Foundation
7.3.4 Name COM Data Type BSTR
Access R/O
COM Property Name Name
C Constant Name IVICONFIG_VAL_CONFIG_STORE_NAME
Description The name of the Configuration Server. This string shall be “IVI Configuration Server”.
IVI Foundation
59
IVI-3.5: IVI Configuration Server Specification
7.3.5 Process Default Location COM Data Type BSTR
Access R/W
COM Property Name ProcessDefaultLocation
C Constant Name IVICONFIG_VAL_CONFIG_STORE_PROC_DEFAULT_LOCATION
Description Specifies the full pathname of the default configuration store for the process in which this property is used. If a non-empty string is assigned to this property by code executed in the process, the property shall return that string when accessed in the same process. The empty string is a legal value for this property. Refer to Section 3.2.3, Instantiating the Right Configuration Store From Software Modules, for more information.
IVI-3.5: IVI Configuration Server Specification
60
IVI Foundation
7.3.6 Revision COM Data Type BSTR
Access R/O
COM Property Name Revision
C Constant Name IVICONFIG_VAL_CONFIG_STORE_REVISION
Description This string shall be the current revision of the Configuration Server. The format of the revision string or a revision string is defined in Section 5.18, File Versioning, of the IVI-3.1: Driver Architecture Specification.
IVI Foundation
61
IVI-3.5: IVI Configuration Server Specification
7.3.7 Specification Major Version COM Data Type Long
Access R/O
COM Property Name SpecificationMajorVersion
C Constant Name IVICONFIG_VAL_CONFIG_STORE_SPEC_MAJOR_VERSION
Description This property shall be the major version of the Configuration Server specification supported by the Configuration Server component. The rules related to Specification Major Version are defined in Section 5.18, File Versioning, of the IVI-3.1: Driver Architecture Specification.
IVI-3.5: IVI Configuration Server Specification
62
IVI Foundation
7.3.8 Specification Minor Version COM Data Type Long
Access R/O
COM Property Name SpecificationMinorVersion
C Constant Name IVICONFIG_VAL_CONFIG_STORE_SPEC_MINOR_VERSION
Description This property shall be the minor version of the Configuration Server specification supported by the Configuration Server component. The rules related to Specification Minor Version are defined in Section 5.18, File Versioning, of the IVI-3.1: Driver Architecture Specification.
IVI Foundation
63
IVI-3.5: IVI Configuration Server Specification
7.3.9 Vendor COM Data Type BSTR
Access R/O
COM Property Name Vendor
C Constant Name IVICONFIG_VAL_CONFIG_STORE_VENDOR
Description The vendor of the Configuration Server component. This string shall be “IVI Foundation, Inc.”.
IVI-3.5: IVI Configuration Server Specification
64
IVI Foundation
7.4
IVI Configuration Store Functions The IVI Configuration Store class defines the following functions: • Deserialize • Get Driver Session • Get Session • Serialize This section describes the behavior and requirements of each function.
IVI Foundation
65
IVI-3.5: IVI Configuration Server Specification
7.4.1 Deserialize Description Reads a configuration store file from a data source location, parses the data, and creates the corresponding Configuration Server classes in memory. Deserialize opens the configuration file specified by the Location parameter. The location parameter must be the full pathname of the configuration store file to be opened. If the file is found, but cannot be successfully deserialized, Deseriailize shall return a Deserialized Failed error and the Configuration Server is returned to its initial state. Deserialize may only be run successfully once per instance of the Configuration Server. If Deserialize is called after being previously called successfully it shall return a Already Deserialized error. Multiple copies of the Configuration Server can be accessed by accessing multiple instances of the Configuration Server. COM Method Prototype Deserialize([in] BSTR Location);
C Function Prototype ViStatus _VI_FUNC IviConfig_Deserialize (IviConfigStoreHandle ConfigStoreHandle, ViConstString Location);
Return Values The IVI-3.2: Inherent Capabilities Specification defines general status codes that this function can return. The table below specifies additional IVI configuration server status codes for this function. Completion Codes
Description
Deserialize Failed
The specified Configuration Store file could not be deserialized.
Already Deserialized
A deserialize was attempted after a previous de-serialize had already succeeded.
IVI-3.5: IVI Configuration Server Specification
66
IVI Foundation
7.4.2 Get Driver Session Description Returns a reference to a driver session, given a name that identifies the session. Name may be either the Name of the Driver Session object, or a logical name that refers to the Driver Session object. To find the Driver Session object, Get Driver Session first searches the global Logical Names collection to see if Name is defined in that collection. If Name is found in the collection, Get Driver Session examines the referenced Session. If the Session is a Driver Session, then the Driver Session reference is returned in the DriverSession parameter. If Name is not found in the Logical Names collection, or if the Session referenced by the Logical Name is not a Driver Session, Get Driver Session searches the global Driver Session collection to see if Name is defined in the Driver Session collection. If Name is found in the Driver Session collection, then the Driver Session reference is returned in the DriverSession parameter. If Name is not found in the Logical Names or the Driver Session collections, Get Driver Session shall return a NULL pointer for the DriverSession parameter and shall return a Session Not Found error. Note that if both collections have an item that matches Name, the item found by following the Logical Name reference is returned. COM Method Prototype GetDriverSession([in] BSTR Name, [in,out] IIviDriverSession** DriverSession);
C Function Prototype ViStatus _VI_FUNC IviConfig_GetDriverSession (IviConfigStoreHandle ConfigStoreHandle, ViConstString Name, IviDriverSessionHandle* DriverSessionHandle);
Return Values The IVI-3.2: Inherent Capabilities Specification defines general status codes that this function can return. The table below specifies additional IVI configuration server status codes for this function. Completion Codes Session Not Found
IVI Foundation
Description The session name or logical name could not be resolved to a driver session.
67
IVI-3.5: IVI Configuration Server Specification
7.4.3 Get Session Description Returns a reference to a session, given a name that identifies the session. Name may be either the Name of the Session object, or a logical name that refers to the Session object. To find the Session object, Get Session first searches the global Logical Names collection to see if Name is defined in that collection. If Name is found in the Logical Names collection, then the Session reference is returned in the Session parameter. If Name is not found in the collection, Get Session searches the global Sessions collection to see if Name is defined in the Sessions collection. If Name is found in the collection, then the Session reference is returned in the Session parameter. If Name is not found in the Logical Names or the Sessions collections, Get Session returns a NULL pointer for the Session parameter and returns a Session Not Found error. Note that if both collections have an item that matches Name, the item found by following the Logical Name reference is returned. COM Method Prototype GetSession([in] BSTR Name, [in,out] IIviSession** Session);
C Function Prototype ViStatus _VI_FUNC IviConfig_GetSession (IviConfigStoreHandle ConfigStoreHandle, ViConstString Name, IviSessionHandle* SessionHandle);
Return Values The IVI-3.2: Inherent Capabilities Specification defines general status codes that this function can return. The table below specifies additional IVI configuration server status codes for this function. Completion Codes Session Not Found
IVI-3.5: IVI Configuration Server Specification
Description The session name or logical name could not be resolved to a session.
68
IVI Foundation
7.4.4 Serialize Description Serializes a configuration store from the Configuration Server to a data source location. The Serialize method creates the configuration file specified by the Location parameter. The location parameter must be the full pathname of the configuration store file to be written. If the folders specified in the pathname do not exist, this function will create them. If the file is found, but cannot be successfully serialized, Serialize shall return a Serialize Failed error. COM Method Prototype Serialize([in] BSTR Location)
C Function Prototype ViStatus _VI_FUNC IviConfig_Serialize (IviConfigStoreHandle ConfigStoreHandle, ViConstString Location);
Return Values The IVI-3.2: Inherent Capabilities Specification defines general status codes that this function can return. The table below specifies additional IVI configuration server status codes for this function. Completion Codes Serialize Failed
IVI Foundation
Description The specified Configuration Store file could not be serialized.
69
IVI-3.5: IVI Configuration Server Specification
8. IVI Hardware Asset Class 8.1
IVI Hardware Asset Overview The IVI Hardware Asset class identifies the physical assets available to a system. Hardware assets are identified by their I/O Resource Descriptor, which generally speaking will be unique for a given instrument on a given PC. The Data Components objects referenced by a hardware asset serve to document the hardware asset.
8.1.1 Documentation Data Components Data components that document the hardware asset may be added to the hardware asset’s data components collection at any time. These data components shall have Software Module Key equal to the empty string and Used In Session equal to “None” since they are not used to configure a software module.
8.2
IVI Hardware Asset References The IVI Hardware Asset class inherits the following references from IVI Configurable Component (Section6, IVI Configurable Components Class (Virtual)): • Data Components
8.3
IVI Hardware Asset Properties The IVI Hardware Asset class defines the following properties: • I/O Resource Descriptor The IVI Hardware Asset class inherits the following properties from IVI Configurable Component (Section6, IVI Configurable Components Class (Virtual)): • Description • Name This section describes the behavior and requirements of each property.
IVI-3.5: IVI Configuration Server Specification
70
IVI Foundation
8.3.1 I/O Resource Descriptor COM Data Type
Access
BSTR
R/W
COM Property Name IOResourceDescriptor
C Constant Name IVICONFIG_VAL_HARDWARE_ASSET_IO_DESCRIPTOR
Description I/O Resource Descriptor stores a string that specifies the address of the hardware asset that can be recognized by I/O used by a software module that will access the hardware. For a complete description of the I/O Resource Descriptor property, refer to Section 5.17, Function Compliance Rules and Section 6.14, Initialize, of the IVI-3.2: Inherent Capabilities Specification. The empty string is a legal value for this property.
IVI Foundation
71
IVI-3.5: IVI Configuration Server Specification
9. IVI Published API Class 9.1
IVI Published API Overview Published APIs are APIs that are supported across several products, and as such are published independently of any one component that implements them. Published APIs may be standard APIs published by the IVI Foundation, such as the IviDriver API for IVI driver inherent capabilities (refer to IVI3.2: Inherent Capabilities Specification) or the instrument class specification APIs. Published APIs may also be IVI-MSS roles or IVI Signal Interface APIs. Published APIs may also be vendor-defined APIs that span multiple components. Published APIs are identified by name. The name is a logical description of the API. For instance, the IVIC IviDriver API consists of function prototypes, attribute ID constants, and so on, while the IVI-COM IviDriver API consists of IDL enumerations and interface definitions. In both cases, the name of the published API is “IviDriver”. Published APIs are not necessarily tied to any particular revision of an API. Suppose that the IviDriver API is revised, so that both version 1 and version 2 are implemented in different drivers. In both cases, the name of the published API is “IviDriver”. Published API names are specified by the document that specifies the API. The Type field identifies the syntax of the API. “IVI-C” and “IVI-COM” are predefined values that shall be used for IVI defined APIs. There will be separate Published API entries in the configuration server for the IVI-C IviDriver API and the IVI-COM IviDriver API. The Version fields identify revisions of the API specification which are reflected in the API. Multiple revisions of a specific API (identified by Name and Type) may be stored in the configuration store. Together, the Name, Type, and Version properties identify a unique entry in the global Published API collection. This uniqueness is enforced by the configuration server. However, the properties appear individually in the API.
9.2
IVI Published API Properties The IVI Published API class defines the following properties: • Major Version • Minor Version • Name • Type This section describes the behavior and requirements of each property.
IVI-3.5: IVI Configuration Server Specification
72
IVI Foundation
9.2.1 Major Version COM Data Type long
Access R/W
COM Property Name MajorVersion
C Constant Name IVICONFIG_VAL_PUBLISHED_API_MAJOR_VERSION
Description The major version of this revision of the published API. This is determined by the person or group who publishes the API.
IVI Foundation
73
IVI-3.5: IVI Configuration Server Specification
9.2.2 Minor Version COM Data Type long
Access R/W
COM Property Name MinorVersion
C Constant Name IVICONFIG_VAL_PUBLISHED_API_MINOR_VERSION
Description The minor version of this revision of the published API. This is determined by the person or group who publishes the API.
IVI-3.5: IVI Configuration Server Specification
74
IVI Foundation
9.2.3 Name COM Data Type BSTR
Access R/W
COM Property Name Name
C Constant Name IVICONFIG_VAL_PUBLISHED_API_NAME
Description The name of a Published API. Name may refer to either: • An IVI-defined API. In this case, the first 3 characters of the string shall be “Ivi”. These API names are defined in the various IVI specifications. • An API defined outside of the IVI Foundation. In this case, the first three characters of the string shall not be “Ivi”, where “Ivi” is case insensitive. The definition of these names is specific to the person or group that defines the API. The empty string is not a legal value for this property.
IVI Foundation
75
IVI-3.5: IVI Configuration Server Specification
9.2.4 Type COM Data Type BSTR
Access R/W
COM Property Name Type
C Constant Name IVICONFIG_VAL_PUBLISHED_API_TYPE
Description The type of a Published API. Two predefined values are supported for the IVI defined interfaces, “IVI-C” and “IVI-COM”. These values shall be used for all IVI defined inherent and class APIs. Other user-defined values may be used for other types of APIs. However, if the APIs follow the style guidelines for IVI-C or IVI-COM interfaces as described in IVI-3.4: API Style Guide, it is recommended that “IVI-C” or “IVI-COM” be used as the type, respectively. The empty string is not a legal value for this property.
IVI-3.5: IVI Configuration Server Specification
76
IVI Foundation
10. IVI Software Module Class 10.1 IVI Software Module Overview The Software Module class identifies IVI software components. IVI software components include, but are not limited to, various types of IVI drivers and IVI-MSS components. A Software Module is a software component that exposes its functionality via either an ANSI C or COM API, or both. For ANSI C modules, the value of the Module Path property is the full pathname of the DLL containing the ANSI C entry points. For COM modules, the value of the ProgID property is the version independent ProgID of the software module’s COM coclass. If a single vendor supports both ANSI C and COM APIs for the Software Module object, both Module Path and ProgID have valid values. The Software Module installer is responsible for making sure one or both of these entries are not empty. If both entries are empty, the client program cannot find the Software Module’s executable code. Software Modules may expose one or more APIs that are published and implemented by one or more modules. IVI class-compliant interfaces are examples of such APIs. Refer to Section 9.1, IVI Published API Overview for a description of how Published APIs are defined and treated in the Configuration Server. If a software module implements both ANSI C and COM APIs for the same module, the associated Published API collection shall include references to both types of the APIs. Software Modules may implement repeated capabilities. Refer to Section 2.8.7. IVI API Reference for a description of how repeated capabilities are defined in the Configuration Server. If a Software Module implements repeated capabilities, if must reference a collection of IVI Physical Name objects. The IVI Physical Name objects may be structured hierarchically to reflect a hierarchy of repeated capabilities in the Software Module. Refer to Section 11.1, IVI Physical Name Overview for an overview of how IVI Physical Names may be structured hierarchically. The Data Components objects referenced by a software module are either configurable initial settings or serve to document the software module.
10.1.1 Configurable Initial Settings A configurable initial setting is an IVI Data Component object referenced by an IVI Software Module object with Used In Session equal to “Required” or “Optional”, Read Only equal to “True”, and Type equal to “Boolean”, “String”, “Integer”, “Real”, or “APIReference”. The Value property of the data component is a suitable default value for the setting when the software module is initialized, if possible. The Description property should contain a description of the configurable initial setting and its possible values. If this exceeds the practical size limit for a string, then the data component’s help properties should refer the user to a suitable form of help that fully describes the configurable initial setting and its possible values. Because the configurable initial settings are selected by the software module developer, and are recognized by the software module during initialization, configurable initial settings are only added by the software module when it is installed. Configurable initial settings from the software module are copied to sessions that reference the software module. Refer to Section 14.1.1, Configurable Initial Settings, for more details.
10.1.2 Documentation Data Components Data components that document the software module in some way may be added to the software module’s data components collection at any time. These data components shall have Used In Session equal to “None” since they are not used by the session to configure the software module.
IVI Foundation
77
IVI-3.5: IVI Configuration Server Specification
10.2 IVI Software Module References The IVI Software Module class defines the following references: • Physical Names • Published APIs The IVI Software Module class inherits the following references from IVI Configurable Component Section 6, IVI Configurable Components Class (Virtual) • Data Components This section describes each reference.
IVI-3.5: IVI Configuration Server Specification
78
IVI Foundation
10.2.1 Physical Names COM Data Type
C Data Type
IIviPhysicalNameCollection**
Access
IviPhysicalNameCollectionHandle
R/O
COM Property Name PhysicalNames
C Function Prototype ViStatus _VI_FUNC IviConfig_GetSoftwareModulePhysicalNameCollection (IviSoftwareModuleHandle SoftwareModuleHandle, IviPhysicalNameCollectionHandle* PhysicalNameCollectionHandle);
Parameters Inputs
Description
Datatype
SoftwareModuleHan dle
Handle to an IviSoftwareModule object.
IviSoftwareModu leHandle
Outputs
Description
Datatype
PhysicalNameColle ctionHandle
Handle to an IviPhysicalNameCollection object.
IviPhysicalName CollectionHandl e
Description References a collection of all the PhysicalName objects defined by the Software Module. If a Software Module implements IVI instrument class-compliant APIs that have repeated capabilities, it shall reference a collection of IVI Physical Name objects for the class-defined repeated capabilities. This information is required in order to specify virtual identifiers for IVI Sessions and Driver Sessions, and virtual identifiers are required to use repeated capabilities interchangeably. For other repeated capabilities in a Software Module, physical identifiers are optional but recommended, particularly if needed to support interchangeability. The IVI Physical Name collections may be structured hierarchically to reflect a hierarchy of repeated capabilities in the Software Module. Refer to Section 11.1, IVI Physical Name Overview for an description of how physical identifiers may be structured hierarchically.
IVI Foundation
79
IVI-3.5: IVI Configuration Server Specification
10.2.2 Published APIs COM Data Type
C Data Type
IIviPublishedAPICollection**
Access
IviPublishedAPIsCollectionHandle
R/O
COM Property Name PublishedAPIs
C Function Prototype ViStatus _VI_FUNC IviConfig_GetSoftwareModulePublishedAPIsCollection (IviSoftwareModuleHandle SoftwareModuleHandle, IviPublishedAPIsCollectionHandle* PublishedAPIsCollectionHandle);
Parameters Inputs
Description
Datatype
SoftwareModuleHan dle
Handle to an IviSoftwareModule object.
IviSoftwareModu leHandle
Outputs
Description
Datatype
PublishedAPIsColl ectionHandle
Handle to an IviPublishedAPIsCollection object.
IviPublishedAPI sCollectionHand le
Description References a collection of all the Published APIs that are implemented by the Software Module. Refer to Section 9.1, IVI Published API Overview for an overview of Published APIs. Before a Published API can be added to a Software Module’s Published API collection, it must already exist in the global Published API collection. To add a Published API to a Software Module’s Published API collection first get the Published API from the global collection and the add the returned reference to the Software Module’s collection.
IVI-3.5: IVI Configuration Server Specification
80
IVI Foundation
10.3 IVI Software Module Properties The IVI Software Module class defines the following properties: • Module Path • Prefix • ProgID • Supported Instrument Models The IVI Software Module class inherits the following properties from IVI Configurable Component Section 6, IVI Configurable Components Class (Virtual) • Description • Name This section describes the behavior and requirements of each property.
IVI Foundation
81
IVI-3.5: IVI Configuration Server Specification
10.3.1 Module Path COM Data Type BSTR
Access R/W
COM Property Name ModulePath
C Constant Name IVICONFIG_VAL_SW_MODULE_PATH
Description Returns a string that specifies the full pathname of the software module. This property may be an empty string.
IVI-3.5: IVI Configuration Server Specification
82
IVI Foundation
10.3.2 Prefix COM Data Type BSTR
Access R/W
COM Property Name Prefix
C Constant Name IVICONFIG_VAL_SW_MODULE_PREFIX
Description Prefix is a string that specifies the prefix (for IVI-C components) or the component identifier (for IVI-COM components) of the software module. This shall exactly match the value returned by the Prefix attribute or the Component Identifier attributes. Refer to Section 5.6, Class Driver Prefix, Section 5.13, Component Identifier, and Section 5.32, Specific Driver Prefix, of the IVI-3.2: Inherent Capabilities Specification, for complete details. The empty string is a legal value for this property.
IVI Foundation
83
IVI-3.5: IVI Configuration Server Specification
10.3.3 ProgID COM Data Type BSTR
Access R/W
COM Property Name ProgID
C Constant Name IVICONFIG_VAL_SW_MODULE_PROGID
Description ProgID returns a string that specifies the version-independent COM ProgID of the software module. This property may be an empty string.
IVI-3.5: IVI Configuration Server Specification
84
IVI Foundation
10.3.4 Supported Instrument Models COM Data Type
Access
BSTR
R/W
COM Property Name SupportedInstrumentModels
C Constant Name IVICONFIG_VAL_SW_MODULE_SUPPORTED_INSTR_MODELS
Description A comma-separated string that specifies the instrument models supported by the software module. This shall exactly match the value returned by the Supported Instrument Models attribute as defined in Section 5.35, Supported Instrument Models, of the IVI-3.2: Inherent Capabilities Specification.
IVI Foundation
85
IVI-3.5: IVI Configuration Server Specification
11. IVI Physical Name Class 11.1 IVI Physical Name Overview IVI Physical Name objects describe the physical identifiers supported by a software module. Physical identifiers are the names that an IVI specific instrument driver, IVI-MSS role control module, or other IVI software module gives to instances of the repeated capabilities they implement. For example, one IviScope specific instrument driver might name channels “A”, “B”, and “C” while another might name them “1”, “2”, “3’, and “4”. The RC Name property describes the type of repeated capability. In the above example, RC Name might be “Channel” – the name of the repeated capability in the IviScope specification. An IVI Physical Name object can reference a collection of IVI Physical Name objects, thereby creating a hierarchy of nested repeated capabilities. An IVI Physical Name object can reference a collection of IVI Physical Range objects, which allows an efficient way of creating a large number of physical identifiers by appending integers from the range to the Name property. For a comprehensive overview of the treatment of repeated capabilities in the Configuration Server, including the role that physical identifiers play, refer to Section 2.9, Repeated Capabilities.
11.2 IVI Physical Name References The IVI Physical Name class defines the following references: • Physical Names • Physical Ranges This section describes the behavior and requirements of each property.
IVI-3.5: IVI Configuration Server Specification
86
IVI Foundation
11.2.1 Physical Names COM Data Type
C Data Type
IIviPhysicalNameCollection**
Access
IviPhysicalNameCollectionHandle
R/O
COM Property Name PhysicalNames
C Function Prototype ViStatus _VI_FUNC IviConfig_GetPhysicalNameChildPhysicalNameCollection (IviPhysicalNameHandle PhysicalNameHandle, IviPhysicalNameCollectionHandle* ChildPhysicalNameCollectionHandle);
Parameters Inputs
Description
Datatype
PhysicalNameHandle
Handle to an IviPhysicalName object.
IviPhysicalName Handle
Outputs
Description
Datatype
ChildPhysicalNameC ollectionHandle
Handle to an IviPhysicalNameCollection object.
IviPhysicalName CollectionHandl e
Description References a collection of the IVI Physical Name objects that are hierarchically structured under this IVI Physical Name object. This collection will commonly be empty.
IVI Foundation
87
IVI-3.5: IVI Configuration Server Specification
11.2.2 Physical Ranges COM Data Type
C Data Type
IIviPhysicalRangeCollection **
Access
IviPhysicalRangeCollectionHandle
R/O
COM Property Name PhysicalRanges
C Function Prototype ViStatus _VI_FUNC IviConfig_GetPhysicalNamePhysicalRangeCollection (IviPhysicalNameHandle PhysicalNameHandle, IviPhysicalRangeCollectionHandle* PhysicalRangeCollectionHandle);
Parameters Inputs
Description
Datatype
PhysicalNameHandle
Handle to an IviPhysicalName object.
IviPhysicalName Handle
Outputs
Description
Datatype
PhysicalRangeColle ctionHandle
Handle to an IviPhysicalRangeCollection object.
IviPhysicalRang eCollectionHand le
Description References a collection of IVI Physical Range objects used to qualify the referencing IVI Physical Name object.
IVI-3.5: IVI Configuration Server Specification
88
IVI Foundation
11.3 IVI Physical Name Properties The IVI Physical Name class defines the following properties: • Name • RC Name This section describes the behavior and requirements of each property.
IVI Foundation
89
IVI-3.5: IVI Configuration Server Specification
11.3.1 Name COM Data Type BSTR
Access R/W
COM Property Name Name
C Constant Name IVICONFIG_VAL_PHYSICAL_NAME_NAME
Description The name of a specific instance of a repeated capability as defined in the software module. This is also known as the physical identifier. Name shall consist of one or more of the following characters: ‘a’-‘z’, ‘A’-‘Z’, ‘0’-‘9’, ‘!’, and ‘_’. The empty string is valid for this property only if the IVI Physical Name object references a non-empty collection of Physical Range objects.
IVI-3.5: IVI Configuration Server Specification
90
IVI Foundation
11.3.2 RC Name COM Data Type BSTR
Access R/W
COM Property Name RCName
C Constant Name IVICONFIG_VAL_PHYSICAL_NAME_RCNAME
Description The repeated capability name as defined in the software module. Each IVI Physical Name object represents an instance of the repeated capability of type RC Name. For software modules that reference Published APIs that define repeated capabilities, the RC Name shall be the repeated capability name defined by the Published API specification. The empty string is not a legal value for this property.
IVI Foundation
91
IVI-3.5: IVI Configuration Server Specification
12. IVI Physical Range Class 12.1 IVI Physical Range Overview The IVI Physical Range class allows multiple instances of a repeated capability to be defined with a minimum of effort. An IVI Physical Range object shall be referenced by exactly one IVI Physical Name object. For a comprehensive overview of the treatment of repeated capabilities in the Configuration Server, including the role that physical names play, refer to Section 2.9, Repeated Capabilities.
12.2 IVI Physical Range Properties The IVI Physical Range class defines the following properties: • Max • Min • Name This section describes the behavior and requirements of each property.
IVI-3.5: IVI Configuration Server Specification
92
IVI Foundation
12.2.1 Max COM Data Type long
Access R/W
COM Property Name Max
C Constant Name IVICONFIG_VAL_PHYSICAL_RANGE_MAX
Description The upper end of a range of integers to be appended to the Name property of the referencing IVI Physical Name object to create a set of physical repeated capability identifiers.
IVI Foundation
93
IVI-3.5: IVI Configuration Server Specification
12.2.2 Min COM Data Type long
Access R/W
COM Property Name Min
C Constant Name IVICONFIG_VAL_PHYSICAL_RANGE_MIN
Description The lower end of a range of integers to be appended to the Name property of the referencing IVI Physical Name object to create a set of physical repeated capability identifiers.
IVI-3.5: IVI Configuration Server Specification
94
IVI Foundation
12.2.3 Name COM Data Type BSTR
Access R/W
COM Property Name Name
C Constant Name IVICONFIG_VAL_PHYSICAL_RANGE_NAME
Description The name of the physical range. This name is used to uniquely identify the range in the collection, and is not used in creating the set of physical identifiers. The empty string is not a legal value for this property.
IVI Foundation
95
IVI-3.5: IVI Configuration Server Specification
13. IVI Logical Name Class 13.1 IVI Logical Name Overview Logical Names introduce an additional level of indirection when referencing IVI Sessions and IVI Driver Sessions. Logical Names allow users to define and name multiple Sessions and switch between them by referencing a Logical Name in a client program. The user changes the Logical Name reference to point to any one of the Sessions depending on the situation, without changing source code. It is impossible to tell by looking at a Logical Name object whether the reference is to a Session or a Driver Session. The Session object must be examined by the client code to determine whether or not it is a Driver Session.
13.2 IVI Logical Name References The IVI Logical Name class defines the following properties: • Session This section describes each reference.
IVI-3.5: IVI Configuration Server Specification
96
IVI Foundation
13.2.1 Session COM Data Type IIviSession**
C Data Type IviSessionHandle
Access R/W
COM Property Name Session
C Function Prototype ViStatus _VI_FUNC IviConfig_GetLogicalNameSessionReference (IviLogicalNameHandle LogicalNameHandle, IviSessionHandle* SessionHandle); ViStatus _VI_FUNC IviConfig_SetLogicalNameSessionReference (IviLogicalNameHandle LogicalNameHandle, IviSessionHandle SessionHandle);
Parameters Inputs
Description
Datatype
LogicalNameHandle
Handle to an IviLogicalNameHandle object.
IviLogicalNameH andle
SessionHandle
Handle to an IviSession object.
IviSessionHandl e
Outputs
Description
Datatype
SessionHandle
Handle to an IviSession object.
IviSessionHandl e
Description The IVI Session to which the logical name refers. The IVI Session may be an IVI Driver Session. Return Values The IVI-3.2: Inherent Capabilities Specification defines general status codes that this function can return. The table below specifies additional IVI configuration server status codes for this function. Completion Codes Not In Global Collection
IVI Foundation
Description The item does not exist in the global collection.
97
IVI-3.5: IVI Configuration Server Specification
13.3 IVI Logical Name Properties The IVI Logical Name class defines the following properties: • Name This section describes the behavior and requirements of each property.
IVI-3.5: IVI Configuration Server Specification
98
IVI Foundation
13.3.1 Name COM Data Type BSTR
Access R/W
COM Property Name Name
C Constant Name IVICONFIG_VAL_LOGICAL_NAME_NAME
Description The logical name. The empty string is not a legal value for this property.
IVI Foundation
99
IVI-3.5: IVI Configuration Server Specification
14. IVI Session Class 14.1 IVI Session Overview The IVI Session class provides the information needed to configure a software module. A software module may be referenced by several sessions. In other words, the configuration store may contain several configurations for one software module. The client specifies at run time which configuration will be used. The Software Module property refers to the specific module configured by an IVI Session object. The Hardware Asset property refers to the hardware asset that identifies the specific instrument or other physical asset that will be used by the software module. Virtual identifiers are used to assign client specific names to the physical identifiers used by the software module for repeated capabilities. Refer to Section 16.1, IVI Virtual Name Overview, for more information. The Data Components objects referenced by a session are either configurable initial settings or serve to document the session.
14.1.1 Configurable Initial Settings Configurable initial settings from the software module are copied to the configurable initial settings of the sessions that reference the software module. A configurable initial setting for a session is an IVI Data Component object referenced by an IVI Session object with Used In Session equal to “Required” or “Optional”. Read Only is set to “False”. The Value property of the data component is set to the desired initial value for the software module when it is initialized. All of the other properties are copied over unchanged from the software module referenced by the session. A session shall include all of the configurable initial settings with Used In Session equal to “Required” from the referenced software module. Clients may optionally copy configurable initial settings with Used In Session equal to “Optional” from the referenced software module. In general, the configuration server tries to preserve a session and all of its configurable initial settings, even if the referenced software module is deleted. This preserves configuration information when, for instance, a driver is reinstalled or upgraded to a new version. The configuration server employs relatively complex logic to meet this objective. •
When the session’s Software Module reference property is set for the first time, the configuration server copies all of the configurable initial settings with Used In Session equal to “Required” from the referenced software module. Users may subsequently copy configurable initial settings with Used In Session equal to “Optional” over to the session using a configuration utility.
•
When the session’s Software Module reference property is set to a null reference or the reference is changed explicitly, the configuration server deletes all of the configurable initial settings from the session. The session will not “remember” the previously referenced software module by its Name.
•
If the software module referenced by the session’s Software Module reference property is deleted, the session’s Software Module reference property is set to a null reference implicitly. However, the session will “remember” the previously referenced software module by its Name. This remembered name is returned by the Software Module Name property. The configuration server does not delete the session’s configurable settings in this case.
•
When the configuration server adds a new software module, it finds all sessions with Software Module Name identical to that of the newly added software module. For each session found, the configuration
IVI-3.5: IVI Configuration Server Specification
100
IVI Foundation
server checks to see if the session’s configurable initial settings match the newly added software module’s configurable settings. • A software module configurable setting matches a session configurable setting if the two have identical values for the Name, Type, and, where applicable, Units properties. • If a matching configurable setting is found, then the values for Description, Help Context ID, Help File Path, Software Module Key, and Used In Session are copied from the software module’s configurable setting to the matching session’s configurable setting. Read Only and Value are not changed in the session’s configurable setting. • Software module configurable settings that don’t match any session configurable settings are copied to the session if Used In Session is equal to “Required”. • Session configurable settings that don’t match any software module configurable settings are deleted from the session if Used In Session is equal to “Required”.
14.1.2 Documentation Data Components Data components that document the session in some way may be added to the session’s data components collection at any time. These data components shall have “Used In Session” equal to “None” since they are not used by the session to configure the software module.
14.2 IVI Session References The IVI Session class defines the following references: • Hardware Asset • Software Module • Virtual Names The IVI Software Module class inherits the following reference from IVI Configurable Component Section 6, IVI Configurable Components Class (Virtual) • Data Components This section describes each reference.
IVI Foundation
101
IVI-3.5: IVI Configuration Server Specification
14.2.1 Hardware Asset COM Data Type IIviHardwareAsset**
C Data Type
Access
IviHardwareAssetHandle
R/W
COM Property Name HardwareAsset
C Function Prototype ViStatus _VI_FUNC IviConfig_GetSessionHardwareAssetReference (IviSessionHandle SessionHandle, IviHardwareAssetHandle* HardwareAssetHandle); ViStatus _VI_FUNC IviConfig_SetSessionHardwareAssetReference (IviSessionHandle SessionHandle, IviHardwareAssetHandle HardwareAssetHandle);
Parameters Inputs
Description
Datatype
SessionHandle
Handle to an IviSession object.
IviSessionHandl e
Outputs
Description
Datatype
HardwareAssetHand le
Handle to an IviHardwareAsset object.
IviHardwareAsse tHandle
Description References the Hardware Asset used by the Session. Return Values The IVI-3.2: Inherent Capabilities Specification defines general status codes that this function can return. The table below specifies additional IVI configuration server status codes for this function. Completion Codes Not In Global Collection
IVI-3.5: IVI Configuration Server Specification
Description The item does not exist in the global collection.
102
IVI Foundation
14.2.2 Software Module COM Data Type IIviSoftwareModule**
C Data Type
Access
IviSoftwareModuleHandle
R/W
COM Property Name SoftwareModule
C Function Prototype ViStatus _VI_FUNC IviConfig_GetSessionSoftwareModuleReference (IviSessionHandle SessionHandle, IviSoftwareModuleHandle* SoftwareModuleHandle); ViStatus _VI_FUNC IviConfig_SetSessionSoftwareModuleReference (IviSessionHandle SessionHandle, IviSoftwareModuleHandle SoftwareModuleHandle);
Parameters Inputs
Description
Datatype
SessionHandle
Handle to an IviSession object.
IviSessionHandl e
Outputs
Description
Datatype
SoftwareModuleHan dle
Handle to an IviSoftwareModule object.
IviSoftwareModu leHandle
Description References the Software Module configured by the Session. Return Values The IVI-3.2: Inherent Capabilities Specification defines general status codes that this function can return. The table below specifies additional IVI configuration server status codes for this function. Completion Codes Not In Global Collection
IVI Foundation
Description The item does not exist in the global collection.
103
IVI-3.5: IVI Configuration Server Specification
14.2.3 Virtual Names COM Data Type
C Data Type
IIviVirtualNameCollection**
Access
IviVirtualNameCollectionHandle
R/O
COM Property Name VirtualNames
C Function Prototype ViStatus _VI_FUNC IviConfig_GetSessionVirtualNameCollection (IviSessionHandle SessionHandle, IviVirtualNameCollectionHandle* VirtualNameCollectionHandle);
Parameters Inputs
Description
Datatype
SessionHandle
Handle to an IviSession object.
IviSessionHandl e
Outputs
Description
Datatype
VirtualNameCollec tionHandle
Handle to an IviVirtualNameCollection object.
IviVirtualNameC ollectionHandle
Description References a collection of all the IVI Virtual Name objects used by the Session. Within a collection, the Name property uniquely identifies an IVI Virtual name object. IVI Virtual Name objects cannot be reused between sessions.
IVI-3.5: IVI Configuration Server Specification
104
IVI Foundation
14.3 IVI Session Properties The IVI Session class defines the following property: • Software Module Name The IVI Session class inherits the following properties from IVI Configurable Component - Section 6, IVI Configurable Components Class (Virtual) • Description • Name This section describes the behavior and requirements of each property.
IVI Foundation
105
IVI-3.5: IVI Configuration Server Specification
14.3.1 Software Module Name COM Data Type BSTR
Access R/O
COM Property Name SoftwareModuleName
C Constant Name IVICONFIG_VAL_SESSION_SOFTWARE_MODULE_NAME
Description The name of the current or most recently referenced software module referenced by the Software Module property.
IVI-3.5: IVI Configuration Server Specification
106
IVI Foundation
15. IVI Driver Session Class 15.1 IVI Driver Session Overview The IVI Driver Session class inherits from the IVI Session class, and adds several properties that may be configured for IVI instrument driver software modules. These properties are common to all IVI instrument drivers, and are defined in IVI-3.2: Inherent Capabilities Specification.
15.2 IVI Driver Session References The IVI Driver Session class inherits the following references from IVI Session - Section 14, IVI Session Class: • Hardware Asset • Software Module • Virtual Names The IVI Driver Session class inherits the following reference from IVI Configurable Component – Section 6, IVI Configurable Components Class (Virtual): • Data Components
15.3 IVI Driver Session Properties The IVI Driver Session class defines the following properties: • Cache • Driver Setup • Interchange Check • Query Instrument Status • Range Check • Record Coercions • Simulate The IVI Driver Session class inherits the following properties from IVI Configurable Component – Section 6, IVI Configurable Components Class (Virtual): • Description • Name This section describes the behavior and requirements of each property.
IVI Foundation
107
IVI-3.5: IVI Configuration Server Specification
15.3.1 Cache COM Data Type
Access
VARIANT_BOOL
R/W
COM Property Name Cache
C Constant Name IVICONFIG_VAL_DRIVER_SESSION_CACHE
Description Cache stores the Boolean value that initializes the Cache attribute in an IVI instrument specific driver. For a complete description of the Cache attribute, refer to Section 5.1, Cache, of IVI-3.2: Inherent Capabilities Specification.
IVI-3.5: IVI Configuration Server Specification
108
IVI Foundation
15.3.2 Driver Setup COM Data Type BSTR
Access R/W
COM Property Name DriverSetup
C Constant Name IVICONFIG_VAL_DRIVER_SESSION_DRIVER_SETUP
Description Driver Setup stores the string that initializes the Driver Setup attribute in an IVI instrument specific driver. For a complete description of the Driver Setup attribute, refer to Section 5.16, Driver Setup, of IVI-3.2: Inherent Capabilities Specification. The empty string is a legal value for this property.
IVI Foundation
109
IVI-3.5: IVI Configuration Server Specification
15.3.3 Interchange Check COM Data Type
Access
VARIANT_BOOL
R/W
COM Property Name InterchangeCheck
C Constant Name IVICONFIG_VAL_DRIVER_SESSION_INTERCHANGE_CHECK
Description Interchange Check stores the Boolean value that initializes the Interchange Check attribute in an IVI instrument specific driver. For a complete description of the Interchange Check attribute, refer to Section 5.22, Interchange Check, of IVI-3.2: Inherent Capabilities Specification.
IVI-3.5: IVI Configuration Server Specification
110
IVI Foundation
15.3.4 Query Instrument Status COM Data Type
Access
VARIANT_BOOL
R/W
COM Property Name QueryInstrStatus
C Constant Name IVICONFIG_VAL_DRIVER_SESSION_QUERY_INSTR_STATUS
Description Query Instrument Status stores the Boolean value that initializes the Query Instrument Status attribute in an IVI instrument specific driver. For a complete description of the Query Instrument Status attribute, refer to Section 5.24, Query Instrument Status, of IVI-3.2: Inherent Capabilities Specification.
IVI Foundation
111
IVI-3.5: IVI Configuration Server Specification
15.3.5 Range Check COM Data Type
Access
VARIANT_BOOL
R/W
COM Property Name RangeCheck
C Constant Name IVICONFIG_VAL_DRIVER_SESSION_RANGE_CHECK
Description Range Check stores the Boolean value that initializes the Range Check attribute in an IVI instrument specific driver. For a complete description of the Range Check attribute, refer to Section 5.25, Range Check, of IVI-3.2: Inherent Capabilities Specification.
IVI-3.5: IVI Configuration Server Specification
112
IVI Foundation
15.3.6 Record Value Coercions COM Data Type
Access
VARIANT_BOOL
R/W
COM Property Name RecordCoercions
C Constant Name IVICONFIG_VAL_DRIVER_SESSION_RECORD_COERCIONS
Description Record Value Coercions stores the Boolean value that initializes the Record Value Coercions attribute in an IVI instrument specific driver. For a complete description of the Record Value Coercions attribute, refer to Section 5.26, Record Value Coercions, of IVI-3.2: Inherent Capabilities Specification.
IVI Foundation
113
IVI-3.5: IVI Configuration Server Specification
15.3.7 Simulate COM Data Type
Access
VARIANT_BOOL
R/W
COM Property Name Simulate
C Constant Name IVICONFIG_VAL_DRIVER_SESSION_SIMULATE
Description Simulate stores the Boolean value that initializes the Simulate attribute in an IVI instrument specific driver. For a complete description of the Simulate attribute, refer to Section 5.27, Simulate, of IVI-3.2: Inherent Capabilities Specification.
IVI-3.5: IVI Configuration Server Specification
114
IVI Foundation
16. IVI Virtual Name Class 16.1 IVI Virtual Name Overview IVI Virtual Name objects describe virtual identifiers defined by the user for a particular session. Virtual identifiers are the names that a client program gives to instances of the repeated capabilities it accesses in software modules. For example, an IVI Scope specific instrument driver might name channels “A”, “B”, and “C” while the client programmer might choose to name them “Chan1”, “Chan2”, and “Chan3”. In this case, “A”, “B”, and “C” are physical identifiers defined by the software module and “Chan1”, “Chan2”, and “Chan3” are the corresponding virtual identifiers used by the client program. Name is the virtual identifier string. It may be qualified by referenced Virtual Ranges. MapTo is the string that is substituted for the virtual identifier. It may be qualified by referenced Virtual Ranges. An IVI Virtual Name object can reference a collection of IVI Virtual Range objects, which allows an efficient way of creating a large number of virtual identifiers by appending integers from the range to the Name property. For a comprehensive overview of the treatment of repeated capabilities in the Configuration Server, including the role that IVI Virtual Names play, refer to Section 2.9, Repeated Capabilities.
16.2 IVI Virtual Name References The IVI Virtual Name class defines the following reference: • Virtual Ranges This section describes each reference.
IVI Foundation
115
IVI-3.5: IVI Configuration Server Specification
16.2.1 Virtual Ranges COM Data Type
C Data Type
IIviVirtualRangeCollection **
Access
IviVirtualRangeCollectionHandle
R/O
COM Property Name VirtualRanges
C Function Prototype ViStatus _VI_FUNC IviConfig_GetVirtualNameVirtualRangeCollection (IviVirtualNameHandle VirtualNameHandle, IviVirtualRangeCollectionHandle* VirtualRangeCollectionHandle);
Parameters Inputs
Description
Datatype
VirtualNameHandle
Handle to an IviVirtualName object.
IviVirtualNameH andle
Outputs
Description
Datatype
VirtualRangeColle ctionHandle
Handle to an IviVirtualRangeCollection object.
IviVirtualRange CollectionHandl e
Description References a collection of IVI Virtual Range objects used to qualify the referencing IVI Virtual Name object.
IVI-3.5: IVI Configuration Server Specification
116
IVI Foundation
16.3 IVI Virtual Name Properties The IVI Virtual Name class defines the following properties: • Map To • Name This section describes the behavior and requirements of each property.
IVI Foundation
117
IVI-3.5: IVI Configuration Server Specification
16.3.1 Map To COM Data Type BSTR
Access R/W
COM Property Name MapTo C Constant Name IVICONFIG_VAL_VIRTUAL_NAME_MAPTO
Description A string used to replace the virtual identifier when the virtual identifier is used to specify repeated capability instances in a software module. When the software module encounters the associated virtual identifier in a repeated capability selector, it substitutes the Map To string for the virtual identifier. The software module is responsible for determining if the resulting string is a valid physical repeated capability selector in context. Refer to section 5.9.2, Applying Virtual Identifier Mappings, of IVI-3.1: Driver Architecture Specification for a description of how software modules resolve virtual identifiers. The empty string is a legal value for this property only if the IVI Virtual Name object references a nonempty collection of IVI Virtual Range objects.
IVI-3.5: IVI Configuration Server Specification
118
IVI Foundation
16.3.2 Name COM Data Type BSTR
Access R/W
COM Property Name Name
C Constant Name IVICONFIG_VAL_VIRTUAL_NAME_NAME
Description The virtual identifier name. When the software module encounters the virtual identifier name in a repeated capability selector, it substitutes the Map To string for the virtual identifier. The software module is responsible for determining if the resulting string is a valid physical repeated capability selector in context. Refer to section 5.9.2, Applying Virtual Identifier Mappings, of IVI-3.1: Driver Architecture Specification for a description of how software modules resolve virtual identifiers. Name shall consist of one or more of the following characters: ‘a’-‘z’, ‘A’-‘Z’, ‘0’-‘9’, ‘!’, and ‘_’. The empty string is not a legal value for this property.
IVI Foundation
119
IVI-3.5: IVI Configuration Server Specification
17. IVI Virtual Range Class 17.1 IVI Virtual Range Overview The IVI Virtual Range class allows multiple virtual identifiers to be defined with a minimum of effort. An IVI Virtual Range object shall be referenced by exactly one IVI Virtual Name object. For a comprehensive overview of the treatment of repeated capabilities in the Configuration Server, including the role that virtual names play, refer to Section 2.9, Repeated Capabilities.
17.2 IVI Virtual Range Properties The IVI Virtual Range class defines the following properties: • Max • Min • Name • Starting Physical Index This section describes the behavior and requirements of each property.
IVI-3.5: IVI Configuration Server Specification
120
IVI Foundation
17.2.1 Max COM Data Type long
Access R/W
COM Property Name Max
C Constant Name IVICONFIG_VAL_VIRTUAL_RANGE_MAX
Description The upper bound of a range of integers to be appended to the Name property of the referencing IVI Virtual Name object to create a set of virtual repeated capability identifiers.
IVI Foundation
121
IVI-3.5: IVI Configuration Server Specification
17.2.2 Min COM Data Type long
Access R/W
COM Property Name Min
C Constant Name IVICONFIG_VAL_VIRTUAL_RANGE_MIN
Description The lower bound of a range of integers to be appended to the Name property of the referencing IVI Virtual Name object to create a set of virtual repeated capability identifiers.
IVI-3.5: IVI Configuration Server Specification
122
IVI Foundation
17.2.3 Name COM Data Type BSTR
Access R/W
COM Property Name Name
C Constant Name IVICONFIG_VAL_VIRTUAL_RANGE_NAME
Description The name of the IVI Virtual Range. This name is used to uniquely identify the range in the collection, and is not used in creating the set of virtual identifiers. The empty string is not a legal value for this property.
IVI Foundation
123
IVI-3.5: IVI Configuration Server Specification
17.2.4 Starting Physical Index COM Data Type long
Access R/W
COM Property Name StartingPhysicalIndex
C Constant Name IVICONFIG_VAL_VIRTUAL_RANGE_START_PHYSICAL_INDEX
Description When a range of integers is appended to the Name property of the referencing IVI Virtual Name object to create a set of virtual repeated capability identifiers, Starting Physical Index is added to each integer in the range, and the result is appended to the Map To property to obtain the corresponding set of physical identifiers.
IVI-3.5: IVI Configuration Server Specification
124
IVI Foundation
18. IVI Data Component Class 18.1 IVI Data Component Overview The IVI Data Component class is used to extend the set of properties that can be supported by other Configuration Server classes. This class is not implemented directly – it is a virtual base class. The following Configuration Server classes inherit from the IVI Data Component class: • IVI API Reference • IVI Boolean • IVI Integer • IVI Real • IVI String • IVI Structure Each of these classes inherits Name, Description, ReadOnly, Used In Session, and Type properties from IVI Data Component class. All IVI Configuration Server classes that inherit from the IVI Configurable Component class include a reference to a collection of IVI Data Components. In addition, the IVI Structure class also contains a reference to a collection of Data Components, allowing the hierarchical definition of a data components structure.
18.2 IVI Data Component Properties The IVI Data Component class defines the following properties: • Description • Help Context ID • Help File Path • Name • Read Only • Software Module Key • Type • Used In Session This section describes the behavior and requirements of each property.
IVI Foundation
125
IVI-3.5: IVI Configuration Server Specification
18.2.1 Description COM Data Type BSTR
Access R/W
COM Property Name Description
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_DESCRIPTION
Description A description of the IVI Data Component. The empty string is a legal value for this property.
IVI-3.5: IVI Configuration Server Specification
126
IVI Foundation
18.2.2 Help Context ID COM Data Type long
Access R/W
COM Property Name HelpContextID
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_HELP_CONTEXT_ID
Description The help context ID for the data component. The default value for this property shall be 0. The value of this property is not meaningful if the Help File property does not contain a valid help file pathname. If the Help File property does contain a valid help file pathname, Help Context ID shall return the help context ID for the topic in the help file that provides the help for the data component. The configuration server does not verify the content of this property. The person or tool that maintains the field is responsible for its validity.
IVI Foundation
127
IVI-3.5: IVI Configuration Server Specification
18.2.3 Help File Path COM Data Type BSTR
Access R/W
COM Property Name HelpFilePath
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_HELP_FILE_PATH
Description The fully qualified pathname of the help file that provides the help for the data component. The default value for this property shall be the empty string. If Help File Path is not the empty string, it shall contain the fully qualified pathname of a help file that conforms to one of the standard formats for Windows help. If Help File Path is not the empty string, Help Context ID shall return the help context ID for the topic in the help file that provides the help for the data component. The configuration server does not verify the content of this property. The person or tool that maintains the field is responsible for its validity.
IVI-3.5: IVI Configuration Server Specification
128
IVI Foundation
18.2.4 Name COM Data Type BSTR
Access R/W
COM Property Name Name
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_NAME
Description The name of the IVI Data Component. The empty string is not a legal value for this property.
IVI Foundation
129
IVI-3.5: IVI Configuration Server Specification
18.2.5 Read Only COM Data Type
Access
VARIANT_BOOL
R/W
COM Property Name ReadOnly
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_READ_ONLY
Description Indicates whether the value of the data component may be changed in a configuration store GUI. If True, a Configuration Utility must not allow the user to modify the contents of the data component object. If False, the associated data component objects may be read or written.
IVI-3.5: IVI Configuration Server Specification
130
IVI Foundation
18.2.6 Software Module Key COM Data Type BSTR
Access R/W
COM Property Name SoftwareModuleKey
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_SW_MODULE_KEY
Description A string that the software module uses to identify the internal software element that the data component applies to. If Used In Session is “None”, the value of this property shall be the empty string. If Used In Session is “Required” or “Optional”, the value of this property shall not be the empty string.
IVI Foundation
131
IVI-3.5: IVI Configuration Server Specification
18.2.7 Type COM Data Type BSTR
Access R/O
COM Property Name Type
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_TYPE
Description A string denoting the data type of the associated data element. Valid values for this field are “Structure”, “Integer”, “Real”, “Boolean”, “String”, and “APIReference”.
IVI-3.5: IVI Configuration Server Specification
132
IVI Foundation
18.2.8 Used In Session COM Data Type BSTR
Access R/W
COM Property Name UsedInSession
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_USED_IN_SESSION
Description This property determines whether a data component associated with a software module is used in a session that references the software module. The possible values are “Required”, “Optional”, and “None”. The values are case insensitive. For data components associated with software modules and sessions, Used In Session shall be “Required”, “Optional”, or “None”. For data components associated with hardware assets, Used In Session shall be “None”. If the value is “Required”, the data component must be present as part of a session’s data components, with a valid value, for the associated software module to operate correctly. If the value is “Optional”, the data component may be present as part of a session’s data components, but is not required for the associated software module to operate correctly. This allows the user to choose whether to override the driver’s default value. If the value is “None”, the data component is ignored by the software module. Its presence and value have no effect on the operation of the software module. The configuration server shall enforce the valid values for this field. If an invalid value is entered manually, the configuration server shall return an Invalid Value error.
IVI Foundation
133
IVI-3.5: IVI Configuration Server Specification
19. IVI Structure Class 19.1 IVI Structure Overview The IVI Structure class allows one collection of IVI Data Components to reference another collection of IVI Data Components. This allows data components to be structured hierarchically.
19.2 IVI Structure References The IVI Structure class defines the following reference: • DataComponents This section describes the reference.
IVI-3.5: IVI Configuration Server Specification
134
IVI Foundation
19.2.1 Data Components COM Data Type
C Data Type
IIviDataComponentCollection**
IviDataComponentCollectionHandle
Access R/O
COM Property Name DataComponents
C Function Prototype ViStatus _VI_FUNC IviConfig_GetStructureDataComponentCollection (IviDataComponentHandle StructureHandle, IviDataComponentCollectionHandle* DataComponentCollectionHandle);
Parameters Inputs
Description
Datatype
StructureHandle
Handle to an IviDataComponent object.
IviDataComponen tHandle
Outputs
Description
Datatype
DataComponentColl ectionHandle
Handle to an IviDataComponentCollection object.
IviDataComponen tCollectionHand le
Description References a collection of IVI Data Component objects. Circular references or a circular series of references are not allowed.
IVI Foundation
135
IVI-3.5: IVI Configuration Server Specification
19.3 IVI Structure Properties The following properties are inherited from IVI Data Component - Section 18, IVI Data Component Class • Description • Help Context ID • Help File Path • Name • Read Only • Software Module Key • Type • Used In Session In an IVI Structure object, Type shall be set to “Structure”.
IVI-3.5: IVI Configuration Server Specification
136
IVI Foundation
20. IVI Integer Class 20.1 IVI Integer Overview The IVI Integer class defines a 32-bit integer data type for use in the IVI configuration server. This includes an integer value and other type information. An IVI Integer object cannot exist independently of an IVI Data Components collection.
20.2 IVI Integer Properties The IVI Integer class defines the following properties: • Units • Value The following properties are inherited from IVI Data Component - Section 18, IVI Data Component Class • Description • Help Context ID • Help File Path • Name • Read Only • Software Module Key • Type • Used In Session In an IVI Integer object, type shall be set to “Integer”. This section describes the behavior and requirements of each property.
IVI Foundation
137
IVI-3.5: IVI Configuration Server Specification
20.2.1 Units COM Data Type BSTR
Access R/W
COM Property Name Units
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_UNITS
Description A string that specifies the units to be applied to Value. The empty string is a legal value for this property.
IVI-3.5: IVI Configuration Server Specification
138
IVI Foundation
20.2.2 Value COM Data Type long
Access R/W
COM Property Name Value
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_VALUE
Description The integer value of the data component.
IVI Foundation
139
IVI-3.5: IVI Configuration Server Specification
21. IVI Real Class 21.1 IVI Real Overview The IVI Real class defines a 64-bit real data type for use in the IVI configuration server. This includes a real value and other type information. An IVI Real object cannot exist independently of an IVI Data Components collection.
21.2 IVI Real Properties The IVI Real class defines the following properties: • Units • Value The following properties are inherited from IVI Data Component - Section 18, IVI Data Component Class • Description • Help Context ID • Help File Path • Name • Read Only • Software Module Key • Type • Used In Session In an IVI Real object, type shall be set to “Real”. This section describes the behavior and requirements of each property.
IVI-3.5: IVI Configuration Server Specification
140
IVI Foundation
21.2.1 Units COM Data Type BSTR
Access R/W
COM Property Name Units
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_UNITS
Description A string that specifies the units to be applied to Value. The empty string is a legal value for this property.
IVI Foundation
141
IVI-3.5: IVI Configuration Server Specification
21.2.2 Value COM Data Type double
Access R/W
COM Property Name Value
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_VALUE
Description The real value of the data component.
IVI-3.5: IVI Configuration Server Specification
142
IVI Foundation
22. IVI Boolean Class 22.1 IVI Boolean Overview The IVI Boolean class defines a Boolean data type for use in the IVI configuration server. This includes a Boolean value and other type information. An IVI Boolean object cannot exist independently of an IVI Data Components collection.
22.2 IVI Boolean Properties The IVI Boolean class defines the following properties: • Value The following properties are inherited from IVI Data Component - Section 18, IVI Data Component Class • Description • Help Context ID • Help File Path • Name • Read Only • Software Module Key • Type • Used In Session In an IVI Boolean object, type shall be set to “Boolean”. This section describes the behavior and requirements of each property.
IVI Foundation
143
IVI-3.5: IVI Configuration Server Specification
22.2.1 Value COM Data Type
Access
VARIANT_BOOL
R/W
COM Property Name Value
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_VALUE
Description The Boolean value of the data component.
IVI-3.5: IVI Configuration Server Specification
144
IVI Foundation
23. IVI String Class 23.1 IVI String Overview The IVI String class defines a string data type for use in the IVI configuration server. This includes a string value and other type information. An IVI String object cannot exist independently of an IVI Data Components collection.
23.2 IVI String Properties The IVI String class defines the following properties: • Value The following properties are inherited from IVI Data Component - Section 18, IVI Data Component Class • Description • Help Context ID • Help File Path • Name • Read Only • Software Module Key • Type • Used In Session In an IVI String object, Type shall be set to “String”. This section describes the behavior and requirements of each property.
IVI Foundation
145
IVI-3.5: IVI Configuration Server Specification
23.2.1 Value COM Data Type BSTR
Access R/W
COM Property Name Value
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_VALUE
Description The string value of the data component. The empty string is a legal value for this property.
IVI-3.5: IVI Configuration Server Specification
146
IVI Foundation
24. IVI API Reference Class 24.1 IVI API Reference Overview The IVI API Reference class defines a reference to a Published API data type for use in the Configuration Server. An IVI API Reference object cannot exist independently of an IVI Data Components collection. All API references are configurable initial settings for either a software module or a session. An IVI Software Module uses IVI API Reference objects to describe the published APIs that it uses (not the ones that it implements). A software module (the “using” software module) “uses” an API when it makes API calls to another software module (the “used” software module) that implements the API. When an IVI API Reference object is created at install time in a software module’s data components collection, the value of the Published API reference is set and may not be subsequently changed.
PI
When an IVI Session includes an IVI API Reference object, it associates the Published API with a session or driver session. This session configures the “used” software module chosen to implement the published API. The Value property is a session name or logical name. Get Session and Get Driver Session may be used to resolve the name to a session. Refer to Section 7.4.3, Get Session and Section 7.4.2, Get Driver Session for more details.
lish
A PI R e feren ce
Pu b
D a ta C o m p o n e n ts
P u b lish e d A PI
dA P
I
S o ft w a r e M o d u le
e dA
T y p ic a l S o f t w a r e M o d u le E n tr ie s
D a ta C o m p o n e n ts
A PI R e feren ce
Pu b
U sin g S ession
lish e
T y p ic a l S e s s io n C o n f ig u r a tio n
P u b lish e d A PI
V a lu e P u b lis h e d A P Is
U sin g S o ft w a r e M o d u le
U sed S ession
U sed S o ft w a r e M o d u le
Figure 24-1 Typical API Reference Configuration Store Entries Figure 24-1 shows two typical uses of the API reference data component. The first shows the set of configuration store entries for a software module that uses an API reference. The second shows the set of configuration store entries for a session that configures the software module. While an API Reference may be used by IVI Drivers, the typical use is for IVI-MSS components. Attempts to add an IVI API Reference object will fail with an Invalid Data Component error if one of the following conditions is true: • The data components collection to which is being added is referenced by an IVI Hardware Asset object. • Its Used In Session property is “None”.
IVI Foundation
147
IVI-3.5: IVI Configuration Server Specification
24.2 IVI API Reference References The IVI API Reference class defines the following reference: • Published API This section describes the reference.
IVI-3.5: IVI Configuration Server Specification
148
IVI Foundation
24.2.1 Published API COM Data Type IIviPublishedAPI*
C Data Type
Access
IviPublishedAPIHandle
R/W
COM Property Name PublishedAPI
C Function Prototype ViStatus _VI_FUNC IviConfig_GetAPIReferencePublishedAPIReference (IviDataComponentHandle ApiReferenceHandle, IviPublishedAPIsHandle* PublishedAPIsHandle); ViStatus _VI_FUNC IviConfig_SetAPIReferencePublishedAPIReference (IviDataComponentHandle ApiReferenceHandle, IviPublishedAPIsHandle PublishedAPIsHandle);
Parameters Inputs
Description
Datatype
APIReferenceHandl e
Handle to an IviDataComponent object.
IviDataComponen tHandle
Outputs
Description
Datatype
PublishedAPIHandl e
Handle to an IviPublishedAPI object.
IviPublishedAPI sHandle
Description The Published API property references a published API to be associated with the client role identified by the Name property. The Value property designates a session name that implements the published API.
IVI Foundation
149
IVI-3.5: IVI Configuration Server Specification
24.3 IVI API Reference Properties The IVI API Reference class defines the following properties: • Value The following properties are inherited from IVI Data Component - Section 18, IVI Data Component Class • Description • Help Context ID • Help File Path • Name • Read Only • Software Module Key • Type • Used In Session In an IVI API Reference object, Type shall be set to “APIReference”. This section describes the behavior and requirements of each property.
IVI-3.5: IVI Configuration Server Specification
150
IVI Foundation
24.3.1 Value COM Data Type BSTR
Access R/W
COM Property Name Value
C Constant Name IVICONFIG_VAL_DATA_COMPONENT_VALUE
Description A logical name or session name. Value can be passed to GetSession() or GetDrverSession() in the Name parameter. A session reference is returned according to the semantics defined for GetSession() and GetDriverSession(). The empty string is a legal value for this property.
IVI Foundation
151
IVI-3.5: IVI Configuration Server Specification
25. Configuration Server Error and Completion Codes The Configuration Server specification defines the following error codes in addition to the generic IVI error codes defined in IVI-3.2: Inherent Capabilities.
Table 25-1 Configuration Server Completion Codes Error Name
Description Language
Deserialize Failed
Already Deserialized
Serialize Failed
Session Not Found
Not In Global Collection
Duplicate Entry
Master Not Found
Does Not Exist
Invalid Data Component
Invalid Handle
Identifier
Value(hex)
The specified configuration store file could not be deserialized. C
IVICONFIG_ERROR_DESERIALIZE_FAILED
0xBFFA1200
COM
E_IVICONFIG_DESERIALIZE_FAILED
0x80041200
A deserialize was attempted after a previous deserialize had already succeeded. C
IVICONFIG_ERROR_ALREADY_DESERIALIZED
0xBFFA1201
COM
E_IVICONFIG_ALREADY_DESERIALIZED
0x80041201
The specified configuration store file could not be serialized. C
IVICONFIG_ERROR_SERIALIZE_FAILED
0xBFFA1202
COM
E_IVICONFIG_SERIALIZE_FAILED
0x80041202
The session name or logical name could not be resolved to a session or driver session. C
IVICONFIG_ERROR_SESSION_NOT_FOUND
0xBFFA1203
COM
E_IVICONFIG_SESSION_NOT_FOUND
0x80041203
The item does not exist in the global collection. C
IVICONFIG_ERROR_NOT_IN_GLOBAL
0xBFFA1204
COM
E_IVICONFIG_NOT_IN_GLOBAL
0x80041204
An entry with name already exists in the collection. C
IVICONFIG_ERROR_ALREADY_EXIST
0xBFFA1205
COM
E_IVICONFIG_ALREADY_EXIST
0x80041205
The registry entry for the master configuration store does not exist or the file could not be found. C
IVICONFIG_ERROR_MASTER_NOT_FOUND
0xBFFA1206
COM
E_IVICONFIG_MASTER_NOT_FOUND
0x80041206
The item does not exist in the collection. C
IVICONFIG_ERROR_NOT_EXIST
0xBFFA1207
COM
E_IVICONFIG_NOT_EXIST
0x80041207
The data component is not a valid data component. C
IVICONFIG_ERROR_INVALID_DATA_COMPONENT
0xBFFA1208
COM
E_IVICONFIG_INVALID_DATA_COMPONENT
0x80041208
The specified handle is invalid or of an incorrect type. C
IVICONFIG_ERROR_INVALID_HANDLE
COM
N/A
IVI-3.5: IVI Configuration Server Specification
152
0xBFFA1220
IVI Foundation
The specified property ID is not valid for this function.
Invalid Property ID
Reference Still Exists
C
IVICONFIG_ERROR_INVALID_PROPERTY_ID
COM
N/A
0xBFFA1221
The element cannot be removed from the global collection when it is referenced in the local collections. C
IVICONFIG_ERROR_LOCAL_REFERENCE_EXIST
0xBFFA1209
COM
E_IVICONFIG_LOCAL_REFERENCE_EXIST
0x80041209
Table 25-2 defines the format of the message string associated with the error. In C, this string is returned by the Error Message function. In COM, this string is the description contained in the ErrorInfo object.
Table 25-2. Configuration Server Error Message Strings Name
Message String
Deserialize Failed
“IviConfigServer.IviConfigStore.1: Deserialize failed. %1”
Already Deserialized
“IviConfigServer.IviConfigStore.1: A previous deserialize has already succeeded.”
Serialize Failed
“IviConfigServer.IviConfigStore.1: Serialize failed. %1”
Session Not Found
“IviConfigServer.IviConfigStore.1: Get%1 failed. Name %2 could not be resolved to a %1.”
Not In Global Collection
“IviConfigServer.IviConfigStore.1: %1 failed. %2 does not exist in the global collection or the object is not the same as in the global collection.”
Duplicate Entry
“IviConfigServer.IviConfigStore.1: %1 failed. %2 already exists in the collection.”
Master Not Found
“IviConfigServer.IviConfigStore.1: get_MasterLocation failed. The registry key does not exist or the file can not be found.”
Does Not Exist
“IviConfigServer.IviConfigStore.1: %1 failed. %2 does not exist in the collection.”
Invalid Data Component
“IviConfigServer.IviConfigStore.1: : %1 failed. The data component is not a valid data component. %2”
Invalid Handle
“IviConfigServer: %1: The specified handle is either invalid or is of an incorrect type.”
Invalid Property ID
“IviConfigStore: %1: The specified property ID is not a valid ID for this function.”
Reference Still Exists
“IviConfigStore: %1: %2 failed. The element cannot be removed from the global collection when it is referenced in the local collections.”
IVI Foundation
153
IVI-3.5: IVI Configuration Server Specification
26. Configuration Store Data Format Configuration Store data is stored in an XML file. The format is specified by a schema file, IviConfigurationStore.xsd which is installed in the same directory as the master configuration store file.
IVI-3.5: IVI Configuration Server Specification
154
IVI Foundation
27. Configuration Utility Implementation Guidelines Configuration utilities facilitate the process of “manually” editing of the configuration store. They are not specified by the IVI Foundation, and so discussion of implementation is confined to these guidelines. Users will prefer using a configuration utility to either manually editing the configuration store XML file using a text editor, or using the configuration server API to edit the configuration store as needed, since this requires programming. To provide this ease of use, configuration utilities may use a graphical user interface designed to perform the tasks that users must perform to review configuration store content and configure IVI instrument drivers and/or IVI-MSS role control modules. Vendors may choose to tailor the functionality of a configuration utility to particular business needs, or to develop a broadly applicable utility that performs many general configuration server tasks.
27.1 General Configuration utilities should always use the configuration server to make any modifications to any configuration store. Configuration utilities should preserve the data integrity of the configuration store as described in this specification. While the configuration server API handles quite a bit of the data integrity as described in this specification, some items must be handled by the configuration utility and those are described in the following guidelines.
27.2 Hardware Assets The configuration utility should allow users to add, modify, and delete hardware assets. The configuration utility should not limit the format of the IO Resource Descriptor so as to limit future potential formats for I/O addresses.
27.3 Published APIs The installation of a Software Module may add a Published API to the global collection. Configuration utilities may also add Published APIs, but they should be very careful about modifying or deleting them.
27.4 Software Modules Configuration utilities should not add or delete software modules to the master configuration store. Software modules are added to the configuration store when they are installed, and are deleted when they are uninstalled. Configuration utilities should not modify any of the data referenced directly or indirectly by software modules. The only exception is that they may add, modify, and delete documentation data components referenced by the software module. Configuration utilities may copy software modules to, and delete software modules from “slave” configuration stores. When they do, all of the referenced data should also be copied or deleted.
27.5 Sessions The configuration utility should allow users to add, modify, and delete sessions. Configuration utilities should be able to configure the configurable initial settings of a session accurately. That means modifying the Value property. Users should not be able to modify the following properties in a configurable initial setting: Description, Help Context ID, Help File Path, Name, Read Only, Software Module Key, Type, Used In Session or Units.
IVI Foundation
155
IVI-3.5: IVI Configuration Server Specification
27.6 Documentation Data Components Configuration utilities should add, modify, or delete documentation data components for a hardware asset, software module, or session accurately. In general, users may modify any property of documentation data components.
IVI-3.5: IVI Configuration Server Specification
156
IVI Foundation
28. Limitations 28.1 Distributed Systems Remote access to the Configuration Server has not been validated to work. Specifying this support will introduce new issues related to DCOM security and system configuration.
28.2 Concurrent Reading and Writing The Configuration Server does not support multiple concurrent writers or concurrent readers and writers. It does support multiple concurrent readers.
IVI Foundation
157
IVI-3.5: IVI Configuration Server Specification
Appendix A: IVI Configuration Server IDL file /************************************************************************* IviConfigServer.idl This source file was developed by and is the property of Agilent Technologies. Use and distribution of this file is governed by US Copyright law and the IVI Consortium Shared Open-Source Component Licensing agreement. Copyright 2002, Agilent Technologies *************************************************************************/ // This file will be processed by the MIDL tool to // produce the type library (IviConfigServer.tlb) and marshalling code. import "oaidl.idl"; import "ocidl.idl"; [ uuid(C6F576F5-7394-458E-B38A-C20C668585E7), version(1.0), helpstring("Ivi Configuration Server 1.0 Type Library") ] library IVICONFIGSERVERLib { importlib("stdole32.tlb"); importlib("stdole2.tlb"); typedef [ public, v1_enum, helpstring("Ivi Configuration Server Error Enum") ] enum IviConfigServerErrorEnum { E_IVICONFIG_DESERIALIZE_FAILED = 0x80041200, E_IVICONFIG_ALREADY_DESERIALIZED = 0x80041201, E_IVICONFIG_SERIALIZE_FAILED = 0x80041202, E_IVICONFIG_SESSION_NOT_FOUND = 0x80041203, E_IVICONFIG_NOT_IN_GLOBAL = 0x80041204, E_IVICONFIG_ALREADY_EXIST = 0x80041205, E_IVICONFIG_MASTER_NOT_FOUND = 0x80041206, E_IVICONFIG_NOT_EXIST = 0x80041207, E_IVICONFIG_INVALID_DATA_COMPONENT = 0x80041208, E_IVICONFIG_LOCAL_REFERENCE_EXIST = 0x80041209 } IviConfigServerErrorEnum; interface interface interface interface interface interface interface interface interface interface interface interface interface
IIviLogicalNameCollection; IIviSessionCollection; IIviPublishedAPICollection; IIviHardwareAssetCollection; IIviSoftwareModuleCollection; IIviDriverSessionCollection; IIviConfigComponent; IIviConfigStore; IIviSoftwareModule; IIviPhysicalName; IIviLogicalName; IIviHardwareAsset; IIviSession;
IVI-3.5: IVI Configuration Server Specification
158
IVI Foundation
interface interface interface interface interface interface interface interface interface interface interface interface interface interface interface interface interface interface interface
IIviPublishedAPI; IIviVirtualName; IIviVirtualNameCollection; IIviDataComponentCollection; IIviDriverSession; IIviPhysicalNameCollection; IIviPublishedAPI; IIviPublishedAPICollection; IIviVirtualRange; IIviPhysicalRange; IIviVirtualRangeCollection; IIviPhysicalRangeCollection; IIviDataComponent; IIviStructure; IIviAPIReference; IIviReal; IIviInteger; IIviString; IIviBoolean;
[ uuid(EBC90D48-10D2-4E40-AE35-C993E127B815), helpstring("IviConfigStore Class") ] coclass IviConfigStore { [default] interface IIviConfigStore; }; [ uuid(CB1A5E7B-AEE1-4967-B8B8-F490CACAC91E), helpstring("IIviConfigStore Interface"), dual, object, pointer_default(unique) ] interface IIviConfigStore : IDispatch { [id(0), propget] HRESULT Name([out,retval] BSTR* pVal); [id(1), propget] HRESULT Description([out,retval] BSTR* pVal); [id(1), propput] HRESULT Description([in] BSTR newVal); [propget, helpstring("property Vendor"), id(2)] HRESULT Vendor([out, retval] BSTR *pVal); [propget, helpstring("property Revision"), id(3)] HRESULT Revision([out, retval] BSTR *pVal); [id(4), propget] HRESULT SpecificationMajorVersion([out,retval] long* pVal); [id(5), propget] HRESULT SpecificationMinorVersion ([out,retval] long* pVal); [id(6), propget] HRESULT HardwareAssets([out,retval] IIviHardwareAssetCollection** pVal); [id(7), propget] HRESULT DriverSessions([out,retval] IIviDriverSessionCollection** pVal); [id(8), propget] HRESULT LogicalNames([out,retval] IIviLogicalNameCollection** pVal); [id(9), propget] HRESULT Sessions([out,retval] IIviSessionCollection** pVal); [id(10), propget] HRESULT PublishedAPIs([out,retval] IIviPublishedAPICollection** pVal); [id(11), propget] HRESULT SoftwareModules([out,retval] IIviSoftwareModuleCollection** pVal); [id(12)] IVI Foundation
159
IVI-3.5: IVI Configuration Server Specification
HRESULT Deserialize([in] BSTR DataStoreFileSpec); [id(13)] HRESULT Serialize([in] BSTR DataStoreFileSpec); [id(14)] HRESULT GetDriverSession(BSTR LogicalName, [out, retval] IIviDriverSession **pVal); [id(15)] HRESULT GetSession(BSTR LogicalName, [out, retval] IIviSession **pVal); [propget, id(16), helpstring("property MasterLocation")] HRESULT MasterLocation([out, retval] BSTR *pVal); [propget, id(17), helpstring("property ProcessDefaultLocation")] HRESULT ProcessDefaultLocation([out, retval] BSTR *pVal); [propput, id(17), helpstring("property ProcessDefaultLocation")] HRESULT ProcessDefaultLocation([in] BSTR newVal); [propget, id(18), helpstring("property ActualLocation")] HRESULT ActualLocation([out, retval] BSTR *pVal); }; [ uuid(6BC6718E-EEF2-4630-9E0B-C767DD27C49B), helpstring("IviSoftwareModule Class") ] coclass IviSoftwareModule { [default] interface IIviSoftwareModule; }; [ uuid(F0172C7A-620C-44BC-AA10-288901808128), helpstring("IIviSoftwareModule Interface"), dual, object, pointer_default(unique) ] interface IIviSoftwareModule : IDispatch { [id(0), propget] HRESULT Name([out,retval] BSTR* pRetVal); [id(0), propput] HRESULT Name([in] BSTR newVal); [id(1), propget] HRESULT Description([out,retval] BSTR* pRetVal); [id(1), propput] HRESULT Description([in] BSTR newVal); [id(2), propget] HRESULT ProgID([out,retval] BSTR* pRetVal); [id(2), propput] HRESULT ProgID([in] BSTR newVal); [id(3), propget, helpstring("property ModulePath")] HRESULT ModulePath([out,retval] BSTR* pRetVal); [id(3), propput, helpstring("property ModulePath")] HRESULT ModulePath([in] BSTR newVal); [id(4), propget] HRESULT Prefix([out,retval] BSTR* pRetVal); [id(4), propput] HRESULT Prefix([in] BSTR newVal); [id(5), propget] HRESULT SupportedInstrumentModels([out,retval] BSTR* pRetVal); [id(5), propput] HRESULT SupportedInstrumentModels([in] BSTR newVal); [id(7), propget] HRESULT DataComponents([out,retval] IIviDataComponentCollection** pRetVal); [id(8), propget] HRESULT PublishedAPIs([out,retval] IIviPublishedAPICollection** pRetVal);
IVI-3.5: IVI Configuration Server Specification
160
IVI Foundation
[propget, helpstring("property PhysicalNames"), id(9)] HRESULT PhysicalNames([out, retval] IIviPhysicalNameCollection * *pVal); }; [
uuid(7248E7EC-E3A0-47C2-B70B-56C19BD428DC), helpstring("IviHardwareAssetCollection Class")
] coclass IviHardwareAssetCollection { [default] interface IIviHardwareAssetCollection; }; [ uuid(FA1B41A4-2667-4C67-B6C1-9945251EF37D), helpstring("IIviHardwareAssetCollection Interface"), dual, object, pointer_default(unique) ] interface IIviHardwareAssetCollection : IDispatch { [id(1)] HRESULT Add([in] IIviHardwareAsset *pVal); [id(2), propget] HRESULT Count([out, retval] long* pVal); [id(DISPID_VALUE), propget] HRESULT Item([in] VARIANT varIndex,[out, retval]IIviHardwareAsset**pVal); [id(DISPID_NEWENUM), propget] HRESULT _NewEnum([out, retval] IUnknown** ppunkEnum); [id(3)] HRESULT Remove([in] VARIANT varIndex); }; [ uuid(7EE56C3F-5EB7-40D4-81A9-ED682BFA4DB7), helpstring("IviPhysicalName Class") ] coclass IviPhysicalName { [default] interface IIviPhysicalName; };
[ uuid(838FA3E6-307A-46C4-A601-53D0986894B9), helpstring("IviLogicalName Class") ] coclass IviLogicalName { [default] interface IIviLogicalName; }; [ uuid(8224C215-B122-499C-899F-3E73D2C80551), helpstring("IviHardwareAsset Class") ] coclass IviHardwareAsset { [default] interface IIviHardwareAsset; };
IVI Foundation
161
IVI-3.5: IVI Configuration Server Specification
[ uuid(6A6B75C4-3DEE-4DEC-B281-BD5D463B25E2), helpstring("IviSession Class") ] coclass IviSession { [default] interface IIviSession; }; [ uuid(EF53811B-90B3-49D4-B85C-714BD6DC125E), helpstring("IviRoleName Class") ] coclass IviPublishedAPI { [default] interface IIviPublishedAPI; }; [ uuid(E55DF0EF-A4A3-4A5A-A241-607E88539634), helpstring("IviVirtualName Class") ] coclass IviVirtualName { [default] interface IIviVirtualName; }; [ uuid(C9A9FAE4-7B99-4DE2-B921-ABDA914C2FBD), helpstring("IIviPhysicalName Interface"), dual, object, pointer_default(unique) ] interface IIviPhysicalName : IDispatch { [id(0), propget] HRESULT Name([out,retval] BSTR* pRetVal); [id(0), propput] HRESULT Name([in] BSTR newVal); [propget, helpstring("property PhysicalNames"), id(1)] HRESULT PhysicalNames([out, retval] IIviPhysicalNameCollection **pVal); [propget, helpstring("property RCName"), id(2)] HRESULT RCName([out, retval] BSTR *pVal); [propput, helpstring("property RCName"), id(2)] HRESULT RCName([in] BSTR newVal); [propget, helpstring("property PhysicalRanges"), id(3)] HRESULT PhysicalRanges([out, retval] IIviPhysicalRangeCollection * *pVal); }; [ uuid(CFCFC60C-EA96-44E7-895C-93FB6013FE20), helpstring("IIviLogicalName Interface"), dual, object, pointer_default(unique) ] interface IIviLogicalName : IDispatch { [id(0), propget] HRESULT Name([out,retval] BSTR* pRetVal); [id(0), propput] HRESULT Name([in] BSTR newVal); IVI-3.5: IVI Configuration Server Specification
162
IVI Foundation
[id(1), HRESULT [id(1), HRESULT [id(2), HRESULT [id(2), HRESULT
propget] Description([out,retval] BSTR* pRetVal); propput] Description([in] BSTR newVal); propget] Session([out,retval] IIviSession** pRetVal); propputref] Session([in] IIviSession* newVal);
}; [ uuid(EA0DCA91-704B-48E6-99B4-9E32440571F7), helpstring("IIviPublishedAPI Interface"), dual, object, pointer_default(unique) ] interface IIviPublishedAPI : IDispatch { [id(0), propget] HRESULT Name([out,retval] BSTR* pRetVal); [id(0), propput] HRESULT Name([in] BSTR newVal); [propget, id(1), helpstring("property MajorVersion")] retval] long *pVal); [propput, id(1), helpstring("property MajorVersion")] long newVal); [propget, id(2), helpstring("property MinorVersion")] retval] long *pVal); [propput, id(2), helpstring("property MinorVersion")] long newVal); [propget, id(3), helpstring("property Type")] HRESULT *pVal); [propput, id(3), helpstring("property Type")] HRESULT
HRESULT MajorVersion([out, HRESULT MajorVersion([in] HRESULT MinorVersion([out, HRESULT MinorVersion([in] Type([out, retval] BSTR Type([in] BSTR newVal);
};
[ uuid(49E73D41-FA90-4B68-B01A-CE655AF6C238), helpstring("IIviHardwareAsset Interface"), dual, object, pointer_default(unique) ] interface IIviHardwareAsset : IDispatch { [id(1), propget] HRESULT Name([out,retval] BSTR* pRetVal); [id(1), propput] HRESULT Name([in] BSTR newVal); [id(2), propget] HRESULT Description([out,retval] BSTR* pRetVal); [id(2), propput] HRESULT Description([in] BSTR newVal); [id(3), propget] HRESULT IOResourceDescriptor([out,retval] BSTR* pRetVal); [id(3), propput] HRESULT IOResourceDescriptor([in] BSTR newVal); [id(4), propget] HRESULT DataComponents([out,retval] IIviDataComponentCollection** pRetVal); }; [ IVI Foundation
163
IVI-3.5: IVI Configuration Server Specification
uuid(B106D7AB-1D5B-4857-ADBB-22C8C5B7307C), helpstring("IIviVirtualName Interface"), dual, object, pointer_default(unique) ] interface IIviVirtualName : IDispatch { [id(0), propget] HRESULT Name([out,retval] BSTR* pRetVal); [id(0), propput] HRESULT Name([in] BSTR newVal); [propget, helpstring("property MapTo"), id(1)] HRESULT MapTo([out, retval] BSTR *pVal); [propput, helpstring("property MapTo"), id(1)] HRESULT MapTo([in] BSTR newVal); [propget, helpstring("property VirtualRanges"), id(2)] HRESULT VirtualRanges([out, retval] IIviVirtualRangeCollection * *pVal); }; [ uuid(3221CA37-4D77-46A1-936C-60A9E7D68476), helpstring("IIviSession Interface"), dual, object, pointer_default(unique) ] interface IIviSession : IDispatch { [id(0), propget] HRESULT Name([out,retval] BSTR* pRetVal); [id(0), propput] HRESULT Name([in] BSTR newVal); [id(1), propget] HRESULT Description([out,retval] BSTR* pRetVal); [id(1), propput] HRESULT Description([in] BSTR newVal); [id(2), propget] HRESULT DataComponents([out,retval] IIviDataComponentCollection** pRetVal); [id(3), propget] HRESULT HardwareAsset([out,retval] IIviHardwareAsset** pRetVal); [id(3), propputref] HRESULT HardwareAsset([in] IIviHardwareAsset* newVal); [id(4), propget] HRESULT VirtualNames([out,retval] IIviVirtualNameCollection** pRetVal); [id(5), propget] HRESULT SoftwareModule([out,retval] IIviSoftwareModule** pRetVal); [id(5), propputref] HRESULT SoftwareModule([in] IIviSoftwareModule* newVal); [id(6), propget] HRESULT SoftwareModuleName([out,retval] BSTR * name); };
[
uuid(D90E0437-D890-40F9-8044-B100CC48CCA3), helpstring("IviVirtualNameCollection Class")
] coclass IviVirtualNameCollection { [default] interface IIviVirtualNameCollection; }; [ IVI-3.5: IVI Configuration Server Specification
164
IVI Foundation
uuid(409C4FF6-25DB-4C89-867E-0D794A6EB1B3), helpstring("IIviVirtualNameCollection Interface"), dual, object, pointer_default(unique) ] interface IIviVirtualNameCollection : IDispatch { [helpstring("method Add"), id(1)] HRESULT Add([in] IIviVirtualName *pVal); [propget, id(2)] HRESULT Count([out, retval] long* pVal); [propget, id(DISPID_VALUE)] HRESULT Item([in] VARIANT varIndex,[out, retval]IIviVirtualName**pVal); [propget, id(DISPID_NEWENUM)] HRESULT _NewEnum([out, retval] IUnknown** ppunkEnum); [id(3)] HRESULT Remove([in] VARIANT varIndex); }; [ uuid(3486A6CB-52F6-44F6-8A53-FD012B221204), helpstring("IviDataComponentCollection Class") ] coclass IviDataComponentCollection { [default] interface IIviDataComponentCollection; }; [
uuid(9C8C5AF3-D308-4F0C-BB47-1B073CBA760E), helpstring("IIviDataComponentCollection Interface"), dual, object, pointer_default(unique)
] interface IIviDataComponentCollection : IDispatch { [helpstring("method Add"), id(1)] HRESULT Add([in] IIviDataComponent *); [propget, id(2)] HRESULT Count([out, retval] long* pVal); [propget, id(DISPID_VALUE)] HRESULT Item([in] VARIANT varIndex,[out, retval]IIviDataComponent**pVal); [propget, id(DISPID_NEWENUM)] HRESULT _NewEnum([out, retval] IUnknown** ppunkEnum); [id(3)] HRESULT Remove([in] VARIANT varIndex); }; [ uuid(31C4C811-A98B-4008-9DDB-2BB642D97B06), helpstring("IviRoleNameCollection Class") ] coclass IviPublishedAPICollection { [default] interface IIviPublishedAPICollection; }; [ uuid(2D4258A6-4D9F-4C9A-921B-3DAA96366C8F), helpstring("IIviPublishedAPICollection Interface"), dual, object, pointer_default(unique) IVI Foundation
165
IVI-3.5: IVI Configuration Server Specification
] interface IIviPublishedAPICollection : IDispatch { [id(1)] HRESULT Add([in] IIviPublishedAPI *pVal); [propget, id(2)] HRESULT Count([out, retval] long* pVal); [propget, id(DISPID_VALUE)] HRESULT Item([in] VARIANT varIndex, [in] long MajorVersion, [in] long MinorVersion, [in] BSTR Type, [out, retval]IIviPublishedAPI**pVal); [propget, id(DISPID_NEWENUM)] HRESULT _NewEnum([out, retval] IUnknown** ppunkEnum); [id(3)] HRESULT Remove([in] VARIANT varIndex, [in] long MajorVersion, [in] long MinorVersion, [in] BSTR Type); }; [
uuid(EDF186A7-0AE1-487B-AE60-587812FA72D6), helpstring("IviSoftwareModuleCollection Class")
] coclass IviSoftwareModuleCollection { [default] interface IIviSoftwareModuleCollection; }; [ uuid(D97EEC1E-9906-48F9-8414-6574AA9F0377), helpstring("IIviSoftwareModuleCollection Interface"), dual, object, pointer_default(unique) ] interface IIviSoftwareModuleCollection : IDispatch { [id(1)] HRESULT Add([in] IIviSoftwareModule *pVal); [propget, id(2)] HRESULT Count([out, retval] long* pVal); [propget, id(DISPID_VALUE)] HRESULT Item([in] VARIANT varIndex,[out, retval]IIviSoftwareModule**pVal); [propget, id(DISPID_NEWENUM)] HRESULT _NewEnum([out, retval] IUnknown** ppunkEnum); [id(3)] HRESULT Remove([in] VARIANT varIndex); }; [ uuid(D349355E-56C0-4D73-8A8B-CA3F7407A357), helpstring("IviDriverSession Class") ] coclass IviDriverSession { [default] interface IIviDriverSession; };
[ uuid(3FB118A4-FDB1-4CE3-84FE-1315FB026C33), helpstring("IIviDriverSession Interface"), dual, object, pointer_default(unique) IVI-3.5: IVI Configuration Server Specification
166
IVI Foundation
] interface IIviDriverSession : IIviSession { [id(7), propget] HRESULT DriverSetup([out,retval] BSTR* pVal); [id(7), propput] HRESULT DriverSetup([in] BSTR newVal); [id(8), propget] HRESULT Cache([out,retval] VARIANT_BOOL* pVal); [id(8), propput] HRESULT Cache([in] VARIANT_BOOL newVal); [id(9), propget] HRESULT InterchangeCheck([out,retval] VARIANT_BOOL* pVal); [id(9), propput] HRESULT InterchangeCheck([in] VARIANT_BOOL newVal); [id(10), propget] HRESULT QueryInstrStatus([out,retval] VARIANT_BOOL* pVal); [id(10), propput] HRESULT QueryInstrStatus([in] VARIANT_BOOL newVal); [id(11), propget] HRESULT RangeCheck([out,retval] VARIANT_BOOL* pVal); [id(11), propput] HRESULT RangeCheck([in] VARIANT_BOOL newVal); [id(12), propget] HRESULT RecordCoercions([out,retval] VARIANT_BOOL* pVal); [id(12), propput] HRESULT RecordCoercions([in] VARIANT_BOOL newVal); [id(13), propget] HRESULT Simulate([out,retval] VARIANT_BOOL* pVal); [id(13), propput] HRESULT Simulate([in] VARIANT_BOOL newVal); }; [ uuid(C8E3D0D2-B529-411E-A13E-161DA7C29454), helpstring("IviDriverSessionCollection Class") ] coclass IviDriverSessionCollection { [default] interface IIviDriverSessionCollection; }; [ uuid(9851A673-2452-4A7E-B7AA-A6EAB8A5055B), helpstring("IIviDriverSessionCollection Interface"), dual, object, pointer_default(unique) ] interface IIviDriverSessionCollection : IDispatch { [id(1)] HRESULT Add([in] IIviDriverSession *pVal); [propget, id(2)] HRESULT Count([out, retval] long* pVal); [propget, id(DISPID_VALUE)] HRESULT Item([in] VARIANT varIndex,[out, retval]IIviDriverSession**pVal); [propget, id(DISPID_NEWENUM)] HRESULT _NewEnum([out, retval] IUnknown** ppunkEnum); [id(3)] HRESULT Remove([in] VARIANT varIndex); };
IVI Foundation
167
IVI-3.5: IVI Configuration Server Specification
[ uuid(E3042EA2-1718-4216-9C06-1DDABF124BB3), helpstring("IIviDataComponent Interface"), dual, object, pointer_default(unique) ] interface IIviDataComponent : IDispatch { [propget, helpstring("property Name"), id(1)] HRESULT Name([out, retval] BSTR *pVal); [propput, helpstring("property Name"), id(1)] HRESULT Name([in] BSTR newVal); [propget, helpstring("property Description"), id(2)] HRESULT Description([out, retval] BSTR *pVal); [propput, helpstring("property Description"), id(2)] HRESULT Description([in] BSTR newVal); [propget, helpstring("property UsedInSession"), id(3)] HRESULT UsedInSession([out, retval] BSTR *pVal); [propput, helpstring("property UsedInSession"), id(3)] HRESULT UsedInSession([in] BSTR newVal); [propget, helpstring("property Type"), id(4)] HRESULT Type([out, retval] BSTR *pVal); [propget, helpstring("property ReadOnly"), id(5)] HRESULT ReadOnly([out, retval] VARIANT_BOOL *pVal); [propput, helpstring("property ReadOnly"), id(5)] HRESULT ReadOnly([in] VARIANT_BOOL newVal); [propget, helpstring("property HelpContextID"), id(6)] HRESULT HelpContextID([out, retval] long *pVal); [propput, helpstring("property HelpContextID"), id(6)] HRESULT HelpContextID([in] long newVal); [propget, helpstring("property HelpFilePath"), id(7)] HRESULT HelpFilePath([out, retval] BSTR *pVal); [propput, helpstring("property HelpFilePath"), id(7)] HRESULT HelpFilePath([in] BSTR newVal); [propget, helpstring("property SoftwareModuleKey"), id(8)] HRESULT SoftwareModuleKey([out, retval] BSTR *pVal); [propput, helpstring("property SoftwareModuleKey"), id(8)] HRESULT SoftwareModuleKey([in] BSTR newVal); }; [
uuid(ECA7E07E-0A9D-4750-92D1-CFD8F9DB2CA3), helpstring("IviLogicalNameCollection Class")
] coclass IviLogicalNameCollection { [default] interface IIviLogicalNameCollection; }; [ uuid(B7957C4F-D86B-47E7-8384-895ABBE654AB), helpstring("IIviLogicalNameCollection Interface"), dual, object, pointer_default(unique) ] interface IIviLogicalNameCollection : IDispatch { [id(1)] HRESULT Add([in] IIviLogicalName *pVal); [propget, id(2)] HRESULT Count([out, retval] long* pVal); [propget, id(DISPID_VALUE)] IVI-3.5: IVI Configuration Server Specification
168
IVI Foundation
HRESULT Item([in] VARIANT varIndex,[out, retval]IIviLogicalName**pVal); [propget, id(DISPID_NEWENUM)] HRESULT _NewEnum([out, retval] IUnknown** ppunkEnum); [id(3)] HRESULT Remove([in] VARIANT varIndex); }; [ uuid(49031FD4-9E0B-40AF-BB4E-DF9D9DAB5750), helpstring("IviSessionCollection Class") ] coclass IviSessionCollection { [default] interface IIviSessionCollection; }; [
uuid(F5F6AB1A-06D1-43E4-88BA-750F112B4B0F), helpstring("IIviSessionCollection Interface"), dual, object, pointer_default(unique)
] interface IIviSessionCollection : IDispatch { [id(1)] HRESULT Add([in] IIviSession *pVal); [propget, id(2)] HRESULT Count([out, retval] long* pVal); [propget, id(DISPID_VALUE)] HRESULT Item([in] VARIANT varIndex,[out, retval]IIviSession**pVal); [propget, id(DISPID_NEWENUM)] HRESULT _NewEnum([out, retval] IUnknown** ppunkEnum); [id(3)] HRESULT Remove([in] VARIANT varIndex); };
[ uuid(14527192-79F0-4BCE-AE03-4C534D16858B), helpstring("IviPhysicalNameCollection Class")
] coclass IviPhysicalNameCollection { [default] interface IIviPhysicalNameCollection; }; [ uuid(273B5A6E-2D37-4C1F-85BA-AF1C4F8D65E0), helpstring("IIviPhysicalNameCollection Interface"), dual, object, pointer_default(unique)
] interface IIviPhysicalNameCollection : IDispatch { [id(1)] HRESULT Add([in] IIviPhysicalName *pVal); [propget, id(2)] HRESULT Count([out, retval] long* pVal); [propget, id(DISPID_VALUE)] HRESULT Item([in] VARIANT varIndex,[out, retval]IIviPhysicalName**pVal); [propget, id(DISPID_NEWENUM)] IVI Foundation
169
IVI-3.5: IVI Configuration Server Specification
HRESULT _NewEnum([out, retval] IUnknown** ppunkEnum); [id(3)] HRESULT Remove([in] VARIANT varIndex); }; [ uuid(8F44405A-8DD1-11D5-8F8F-0060B0FC9326), helpstring("IviVirtualRange Class") ] coclass IviVirtualRange { [default] interface IIviVirtualRange; }; [ uuid(8F44405B-8DD1-11D5-8F8F-0060B0FC9326), helpstring("IIviVirtualRange Interface"), dual, object, pointer_default(unique) ] interface IIviVirtualRange : IDispatch { [propget, helpstring("property Min"), id(1)] HRESULT Min([out, retval] long *pVal); [propput, helpstring("property Min"), id(1)] HRESULT Min([in] long newVal); [propget, helpstring("property Max"), id(2)] HRESULT Max([out, retval] long *pVal); [propput, helpstring("property Max"), id(2)] HRESULT Max([in] long newVal); [propget, helpstring("property Name"), id(3)] HRESULT Name([out, retval] BSTR *pVal); [propput, helpstring("property Name"), id(3)] HRESULT Name([in] BSTR newVal); [propget, helpstring("property StartingPhysicalIndex"), id(4)] HRESULT StartingPhysicalIndex([out, retval] long *pVal); [propput, helpstring("property StartingPhysicalIndex"), id(4)] HRESULT StartingPhysicalIndex([in] long newVal); }; [ uuid(8F444069-8DD1-11D5-8F8F-0060B0FC9326), helpstring("IviPhysicalRange Class")
] coclass IviPhysicalRange { [default] interface IIviPhysicalRange; }; [
uuid(8F44406A-8DD1-11D5-8F8F-0060B0FC9326), helpstring("IIviPhysicalRange Interface"), dual, object, pointer_default(unique)
] interface IIviPhysicalRange : IDispatch { [propget, helpstring("property Max"), *pVal); [propput, helpstring("property Max"), [propget, helpstring("property Min"), *pVal); [propput, helpstring("property Min"),
IVI-3.5: IVI Configuration Server Specification
id(1)] HRESULT Max([out, retval] long id(1)] HRESULT Max([in] long newVal); id(2)] HRESULT Min([out, retval] long id(2)] HRESULT Min([in] long newVal);
170
IVI Foundation
[propget, helpstring("property Name"), id(3)] HRESULT Name([out, retval] BSTR *pVal); [propput, helpstring("property Name"), id(3)] HRESULT Name([in] BSTR newVal); }; [ uuid(8F44407A-8DD1-11D5-8F8F-0060B0FC9326), helpstring("IviVirtualRangeCollection Class") ] coclass IviVirtualRangeCollection { [default] interface IIviVirtualRangeCollection; }; [ uuid(8F444084-8DD1-11D5-8F8F-0060B0FC9326), helpstring("IviPhysicalRangeCollection Class")
] coclass IviPhysicalRangeCollection { [default] interface IIviPhysicalRangeCollection; }; [ uuid(8F444085-8DD1-11D5-8F8F-0060B0FC9326), helpstring("IIviPhysicalRangeCollection Interface"), dual, object, pointer_default(unique)
] interface IIviPhysicalRangeCollection : IDispatch { [helpstring("method Add"), id(1)] HRESULT Add([in] IIviPhysicalRange * pVal); [helpstring("method Remove"), id(2)] HRESULT Remove([in] VARIANT varIndex); [propget, helpstring("property Count"), id(3)] HRESULT Count([out, retval] long *pVal); [propget, helpstring("property Item"), id(DISPID_VALUE)] HRESULT Item([in] VARIANT varIndex, [out, retval] IIviPhysicalRange * *pVal); [propget, helpstring("property _NewEnum"), id(DISPID_NEWENUM)] HRESULT _NewEnum([out, retval] IUnknown * *pVal); }; [ uuid(8F44407B-8DD1-11D5-8F8F-0060B0FC9326), helpstring("IIviVirtualRangeCollection Interface"), dual, object, pointer_default(unique) ] interface IIviVirtualRangeCollection : IDispatch { [helpstring("method Add"), id(1)] HRESULT Add([in] IIviVirtualRange * pVal); [propget, helpstring("property Count"), id(2)] HRESULT Count([out, retval] long *pVal ); [propget, helpstring("property Item"), id(DISPID_VALUE)] HRESULT Item([in] VARIANT varIndex, [out, retval] IIviVirtualRange * *pVal); [helpstring("method Remove"), id(5)] HRESULT Remove([in] VARIANT varIndex); [propget, helpstring("property _NewEnum"), id(DISPID_NEWENUM)] HRESULT _NewEnum([out, retval] IUnknown * *pVal); }; [ uuid(52272C88-903E-11D5-8F90-0060B0FC9326), IVI Foundation
171
IVI-3.5: IVI Configuration Server Specification
helpstring("IviStructure Class") ] coclass IviStructure { [default] interface IIviStructure; }; [ uuid(52272C89-903E-11D5-8F90-0060B0FC9326), helpstring("IIviStructure Interface"), dual, object, pointer_default(unique) ] interface IIviStructure : IIviDataComponent { [propget, helpstring("property DataComponents"), id(9)] HRESULT DataComponents([out, retval] IIviDataComponentCollection * *pVal); }; [ uuid(E15B3F69-90FA-11D5-8F90-0060B0FC9326), helpstring("IviBoolean Class") ] coclass IviBoolean { [default] interface IIviBoolean; }; [
uuid(E15B3F6F-90FA-11D5-8F90-0060B0FC9326), helpstring("IviInteger Class")
] coclass IviInteger { [default] interface IIviInteger; }; [ uuid(E15B3F73-90FA-11D5-8F90-0060B0FC9326), helpstring("IviAPIReference Class") ] coclass IviAPIReference { [default] interface IIviAPIReference; }; [ uuid(E15B3F71-90FA-11D5-8F90-0060B0FC9326), helpstring("IviString Class") ] coclass IviString { [default] interface IIviString; }; [ uuid(E15B3F6D-90FA-11D5-8F90-0060B0FC9326), helpstring("IviReal Class") ] coclass IviReal { [default] interface IIviReal; }; [ IVI-3.5: IVI Configuration Server Specification
172
IVI Foundation
uuid(E15B3F72-90FA-11D5-8F90-0060B0FC9326), helpstring("IIviString Interface"), dual, object, pointer_default(unique) ] interface IIviString : IIviDataComponent { [propget, helpstring("property Value"), id(9)] HRESULT Value([out, retval] BSTR *pVal); [propput, helpstring("property Value"), id(9)] HRESULT Value([in] BSTR newVal); }; [ uuid(E15B3F6E-90FA-11D5-8F90-0060B0FC9326), helpstring("IIviReal Interface"), dual, object, pointer_default(unique) ] interface IIviReal : IIviDataComponent { [propget, helpstring("property Units"), *pVal); [propput, helpstring("property Units"), [propget, helpstring("property Value"), double *pVal); [propput, helpstring("property Value"), newVal); };
id(9)] HRESULT Units([out, retval] BSTR id(9)] HRESULT Units([in] BSTR newVal); id(10)] HRESULT Value([out, retval] id(10)] HRESULT Value([in] double
[ uuid(E15B3F74-90FA-11D5-8F90-0060B0FC9326), helpstring("IIviAPIReference Interface"), dual, object, pointer_default(unique) ] interface IIviAPIReference : IIviDataComponent { [propget, helpstring("property Value"), id(9)] HRESULT Value([out, retval] BSTR *pVal); [propput, helpstring("property Value"), id(9)] HRESULT Value([in] BSTR newVal); [propget, helpstring("property PublishedAPI"), id(10)] HRESULT PublishedAPI([out, retval] IIviPublishedAPI **pVal); [propputref, helpstring("property PublishedAPI"), id(10)] HRESULT PublishedAPI([in] IIviPublishedAPI * newVal); }; [ uuid(E15B3F6A-90FA-11D5-8F90-0060B0FC9326), helpstring("IIviBoolean Interface"), dual, object, pointer_default(unique) ] interface IIviBoolean : IIviDataComponent { [propget, helpstring("property Value"), id(9)] HRESULT Value([out, retval] VARIANT_BOOL *pVal); [propput, helpstring("property Value"), id(9)] HRESULT Value([in] VARIANT_BOOL newVal); }; IVI Foundation
173
IVI-3.5: IVI Configuration Server Specification
[ uuid(E15B3F70-90FA-11D5-8F90-0060B0FC9326), helpstring("IIviInteger Interface"), dual, object, pointer_default(unique) ] interface IIviInteger : IIviDataComponent { [propget, helpstring("property Units"), *pVal); [propput, helpstring("property Units"), [propget, helpstring("property Value"), *pVal); [propput, helpstring("property Value"), }; };
IVI-3.5: IVI Configuration Server Specification
174
id(9)] HRESULT Units([out, retval] BSTR id(9)] HRESULT Units([in] BSTR newVal); id(10)] HRESULT Value([out, retval] long id(10)] HRESULT Value([in] long newVal);
IVI Foundation
Appendix B: IVI-COM Driver Example The focus of this example is an imaginary IVI-COM instrument specific driver. The driver supports a family of oscilloscopes from GizmoTronics , Inc. The driver supports the IVI inherent interfaces and the IVI scope class-compliant interfaces. In addition to the standard IVI configuration properties, the driver can be configured from the configuration server to turn tracing on and off. The driver supports four channels that it knows as “C1” through “C4”. All examples are in Visual Basic, and may be abbreviated to emphasize configuration server use. The configuration server code that needs to be run when the driver is installed looks like this. Option Explicit Private Sub AddSoftwareModule() Dim Dim Dim Dim Dim Dim
cs As New IviConfigStore sm As IviSoftwareModule pa As IviPublishedAPI pn As IviPhysicalName pr As IviPhysicalRange dcb As IviBoolean
'// Deserialize the master configuration store. On Error GoTo DeserializeError cs.Deserialize cs.MasterLocation On Error GoTo 0 '// Delete the old version of the driver On Error Resume Next cs.SoftwareModules.Remove "gt40xx" On Error GoTo 0 '// Make sure that the Published API entries used by the software module '// exist in the global Published API collection. Set pa = New IviPublishedAPI pa.Name = "IviDriver" pa.Type = "IVI-COM" pa.MajorVersion = 2 pa.MinorVersion = 0 '// If the API is already in the collection, what follows will return '// an error, but it doesn't need to be trapped because the API '// exists in the collection, which is what we want. On Error Resume Next cs.PublishedAPIs.Add pa On Error GoTo 0 Set pa = New IviPublishedAPI pa.Name = "IviScope" pa.Type = "IVI-COM" pa.MajorVersion = 2 pa.MinorVersion = 0 '// If the API is already in the collection, what follows will return '// an error, but it doesn't need to be trapped because the API '// exists in the collection, which is what we want. IVI Foundation
175
IVI-3.5: IVI Configuration Server Specification
On Error Resume Next cs.PublishedAPIs.Add pa On Error GoTo 0 '// Create the new software module entry Set sm = New IviSoftwareModule sm.Name = "gt40xx" sm.Description = "IVI-COM Specific Instrument Driver for GT40xx family of oscilloscopes" sm.Prefix = "gt40xx" sm.ProgId = "gt40xx.gt40xx" sm.ModulePath = "" sm.SupportedInstrumentModels = "gt4000,gt4001,gt4010,gt4011,gt4012" '// Add the Published API entries to the software module sm.PublishedAPIs.Add cs.PublishedAPIs.Item("IviDriver", 2, 0, "IVI-COM") sm.PublishedAPIs.Add cs.PublishedAPIs.Item("IviScope", 2, 0, "IVI-COM") '// Add the physical name and physical range entries Set pn = New IviPhysicalName pn.Name = "C" pn.RCName = "Channel" sm.PhysicalNames.Add pn Set pr = New IviPhysicalRange pr.Name = "C Range 1" pr.Max = 4 pr.Min = 1 pn.PhysicalRanges.Add pr '// Add the data components Set dcb = New IviBoolean dcb.Name = "Trace" dcb.Description = "If True, tracing is on, if False, tracing is off" '// dcb.Type automatically set to "Boolean" by the API dcb.ReadOnly = True dcb.UsedInSession = "Required" '// Software module will default to False dcb.Value = False '// False is the default configuration value sm.DataComponents.Add dcb cs.SoftwareModules.Add sm
Exit Sub DeserializeError: '// Handle the error appropriately. End Sub
Now create a session for the driver. A logical name (“Bob”) will refer to the session. The session will refer to a hardware asset whose resource descriptor is “GPIB0::12::INSTR”. It will also provide logical names for the software modules physical names and configure the values of the trace data component. The configuration server code that needs to be run when a session is created for the driver software module follows. Bear in mind that most end-users will use a GUI to edit the configuration store, but some users may choose to write code like this – for example, as part of a test system. In any case, this example code is
IVI-3.5: IVI Configuration Server Specification
176
IVI Foundation
meant to illustrate the kinds of configuration server entries that must be made. It is not meant to be bulletproof copy and paste code. Private Sub AddDriverSession() Dim Dim Dim Dim Dim Dim Dim Dim Dim
cs As New IviConfigStore ha As IviHardwareAsset hadup As IviHardwareAsset ds As IviDriverSession vn As IviVirtualName vr As IviVirtualRange dc As IviDataComponent dcb As IviBoolean ln As IviLogicalName
'// Deserialize the master configuration store. 'On Error GoTo DeserializeError cs.Deserialize (cs.MasterLocation) On Error GoTo 0 '// Create the Hardware Asset and add it to the global hardware asset '// collection Set ha = New IviHardwareAsset ha.Name = "Scope 5" ha.Description = "GT4010 Scope, test station 5" ha.IOResourceDescriptor = "GPIB0::12::INSTR" On Error GoTo DuplicateHardwareAsset cs.HardwareAssets.Add ha On Error GoTo 0 '// Create the Session fill in the Session object properties Set ds = New IviDriverSession ds.Name = "Scope5" ds.Description = "Driver session forscope at test station 5" ds.Cache = False ds.DriverSetup = "" ds.InterchangeCheck = True ds.QueryInstrStatus = False ds.RangeCheck = False ds.RecordCoercions = False ds.Simulate = True '// Add the Hardware Asset reference to the Session Set ds.HardwareAsset = cs.HardwareAssets.Item("Scope 5") '// Create the Virtual names for the Session. The creates the following '// mappings: Analog -> C1, 1 -> C2, 2 -> C3, and 3 -> C4. Set vn = New IviVirtualName vn.Name = "Analog" vn.MapTo = "C1" ds.VirtualNames.Add vn Set vn = New IviVirtualName vn.MapTo = "C" vn.Name = "" Set vr = New IviVirtualRange vr.Name = "Virt CH 1-3" vr.Max = 3 vr.Min = 1 vr.StartingPhysicalIndex = 2 vn.VirtualRanges.Add vr ds.VirtualNames.Add vn IVI Foundation
177
IVI-3.5: IVI Configuration Server Specification
'// Add the Software Module reference to the Session. The configuration '// server will automatically copy all data components with UsedInSession '// = "Required" or "Optional" to the session's data components, and '// change the ReadOnly property to False. Set ds.SoftwareModule = cs.SoftwareModules.Item("gt40xx") '// Change the default values for Data Components for the Session, if needed Set dcb = ds.DataComponents.Item("Trace") dcb.Value = True cs.DriverSessions.Add ds '// Create the Logical Name and add it to the global logical name collection Set ln = New IviLogicalName ln.Name = "Bob" ln.Description = "Logical name for Scope at test station 5" Set ln.Session = ds On Error GoTo DuplicateLogicalNames cs.LogicalNames.Add ln On Error GoTo 0 Exit Sub '// Error handler for duplicate hardware assets DuplicateHardwareAsset: Set hadup = cs.HardwareAssets.Item("Scope 5") If ha.IOResourceDescriptor = hadup.IOResourceDescriptor _ Then Resume Next '// The hardware asset already exists - we just move forward End If '// The hardware asset "Scope 5" refers to a different IO Resource. '// Handle this error appropriately. Exit Sub '// Error handler for duplicate Logical Names DuplicateLogicalNames: '// The logical name "Bob" already exists. '// Handle this error appropriately. Exit Sub End Sub
The XML file created by this example, with extra line breaks, looks like:
178
IVI Foundation
179
IVI-3.5: IVI Configuration Server Specification
180
IVI Foundation
IVI Foundation
181
IVI-3.5: IVI Configuration Server Specification
Appendix C: XSD File The schema file, IviConfigurationStore.xsd, used by IVI Configuration Store XML files contains: <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata"> <xs:element name="IviConfigStore"> <xs:complexType> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Description" type="xs:string"/> <xs:element name="Vendor" type="xs:string"/> <xs:element name="Revision" type="xs:string"/> <xs:element name="SpecificationMajorVersion" type="xs:int"/> <xs:element name="SpecificationMinorVersion" type="xs:int"/> <xs:element name="MasterLocation" type="xs:string"/> <xs:element name="ProcessDefaultLocation" type="xs:string"/> <xs:element name="ActualLocation" type="xs:string"/> <xs:element name="PublishedAPIs"> <xs:complexType> <xs:sequence> <xs:element name="IviPublishedAPI" type="IviPublishedAPI" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="SoftwareModules" type="SoftwareModules"/> <xs:element name="HardwareAssets"> <xs:complexType> <xs:sequence> <xs:element name="IviHardwareAsset" type="IviHardwareAsset" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="DriverSessions"> <xs:complexType> <xs:sequence> <xs:element name="IviDriverSession" type="IviDriverSession" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="Sessions"> <xs:complexType> <xs:choice minOccurs="0" maxOccurs="unbounded"> <xs:element name="IviSession" type="IviSession"/> <xs:element name="IviDriverSession"> <xs:complexType> <xs:attribute name="idref" type="xs:IDREF"/> IVI-3.5: IVI Configuration Server Specification
182
IVI Foundation
<xs:element name="LogicalNames"> <xs:complexType> <xs:sequence> <xs:element name="IviLogicalName" type="IviLogicalName" minOccurs="0" maxOccurs="unbounded"/> <xs:complexType name="IviPublishedAPI"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="MajorVersion" type="xs:int"/> <xs:element name="MinorVersion" type="xs:int"/> <xs:element name="Type" type="xs:string"/> <xs:attribute name="id" type="xs:ID"/> <xs:complexType name="IviHardwareAsset"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Description" type="xs:string"/> <xs:element name="DataComponents" type="DataComponents"/> <xs:element name="IOResourceDescriptor" type="xs:string"/> <xs:attribute name="id" type="xs:ID"/> <xs:complexType name="IviDriverSession"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Description" type="xs:string"/> <xs:element name="DataComponents" type="DataComponents"/> <xs:element name="IviHardwareAsset" minOccurs="0" maxOccurs="1"> <xs:complexType> <xs:attribute name="idref" type="xs:IDREF"/> <xs:element name="IviSoftwareModuleRef" minOccurs="0" maxOccurs="1"> <xs:complexType> <xs:attribute name="idref" type="xs:IDREF"/> <xs:element name="VirtualNames" type="VirtualNames"/> <xs:element name="SoftwareModuleName" type="xs:string"/> <xs:element name="Cache" type="xs:boolean"/> <xs:element name="DriverSetup" type="xs:string"/> <xs:element name="InterchangeCheck" type="xs:boolean"/> <xs:element name="QueryInstrStatus" type="xs:boolean"/> <xs:element name="RangeCheck" type="xs:boolean"/> <xs:element name="RecordCoercions" type="xs:boolean"/> <xs:element name="Simulate" type="xs:boolean"/> <xs:attribute name="id" type="xs:ID"/> IVI Foundation
183
IVI-3.5: IVI Configuration Server Specification
<xs:complexType name="IviSession"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Description" type="xs:string"/> <xs:element name="DataComponents" type="DataComponents"/> <xs:element name="IviHardwareAsset" minOccurs="0" maxOccurs="1"> <xs:complexType> <xs:attribute name="idref" type="xs:IDREF"/> <xs:element name="IviSoftwareModuleRef" minOccurs="0" maxOccurs="1"> <xs:complexType> <xs:attribute name="idref" type="xs:IDREF"/> <xs:element name="VirtualNames" type="VirtualNames"/> <xs:element name="SoftwareModuleName" type="xs:string"/> <xs:attribute name="id" type="xs:ID"/> <xs:complexType name="IviSoftwareModule"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Description" type="xs:string"/> <xs:element name="DataComponents" type="DataComponents"/> <xs:element name="ModulePath" type="xs:string"/> <xs:element name="Prefix" type="xs:string"/> <xs:element name="ProgID" type="xs:string"/> <xs:element name="SupportedInstrumentModels" type="xs:string"/> <xs:element name="PhysicalNames" type="PhysicalNames"/> <xs:element name="PublishedAPIs" type="PublishedAPIs"/> <xs:attribute name="id" type="xs:ID"/> <xs:complexType name="IviLogicalName"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Description" type="xs:string"/> <xs:element name="IviSession" minOccurs="0" maxOccurs="1"> <xs:complexType> <xs:attribute name="idref" type="xs:IDREF"/> <xs:element name="IviDriverSession" minOccurs="0" maxOccurs="1"> <xs:complexType> <xs:attribute name="idref" type="xs:IDREF"/> <xs:attribute name="id" type="xs:ID"/> <xs:complexType name="IviVirtualName"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="MapTo" type="xs:string"/> <xs:element name="VirtualRanges"> IVI-3.5: IVI Configuration Server Specification
184
IVI Foundation
<xs:complexType> <xs:sequence> <xs:element name="IviVirtualRange" minOccurs="0" maxOccurs="unbounded"> <xs:complexType> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Max" type="xs:int"/> <xs:element name="Min" type="xs:int"/> <xs:element name="StartingPhysicalIndex" type="xs:int"/> <xs:attribute name="id" type="xs:ID"/> <xs:attribute name="id" type="xs:ID"/> <xs:complexType name="IviPhysicalName"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="RCName" type="xs:string"/> <xs:element name="PhysicalNames" type="PhysicalNames"/> <xs:element name="PhysicalRanges"> <xs:complexType> <xs:sequence> <xs:element name="IviPhysicalRange" minOccurs="0" maxOccurs="unbounded"> <xs:complexType> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Max" type="xs:int"/> <xs:element name="Min" type="xs:int"/> <xs:attribute name="id" type="xs:ID"/> <xs:attribute name="id" type="xs:ID"/> <xs:complexType name="SoftwareModules"> <xs:choice minOccurs="0" maxOccurs="unbounded"> <xs:element name="IviSoftwareModule" type="IviSoftwareModule"/> <xs:element name="IviSoftwareModuleRef"> <xs:complexType> <xs:attribute name="idref" type="xs:IDREF"/> <xs:complexType name="PublishedAPIs"> IVI Foundation
185
IVI-3.5: IVI Configuration Server Specification
<xs:sequence> <xs:element name="IviPublishedAPI" minOccurs="0" maxOccurs="unbounded"> <xs:complexType> <xs:attribute name="idref" type="xs:IDREF"/> <xs:complexType name="DataComponents"> <xs:choice minOccurs="0" maxOccurs="unbounded"> <xs:element name="IviStructure" type="IviStructure"/> <xs:element name="IviInteger" type="IviInteger"/> <xs:element name="IviString" type="IviString"/> <xs:element name="IviReal" type="IviReal"/> <xs:element name="IviBoolean" type="IviBoolean"/> <xs:element name="IviAPIReference" type="IviAPIReference"/> <xs:complexType name="PhysicalNames"> <xs:sequence> <xs:element name="IviPhysicalName" type="IviPhysicalName" minOccurs="0" maxOccurs="unbounded"/> <xs:complexType name="VirtualNames"> <xs:sequence> <xs:element name="IviVirtualName" type="IviVirtualName" minOccurs="0" maxOccurs="unbounded"/> <xs:complexType name="IviStructure"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Description" type="xs:string"/> <xs:element name="ReadOnly" type="xs:boolean"/> <xs:element name="UsedInSession" type="xs:string"/> <xs:element name="Type" type="xs:string"/> <xs:element name="HelpContextID" type="xs:int"/> <xs:element name="HelpFilePath" type="xs:string"/> <xs:element name="SoftwareModuleKey" type="xs:string"/> <xs:element name="DataComponents" type="DataComponents"/> <xs:attribute name="id" type="xs:ID"/> <xs:complexType name="IviBoolean"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Description" type="xs:string"/> <xs:element name="ReadOnly" type="xs:boolean"/> <xs:element name="UsedInSession" type="xs:string"/> <xs:element name="Type" type="xs:string"/> <xs:element name="HelpContextID" type="xs:int"/> <xs:element name="HelpFilePath" type="xs:string"/> <xs:element name="SoftwareModuleKey" type="xs:string"/> <xs:element name="Value" type="xs:boolean"/> IVI-3.5: IVI Configuration Server Specification
186
IVI Foundation
<xs:attribute name="id" type="xs:ID"/> <xs:complexType name="IviReal"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Description" type="xs:string"/> <xs:element name="ReadOnly" type="xs:boolean"/> <xs:element name="UsedInSession" type="xs:string"/> <xs:element name="Type" type="xs:string"/> <xs:element name="HelpContextID" type="xs:int"/> <xs:element name="HelpFilePath" type="xs:string"/> <xs:element name="SoftwareModuleKey" type="xs:string"/> <xs:element name="Units" type="xs:string"/> <xs:element name="Value" type="xs:double"/> <xs:attribute name="id" type="xs:ID"/> <xs:complexType name="IviString"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Description" type="xs:string"/> <xs:element name="ReadOnly" type="xs:boolean"/> <xs:element name="UsedInSession" type="xs:string"/> <xs:element name="Type" type="xs:string"/> <xs:element name="HelpContextID" type="xs:int"/> <xs:element name="HelpFilePath" type="xs:string"/> <xs:element name="SoftwareModuleKey" type="xs:string"/> <xs:element name="Value" type="xs:string"/> <xs:attribute name="id" type="xs:ID"/> <xs:complexType name="IviInteger"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Description" type="xs:string"/> <xs:element name="ReadOnly" type="xs:boolean"/> <xs:element name="UsedInSession" type="xs:string"/> <xs:element name="Type" type="xs:string"/> <xs:element name="HelpContextID" type="xs:int"/> <xs:element name="HelpFilePath" type="xs:string"/> <xs:element name="SoftwareModuleKey" type="xs:string"/> <xs:element name="Units" type="xs:string"/> <xs:element name="Value" type="xs:int"/> <xs:attribute name="id" type="xs:ID"/> <xs:complexType name="IviAPIReference"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Description" type="xs:string"/> <xs:element name="ReadOnly" type="xs:boolean"/> <xs:element name="UsedInSession" type="xs:string"/> <xs:element name="Type" type="xs:string"/> <xs:element name="HelpContextID" type="xs:int"/> <xs:element name="HelpFilePath" type="xs:string"/> <xs:element name="SoftwareModuleKey" type="xs:string"/> <xs:element name="Value" type="xs:string"/> IVI Foundation
187
IVI-3.5: IVI Configuration Server Specification
<xs:element name="IviPublishedAPI"> <xs:complexType> <xs:attribute name="idref" type="xs:IDREF"/> <xs:attribute name="id" type="xs:ID"/>
IVI-3.5: IVI Configuration Server Specification
188
IVI Foundation
Related Documents
Ivi-3.5 Configuration Server V1
November 2019 0
Crn-cognos Configuration V1
November 2019 0
Kerio Mail Server Configuration
July 2020 9
Primary Dns Server Configuration
November 2019 12
