Copyright (c) 1997 by the University of Washington. All rights reserved. This is a proprietary and confidential document. Under no circumstances may this document be used, modified, copied, distributed, or sold without the express written permission of the copyright holder.

Visual Etch Command Line Interface

Visual Etch is designed to be used as a graphical user interface, however it can also be invoked directly from the command line with command line flags. There are two major reasons for invoking Visual Etch from its command line interface, rather than interactively. First, this is useful in automated testing of Visual Etch and its environment. Second, Visual Etch provides a very simple command line interface for running Etch experiments, compared to direct invocation of the Etch binary-rewriting engine, because Visual Etch manages the entire etching process (e.g., environmental setup, caching, etching, patching, output file creation, and so on).

The format of the Visual Etch invocation is:

     vetch [project file] [command1] [command2] ...
The commands on the command line form a very primitive scripting language for Visual Etch. The commands are executed sequentially one after another.

For example, the vetch command: 

 
    vetch winword.vpr -application "D:/Program Files/msoffice/word/winword.exe" 
       -tool dllwatch -executeaction -tool cgprof

would:

  1. open a project called winword.vpr
  2. load the application winword.exe into Visual Etch
  3. run the DLLwatch tool on winword
  4. run the call graph profiler tool on winword

This example shows how a complete Etch experiment -- in this case creating a call-graph profile of an application (winword) -- can be invoked with a single command line issued in a command prompt window or from a batch file.

Commands available from the command line interface

The following is a list of commands that Visual Etch recognizes from the command line:

-application [appname]
sets the application name to be [appname]
-tool [toolname]
sets the tool name to be [toolname]
-script [scriptname]
checks the script checkbox and set the script name to be [scriptname]
-logfile [logfile]
logs all message box messages to [logfile].messages and error message box messages to [logfile].errors (this option is not yet implemented)
-noninteractive
turns off message boxes that wait for the user to click okay (this option is not yet implemented)
-commandline [command line arguments]
sets the command line arguments for the application
-clearcache
clears the Visual Etch cache
-etchonly
simulates the user clicking the Etch Only button
-executeaction
simulates the user clicking the Execute Action button
-runonly
simulates the user clicking the Run Only button
-exitvetch
exits Visual Etch

Notes:

  1. The user interface is still enabled when the command line is being parsed: the user can still click on buttons and cause actions to be executed. However, the interaction of the actions specified by the user and those specified on the command line is not defined.
  2. The user may click on the Abort button in the Running Experiment dialog box to abort the parsing and execution of command line arguments. This is useful when something unexpected (i.e. an error) happens in the middle of a series of commands.