Next Previous Up Contents
Next: Examples
Up: votcopy: VOTable Encoding Translator
Previous: votcopy: VOTable Encoding Translator

A.3.1 Usage

The basic usage of votcopy is

    votcopy [<flags>] [<in-file> [<out-file>]]
If you don't have the Unix scripts installed, invoke it as described in Section 2 using the classname uk.ac.starlink.ttools.VotCopy.

If <out-file> is omitted the result is written to standard output, and if <in-file> is also omitted the document to be copied is read from standard input. <in-file> may be a filename or URL, and may represent a VOTable compressed using one of the supported compression formats (gzip, Unix compress and bzip2).

The flags, which may be given in any order, are as follows:

-f[ormat] tabledata|binary|fits|none
Determines the encoding format of the table data in the output document. If none is selected, then the tables will be data-less (contain no DATA element), leaving only the document structure. Data-less tables are legal VOTable elements.
-href
In the case of BINARY or FITS encoding, this determines whether the STREAM elements will contain their data inline or externally. If -href is not specified, the output document will be self-contained, with STREAM data inline as base64-encoded characters. If -href is specified, then for each table in the document the binary data will be written to a separate file and referenced by a href attribute on the corresponding STREAM element. The name of these files is usually determined by the name of the main output file; but see also the -base flag.
-base <name>
Determines the name of external output files written when the -href flag is specified. Normally these are given names based on the name of the output file. But if -base <name> is given, then these will given a name based on <name>. The -base flag is compulsory if -href is given and no output file is specified (output is to standard out), since in this case there is no default base name to use.
-cache
This flag causes any tables being copied to be read into a cache prior to being written out. Usually this doesn't provide any benefit, but under some circumstances it is necessary when the output is in FITS format. If you attempt to run votcopy without the -cache flag when it is required, an error message will tell you so.
-disk
When caching table data, uses a temporary disk file for storage rather than memory. Only has any effect if -cache is specified, and only required for large tables. Equivalent to setting the system property -Dstartable.storage=disk.
-encode <xml-encoding>
Selects the Unicode encoding used for the output XML. The available options and default are dependent on your JVM, but the default is probably UTF-8 and others available probably include UTF-16 etc.
-debug
Causes any error messages, which are usually made brief, to be accompanied by a stack trace. If you are reporting a bug (or debugging the code yourself), then you should use this flag to get the most information about what has gone wrong.
-h[elp]
Prints a usage message and exits.


Next Previous Up Contents
Next: Examples
Up: votcopy: VOTable Encoding Translator
Previous: votcopy: VOTable Encoding Translator

STILTS - Starlink Tables Infrastructure Library Tool Set
Starlink User Note 256
STILTS web page: http://www.starlink.ac.uk/stilts/
Author email: m.b.taylor@bristol.ac.uk