Instrument Command Syntax

Parameter replacement tags are enclosed in curly braces { } and can appear anywhere within an instrument command. They have the following general form:

{<paramName> | value[:<formatSpec>]}

The paramName is the name of the parameter in the method signature.

The value keyword is used to refer to the property value itself when defining property setter commands and property getter responses. The value keyword is also used to refer to a method return value. Use of the {value} keyword is discussed further in the sections below.

The formatSpec is an optional format specification for the parameter. This format specification is similar to that supported by the C Run-Time Library's familiar sprintf function. More precisely, this format specification can be any of those supported by VISA.NET. For a complete list of format specifications, see the documentation for your VISA.NET supplier.

Tip
In general, the format specifications supported by VISA.NET match those supported by the viPrintf and viScanf methods that are part of the long-standing VISA-C specification. The IVI Foundation has made a concerted effort to follow these format specifications from VISA-C whereever possible, so that users already familiar with viPrintf and viScanf can use VISA.NET easily and effectively.

If no formatSpec is provided, then the default format specification is used. The default format specification only applies to integers, floating-point, and boolean parameters. These defaults are configured on the I/O Page of the Driver Settings Editor.

Special support is provided for formatting boolean and enum parameters.

Example: Basic Parameter Replacement

void Configure([double resBW, double videoBW, double sweepTime);

Property setters support a special {value} replacement tag to represent the value of the property itself. This special tag allows you to insert the runtime value of the property into the command string.

The following instrument command applied to a property setter would append the value of the property to the SENS:BAND string:

SENS:BAND {value}

Since most functionality in IVI.NET drivers is provided by properties, Nimbus simplifies the instrument command syntax by not requiring a replacement tag to be provided explicitly for property setters. Rather, the formatted property value will simply be appended to the command string. If the formatted parameter should appear elsewhere in the command string, then an explicit parameter replacement tag must be specified.

Given this shorthand notation, the following two instrument commands applied to a property setter produce identical results:

• SENS:BAND

• SENS:BAND {value}

Both command strings will append the formatted value of the property to the SENSE:BAND string. Note that in both cases the default parameter formatting for the property type will be applied, since no format specification is provided. If an alternate format specification is desired, then the {value} replacement tag must be specified.

The following example shows an instrument command using the {value} tag with a format specification:

SENS:BAND {value:%3.2e}

The above example will append the value of the property in exponentional form with a minimum length of 3 characters and 2 digits following the decimal point.

Properties may have parameters. Thus, the associated instrument command may include parameter replacement tags, just as with methods. The following example demonstrates use of the {value} tag in conjunction with a normal parameter replacement tag.

:CURRent:AC:BANDwidth {value}, {channelList}

The above example would be valid for a property setter that accepted a parameter named channelList.

Property getters utilize the {value} tag in precisely the same way as methods use the tag for responses. Only the getter response string may use the {value} tag -- the getter command may only use input and input/output (ref) parameter tags and repeated capability tags, not the {value}. See the discussion in the following section on how to use the {value} tag in method responses.

Methods often have a return value associated with them. Since there is no parameter name to reference, the {value} tag is used to represent the method return value. A method return value is effectively an output parameter, so the {value} tag can only be used in the method response. The {value} tag cannot be used in the method command.

Consider a method defined as follows in the IVI.NET Driver Designer:

double[] Fetch(long start, long numPoints)

The method command might be the following:

CALC:DATA? {start}, {numPoints}

The above command uses parameter replacement tags for the two input parameters Start and NumPoints. After issuing the above command, the driver needs to read data from the instrument and assign the resulting array of double-precision floating point numbers to the return value of the method. This can be done with the following method response string.

{value:%,e}

The response string above uses the {value} tag with a format specification of %,e. This format specification indicates that the instrument response is a comma-separated list of floating-point numbers in ASCII format.

When an instrument command parameter tag refers to a boolean or enum parameter, Nimbus must generate code that converts the boolean or enum value to a string. Correspondingly, when an instrument response uses a parameter tag that references a boolean or enum, the instrument response string must be parsed and converted to the appropriate boolean or enum value.

The string-to-enum mappings are created using the Enum Member Editor. These mappings will apply to every property and method in which that enum is used as a parameter or return value. If a particular method or property using that enum needs unique string-to-enum mappings, then that method or property must be manually implemented.

The string-to-boolean mappings are managed differently -- by simply changing the settings in the I/O Page of the Driver Settings Editor.

As an example, consider the definition of a simple Source property:

Acme.Acme4301.TriggerSource Source { get; set; }

The Source property is a read-write property of type TriggerSource. The command for the setter is defined as:

TRIG:SOUR {value}

The command for the getter is defined as:

TRIG:SOUR?

Finally, the response for the getter is defined simply as:

{value}

When the setter is executed, the specified value for the Source parameter needs to be converted to a string and inserted into the setter command where the {value} tag appears. For instance, if the property were set to the value TriggerSource.External, the enum value might need to be converted to EXT to produce the following command:

TRIG:SOUR EXT

Similarly, when the TRIG:SOUR? query is issued upon executing the property getter, the instrument might respond with a string such as INT (to represent an internal trigger source). This string needs to be converted to a valid TriggerSource enum value, such as TriggerSource.Internal.

Because the TimeSpan and PrecisionTimeSpan data types are common in IVI.NET driver APIs, Nimbus provides special support for converting parameters of these types to and from instrument commands. When a parameter of type TimeSpan or PrecisionTimeSpan is used in an instrument command, Nimbus internally accesses the TotalSeconds member of the data type and formats the result as a string. Similarly, when an instrument response is received, it is parsed as a double and that value is used to create a TimeSpan or PrecisionTimeSpan object via the FromSeconds member.

Instrument commands sent from methods implemented on repeated capability classes often need to incorporate runtime information about the specific repeated capability instance issuing the command. For example, a spectrum analyzer driver might define a repeated capability class to represent multiple traces stored in the instrument. A command that would read data from a specific trace might look something like the following:

DATA:TRACE4:READ?

Note that the 4 included in the command refers to a specific trace within the instrument.

Note
Repeated capability tags cannot appear in instrument response strings.

Repeated capability replacement tags are used to insert into command strings runtime information about the repeated capability instance sending the command. These special tags can be replaced by either the name or the index of the repeated capability.

For more information on repeated capabilities, see Repeated Capabilities.

Repeated capability replacement tags are enclosed in curly braces { } and can appear anywhere within an instrument command. They have the following general form:

{ [<parentRepCap>.]rcindex[+|-<offset>] | rcname }

The rcindex keyword is used to insert into the command string the runtime value of the index of the repeated capability instance issuing the command. The rcindex keyword can optionally be followed by an offset, such as +1 or -3, to account for differences between how repeated capabilities are indexed by the driver and how the instrument expects them to appear in the command string.

The rcname keyword is used to insert into the command string the runtime value of the name of the repeated capability instance issuing the command.

The parentRepCap is an optional parameter used to designate a parent (or any ancestor) repeated capability.

Example: Using the repeated capability index in instrument commands

double Resolution { get; set; }

Example: Using the repeated capability index with an offset

double Resolution { get; set; }

Example: Using the repeated capability name in an instrument command

double Amplitude { get; set; }

Example: Building instrument commands with nested repeated capabilities

void StoreReferenceTrace();