BrainVoyager 2000 supports an open interface via COM-based automation. Information about COM and scripting can be found on the Microsoft web sites http://www.microsoft.com/com and http://www.microsoft.com/scripting/. With the open interface implemented in BrainVoyager you can:
Write scripts to perform sequences of commands. Three major scripting languages are supported: Visual Basic (VBScript), Java (JScript) and Perl (PerlScript). An important application of scripting is to run a set of preprocessing steps and statistical analysis routines in batch mode across data sets from many subjects.
Write your own C/C++ code and interoperate with BrainVoyager. In combination with the knowledge of the documented BrainVoyager file formats, this is the most efficient way to access the internal routines of BrainVoyager and to combine own programs with the tools provided by BrainVoyager.
Launch BrainVoyager on remote machines in your local area network and control them from a single computer.
Exchange scripts with other user's as a clear and precise description of performed data analysis steps.
Setting up demonstrations, explanations and tutorials for you and others using methods controlling the Graphical User Interface (GUI).
In order to be able to use BrainVoyager routines "from outside",
the routines have been made available through defining a set of dual COM
interfaces. These interfaces are exposed by BrainVoyager acting as a COM
server. The set of interfaces
provide an object model consisting
of a growing number of methods
and properties which can be called
by the client (the user's script
or C++ code). Another way to view the situation is that the exposed routines
are "added" to the supported scripting languages resulting in
a kind of "high-level neuroimaging programming language". The
VBScript and JScript scripting languages are provided by Microsoft. If
your system does not have the necessary files installed, BrainVoyager
2000 will install them during setup. PerlScript is provided by ActiveState
(see http://www.activestate.com)
and can be also installed directly from the BrainVoyager 2000 CD.
Chapter overview
The next topic introduces the basics of automation using a very simple
script. The simple script demonstrates the use of all three supported
scripting languages. Then it is described how you can modify
and run scripts from within BrainVoyager. After that, a
more elaborate and useful script is presented which you can use as
a template for own batch processing scripts. The script shows how to run
preprocessing steps across multiple subjects and runs.
It follows a description of two small C++ programs which demonstrate how
to interoperate with BrainVoyager including direct access of BrainVoyager
files. The two programs perform exactly the same task but use two different
appraoches to access a COM server, the first
program uses a universal but complicated approach while the second
program uses an easy approach which is, however, only possible with
the Microsoft Visual C++ compiler.
Then follows the largest section of this chapter which consists of a description
of exposed methods and properties which you can use to (remotely) control
BrainVoyager. Since this list will be further expanded in the future,
check http://www.BrainVoyager.com/HelpUpdate to obtain always the latest
version of this document. In future versions of this document, some advanced
topics will be described, i.e. registering callback routines which enable
BrainVoyager to call routines in your code.
Additional documentation and references
This chapter describes the COM objects and methods provided by BrainVoyager. It assumes, however, basic programming knowledge sufficient to write scripts or C/C++ programs. This section provides you with further informations about documentation and references which will help you to get started quickly.
Excellent online documentation for VBScript and JScript is provided
by Microsoft. For your conveniency, we have included this documentation
on the BrainVoyager 2000 CD. Simply double-click the files "vbsdoc.exe"
and "jsdoc.exe" to install the online documentation. After installation,
you will find the documentation in the "Start->Programs
->Microsoft Windows Script" menu.
Excellent documentation for PerlScript is provided by Active State Tools
Inc. The online documentation is installed automatically when you install
Perl which can be found on their Web page (http://www.activestate.com).
You can also install Perl directly from the BrainVoyager 2000 CD. After
installation, you will find the documentation in the "Start->Programs->ActivePerl"
menu. Documentation for automation can be found in the "Win32::OLE"
section which is located in the "Module Docs" section.
If you want to use other objects then those provided by BrainVoyager, i.e. to manipulate your files or registry from your scripts, you should read documentation on the Microsoft "Windows Script Host". We have put the Word file "wshobj.doc" produced by Microsoft on the BrainVoyager 2000 CD which details the object model and methods of the Windows Script Host.
If you are a C/C++ or Java programmer and you want to interoperate with BrainVoyager, we recommend to read a couple of books on COM / DCOM programming. From our own experience, we can highly recommend the following books:
Guy Eddon & Henry Eddon (1998). Inside Distributed COM, Microsoft Press
Thuan L. Thai (1999). Learning DCOM, O'Reilly & Associates, Inc.
David S. Platt (1998). The essence of COM with ActiveX. Prentice Hall.