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 -debug add debugging information to console log messages -demo start with demo data -running use existing TOPCAT instance if one is running -memory use memory storage for tables -disk use disk backing store for large tables -samp use SAMP for tool interoperability -plastic use PLASTIC for tool interoperability -[no]hub [don't] run internal SAMP/PLASTIC hub -exthub run external SAMP/PLASTIC hub -noserv don't run any services (PLASTIC or SAMP) -nocheckvers don't check latest version -stilts <args> run STILTS not TOPCAT -jsamp <args> run JSAMP not TOPCAT 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 storage policy mark.workaround work around mark/reset bug (see topcat -jsamp -help for more)The meaning of the flags is as follows:
-fflag 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
-fflag. 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
-helpflag (this message is shown above). You may also use the classname of a class on the classpath which implements the
TableBuilderinterface - see SUN/252.
-h) flag is given, TOPCAT will write a usage message and exit straight away.
-versionflag is given, TOPCAT will print a summary of its version and the versions and availability of some its components, and exit straight away.
-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.
-debugflag affects how logging messages appear (whether they appear is affected by the
-verboseflag). If present, these messages will provide more detail about where each message was generated from.
-demoflag 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.
-runningflag can be used when specifying tables on the command line. If an existing instance of TOPCAT is already running, the tables are loaded into it. If no instance of TOPCAT is running (or at least one cannot be discovered), then the
-runningflag has no effect and a new instance is started up as usual.
-memoryflag is given then the program will store table data in memory, rather than the default which is to store small tables in memory, and larger ones in temporary disk files.
-diskflag is given then the program will store table data in temporary disk files, rather than the default which is to store small tables in memory, and larger ones on disk. If you get out of memory messages, running with the
-diskflag might help, though the default policy should work fairly well. The temporary data files are written in the default temporary directory (defined by the
java.io.tmpdirsystem property - often
/tmp- and deleted when the program exits, unless it exits in an unusual way.
-hubflag causes TOPCAT to run an internal SAMP or PLASTIC hub (SAMP by default), if no hub is already running, and the
-nohubflag prevents this from happening. The default behaviour, when neither of these flags is given, is currently (since v3.8) to start a hub automatically for SAMP but not for PLASTIC. The hub will terminate when TOPCAT does, or can be shut down manually with the Interop|Stop Internal Hub () menu item. See Section 9.
topcat -stilts -help) for the form of the
topcat -jsamp -helpfor more information.
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.