Echoview Command interface and command syntax
The Echoview Command interface enables access to Echoview's features via instructions given as lines of text. The interface can be accessed by the Console dialog box and the Console controls or by COM scripting and requires a licensed Automation module.
Commands can be typed or pasted into the Console dialog box at the '>' prompt. Batch commands may be read in from an EC, Python or Visual Basic (VB) script file.
The commands specify objects, actions and arguments for the interface. Progress is determined by the values returned by Echoview. The interface is designed to minimize both text input and any in-depth knowledge of commands. However a working knowledge of Echoview is helpful. The interface only supports the display of a single property for multiple objects or multiple properties for a single object.
Note that support for the Command interface is in a continuing state of development and that parts of the command syntax may change.
- Command syntax
- Example display conventions
- Text color
- Text completion
- Objects
- Object matching
- Actions, options and arguments
- Extended commands
- Properties
- Filter
- Actions
- Logical AND
- Logical OR
- Error handling
- Number handling
- COM Exec return handling
- Example to export commands to a VBS file
- Output of properties for all variables via COM and the command interface
- Another VBS script (to download)
Command syntax
The console is case-insensitive. Valid characters include [A...Z] and [0...9]
Reserved symbols include * | = as the wildcard, command element separation and assignment characters.
The command interface handles variable names according to Echoview object naming rules. However, Echoview removes the File name illegal characters if you use any of them to name a file using the console.
To distinguish general/specific references to elements within the discussion text, the <Elements> are bracketed. Examples show an interface command and the Echoview return.
Elements include: <ObjectName>, <ActionName>, <ActionOption>, <Argument>, <FilterAction>
A general example of a command:
<ObjectName> | ... | <ActionName> <ActionOption>| <Argument> | ...
Press Enter to issue a command.
Example display conventions
The depiction of command interface examples is similar to what you would see in the Console dialog box. Using your own EV file and variable names, you can enter an example command line and view the return.
An example shows:
- A '>' prompt followed by a command line. When no key press instructions are displayed next to the command line, a key press Enter is assumed. Some text completion examples include key press instructions enclosed in brackets.
- The immediate following text is the Echoview command interface return.
The following example is general enough to use with your EV file and variables with Sv in the variable name.
Console display |
Command line description |
| > sv* (Press Enter) Fileset 1: Sv raw pings T1 | Fileset 1: Sv raw pings T2 > |
Lists all the Sv variables. |
| > sv* | GridXAxisSpacingInNauticalMiles Fileset 1: Sv raw pings T1 | 0.5 | Fileset 1: Sv raw pings T2 | 0.5 > sv* | GridXAxisSpacingInNauticalMiles =| 22 > sv* | GridXAxisSpacingInNauticalMiles Fileset 1: Sv raw pings T1 | 22.0 | Fileset 1: Sv raw pings T2 | 22.0 > |
Lists the Grid page ping axis spacing in nautical miles, for all variables matched to Sv*. For all the Sv* variable names change the Grid page ping axis spacing to a value of 22 nm. List the Grid page ping axis values for all the Sv* variable names (as a visual check). |
Text color
Console text colors differentiate between console information types.
- Black for text entry
- Dark grey for Shift+Tab return text
- Dark blue for returned text
- Red for error message text
Text completion
The Console dialog box offers command interface text matching and text completion with prefix text and with the Tab and Shift+Tab key presses.
Press Tab to complete object text.
> sv(Press Tab)
> Fileset 1: Sv raw pings T
Press Shift+Tab to use text-prefix matching.
> sv(Shift+Tab)
"sv" matches objects
Fileset 1: Sv raw pings T1
Fileset 1: Sv raw pings T2.
> sv
Press Shift+Up arrow or Shift+Down arrow to complete a command with a selection from the latest list or a selection from a list of associated matches.
> sv(Shift+Tab)
"sv" matches objects
Fileset 1: Sv raw pings T1
Fileset 1: Sv raw pings T2.
> sv(Press Tab)> Fileset 1: Sv raw pings T then (Shift+Up arrow twice) returns > Fileset 1: Sv raw pings T1
> EV File | (Shift+Up arrow) returns >EvFile | Save
> EV File | (Shift+Up arrow twice) returns > Ev File | Properties
> EV File | (Shift+Up arrow thrice) returns > Ev File | CreateLine
> EV File | (Shift+Up arrow four times) returns > Ev File | Close
> EV File | (Shift+Up arrow five times) returns > Ev File | AppliedObjects
In this case, use a trailing space and Shift+Tab to match <Actions>.
> sv | (Shift+Tab)
The following actions are applicable:
AppliedObjects
CreateLine
Properties.
> sv |
The '*' wildcard is supported by the Command Interface.
- The use of * on its own followed by Enter returns a running list of all objects.
- The use of * on its own followed by Shift+Tab returns a list of all objects with an object per line.
Objects
<ObjectNames> represent key and unique parts of the Echoview interface. Some <ObjectNames> support <ActionNames>, other <ObjectNames> don't support <ActionNames> but may be considered when filtering. For further information refer to <ObjectTypes>.
The <Objects> list is made up of specific <ObjectNames>.
<ObjectNames> that support <ActionNames> include:
| <Object> | Instance of the <ObjectName> | Details |
| <Echoview> | <Echoview> |
An instance of Echoview. |
| <Ev File> | <Ev File> |
The open EV file in Echoview. |
| <Variables> | <svrawpingst1> |
An Echoview data variable.
|
| <Transducers> | <T1> |
A Dataflow transducer in Echoview. |
Object matching
The interface attempts to match partial text to known <ObjectNames>.
- An <ObjectName> is case and space insensitive. For example <Spaced Oubt> and <space doubt> name the same object.
- <ObjectNames> can be prefix-matched with initial text followed by the * symbol.
- Press Tab to display the closest text match.
- Press Shift+Tab to list potential matches.
- Press Shift+Up arrow/DOWN ARROW to complete a command with a selection from a list of matches.
- The symbol * used alone returns all <Objects>.
- The fileset name of an <ObjectName> can be omitted. However, an <ObjectName> without a fileset prefix will match that text in every fileset.
- If there is no <Objects> list then the <ActionName> is applied to every <ObjectName> that supports it.
Examples
Refer to the Text completion section for examples.
The following is the syntax to save changes for the open EV file:
> Echoview | EVFile | Save | c:\YourFolder\YourFile
The following command can also be used to save changes for the open EV file:
> Save | c:\YourFolder\YourFile
Actions, Options and Arguments
ObjectName | ActionName ActionOption | Argument
- <Actions> act on <objects>. Some actions have mandatory and/or optional parameters.
- An <ActionName> can be applied to a list of objects.
- If there is no action then the objects list itself is produced.
- ActionName is case insensitive.
- ActionName can be prefix matched by a single Tab key press.
- ActionName can be omitted if the option is unique.
- ActionOptions are available for Ev file, <Variables> and <Transducers> Properties.
Example
Request for prefix-matched "Sv" <Objects> followed by <ActionName><Shift+Tab> matching for the partial text "gridxaxissp". The interface returns possible matching <ActionNames>.
> sv* | gridxaxissp(Shift+Tab)
"gridxaxissp" matches actions
Properties GridXAxisSpacingInDays
Properties GridXAxisSpacingInHours
Properties GridXAxisSpacingInMeters
Properties GridXAxisSpacingInMinutes
Properties GridXAxisSpacingInNauticalMiles
Properties GridXAxisSpacingInPings.
> sv* | gridxaxissp
Extended commands
A command that produces a list of objects can be extended with another action element and arguments list.
For example, <variablesvirtual | variablesacoustic | gridxaxis> command line lists the Grid Show time/distance value for all virtual acoustic variables as a <variablename | value |> ordered list. This extended command uses a logical AND arrangement and returns a list of virtual acoustic variables.
> variablesvirtual | variablesacoustic | gridxaxis
AAProcessed data 1 | GPSDistanceNmi |
Background noise removal 1 | GPSDistanceNmi |
Code 1 | GPSDistanceM |
Data range bitmap 1 | GPSDistanceM |
dB diff | PingNumber |
Formula 1 | GPSDistanceNmi |
Ping subset 1 | GPSDistanceM |
Processed data 3 | None |
STDM2 | None |
Target samples bitmap 1 | None
A similar command using a logical OR arrangement returns a list that includes virtual variables and acoustic variables.
> VariablesVirtual VariablesAcoustic | GridXAxis
0.2m | None |
AAProcessed data 1 | GPSDistanceNmi |
Background noise removal 1 | GPSDistanceNmi |
Code 1 | GPSDistanceM |
Data range bitmap 1 | GPSDistanceM |
dB diff | PingNumber |
Fileset 1: angular position raw pings T1 | None |
Fileset 1: angular position raw pings T2 | None |
Fileset 1: Power dB raw pings T1 | None |
Fileset 1: Power dB raw pings T2 | None |
Fileset 1: Sv raw pings T1 | GPSDistanceNmi |
Fileset 1: Sv raw pings T2 | None |
Fileset 1: TS raw pings T1 | None |
Fileset 1: TS raw pings T2 | None |
Formula 1 | GPSDistanceNmi |
Ping subset 1 | GPSDistanceM |
Processed data 3 | None |
STDM2 | None |
Target samples bitmap 1 | None |
Threshold offset 1 | None |
Vegetation? | None |
Veg from above | None
The addition of <| Value> returns just the <value> ordered list.
> VariablesVirtual | VariablesAcoustic | GridXAxis | Value
GPSDistanceM | GPSDistanceM | GPSDistanceM | GPSDistanceNmi | GPSDistanceNmi | GPSDistanceNmi | None | None | None | PingNumber
An extended command can be used to display operands up a virtual chain or change an operand.
The dataflow (right) for the virtual chain is from the Echoview tutorial: Introduction to Multibeam Target Data Processing. The virtual variable at the bottom of the chain is marked. The initial operand and new operand five variables up the chain are marked. Displaying operands for a virtual variable, then displaying the first operand up the virtual dataflow.
Changing an operand that lays up a virtual dataflow.
|
 |
Filter
The interface can filter any list of objects using either logical AND or logical OR.
See also Ev File, Variable and Transducer <Properties> and <PropertiesOptions>.
<FilterActions>
| FilterActionName | Description | ||||||
| Count | Returns the number of objects in a list or returns the number of items for a <PropertyName>. Syntax
Description<count> may be used as an <ActionName> with respect to an <ObjectList>. <count> may be used as an <ActionOption> with respect to a <PropertyName>. <VariablePropertyName Count> returns a count with respect to each variable. See also Ev File Properties, Variable Properties, Transducer Properties. Note: <ActionName> matches are prioritized over <ActionOption> matches for an ambiguous wildcard <ObjectName>.
<ObjectList> examples
<PropertyName> example
|
||||||
| Only | Syntax<ObjectList> | only <FilterActionOption> <ObjectType> <ObjectList> | <FilterActionOption> <ObjectType> DescriptionRestricts filter to an <ObjectType>. ! is a <FilterActionOption> that applies a logical NOT so the <ObjectType> is filtered out from the returned list. The syntax is <!> followed by a space and then <ObjectType>. Example
A variation, to view unavailable variables. Under the Filesets dialog box, the Sv raw pings T1 checkbox is clear. The return lists all the subsequent unavailable variables.
See also Example for SPACE+Shift+Tab. |
||||||
|
<positive integer>..<positive integer> |
Syntax<ObjectList> | <j> <ObjectList> | <n..m> DescriptionA single positive integer j specifies a list index and the interface returns the list element. The list index begins at 0. An integer range, n..m, specifies a list index range and the interface returns the range of list elements. Example
|
||||||
| ObjectTypes | <ObjectTypes> can be used to filter an <Objects> list. <ObjectTypes> may be used in logical AND and logical OR commands.
|
Properties
Variable Properties and other object properties are handled with the "=" action option immediately followed by "|" and the property value. Note, some properties may be read-only on the Console.
The special value 'No data' serves as a default value for Graph axis minimums and maximums, and some Calibration Assistant properties.
For further information refer to EV File object Properties, Variables object Properties, Transducers object Properties, VariablesVirtual object and PropertiesOptions.
Logical AND
List objects that are not acoustic and not lines and not movement and not transducers. See also: Only example, Extended commands.
List objects that are virtual variables and lines.
> variablesvirtual | variablesline
0.2m | Threshold offset 1 | Vegetation? | Veg from above
Logical OR
List objects that are <lines> or <movement> objects. See also: Extended commands.
> variablesline variablesmovement
0.2m | Bottom | Fileset 1: heading data GPVTG | Fileset 1: line data depth GPGGA | Fileset 1: position GPS fixes | Fileset 1: position GPS fixes GPGGA | Fileset 1: position GPS fixes GPGLL | Fileset 1: position GPS fixes GPRMC | Threshold offset 1 | Threshold offset 1EchoviewEVL | Vegetation? | Veg from above
Error handling
The interface returns an ERROR message when it is unable to execute a command line.
Troubleshooting ideas include:
- The interface can't match 'x...x' to an <Object>
or <Action>.
- Is 'x...x' misspelled?
- The interface is not configured to recognize 'x...x'.
- Is the syntax correct? <!> and following text requires a space separator.
- Command syntax is incorrect. The interface returns a best guess list based on text in the command line. Review the <Object>, <Action>, <Option>, <Filter> and <Argument> elements of the command line.
- The assign a new value option < =|> requires a space before it and a <Value> after it.
- The interface can't display the (entire) <Properties> list for multiple <Objects>.
Python error handling
Console dialog box Export Commands As Python... includes Console command and Console error handling code.
Number handling
Properties that take integer values will truncate assigned real values.
COM Exec return handling
Echoview provides VB script code to handle the returns of the COM Exec method. The Console dialog box feature Export Commands As VBScript creates a VBS file containing successful command lines and Command interface return handling functions.
Example to export commands to a VBS file
Substitute your EV file in place of "C:\TEMP\YourEvFile.EV".
- Start Echoview.
- On the View menu select Console.
- In Console dialog box at >, type Open | "C:\TEMP\YourEvFile.EV", then press Enter.
- In Console dialog box at >, type Variables, then press Enter.
- Steps 3 and 4 are command lines sent to the Echoview Command interface. Step 3, opens YourEvFile.ev. Step 4 returns all the variable names in the EV file.
- In Console dialog box at >, type ExportCommandsAsVbs | C:\Temp\ExampleScript.vbs, then press Enter.
- Open C:\Temp\ExampleScript.vbs in a text editor, review and modify as required.
- The content of ExampleScript.vbs includes default functions created as part of ExportCommandsAsVbs, these include COM Exec content for the successful command lines from the Console export. Other content includes error and command interface return handling functions.
Output of properties for all variables via COM and the command interface
COM ExportSettings exports supported Variable Properties settings to a text file.
Command interface Export and its variations can export supported Variable Properties, EV File Properties and Transducer Properties to a text file. The Console dialog box and Command interface can display such settings.
Building upon the previous example, the following script includes the return and error handling functions, and COM content (red text) that sends commands to the command interface (via COM Exec) to request the properties for all the acoustic variables in the EV file. A Windows Message box displays a list of truncated properties for each acoustic variable.
''''''''''''''''''''''''''''''''''''''''''''''''''
' PropertyOutput.vbs
''''''''''''''''''''''''''''''''''''''''''''''''''
Dim ev: Set ev = GetObject(, "EchoviewCom.EvApplication")
' Trim all strings in array
Function TrimArray(arr)
ReDim result(UBound(arr))
For i = 0 To UBound(arr)
result(i) = Replace(Trim(arr(i)), vbCrLf, "")
Next
TrimArray = result
End Function
' Skip the first n elements of array
Function Skip(arr, n)
ReDim result(UBound(arr) - n)
For i = n To UBound(arr)
result(i - n) = arr(i)
Next
Skip = result
End Function
' Take the first n elements of array
Function Take(arr, n)
ReDim result(n - 1)
For i = 0 To n - 1
result(i) = arr(i)
Next
Take = result
End Function
' Convert reply string to the result, handling any message
Function GetResults(request, reply)
Dim results: results = TrimArray(Split(reply, "|"))
If UBound(results) >= 0 Then
If StrComp("ERROR", results(0)) = 0 Then
' error message & exit
MsgBox request & vbCrLf & "** " & Join(results, vbCrLf)
WScript.Quit
Elseif StrComp("WARNING", results(0)) = 0 Then
' script-formatted warning message & values
MsgBox request & vbCrLf & "-- Warning" & vbCrLf & Skip(results, 1)(0)
results = Skip(results, 2)
Elseif StrComp("HELP", results(0)) = 0 Then
' script-formatted message, no values
MsgBox request & vbCrLf & "Help" & vbCrLf & Join(Skip(results, 1), vbCrLf)
results = Array()
End If
End If
GetResults = results
End Function
Sub Ex(request)
ev.Exec("Log | " & request)
Dim results: results = GetResults(request, ev.Exec(request))
If UBound(results) >= 0 Then
MsgBox Join(results, vbCrLf)
End If
End Sub
Function Exec(request)
Exec = GetResults(request, ev.Exec(request))
End Function
ev.Exec("Log | Starting PropertyOutput.vbs")
Exec "open | C:\TEMP\YourEvFile.EV "
Dim vars: vars = Exec("VariablesAcoustic")
Dim var
For Each var In vars
Dim Props: Props = Join(Exec(var & " | Properties"), vbCrLf)
MsgBox Props
Next
ev.Exec("Log | Finished PropertyOutput.vbs")
Variations on this example script include:
- Use of a different script language.
- Use of multiple EV files.
- Writing settings out to a file instead of a Message box.
- Changing properties, listing virtual variable properties, listing transducer properties, listing all lines etc.
Another VBS script
Supported variable properties are accessible via the Command interface. The annotated example code from the file (below) changes a Variable Properties setting which is not accessible to COM. The code could be expanded to work through multiple EV files and/or multiple variable properties.
EV script 016 - Combine COM and Command interface to change variable properties.vbs is available at: https://echoview.com/support/example-scripts/