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.

- 3.1 Class Path
- 3.2 Java Flags
- 3.3 System Properties
- 3.4 JDBC Configuration

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