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.

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.

The simplest way to create proper format specifications is to use the Instrument Command Editor. Full documentation of the parameter format specification syntax can be found in the topic Parameter Format Specifications.

Special support is provided for formatting boolean and enum parameters.

Example: Basic Parameter Replacement

HRESULT Configure([in] double ResBW, [in] double VideoBW, [in] 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-COM 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, and, 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 [in] 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 [out] 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-COM 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. These string-to-enum and boolean-to-enum mappings are configured with the Instrument Command Editor.

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

[propput]
HRESULT TriggerSource([in] Acme4321TriggerSourceEnum Source);

[propget]
HRESULT TriggerSource([out,retval] Acme4321TriggerSourceEnum* Source);

The TriggerSource property is a read-write property of type Acme4321TriggerSource. 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 Acme4321TriggerSourceExternal, 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 Acme4321TriggerSourceEnum value, such as Acme4321TriggerSourceInternal.

These mappings between strings and enum (or boolean) values are established with the Instrument Command Editor.

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:

{ [<className>.]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 className is an optional parameter used to designate a class other than the class from which the command is being sent. This is most often useful when the name or index of a parent repeated capability must also be included in the command string.

Example: Using the repeated capability index in instrument commands

[propput]
HRESULT Resolution([in] double resolution);

Example: Using the repeated capability index with an offset

[propput]
HRESULT Resolution([in] double resolution);

Example: Using the repeated capability name in an instrument command

[propget]
HRESULT Amplitude([out, retval] double* pVal);

Example: Building instrument commands with nested repeated capabilities

HRESULT StoreReferenceTrace();

Other Resources