Fact 5. Learn Common Child Commands

As seen in the SCPI Command Tree Viewer, most commands have lower-level commands (children). Some child commands are unique and documented in the Interactive SCPI Command Tree. Other child commands are repeated under many commands, are not shown in the Interactive SCPI Command Tree, and are known as common child commands.

For example, FlexDCA's :TIMebase:SCALe command has the following common child commands:

				:TIMebase:SCALe 1E-9
				:TIMebase:SCALe:DEFault
				:TIMebase:SCALe:MAXimum
				:TIMebase:SCALe:MINimum
				:TIMebase:SCALe:STEP

Commands with ON/OFF Parameter Arguments

Some commands turn on or off a setting with ON and OFF parameter arguments. For example, the :CHANnel:DISPlay ON command, which displays an input channel waveform. The available child command for on off settings is:

:TOGGle: Toggles the setting which turns the display on if it is currently off. Or, if the display is on, turns the display off. For example, :CHANnel:DISPlay:TOGGle.

Commands with Parameter Arguments

An example of a command with parameter arguments is the :CHANnel:COLor command, which has the arguments TCOLor1 through TCOLor16. These commands generally have the following common child commands:

:DEFault: Sets the setting to the corresponding default argument. Use the query form of this common child command to return the default argument.
:NEXT: Sets the setting to the corresponding next argument. To learn the order of the arguments, use the VSET? common query described below. There is no query form of this common child command.
:PREVious: Sets the setting to the corresponding previous argument. To learn the order of the arguments, use the VSET? common query described below. There is no query form of this common child command.
:VSET?: Returns a list of all valid arguments.

Commands with Numerical Arguments

An example of a command with parameter arguments is the :TIMebase:SCALe command. These commands generally have the following common child commands:

:DEFault: Sets the setting to the default value. Use the query form of this common child command to return the default value.
:MINimum: Sets the setting to its minimum possible value.
:MAXimum: Sets the setting to its maximum possible value.
:STEP: This common child command steps (increases or decreases) the current setting. An optional integer argument can be used to specify the direction (increase or decrease value) and size of the change from the current value. Generally, positive integers decrease a value and negative integer increase a value, but confirm before using as these directions can be swapped for some commands. Depending on the setting, the value of the integer either selects either a fixed change from the current value or a change according to a 1, 2, 5 sequence. For fixed changes, each time that you sent the child command :STEP -1, the change would be the same. For example, a 1ns setting would change to 2 ns, 3 ns, and so forth with each command. For sequence changes, if a time span is set to 1 ns, sending the child command :STEP -1 would change the span to 2 ns. Sending the command a second time would set the span to 5 ns, and a third time to 10 ns and so forth.

Commands for Scalar Statistic Measurement

The :MEASure subsystem's scalar measurement commands have common child queries that return statistical measurement results and also query the validity of those values. The common child commands and queries are available for most measurements. Common statistical queries are children of each scalar measurement command and include the following:

:MEAN?

Returns the Mean measurement. It is calculated over the number of waveform acquisitions returned by the COUNt? query.

:MINimum?

Returns the Minimum measurement. It is calculated over the number of waveform acquisitions returned by the COUNt? query.

:MAXimum?

Returns the Maximum measurement. It is calculated over the number of waveform acquisitions returned by the COUNt? query.

:SDEViation?

Returns the standard deviation (Std Dev) measurement, which is only displayed in the result table for Oscilloscope Mode measurements. It is calculated over the number of waveform acquisitions returned by the COUNt? query.

:COUNt?

Returns the number of waveform acquisitions (Count) that have occurred for the parent measurement.

:LOCation?

Returns the location (index) of the measurement in the displayed results table. This query is available for all Oscilloscope mode, Eye mode, Jitter/Amplitude mode, JSA, mask test, and histograms measurements. The active measurement list is indexed starting at 1 representing row 1 column 1 and continuing row-by-row until the last column in the last row. If a table cell is not used for data in a table, the index is not increased for that cell.

:REGion?

For FlexDCA measurements, selects a time span over which an oscilloscope or TDR measurement is made.

:SOURce?

This command specifies the source waveform on which to perform the measurement.

:STATus?

Queries the status of the common statistical measurement results. Use the :STATus:REASon? child query to determine the reason for a invalid or questionable measurement.

:STATus? Query Response
Response	Description
CORR	The measurement result is correct.
INV	The measurement result is invalid. A question mark (?) is shown in the displayed results table instead of a measurement result.
QUES	The measurement result is questionable. A question mark (?) is shown in the displayed results table next to the measurement result.

:STATus:REASon?

Queries the explanation why the :STATus? child query indicates an unsuccessful measurement. Refer to the table "Possible Common :STATus:REASon? Query Responses". If the :STATus? child query indicates a successful measurement, STATus:REASon? returns a null string.

To return the current measurement result (listed as Current in the results tables) use the parent command. For example, use :OSCilloscope:RISetime?, which returns the value for the last waveform acquisition.

Examples

The :MEASure:OSCilloscope:RISetime? query has the following common child queries:

				:MEASure:OSCilloscope:RISetime:COUNt?
				:MEASure:OSCilloscope:RISetime:MAXimum?
				:MEASure:OSCilloscope:RISetime:MEAN?
				:MEASure:OSCilloscope:RISetime:MINimum?
				:MEASure:OSCilloscope:RISetime:SDEViation?
				:MEASure:OSCilloscope:RISetime:STATus?
				:MEASure:OSCilloscope:RISetime:STATus:REASon?

You can also append the :STATus? and :STATus:REASon? child queries to the common statistical queries to determine the validity of those measurements. For example,

				:MEASure:OSCilloscope:RISetime:MAXimum:STATus?:MEASure:OSCilloscope:RISetime:MAXimum:STATus:REASon?

With Smoothing Applied

If smoothing is turned on (:ACQure:SMOothing), the Current, Mean, Minimum, Maximum, and standard deviation (Std Dev) measurements are an average of all previous waveform or pattern acquisitions and are not available until the terminal acquisition Count has been reached (:ACQuire:ECOunt). For example, in 16-count smoothing, the mean measurement is reported after the first 16 acquisitions have completed and the displayed Count value is then incremented from 0 to 1. Each subsequent acquisition increments the Count value.