SCPI commands, which are also referred to as SCPI instructions, are messages to the instrument to perform specific tasks and to return data. The following sections provide descriptions of the command syntax and notational conventions, command types and the hierarchical command structure, command subsystems, and data parameter format. For further information about SCPI, refer to the Standard Commands for Programmable Instruments (SCPI) 1999.0 document hosted by the IVI Foundation. A subset of the standard conventions defined in that document as they apply to the MS276xA are covered in this manual.
Command Names
Typical SCPI commands consist of one or more keywords, parameters, and punctuation marks. SCPI command keywords can be a mixture of upper- and lower- case characters. As with any programming language, the exact command keywords and command syntax must be used. The syntax of the individual commands is described in detail in the programming command chapters. Unrecognized versions of long form or short form commands or improper syntax will generate errors.
Long Format vs. Short Format
Except for common commands, each keyword has a long and a short form. The short form is a subset of the long form of the command. In this manual, the short form is presented in upper case and the long form in lower case. For example, the long form of the command keyword to control the instrument display is :DISPlay. If the short form is not used, the entire long form of the keyword must be used.
The short form keyword is usually the first four characters of the long form (:DISP for :DISPlay). The exception to this rule is when the long form is longer than four characters and the fourth character is a vowel. In such cases, the vowel is dropped and the short form becomes the first three characters of the keyword. For example, the short form of the keyword :POWer is :POW.
A mixture of short form keywords with the entire long form keyword of each command is acceptable. For example, :SENS:FREQuency:STAR is an acceptable form of the command. However, :SENS:FREQuen:STAR is not an acceptable form of the command because :FREQuen is not the entire short nor long form of the command keyword.
Command Syntax
The command statement usually starts with a colon “:” and includes a number of keywords and parameters. The leading colon is optional, but each subsequent keyword must be separated by a colon and may be followed by parameter settings when they are available. The end of the command string and the first command parameter must be separated by a space. For example:
:DISPlay:POINtcount 201
A comma “,” is generally used for separating multiple command parameters, for example:
:CALCulate:LIMit1:LOWer 1DBM,2DBM,3DBM
Complete command strings may be combined on a single line and separated by a semicolon “;” as follows:
Some command keywords may have a keyword parameter suffix to differentiate between multiple instrument features such as multiple trace options. When these features are available, the keyword parameter is identified and enclosed by curly braces. For example, :TRACe{1|2|3} is entered as :TRACe1 or :TRACe3.
Note
If a keyword parameter is not included in a command, the first option is implied. In the previous paragraph, :TRACe is identical to :TRACe1.
The SCPI interface standardizes command syntax and style that simplifies the task of programming across a wide range of instrumentation. As with any programming language, the exact command syntax, and command keywords, must be used. Unrecognized commands or improper syntax will not function and most often produce an error condition. The table below lists the standard notational conventions used in this document.
Notational Conventions
:
A colon links command keywords together to form commands. The colon is not an actual part of the keyword, but is a signal to the SCPI interface parser. A colon must precede a root keyword immediately following a semicolon (see Notational Examples).
;
A semicolon separates commands if multiple commands are placed on a single program line.
[ ]
Square brackets enclose one or more optional keywords.
{ }
Curly braces enclose one or more keyword or command parameters that may be included one or more times.
|
A vertical bar indicates “or” and is used to separate alternative parameter options. For example: ON|OFF is the same as ON or OFF.
< >
Angle brackets enclose command parameter descriptions (see Data Parameters).
Command Terminators
The new line character (ASCII 10) or a semi-colon in the last data byte of a command string is used as a command terminator. Use of a command terminator will reset the command path to the root of the tree.
Data Parameters
Data parameters, referred to simply as “parameters,” are the quantitative values used as arguments for the SCPI commands. The parameter type associated with a particular SCPI command is determined by the type of information required to control the particular instrument function. For example, Boolean (ON|OFF) type parameters are used with commands that control switch functions. Some command descriptions specify the type of data parameter to be used with each command. The most commonly used parameter types are numeric, extended numeric, discrete, and Boolean.
Numeric
Numeric parameters comprise integer numbers or any number in decimal or scientific notation, and might include polarity signs. This includes specific extended values as defined in Data Parameter Notations below.
Extended Numeric
Extended numeric parameters include values such as NAN|INFinity|NINFinity (not a number|infinity|negative infinity).
Discrete
Discrete parameters, such as INTernal and EXTernal, are used to control program settings to a predetermined finite value or condition.
Boolean
Boolean parameters represent binary conditions and may be expressed as ON, OFF or 1, 0.
Data Parameter Notations
The following conventions are used to note data parameter descriptions:
Parameter Notations
<integer>
an unsigned integer without a decimal point (implied radix point)
<numeric_value>
SCPI numeric value: <NRf>|NAN|INFinity|NINFinity or other types
<NRf> is any of <NR1>|<NR2>|<NR3> <NR1> is a signed integer without a decimal point (implied radix point) <NR2> is a signed number with an explicit radix point <NR3> is a scaled, explicit decimal point numeric with an exponent (floating point number)
Values can be specified for parameters of type NR3, with +/- 9.9e37 representing +/- infinity (INFinity|NINFinity), and 9.91e37 representing Not-A-Number (NAN).
<char>
<CHARACTER PROGRAM DATA> Examples: CW, FIXed, UP, and DOWN
<string>
<STRING PROGRAM DATA> ASCII characters enclosed by double quotes, such as “OFF”
Trace data uses SCPI standard (IEEE 488.2) block data format. The data format is '#AXD', where D is a comma separated list of amplitudes (in ASCII), X is one or more ASCII digits specifying the number of bytes in D, and A is a single ASCII digit specifying the number of digits in X.
Trace data only contain amplitude. The frequency information for each point is given by:
Frequency = start_frequency + (span/(display_points-1))*N where N = 0, 1, 2, … display_points
Unit Suffixes
Unit suffixes are not required for data parameters, provided the values are scaled for the global default units, they do not require a space, and they are not case-sensitive. The instrument SCPI default units are:
• HZ (hertz) for frequency related parameters
• DB for power related parameters
• MS (milliseconds) for time related parameters
• M (meters) for distance related parameters
Query Commands
All commands, unless specifically noted in the commands syntax descriptions, have a query form. As defined in IEEE-488.2, a query is a command with a question mark “?” appended to the command. For example:
:OPTions?
When a query form of a command is received, the current setting associated with the command is placed in the output buffer. Query commands always return the short form of the parameter unless otherwise specified. Boolean values are returned as 1 or 0, even when they can be set as on or off.
Hierarchical Command Structure
All SCPI commands, except the common commands, are organized in a hierarchical structure similar to the inverted tree file structure used in most computers. The SCPI standard refers to this structure as “the Command Tree.” The command keywords that correspond to the major instrument control functions are located at the top of the command tree. The root command keywords for the SCPI command set are shown in Figure: SCPI Command Tree.
SCPI Command Tree
All instrument SCPI commands, except the :ABORt command, have one or more subcommands (keywords) associated with them to further define the instrument function to be controlled. The subcommand keywords might also have one or more associated subcommands (keywords). Each subcommand level adds another layer to the command tree. The command keyword and its associated subcommand keywords form a portion of the command tree called a command subsystem. A sample of the :UNIT command subsystem is shown in Figure: SCPI :Sample :UNIT Subsystem.
