Understanding Parameter Direction

The IVI specifications prescribe specific rules for output parameters in IVI-COM drivers. These rules often lead to confusion — both for the driver developer and for the end-user working with an IVI driver. This topic is dedicated to explaining output parameters in IVI-COM drivers.

IVI Requirements for Output Parameters

The IVI specifications require that all output parameters in IVI-COM drivers be specified as [in, out] when constructing the driver IDL file. An [in,out] parameter in IVI-COM is also referred to as a reference parameter (ref in C#) or a two-way parameter. The rule prohibiting [out]-only parameters holds even if the parameter is logically a pure output parameter — such as with the Fetch function in IviScope, which returns an array of data from the device. The only exception to this rule is when the parameter is a method return value and marked as [out, retval] in the IDL. Thus there are no “pure” output parameters in IVI-COM drivers.

The reason this rule exists is historical — to preserve compatibility with Visual Basic 6, which was the dominant Microsoft development tool at the time the original IVI-COM specifications were authored. Visual Basic 6 has a well-documented flaw whereby it leaks memory when using a COM component that has [out]-only parameters. The solution has always been to avoid [out]-only parameters in any component targeting Visual Basic 6, and to use [in, out] instead.

Using IVI Drivers with Output Parameters

The consequences of using [in, out] for all output parameters in IVI-COM drivers is quite visible. Consider the following IDL signature of the FetchWaveform method from the IviScope class-specification:

HRESULT FetchWaveform([in, out] SAFEARRAY(double)* WaveformArray, [in, out] double* InitialX, [in, out] double* XIncrement);

As the name of the method implies, the parameters are all logically output parameters. However, as per the IVI specifications, each is specified as [in, out].

When using such a method from C#, each [in, out] parameter will appear as a ref parameter. Since C# requires that ref parameters be initialized prior to calling a method, this leads to a somewhat non-intuitive calling syntax where each parameter is “artificially” initialized to a dummy value simply to satisfy the C# compiler. The following code demonstrates how one would call the IviScope FetchWaveform method shown above.

double[] WaveformArray = { 0 };
double InitialX = 0;
double XIncrement = 0;

driver.Measurements.Item("").FetchWaveform(ref WaveformArray, ref InitialX, ref XIncrement);

Note

It may be desirable to have parameters that logically are two-way parameters. For instance, a driver may wish to pass some existing data into the driver, have the driver operate on that data, and then return transformed data to the client in the same parameter. Or, a two-way parameter might be useful to allow arrays to be preallocated by the client and passed to the driver. This avoids having the driver reallocate an output array for each method call, as is the case for [out]-only parameters.

If an IVI specification denotes a parameter as [in, out] when the parameter is logically only an output parameter, the specification is supposed to indicate if the parameter “really” is a pure output parameter or if the driver must consider any data passed in via the parameter. At present, the IVI class specifications are not consistent here, but drivers should indicate this in their documentation.

How Nimbus Handles Output Parameters

The IVI-COM Parameter Editor offers three choices for parameter direction — Input, Output, and Input/Output. As per the IVI specification requirements, Nimbus always generates [in, out] in the IDL method signature, even if Output is specified in the editor.

However, it is important to use the direction setting to tell Nimbus what the logical direction of the parameter is, even though the generated code is the same for Output and Input/Output. Doing so allows Nimbus to generate more efficient code. For instance, if a parameter is specified as Output, then Nimbus will not attempt to copy any data from the parameter, since the user will not have provided any. Had the parameter been specified as Input/Output, then Nimbus assumes there may be useful data in the parameter and will perform internal copy operations in some circumstances. For array parameters with a significant number of elements, this can impact driver performance.

Important

When trying to decide between Output and Input/Output in the IVI-COM Parameter Editor always specify the logical direction of the parameter, even though Nimbus will generate the same IDL method signature for either choice. This allows Nimbus to generate the most efficient implementation code. Typically, choosing Output is the more appropriate option. True Input/Output parameters are rare in IVI-COM. In fact, at present there is only one IVI class specification with methods that have logical input/output parameters — these are the various Fetch and Read methods in the IviDigitizer class specification.