You can start TOPCAT from the command line with no arguments - in this case it will just pop up the command window from which you can load in tables. However you may specify flags and/or table locations and formats.
If you invoke the program with the "-help
" flag you
will see the following usage message:
Usage: topcat <flags> [[-f <format>] <table> ...] General flags: -help print this message and exit -version print component versions etc and exit -verbose increase verbosity of reports to console -demo start with demo data -disk use disk backing store for large tables -hub run internal PLASTIC hub -exthub run external PLASTIC hub -[no]plastic do [not] connect to running PLASTIC hub -[no]soap do [not] start SOAP services -noserv don't run any services -stilts <args> run STILTS not TOPCAT Optional load dialogue flags: -tree hierarchy browser -file basic file browser -sql SQL query on relational database -cone cone search dialogue -gavo GAVO Millennium run database query -registry VO registry query -siap Simple Image Access Protocol queries Useful Java flags: -classpath jar1:jar2.. specify additional classes -XmxnnnM use nnn megabytes of memory -Dname=value set system property Auto-detected formats: fits-plus, colfits-plus, colfits-basic, fits, votable All known formats: fits-plus, colfits-plus, colfits-basic, fits, votable, ascii, csv, tst, ipac, wdc Useful system properties (-Dname=value - lists are colon-separated): java.io.tmpdir temporary filespace directory jdbc.drivers JDBC driver classes jel.classes custom algebraic function classes jel.classes.activation custom action function classes star.connectors custom remote filestore classes startable.load.dialogs custom load dialogue classes startable.readers custom table input handlers startable.writers custom table output handlers startable.storage default storage policy mark.workaround work around mark/reset bug myspace.cache MySpace performance workaroundThe meaning of the flags is as follows:
-f
flag what format the named files are in.
Any table file on the command line following a
-f <format>
sequence must be in the named format until the next -f
flag.
The names of both the auto-detected formats (ones which don't need
a -f
) and the non-auto-detected formats (ones which do)
are given in the usage message you can see by giving the
-help
flag (this message is shown above).
You may also use the classname of a class on the classpath which
implements the TableBuilder
interface -
see SUN/252.
-help
(or -h
)
flag is given, TOPCAT will write a usage
message and exit straight away.
-version
flag is given, TOPCAT will print
a summary of its version and the versions and availability of some
its components, and exit straight away.
-demo
flag causes the program to start up with
a few demonstration tables loaded in. You can use these to play
around with its facilities. Note these demo tables are quite small
to avoid taking up a lot of space in the installation, and don't
contain particularly sensible data, they are just to give an idea.
-disk
flag is given then the program will use
disk backing storage for caching table data that is read in, rather
than keeping it in memory. This means that tables much larger than
the heap memory assigned to Java can be used. It may lead to slower
processing, but usually the performance is not greatly reduced.
If you find TOPCAT running out of memory (you see
OutOfMemoryError
s popping up in windows or on the console)
then re-running with the -disk
flag is a good idea.
The temporary data files are written in the default temporary
directory (defined by the java.io.tmpdir
system property -
often /tmp
- and deleted when the program exits, unless
it exits in an unusual way.
Note however that uncompressed FITS binary tables on disk are not
read into memory in any case (they are mapped)
so the -disk
flag may not make much difference with FITS.
-verbose
(or -v
) flag increases
the level of verbosity of messages which TOPCAT writes to standard
output (the console).
It may be repeated to increase the verbosity further.
The messages it controls are currently those written through
java's standard logging system - see the description of the
Log Window for more
information about this.
topcat -stilts -help
)
for the form of the <stilts-args>
.
Some of the flags control what load dialogues are visible in the Load Window. In fact all of these load dialogues can be accessed from the Load Window's DataSources menu as long as the classes are available, but if you specify these flags on the command line, the corresponding button will appear in the main part of the window, making the option more obvious. The load dialogue flags are:
startable.load.dialogs
system property (see Section 9.2.3).
Other arguments on the command line are taken to be the locations of tables. Any tables so specified will be loaded into TOPCAT at startup. These locations are typically filenames, but could also be URLs or SQL queries, or perhaps something else. In addition they may contain "fragment identifiers" (with a "#") to locate a table within a given resource, so that for instance the location
/my/data/cat1.fits#2means the second extension in the multi-extension FITS file
/my/data/cat1.fits
.
Section 4.2 describes in more detail the
kinds of URLs which can be used here.
Note that options to Java itself may also be specified on the command-line, as described in the next section.