10.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
        -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, cdf, ecsv, pds4, mrt, parquet, feather, gbin

    All known formats:
        fits-plus, colfits-plus, colfits-basic, fits, votable, cdf, ecsv, pds4, mrt, parquet, feather, gbin, ascii, csv, tst, ipac, hapi, 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)

-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.

-debug

The -debug flag affects how logging messages appear (whether they appear is affected by the -verbose flag). If present, these messages will provide more detail about where each message was generated from.

-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.

-running

The -running flag 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 -running flag has no effect and a new instance is started up as usual.

-memory

If the -memory flag 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.

-disk

If the -disk flag 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 -disk flag 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.tmpdir system property - often /tmp - and deleted when the program exits, unless it exits in an unusual way.

-samp

Forces TOPCAT to use SAMP for tool interoperability (see Section 9). SAMP rather than PLASTIC is the default, so this flag has no effect.

-plastic

Forces TOPCAT to use PLASTIC instead of SAMP for tool interoperability (see Section 9).

-[no]hub

The -hub flag causes TOPCAT to run an internal SAMP or PLASTIC hub (SAMP by default), if no hub is already running, and the -nohub flag prevents this from happening. The default behaviour, when neither of these flags is given, is 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.

-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 9.

-noserv

Prevents TOPCAT from running any services. Currently the services which it may run are SAMP or PLASTIC (see above).

-checkvers

Prevents TOPCAT from checking an external URL so it can determine whether the latest version is being run.

-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>.

-jsamp <jsamp-args>

This flag is a convenience which allows you to run the jsamp command-line tool, from the JSAMP package, instead of TOPCAT. This is possible because TOPCAT contains the JSAMP library. JSAMP provides various SAMP-related utilities, such as a freestanding hub and diagnostic tools. See the JSAMP documentation, or do topcat -jsamp -help for 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 scheme specifications. 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

Note that options to Java itself may also be specified on the command-line, as described in the next section.