Next Previous Up Contents
Next: Class Path
Up: Top
Previous: Getting Help


3 Invocation

There are a number of ways of invoking commands in the stilts application, depending on how you have installed the package. This section describes how to invoke it from the command line. Other options are using it from Jython (the Java implementation of the Python language) as described in Section 4, invoking it over HTTP as described in Section 11, and invoking it from within a Java application as described in Section 12.

If you're using a Unix-like operating system, the easiest way is to use the stilts script. It is a simple shell script which just invokes java with the right classpath and the supplied arguments.

If you have a full starjava installation the stilts script is in the starjava/bin directory. Otherwise you can download it separately from wherever you got your STILTS installation in the first place, or find it at the top of the stilts.jar or topcat-*.jar file that contains your STILTS installation, so do something like

   unzip stilts.jar stilts
   chmod +x stilts
to extract it (if you don't have unzip, try jar xvf stilts.jar stilts). If you have mounted the topcat-all.dmg file on MacOS (hdiutil attach topcat-all.dmg) it will probably be present at a location like /Volumes/topcat/TOPCAT.app/Contents/Resources/app/stilts.

To run using the stilts script, first make sure that both the java executable and the stilts script itself are on your path, and that the stilts.jar or topcat-*.jar jar file is in the same directory as stilts. Then the form of invocation is:

   stilts <java-flags> <stilts-flags> <task-name> <task-args>
A simple example would be:
   stilts votcopy format=binary t1.xml t2.xml
in this case, as often, there are no <java-flags> or <stilts-flags>. If you use the -classpath argument or have a CLASSPATH environment variable set, then classpath elements thus specified will be added to the classpath required to run the command. The examples in the command descriptions below use this form for convenience.

If you don't have a Unix-like shell available however, you will need to invoke Java directly with the appropriate classes on your classpath. If you have the file stilts.jar, in most cases you can just write:

   java <java-flags> -jar stilts.jar <stilts-flags> <task-name> <task-args>
which in practice would look something like
   java -jar /some/where/stilts.jar votcopy format=binary t1.xml t2.xml

In the most general case, Java's -jar flag might be no good, for one of the following reasons:

  1. You have the classes in some form other than the stilts.jar file (such as topcat-full.jar)
  2. You need to specify some extra classes on the classpath, which is required e.g. for use with JDBC or if you are extending the commands using your own classes at runtime
In this case, you will need an invocation of this form:
   java <java-flags> -classpath <class-path> 
        uk.ac.starlink.ttools.Stilts <stilts-flags> <task-name> <task-args>
The example above in this case would look something like:
   java -classpath /some/where/topcat-full.jar uk.ac.starlink.ttools.Stilts 
        votcopy format=binary t1.xml t2.xml

Finally, as a convenience, it is possible to run STILTS from a TOPCAT installation by using its -stilts flag, like this:

   topcat <java-flags> -stilts <stilts-flags> <task-name> <task-args>
This is possible because TOPCAT is built on top of STILTS, so contains a superset of its code.

The <stilts-flags>, <task-name> and <task-args> parts of these invocations are explained in Section 2, and the <class-path> and <java-flags> parts are explained in the following subsections.


Next Previous Up Contents
Next: Class Path
Up: Top
Previous: Getting Help

STILTS - Starlink Tables Infrastructure Library Tool Set
Starlink User Note256
STILTS web page: http://www.starlink.ac.uk/stilts/
Author email: m.b.taylor@bristol.ac.uk
Mailing list: topcat-user@jiscmail.ac.uk