Getting started with scripting

A script is a simple computer program that communicates instructions to an application like Echoview. Scripts can save time because they enable you to automate repetitive tasks. This topic briefly discusses the things you need to know, or need to do, in order to begin writing scripts for Echoview. Examples are given for VBScript.

To use the Automation module you will need to have an installed copy of Echoview and be licensed for the Automation module and have registered Echoview COM.

To write a script you need to:

Decide which tasks you want Echoview to carry out. This includes decisions about data files, EV files, EV file templates and desired analysis outputs.
Select a scripting language or computer language that can create and use COM objects.
Use the syntax of the selected language together with supported commands or COM objects to communicate with Echoview.

Echoview's script interface
Script languages
- VBScript
- Other languages
- Windows Script Files
Script editors
Script content and structure
- Content
- Language syntax
Using Echoview scripting objects
- Accessing object methods and properties
- Dim and Set
- Using enums
- Further script examples

Echoview's scripting interface

COM object interface

The COM object interface (introduced with Echoview 4.10) offers COM objects. The automation of Echoview can come from a script, web page or other program.

The general syntax of COM objects is documented in Scripting with COM objects - COM object property and method syntax.
The specific syntax of COM objects can be displayed by following the hyperlinks for Echoview COM objects and Echoview COM enums.
The hierarchy of COM object methods and properties is discussed in Scripting with COM objects - Echoview COM object hierarchy.
A common way to start a COM script is discussed in Scripting with COM objects - Creating_a_script.
Echoview COM error handling is discussed in Scripting with COM objects - Echoview COM error handling and Scripting errors.

Script languages

Choose a scripting language or computer language that can create and use COM objects. A general discussion about scripting languages can be found at https://en.wikipedia.org/wiki/Scripting_language.

VBScript

You can download example scripts from the Echoview website.

The help file also provides example COM object scripts.

If you are going to use Windows Script Host to write scripts, you will need to have Windows Script Host installed on your computer. See Installing Windows Script Host.

Other languages

Other languages include (but are not limited to): Python®, R, MATLAB, JScript, Java script, Visual Basic, Visual Basic for Applications, Borland C++ Builder, Delphi, Visual C++, C# and Visual J++

Windows Script Files

Windows Script Files (.wsf) can be useful in a number of ways. In a WSF file you can:

Include other files, for example a library of useful functions you’ve written before.
Bind to a type library which lets you write enums by their name, not value. This technique uses the <reference> tag.
Use several script languages in the one file, for example a mix of VBScript and JScript. The modular structure can also be useful in isolating errors.
One file can contain multiple jobs that can be run separately.

The following is a .wsf script that consists of:

	WSF tag	Description
		A definition for the Echoview type library, so that you can use Echoview COM enum names rather than enum values.
		Multiple scripts.
		Different script languages.
		Job.
<job id="Multiple-language-example"> <reference object="EchoviewCom.EvApplication"/> <script language="VBScript"> Option Explicit Const fName = "C:/Echoview Software/Echoview/EchoviewN/EVFiles/FileA.EV" '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' ' A simple example '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' Dim EvApp Set EvApp = CreateObject("EchoviewCom.EvApplication") ' Open the EV file Dim EvFile Set EvFile = EvApp.OpenFile(fName) If Not EvFile Is Nothing Then MsgBox "Successfully opened EV file with VBScript:" & vbcrlf & EvFile.FileName EvFile.Close Else MsgBox "Failed to open EV file '" & fName & "' with VBScript." End If </script> <script language="JScript"> // Start of the JScript code // Note that we can still use constants And variables which were declared in the // VBScript code above, so we don't have to re-declare EvApp, EvFile, etc. // And we can still use the 'fName' constant for the file Name // Connect To Echoview - commented out because the EvApp Object from above // can still be used // var EvApp; // EvApp = new ActiveXObject("EchoviewCom.EvApplication"); // This declaration also doesn't have to be made again // var fname = "C:/Echoview Software/Echoview/EchoviewN/EVFiles/FileA.EV"; // var EvFile; EvFile = EvApp.OpenFile(fname); // Note that keywords like 'if', 'else' and 'null' are case-sensitive in JScript if (EvFile != null) { WScript.echo("Successfully opened EV file with JScript:\n" + EvFile.FileName); EvFile.Close(); } else { WScript.echo("Failed to open EV file '" + fName + "' with JScript."); } </script> </job>	Code snippet that you can copy/paste into a plain text editor and save as a *.wsf file. "fname" can be edited to refer to a different EV file name and path.

To execute the job in this .wsf, simply double-click the file.

Note: You must have Windows Script Host installed on your computer to run .wsf.

For further information refer to:

Script editors

Text editor

Plain text editors (Notepad, for instance) provide a medium in which to view and write scripts quickly. However you can't do much more than write new scripts, or copy/paste snippets of code to customize your data. You save the script with an appropriate file extension. For example, a script file written using VBScript has a .vbs extension.

Text editor with features

Enhanced editors can provide tools that help you modify, create and debug scripts. Tools can include a COM object browser, debugging features, an interactive display for COM object methods and properties and code snippets. Such editors can be open-source applications or be applications available for trial and/or purchase (such as VBSedit).

Script content and structure

Content

The content of a script is reflection of the tasks you are able to ask Echoview to do. Echoview supports a COM scripting model, it is easy to program with and continues to evolve.

With knowledge of the set of accessible settings and processes, you can then consider the tasks you want to automate. This includes decisions about data files, EV files, EV file templates, analyses and outputs.

Language syntax

The syntax of your chosen language allows you construct a script for the tasks that you want Echoview to perform.

A script consists of:

Statements	Syntax elements or syntax elements with COM object syntax/export scripting commands.
Comments	Text within the script for documentation.

VBScript statements that are useful include:

Variables, constants and arrays.
Arithmetic, logical and comparison operators.
Control structures - If...Then, Else, ElseIf and Case.
Loop structures.
Procedures and functions.

There are many training materials that cover language syntax. Examples of useful materials that can be found on the internet are:

VBScript Tutorials - Herong's Tutorial Notes	Extensive tutorials and examples for the syntax available with VBScript.
VBScript Fundamentals for Windows Scripting – The Basics	Short treatment of the VBScript basics with two annotated script examples.
WSH Tutorial Light (Free Stuff)	Extensive tutorials and examples for the syntax available with VBScript (Appendix C) and JScript (Appendix D).
Visual Basic Guide	Microsoft Technet - Visual Basic guide.

Using Echoview scripting objects

Accessing object properties and methods

To access a COM object’s property or method, you type the object followed by a period and then the method or property.

To access the version number of your Echoview application, you would query the Version property of the EvApplication object:

EvApp.Version

EvApp refers to the object Echoview.EvApplication, which has been declared as a script variable earlier in a script.

To access an object’s method, you follow the same rules, but also add brackets around the parameters.

EvApp.OpenFile("C:\Users\Public\Documents\Echoview Software\Echoview N\Example data\AutoOpen.EV")

This example uses the EvApplication method OpenFile to open AutoOpen.EV.

N is the Echoview version number.

In both of the previous examples script variables like EvApp can use the period modifier (with objects and their methods and properties) as well.

Dim and Set

In a VBScript, before you use Echoview scripting objects, you need to initiate access to the objects. The Dim and Set statements are important in initiating access to objects.

The Dim statement is used to explicitly define a variable or an array variable.
The Set statement is used to refer to an object.

The script variables declared by the Dim/Set statements represent the objects, object properties and object methods that you want to work with. An incidental benefit of using script variables is that long COM object expressions can be referred to instead of being used as is through the script.

At the beginning of a script, Dim and Set are used to connect to Echoview using the EvApplication object. Refer to Scripting with COM objects - Creating_a_script.

Advancing through a script, access to other COM objects is managed in a similar way.

The following COM script snippet is from PickLine.vbs.

Dim EvApp: Set EvApp = CreateObject("EchoviewCom.EvApplication")
 fOut.WriteLine "Echoview version: " & EvApp.Version & " at " & Date & " " & Time
' Open the EV file
Dim EvFile: Set EvFile = EvApp.OpenFile(ScriptsFolder & "EVFiles\FileA.EV")
 If EvFile Is Nothing Then
   fOut.WriteLine "Could not open EV file - " & EvApp.GetLastLogMessage
   WScript.Quit
 End If

The first Dim/Set pair connects to the Echoview COM scripting object EchoviewCom.EvApplication.

The second Dim/Set pair connects to the OpenFile method of the EvApplication object.

Using enums

Some object properties use enums to refer to specific Echoview settings. Script languages can require you to refer to enums in particular ways.

To use an enum name rather than the enum value:

VBScript users are required to define enum name constants at the top of a VBS script. See also Echoview COM enum values: Note
WSF users can use that language's keyword <reference> (at the top of a script job) to define Echoview's enum names. <reference> can be used with any script language job within the .wsf file. See also Windows Script Files.

Further script examples

If you have previous programming experience, example scripts can be useful as demonstration/learning and (script) templating tools.

Example COM scripts are discussed in Example scripts for COM automation. A selection of these scripts emulate the outcome of several export analysis scripts (see below). Other scripts demonstrate more advanced tasks.