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

### 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:

    Jan 20, 2020 11:16:31 PM uk.ac.starlink.fits.FitsConstants configureHierarch
    INFO: Resetting FITS use of HIERARCH convention false -> true

    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
            -[no]hub       [don't] run internal SAMP/PLASTIC hub
            -exthub        run external SAMP/PLASTIC hub
            -noserv        don't run any services (PLASTIC or SAMP)
            -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:

-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 is always used, so this flag has no effect.
-[no]hub
  The `-hub` flag causes TOPCAT to run an internal SAMP hub, 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. 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 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 service which it may run is SAMP (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 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
Mailing list: topcat-user@jiscmail.ac.uk