About the command interface
- Introduction
- Anatomy of a command
- About Lists
- See also
Introduction
The command interface forms part of the automation and scripting features in Echoview.
Use the command interface to issue text-based instructions either via the console window in Echoview or through a script via the COM method Exec.
Here is a glimpse of what you can do. The prompt > is printed by the system in the console window and is not part of a command.
> Open | C:\path_to\echoview-analysis.EV
Close an EV file saving changes to a new file.
> Close Save | C:\path_to\new-echoview-analysis.EV
Match the names of variables (in all filesets) or surfaces with starting with 'sv'.
> sv*
List the raw line variables. (Refer to the Only Action.)
> VariablesRaw | VariablesLines
Set the Grid X Axis spacing in pings of all the acoustic variables (in all filesets) with names starting with 'sv'.
> sv* | GridXAxisSpacingInPings = | 100
Set the Grid X Axis distance in nautical miles of the first operand (in alphabetical order) of the Sv Mask virtual variable. (Refer to the Properties Action.)
> Sv Mask | Operands | 0 | GridXAxisSpacingInPings = | 22
List the properties and values on the analysis page of the variable properties dialog box of the Sv Mask virtual variable.
> Sv Mask | PageAnalysis
The above examples issue commands via the console, but are also applicable to COM. (Refer to ExportCommands.)
For more information on command interface commands, visit the using the command interface page.
Note that support for the command interface is in a continuing state of development. Hence, ensure the syntax in your existing COM scripts or exported commands are up to date before you execute them.
Anatomy of a command
A basic command interface command comprises these elements
ObjectsMatcher | Action Option(s) | Argument
The | is the Separator. It is part of the command and separates the elements. Refer to the sections below for more information on each element.
If the command returns an Object or ObjectList, you can keep applying Actions. Refer to chaining commands.
The command interface can interpret shorthand versions of commands. When issuing a command in the console for example,
> * | Only VariablesRaw | Only VariablesAcoustic
is equivalent to
> VariablesRaw | VariablesAcoustic
Refer to issuing shorthand commands for details.
The ObjectsMatcher part
A command starts with an ObjectsMatcher which generates an ObjectList of matching Objects. For example, * matches all Objects
> *
Echoview | Ev File | Fileset 1: angular position raw pings T1 | Fileset 1: Power dB raw pings T1 | Fileset 1: TS raw pings T1 | Fileset 1: T1 | Fileset 1: vessel logs
If there is no following Action then this SeparatedList is the result of the command.
Refer to matching Objects by name for more examples.
The Object types
|
Type |
Name |
Description |
|
Application |
Echoview |
The instance of the Echoview application. This Object is always available. |
|
Document |
EV File |
The instance of the EV file. Available when you create a new EV file or load an existing one. |
|
Transducer |
The transducer name |
The transducer object (e.g., Fileset 1: T1). |
|
Surface |
The surface name |
Any surface. |
|
Variable |
The variable name |
Any raw or virtual variable (e.g., Fileset 1: Power dB raw pings T1). |
The Action part
If an Action follows the ObjectsMatcher then it applies to the resulting ObjectsList. The Action will ignore any Objects that do not support the Action.
For example, given all available Objects
> *
Echoview | Ev File | Fileset 1: angular position raw pings T1 | Fileset 1: Power dB raw pings T1 | Fileset 1: TS raw pings T1 | Fileset 1: T1 | Fileset 1: vessel logs
the Save Action only applies to the Document Object. Hence,
> * | Save | C:\Users\FileName.EV
only applies to the Ev File Object.
Filter and operational Actions
There are two kinds of Actions: filter and operational. For example, the Only filter with its VariablesRaw Option restricts the ObjectsList to raw variables.
> * | Only VariablesRaw
Fileset 1: Sv raw pings T1 | Fileset 1: TS raw pings T1
An operational Action performs an operation on the matched Objects, for example
> Sv raw pings T* | Properties MinimumDataThreshold
Fileset 1: Sv raw pings T1 | -70.0 |
Fileset 1: Sv raw pings T2 | -70.0
The result of a filter Action and some operational Actions is a List that can be the input for further Actions, for example
> * | Only VariablesRaw | Properties MinimumDataThreshold
Fileset 1: Sv raw pings T1 | -70.0 |
Fileset 1: TS raw pings T1 | -70.0
Command interface Actions
Here are all the command interface Actions. Specify an Action with its name or one of its Options if it is unique to that Action.
- AppliedObjects
- ClearConsole
- ClearHistory
- Close
- Count
- CreateLine
- Exit
- ExportCommands (ExportCommandsAsPython, ExportCommandsAsVBS)
- ImportCommands
- LastLogMessage
- LineBreaks
- Log
- New
- Only
- Open
- Operands
- Pairs
- Properties
- Save
For more information on Actions, refer to Actions and Options.
The Option part
An Option specializes the Action. If the Option applies only to one Action, then you can omit the Action name. Actions can have a single, several or no Options.
In this example, PageEchogram is an Option of the Properties Action.
> Ev File | Properties PageEchogram
There are three kinds of Options
- a preset token—typically the Option name, e.g., ClearErrors
> Echoview | ClearConsole ClearErrors
- a number (or sequence of numbers)—typically to indicate an index or range of indexes into a List, e.g.,
> * | Only 4 5 -3
Echoview | Ev File | Fileset 1: vessel logs
- a value modifier—to accept an Argument for the Action, e.g.,
> Fileset 1: Sv raw pings T1 | Properties CustomLineDisplayThickness += | 1
Refer to the Action pages for more details on their Options, or unpacking the properties Action for more examples.
Assignment and value modifier Options
The assignment character = can be a second Option followed by a Separator and an Argument. Refer to the Properties or Operands Actions for some examples.
The += or -= value modifier Options followed by a Separator and an Argument perform arithmetic operations or expand or shrink adjustable-sized arrays.
Refer to these examples,
- Example: Extending and contracting a variable-sized array
- Example: Obtain and modify values that are SpacedLists
as well as to the examples for the Properties Action, that utilize the assignment and value modifier Options.
The Argument part
The Argument part provides parameters for the Action.
Refer to some examples on these Action pages.
About Lists
The command interface uses Lists for inputting and reporting values. There are two types
- SeparatedLists
Examples include ObjectLists and PairsLists. The items of a SeparatedLists are
- separated by |—the Separator
- typically of the same type
- in alphanumeric order
- indexed from zero
- SpaceLists
The values are spaced and hence each item must be space-free or quoted (refer to the examples in the table below).
SpaceLists are also indexed from zero.
This table provides further details on the different Lists supported by the command interface.
|
Type |
Description |
|
ObjectList |
Every item is the name of an object.
Refer to the ObjectsMatcher section for an example of an ObjectsList. |
|
PairsList |
A SeparatedList of Name-Value pairs. Each pair is displayed on a new line. The Name can be the name of an object or a property. Value can be an integer, a float, presets (e.g., the Options of the Only Action), a Boolean, or a SpacedList.
PairsLists have a Pairs Action. Here are some example PairsLists with a single pair of elements.
Also refer to the examples
|
|
SpacedList |
These include sets, fixed sized arrays, variable sized arrays, values from a PairsList etc. Unlike other Lists, the items in a SpacedLists are separated by a space instead of the Separator. Values that are names containing spaces are typically converted to camel case.
Hence each item must be space-free or quoted, e.g.,
Refer to the examples in PairsList values that are SpacedLists. |
List Actions
These Actions apply only to Lists.
See also
About the console window
Exec
Using the command interface
Using the console