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 stiltsto 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.xmlin 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:
stilts.jar
file (such as topcat-full.jar)
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.