# Common Child Commands

SCPI Introduction

- Quick Start
- LAN and USB Connections
- Starting a Program
- Common Child Commands
- SCPI Basics
- File Path Substitution Strings
- Definite-Length Block Response Data
- Indefinite-Length Block Response Data
- Waveform Content Windows
- SCPI Security in Infiniium
- Concepts

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, the `: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 Arguments

An example of a command with ON/OFF arguments is the `:DISPlay:GRID:STATe` command, which has the arguments `{{ON | 1} | {OFF | 0}}`. These commands generally have the following common child command:

`:TOGGle`
  Sets to OFF if currently ON or to ON if currently OFF.

## Commands with Parameter Arguments

An example of a command with parameter arguments is the `:CHANnel:COLor` command, which has the arguments `TCOLor1` through `TCOLor48`. 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`. 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 2ns, 3ns, and so forth with each command. For sequence changes, if a time span is set to 1ns, sending the child command `:STEP -1` would change the span to 2ns. Sending the command a second time would set the span to 5ns, 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 displayed only in the result table. It is calculated over the number of waveform acquisitions returned by the `COUNt?` query.
:COUNt?
  Returns the number of measurements (Count) that have been made for the parent measurement. If the measurement has Measure All selected, the count can be much larger than the number of waveform acquisitions. Up to 64-bit integer values can be returned.
:LOCation?
  Returns the location (index) of the measurement in the displayed results table. This query is available for all waveform, eye diagram, 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?
  Selects a time span over which an oscilloscope 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 "Common Reasons for INV or QUES Status". 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 `:MEASure:HORizontal:RTIMe?`, which returns the value for the last waveform acquisition.

### Examples

The `:MEASure:HORizontal:RTIMe?` query has the following common child queries:

    :MEASure:HORizontal:RTIMe:COUNt?
    :MEASure:HORizontal:RTIMe:MAXimum?
    :MEASure:HORizontal:RTIMe:MEAN?
    :MEASure:HORizontal:RTIMe:MINimum?
    :MEASure:HORizontal:RTIMe:SDEViation?
    :MEASure:HORizontal:RTIMe:STATus?
    :MEASure:HORizontal:RTIMe: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:HORizontal:RTIMe:MAXimum:STATus?
    :MEASure:HORizontal:RTIMe:MAXimum:STATus:REASon?

### With Smoothing Applied

If smoothing is turned on (`:ACQuire:SMODe`), 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:COUNt`). 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.