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
        -hub         run internal PLASTIC hub
        -[no]plastic do [not] connect to running PLASTIC hub
        -[no]soap    do [not] start SOAP services
        -noserv      don't run any services

    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 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.
-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.
-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.
-[no]plastic
Controls whether TOPCAT will attempt to connect to a running PLASTIC hub on startup. Currently, the default is that it does connect if a hub is running. See Section 8.
-hub
Causes TOPCAT to run an internal PLASTIC hub. This feature is experimental.
-[no]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 SOAP and PLASTIC (see above).

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.5). 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.
-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).
-siap
Simple Image Access Protocol dialogue (experimental), used for obtaining the results of SIAP queries on remote data servers (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