Invoking TOPCAT

The topcat script

If you are using TOPCAT in a standard Starlink java distribution on Unix, you can invoke the TOPCAT application using a script in the Starlink java bin directory just called 

   topcat
Invoked with no arguments, this will pop up the "Open Table" dialogue window.

Alternatively, you can supply command-line arguments giving the name(s) of one or more tables to load - filenames or URLs with optional fragment IDs following a '#' character, or JDBC table specifiers, for example 

   topcat dsscat.xml
or 
   topcat cat1.fits#1 cat1.fits#2 \
          http://astro.org/data/m31.xml

In addition, any arguments which start "-X" are passed as flags to the Java runtime. The main use of this is to modify the size of memory available to the application. By default it is 64 megabytes, but for large tables in memory this may not be enough. If running TOPCAT gives you an OutOfMemoryError then you can try increasing this value with the "-Xmx" flag. For instance the following: 

   topcat -Xmx512M whopper.fits
would open the table "whopper.fits" in TOPCAT with 512 Megabytes to play with.

Most of the other -X flags are only of interest for performance tuning and debugging; a full list can be seen by doing 

   topcat -X

Finally, invoking TOPCAT with the -guihelp flag: 

   topcat -guihelp
causes the help browser to be displayed, but the rest of the program will not run.

Invoking directly

As long as a J2SE1.4 Java Runtime Environment is present, TOPCAT should run in environments other than Unix, though the supplied startup script is unlikely to work. In this case you can probably invoke the Jar file lib/topcat/tocpat.jar file directly, for instance by clicking on it or typing something like 

   java -jar topcat.jar [args]
In this case however, since your normal class path (e.g. your CLASSPATH environment variable) is ignored, it will be impossible to use JDBC drivers, so SQL-type databases and the Mirage launch options will not be available.

For more control over the classpath it can be invoked as 

   java -classpath lib/topcat/topcat.jar \
        uk.ac.starlink.topcat.TableViewer
See the bin/topcat script mentioned above for more information.