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 scripting module you will need to have an installed copy of Echoview and be licensed for the Scripting module.
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 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.
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 http://en.wikipedia.org/wiki/Scripting_language.
VBScript
You can download example scripts from the Echoview website under Data Processing > Automation via Scripting
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): 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. Information about this can be found under Microsoft Windows Script Files.
The following is a .wsf script that consists of:
|
|
WSF tag
|
Decscription
|
 |
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:/Myriax/Echoview/Echoview4/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:/Myriax/Echoview/Echoview4/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.
See also Example scripts for COM automation.
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).
A useful website that lists a variety of editors is http://www.softplatz.com/software/vbscript-editor/.
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:
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:\Myriax\Echoview\Echoview4\AutoOpen.EV)"
|
This example uses the the EvApplication method OpenFile to open AutoOpen.EV
|
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 begining 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.
See also
About automating Echoview
Scripting with COM objects
