Next Previous Up Contents
Next: Java Options
Up: Invoking TOPCAT
Previous: Invoking TOPCAT

9.1 TOPCAT Command-line Arguments

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
        -samp          use SAMP for tool interoperability
        -plastic       use PLASTIC for tool interoperability
        -hub           run internal SAMP/PLASTIC hub
        -exthub        run external SAMP/PLASTIC hub
        -soap          start SOAP services
        -noserv        don't run any services (PLASTIC, SAMP or SOAP)
        -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
        -sia       Simple Image Access Protocol queries
        -ssa       Simple Spectrum 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 workaround

The meaning of the flags is as follows:
-f <format>
Signifies that the file(s) named after it on the command line are in a particular file format. Some file formats (VOTable, FITS) can be detected automatically by TOPCAT, but others (including Comma-Separated Values) cannot - see Section 4.1.1. In this case you have to specify with the -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
If the -help (or -h) flag is given, TOPCAT will write a usage message and exit straight away.
-version
If the -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.
-verbose
The -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.
-demo
The -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
If the -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 OutOfMemoryErrors 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.
-samp
Forces TOPCAT to use SAMP for tool interoperability (see Section 8). This is the default, but PLASTIC mode instead of SAMP will otherwise be chosen if a PLASTIC hub but no SAMP hub is running on startup.
-plastic
Forces TOPCAT to use PLASTIC instead of SAMP for tool interoperability (see Section 8).
-hub
Causes TOPCAT to run an internal SAMP or PLASTIC hub (SAMP by default), if no hub is already running. The hub will terminate when TOPCAT does. See Section 8.
-exthub
Causes TOPCAT to attempt to run an external SAMP or PLASTIC hub, if no hub is already running. The hub will show up in its own window, and can be stopped by closing the window. The hub will continue to run after TOPCAT terminates. Invoking external processes from Java is inherently unreliable, so this is done on a best-efforts basis. See Section 8.
-soap
Controls whether TOPCAT will start up a SOAP server which can accept requests using the SOAP protocol to display tables from other applications. Currently, the default is that it does not start a server. This option may be withdrawn in future releases.
-noserv
Prevents TOPCAT from running any services. Currently the services which it may run are SAMP, PLASTIC and SOAP (see above).
-stilts <stilts-args>
This flag is a convenience which allows you to run the STILTS command-line tool instead of TOPCAT. This is possible because TOPCAT is built on top of STILTS and contains a superset of its code. See the STILTS manual (or 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:

-tree
Hierarchy browser (Appendix A.5.2), used for content-sensitive browsing of the filespace (not available with topcat-lite).
-file
Basic file browser. This doesn't do much that the Filestore Browser (which is present by default, and can also access remote filespaces) can't do, but is provided as a fallback.
-sql
SQL query (Appendix A.5.3), used for obtaining tables from an SQL query on a rleational database (only available if JDBC is set up correctly).
-cone
Cone search dialogue (Appendix A.5.4), used for obtaining catalogues of sources in a region of the sky from remote data servers (not available with topcat-lite).
-gavo
GAVO database query dialogue (Appendix A.5.6). Allows queries to the GAVO (German Astrophysical Virtual Observatory) database services. At time of writing, the most generally useful of these are queries to the Virgo Millennium run database.
-sia
Simple Image Access protocol dialogue (Appendix A.5.5), used for obtaining the results of SIA queries on remote data servers (not available with topcat-lite).
-ssa
Simple Spectral Access protocol dialogue (Appendix A.5.5), used for obtaining the results of SSA queries on remote data servers (not available with topcat-lite).
-registry
Registry query dialogue (experimental), used for obtaining the results of a query on a VO resource registry as a table (not available with topcat-lite).
These flags in most circumstances do just the same as adding the relevant dialogue class name to the 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#2
means 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.


Next Previous Up Contents
Next: Java Options
Up: Invoking TOPCAT
Previous: Invoking TOPCAT

TOPCAT - Tool for OPerations on Catalogues And Tables
Starlink User Note253
TOPCAT web page: http://www.starlink.ac.uk/topcat/
Author email: m.b.taylor@bristol.ac.uk