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 function signature.

The value keyword is used to refer to the attribute value itself when defining attribute setter commands and attribute getter responses. The value keyword is also used to refer to a function 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 the standard VISA library's viPrintf or viScanf functions. For a complete list of format specifications, see the documentation for your VISA supplier.

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

ViStatus _VI_FUNC acme4321_Configure(ViSession Vi, ViReal64 ResBW, ViReal64 VideoBW, ViInt32 SweepTime)

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

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

SENS:BAND {value}

Since most functionality in IVI-C drivers is provided by attributes, Nimbus simplifies the instrument command syntax by not requiring a replacement tag to be provided explicitly for attribute setters. Rather, the formatted attribute 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 attribute setter produce identical results:

• SENS:BAND

• SENS:BAND {value}

Both command strings will append the formatted value of the attribute to the SENSE:BAND string. Note that in both cases the default parameter formatting for the attribute 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 attribute in exponentional form with a minimum length of 3 characters and 2 digits following the decimal point.

Attribute getters utilize the {value} tag in precisely the same way as functions 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 parameter tags and repeated capability tags, not the {value}. See the discussion in the following section on how to use the {value} tag in function responses.

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 attribute and function in which that enum is used as a parameter or attribute value. If a particular function or attribute using that enum needs unique string-to-enum mappings, then that function or attribute 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 an attribute named TRIGGER_SOURCE (the PREFIX_ATTR portion is excluded for brevity). Nimbus generates a #define macro for that attribute in the <prefix>.h file that looks like the following:

// acme4321.h
#define ACME4321_ATTR_TRIGGER_SOURCE    (IVI_SPECIFIC_ATTR_BASE + 3L)  /* ViInt32, read-write */

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 TRIGGER_SOURCE attribute needs to be converted to a string and inserted into the setter command where the {value} tag appears. For instance, if the attribute were set to the value ACME4321_VAL_TRIGGER_SOURCE_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 attribute 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 enum value, such as ACME4321_VAL_TRIGGER_SOURCE_INTERNAL.

Instrument commands sent from functions 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

Example: Using the repeated capability index with an offset

Example: Using the repeated capability name in an instrument command

Example: Building instrument commands with nested repeated capabilities

ViStatus _VI_FUNC acme4321_StoreReferenceTrace(ViSession Vi, ViConstString RepCapIdentifier)