-------------------------------------------------------------
This is the README file for jSVM (Statechart Virtual Machine)
                             by
                         Thomas Feng
                     thomas@email.com.cn
            http://msdl.cs.mcgill.ca/people/tfeng/
-------------------------------------------------------------

1. REQUIREMENTS

If you use the source package:
  a. Jython 2.0 or higher (downloadable from
     http://www.jython.org/)
  b. JRE 1.3 or higher (downloadable from http://www.java.com)

If you use the jar package:
  a. JRE 1.3 or higher



2. INSTALLATION

Simply unpack the package to a directory.



3. GETTING STARTED

If you use the source package:
  Run jsvm.bat or ./jsvm, depending on your operating system
  (either Windows or Unix).
  To run a model:
      jsvm.bat [model_name] [parameters] or
      ./jsvm [model_name] [parameters]

If you use the jar package:
  Run java -jar jsvm.jar.
  To run a model:
      java -jar jsvm.jar [model_name] [parameters]



4. TESTING THE MODELS

Conventionally, a model is written in a .des file. You can
find such files in the subdirectories simple and datatypes.

simple/simple.des
  A very simple model to demonstrate the basic parts of a
  statechart and also submodel importation. It imports
  itself, so it is a recursive structure.
  To run:
      jsvm simple/simple.des

datatypes/boolean.des
  Another very simple model demonstrating a single cell to
  store a boolean value.
  To run:
      jsvm datatypes/boolean.des

datatypes/counter.des
  A little more complex model that makes use of the self
  importation structure. It models a cell to store an
  integer value, which can be increased or decreased by 1 at
  a time. The cell is unbounded.
  To run:
      jsvm datatypes/counter.des

datatypes/integer.des
  A much more complicated model that shows how an integer
  cell can be implemented in statechart. You can set any
  arbitary value to the cell, and you can also retrieve the
  value any any time.
  To run:
      jsvm datatypes/integer.des
  You can also specify command line parameters to the model.
  Parameter MIN and MAX give the lower and upper bounds. By
  default, they are 0 and 9 respectively. INIT gives the
  initial value of the cell. For example:
      jsvm datatypes/integer.des "MIN=0" "MAX=20" "INIT=10"

datatypes/char.des
  A Char model similar to the Integer. You can specify
  parameters START, END and INIT. The default value of the
  cell is null (when you get its value, the result is
  empty because the "get" event is not enabled).
  To run:
      jsvm datatypes/char.des
      jsvm datatypes/char.des "START=x" "END=z" "INIT=x"



5. DEBUGGING

When you run a model in the default graphical interface,
press CTRL-d or send an event "debug" at any time to invoke
the debugger. You can execute any Python command in the
debugger.



6. SNAPSHOT

When you run a model in the default graphical interface,
you can make a snapshot of the current execution by pressing
the Snapshot button. The snapshot is saved to a .snp file
in the same directory where the current model (.des file) is
in. You can resume the execution at exactly the same place
later, by running:
      jsvm [.snp_file]



7. TO-DO LIST

Build more interesting models.
Fix all found errors.
Specify a protocol to facilitate the communication across
models.