Scripting with COM objects

The scripting module allows you to use Echoview COM objects to control and interrogate Echoview. COM automation allows third parties to develop scripts and applications that interact with Echoview in a well-defined and easy to use manner. Details about registered COM objects found by Echoview can be found on the Scripting page of the Echoview Configuration dialog box.

A useful overview of scripting for Echoview is Getting started with scripting.

COM provides several advantages over our previous scripting implementation:

• The COM object can query Echoview as it runs. This allows you to make informed decisions.
• Operations can be easily performed on multiple objects, or an entire collection.
• The object is immediately informed of the failure of a procedure call. This makes it easier to find the source of a failed export or an unexpected result.
• Echoview does not have to initialize and terminate for each script. This has the potential to make small scripts run faster.
• Its functionality is more versatile and easier to extend.

This help file topic does not include a basic course in the use of COM objects. Some sources of general information on using COM objects that may assist you are:

• COM objects: Microsoft® Windows® 2000 Scripting Guide
• The COM Process: Microsoft® Windows® 2000 Scripting Guide
• The Microsoft Script Center
• Introduction to COM - What It Is and How to Use It. by Michel Dunn

This topic covers:

• COM terms
• COM object property and method syntax
• Creating a script
• Determining which Echoview.exe to use
• Echoview COM object hierarchy
• COM objects and Echoview
• Echoview COM error handling
• Known issues

COM terms

COM terms used in this Help file:

COM object syntax

COM objects are accessed through their properties and methods.

The syntax of properties and methods are documented in the following way:

Feature	IsLicensed example
1. The name of the method or property.	IsLicensed is an Ev.Application method.
2. The syntax of the method or property.
(a) The type of access can be implied or stated as (read-only) or (read-write).	(a) The type of access is implied (read-only).
(b) The syntax specifies the data type of required and optional input and the data type of the resulting output.	(b) The output for IsLicesned is boolean (yellow highlight). No input required is required for IsLicensed (pink highlight).
(c) Further information is displayed under the headings: Summary Parameters Return	(c) Summary, Parameters and Return briefly describe the use of IsLicensed.

Data types

Boolean

Refer to the IsLicensed example (above).

String, Integer or int, Double, COM object

DetectSurface is a method of the EvVariableAcoustic object.

DectectSurface inputs:

• A string (e.g. a variable called SurfaceName) for the detected bottom surface.
• An integer (e.g. a variable called FirstPing) to specify the first ping for the detection.
• An integer (e.g. a variable called LastPing) to specify the last ping for the detection.
• A double number (e.g. a variable called BetweenPingInterpolation) to specify the Maximum triangulation distance.

DetectSurface returns a detected bottom surface (with a specified name) that is accessed by the COM object EvObject3D.

DATE

A data type for the date as specified by Microsoft Office DATE or Microsoft Visual Studio 2005/.NET Framework 2.0 DATE .

Enum

DepthRangeMode is a read-only property of the EvGrid object. The property returns information about the grid on an echogram. The information is an enum for EDepthRangeGridMode where

• eNoDRGrid = 0 (There is no depth/range grid.)
• eDepthGrid = 1 (There is a depth/range grid.)

Creating a script

Start by creating a file in a text editor (Notepad, for instance) and name it with the .vbs extension, for example, echoviewscript.vbs.

To connect to Echoview, first create an instance of the EvApplication object:

' Open Echoview (if Echoview is already open, connects to the 
   ' open Echoview instance)
   Dim EvApp 
   Set EvApp = CreateObject("EchoviewCom.EvApplication") 

Notes:

• The Echoview COM scripting module automatically creates a scripting log file when a script is run. See Scripting errors for more information about the log file.

• This scripting log file can become very large, and slow down your processing. To ensure that your scripts run efficiently, create a command to delete the scripting log file before running the script. This command is inserted at the start of the script. For example,

Dim EvApp
Set EvAPP = CreateObject ("EchoviewCom.EvApplication")
Dim FSO 
Set FSO = CreateObject("Scripting.FileSystemObject")
FSO.DeleteFile(EvApp.LogFileName)
  

To view examples of complete COM scripts refer to Example scripts for COM automation.

See also Getting started with scripting - Script content and structure.

Determining which Echoview.exe to use

When Echoview COM objects are requested (by scripts), Microsoft Windows finds the COM object in the last registered version of Echoview that was opened. The last registered version can be:

• An instance of Echoview that is open.
• The last instance of Echoview that was opened and then closed.

Notes:

• If you are using Windows Vista, you may need to run Echoview once using Run as Administrator to register COM scripting. You will need to do this for each version of Echoview you run. For further information, see Echoview and Vista.
• To find out which version of Echoview you are using:

Echoview COM object hierarchy

The relationship of COM objects and collections to each other is discussed in the topic COM object hierarchy. The hierarchy page displays a schematic with image links to relevant COM object documentation.

COM objects and Echoview

All Echoview’s COM automation functionality is begun through the EvApplication object. Many of the create, detect and export command methods for an acoustic variable in an EV file are accessed via the EvVariableAcoustic object.

The relationship between a COM object and Echoview is decscribed in Summary of COM objects.

Echoview COM error handling

It is desirable to detect a failure, or error, in a running script. VBS usually produces an exception after a failure which is not very informative. An alternative for detecting failure of a method is to include a test of the validity of the returned value in the script.

The value returned for a method is usually: the object created; the number of objects created; or a boolean. In each case there is a recognised value that signals failure. NULL and -1 are used for objects or counts, and false is used for booleans. Validity of objects, for example, can be tested in VBScript by comparing them to Nothing (NULL) as in the 'Is Nothing' test for acoustic variables in the example below.

Setting the value of property does not return a value, but the set can be checked with get. A report of the reason for a failure may be accessed using the EvApplication method GetLastLogMessage().

For example:

Dim FSO: Set FSO = CreateObject("Scripting.FileSystemObject")
Dim fOut: Set fOut = FSO.OpenTextFile("tmp.txt", 2, true) 
Dim EvApp: Set EvApp = CreateObject("EchoviewCom.EvApplication")
Dim EvFile: Set EvFile = EvApp.OpenFile("MyEvFile.ev")
for VarIndex = 0 to EvFile.Variables.Count-1
     Dim Var: Set Var = EvFile.Variables.Item(VarIndex)
     Dim VarAc: Set VarAc = Var.AsVariableAcoustic
     If VarAc Is Nothing Then 
         fOut.WriteLine Var.Name & " is not an acoustic variable"
     Else
         Dim iCount: iCount = VarAc.DetectFishtracks("Detected Fish")
         If iCount = -1 Then
              fOut.WriteLine VarAc.Name & ": " & EvApp.GetLastLogMessage
         Else 
              fOut.WriteLine Var.Name & " Schools: " & CStr(iCount)
         End If
     End If
Next
fOut.Close

Note: In the VBS language, NULL is returned as Nothing.

Known issues

The VBS language handles optional parameters and optional object parameters differently.

Optional object parameters can not be omitted

For example, VBS will not accept the omission of Nothing in the following:

If Not VarAc.ExportIntegrationByCells("SomeFile.csv", Nothing) Then

Optional parameters can be omitted

For example VBS will accept the following:

Set Surface = VarAc.DetectSurface("Surface”) 
 

The above script snippet sets a variable to be the surface which is the result of the EvVariableAcoustic.DetectSurface method. In this case the omitted optional parameters default as follows: FirstPing: -1, LastPing: -1 (the whole echogram) and Maximum triangulation distance: 20.0.

Windows and Echoview COM

Echoview COM (known as the Echoview Automation Library) is built into the Echoview software. To register the Echoview Automation Library with Windows (especially with Vista or Windows 7and their tigher security) you will need to run Echoview (once) under Run As Administrator. This registers Echoview and the Echoview Automation Library.

See also

About automating Echoview
Getting started with scripting
Scripting errors
Summary of COM objects

Echoview Help file 5.1.25 for Echoview 5.1.45 Wednesday 1st  February 2012

Please report any errors or omissions to support@echoview.com.