Repeated Capabilities


Boonton55xxx IVI Driver Reference

Repeated Capabilities

Instruments often contain multiple instances of the same kind of functionality or capability. For instance, modern oscilloscopes may have multiple channels, each with independent settings for such things as vertical scale and input attenuation. IVI refers to funtionality that is duplicated in an instrument as a repeated capability.

Instances of repeated capabilities are identified by name. These names are passed as parameters to standard repeated capability accessor functions in order to change settings and execute methods on a driver's repeated capabilities. There are two types of repeated capability names -- physical names and virtual names. Physical repeated capability names are those that the driver writer specifies during driver development. These are the names that the driver natively understands and, as such, they cannot be modified by an end user. They can only be read by an end user. Virtual repeated capability names are explained below.

The physical repeated capability names (or simply physical names) understood by a particular driver can be discovered interactively or programmatically. Each IVI driver is required to register the set of physical names it understands with the IVI Configuration Store. This means an end user can use whatever IVI Configuration Store browser they have to look up the physical names supported by the driver.

Physical names can also be discovered programmatically using standard repeated capability functions. Example code for doing this is given below in the section on Parameter-Style Repeated Capabilities.

Virtual Repeated Capability Names

Virtual names allow end users to specify their own names for repeated capability instances and map those names to the physical names that the driver natively understands. The user establishes the virtual-to-physical name mappings in the IVI Configuration Store. At runtime, the user can supply a virtual channel name to the appropriate function the driver will use the mappings in the IVI Configuration Store to translate the virtual name into a physical name that the driver understands.

The purpose of virtual names is to faciliate driver interchangeability. If a user writes application code using virtual names, then no modifications to the application code are necessary when an existing driver is replaced with one that natively understands different physical names. The user need only modify the appropriate settings in the IVI Configuration Store to map their virtual names to the new driver's physical names.

Types of Repeated Capabilities

The IVI specifications define three different types of repeated capabilities -- parameter-style repeated capabilities, selector-style repeated capabilities, and collection-style repeated capabilities. Each type of repeated capability is often more appropriate depending upon such factors as how common the repeated capability is in a particular instrument class and whether one repeated capability instance is controlled at a time or multiple instances are commonly controlled at a time. Since IVI instrument classes use all three types of repeated capabilities in various instrument classes, it is important to understand the basics of each type of repeated capability.

Parameter-Style Repeated Capabilities

The simplest type of repeated capability is the parameter style. Parameter-style repeated capabilities are used most commonly in IVI-C drivers, though they can also appear in IVI-COM drivers. As the name implies, parameter-style repeated capabilities are supported by simply adding an extra string parameter to any function that applies to a repeated capability (as opposed to a function that applies to the driver as a whole). The client application passes in either a valid physical or virtual repeated capability name for this parameter to identify the particular repeated capability instance to access.

The code below shows an IVI-C driver client using the ConfigureOperationMode function from the IviFGen class specification:

C++	Copy Code
ViSession vi; // ... IviFgen_ConfigureOperationMode(vi, "Output1", IVIFGEN_VAL_OPERATE_BURST);

In the code above, the second parameter is the repeated capability name. The repeated capability name almost always appears as the second parameter to a function that applies to a repeated capability. The example is setting the operation mode to burst for only the output channel identified by "Output1". The name "Output1" could be a physical name or a virtual name.

Drivers that expose a parameter-style repeated capability always expose a couple of additional functions and attributes that allow you to programmatically determine the number of repeated capabilities instances (e.g. "channels") and the physical names supported (e.g. channel names). The names of these support functions are also standardized, so that they can easily be identified when the name of the capability is know. IVI-COM drivers and IVI-C drivers differ slightly in the repeated capability support functions they expose for parameter-style repeated capabilities.

With either IVI-COM or IVI-C, the use model for these attributes is virtually identical. Specifically, the client code simply reads the value of the Count attribute and then uses this value to iterate through the repeated capability instances. The Name attribute (for IVI-COM) and the GetName function (for IVI-C) both accept a one-based index parameter to identify which repeated capability instance name is desired. The code below shows how to iterate through all of the physical names supported by an IVI-C FGen driver that exposes a "Channel" repeated capability.

C++	Copy Code
ViSession vi; ViInt32 i; ViChar name[1024]; // ... ViInt32 count; IviFgen_GetAttributeViInt32(vi, VI_NULL, IVIFGEN_VAL_CHANNEL_COUNT); for (i = 1; i <= count; i++) { // Note: One-based indexing IviFgen_GetChannelName(vi, i, 1024, name); printf(name); }

Selector-Style Repeated Capabilities

Selector-style repeated capabilities use a special selector function to set the "active" repeated capability. Subsequent function calls that apply to a repeated capability are understood to apply to the active instance. The active instance remains active until the client code sets the active instance to another repeated capability name.

Selector-style repeated capabilities can be used in both IVI-COM and IVI-C drivers, and, though less common than the parameter style and collection style (discussed shortly), selector-style repeated capabilities have the advantage of not requiring a repeated capability name to be passed to every function that applies to the repeated capability.

As with parameter-style repeated capabilities, drivers that expose a selector-style repeated capability always expose additional functions for managing the repeated capability instances. Indeed, the selector-style repeated capability uses the same functions and attributes as the parameter style, with the addition of one attribute and one function for setting and getting the active instance.

Since the selector-style repeated capability uses the same Count attribute and GetName function as the parameter style, the code required to iterate through the instance names for a selector-style repeated capability is identical to that shown above for the parameter style.

Collection-Style Repeated Capabilities (IVI-COM only)

By far, the most common type of repeated capability for IVI-COM drivers is the collection-style repeated capability. Collection-style repeated capabilities are not supported for IVI-C drivers.

As with the parameter and collection style, collection-style repeated capabilities always expose a Count and Name attribute for iterating through the list of available repeated capability names. Unique to collection-style repeated capabilities is the Item property, which provides access to individual repeated capability instances. The Item property accepts a repeated capability name (physical name or virtual name) and returns an interface pointer to the desired repeated capability instance. All method and property calls on the returned interface pointer implicitly apply to the repeated capability instance chosen with the Item property.

The C# code below demonstrates how to use the Item property to access a channel called "CH1" and enable it.

C#	Copy Code
IIviScope scope = new AcmeScopeClass(); // ... Initialize called IIviScopeChannel channel = scope.Channels.get_Item("CH1"); channel.Enabled = true;

Note that in C#, the Item property is invoked using the get_Item accessor method. This is required for C# because that language does not support parameterized properties. Thus, any property that accepts one or more parameters must be accessed as if it were a method. The standard way in which such properties appear in C# is with a "get_" prefix (for reads) and a "set_" prefix (for writes).

Note also that declaring the intermediate variable for the IIviScopeChannel interface returned by get_Item is not necessary. Depending upon the client application, it may be more convenient to write the code as follows:

C#	Copy Code
IIviScope scope = new AcmeScopeClass(); // ... Initialize called scope.Channels.get_Item("CH1").Enabled = true;

Static and Dynamic Repeated Capabilities

Many instruments have a fixed number of repeated capabilities. For instance, a function generator typically has a fixed number of output channels. However, some instruments can have a variable number of repeated capabilities, depending upon end-user configuration. For instance, a switching mainframe might have any of a number of combinations of multiplexer cards installed on a particular end-user system. Thus, the number of channels is not fixed and can only be determined at runtime. Such instruments possess what are termed dynamic repeated capabilities. Conversely, instruments that always have a fixed number of repeated capabilities use the term static repeated capabilities.

A driver that exposes dynamic repeated capabilities cannot register the supported repeated capability names during driver installation. Instead, during the driver Initialize call, the driver typically queries the instrument to determine its exact configuration. The mechanism by which a driver determines the name and number of the supported repeated capabilities is always instrument specific, but the net result is that the end user must use the Count and Name attributes to programmatically determine what repeated capability instances are available. An IVI Configuration Store browser is useless in determining what dynamic repeated capabilities a driver supports. It relies only upon static information in the IVI Configuration Store, so it can only report details on static repeated capabilities.