Normal use of votcopy is pretty straightforward.
We give here a couple of examples of its input and output.
Here is an example VOTable document, cat.vot:
<VOTABLE>
<RESOURCE>
<TABLE name="Authors">
<FIELD name="AuthorName" datatype="char" arraysize="*"/>
<DATA>
<TABLEDATA>
<TR><TD>Charles Messier</TD></TR>
<TR><TD>Mark Taylor</TD></TR>
</TABLEDATA>
</DATA>
</TABLE>
<RESOURCE>
<COOSYS equinox="J2000.0" epoch="J2000.0" system="eq_FK4"/>
<TABLE name="Messier Objects">
<FIELD name="Identifier" datatype="char" arraysize="10"/>
<FIELD name="RA" datatype="double" units="degrees"/>
<FIELD name="Dec" datatype="double" units="degrees"/>
<DATA>
<TABLEDATA>
<TR> <TD>M51</TD> <TD>202.43</TD> <TD>47.22</TD> </TR>
<TR> <TD>M97</TD> <TD>168.63</TD> <TD>55.03</TD> </TR>
</TABLEDATA>
</DATA>
</TABLE>
</RESOURCE>
</RESOURCE>
</VOTABLE>
Note that it contains more structure than just a flat table: there are
two TABLE elements,
the RESOURCE element of the second one being nested
in the RESOURCE of the first.
Processing this document using a generic table tool such as
tpipe or tcopy would lose this structure.
To convert the data encoding to BINARY format, we simply execute
votcopy -f binary cat.vot
and the output is
<?xml version="1.0"?>
<VOTABLE>
<RESOURCE>
<TABLE name="Authors">
<FIELD name="AuthorName" datatype="char" arraysize="*"/>
<DATA>
<BINARY>
<STREAM encoding='base64'>
AAAAD0NoYXJsZXMgTWVzc2llcgAAAAtNYXJrIFRheWxvcg==
</STREAM>
</BINARY>
</DATA>
</TABLE>
<RESOURCE>
<COOSYS equinox="J2000.0" epoch="J2000.0" system="eq_FK4"/>
<TABLE name="Messier Objects">
<FIELD name="Identifier" datatype="char" arraysize="10"/>
<FIELD name="RA" datatype="double" units="degrees"/>
<FIELD name="Dec" datatype="double" units="degrees"/>
<DATA>
<BINARY>
<STREAM encoding='base64'>
TTUxAAAAAAAAAEBpTcKPXCj2QEecKPXCj1xNOTcAAAAAAAAAQGUUKPXCj1xAS4PX
Cj1wpA==
</STREAM>
</BINARY>
</DATA>
</TABLE>
</RESOURCE>
</RESOURCE>
</VOTABLE>
Note that both tables have been translated to BINARY format.
The basic structure of the document is unchanged: the only differences
are within the DATA elements. If we ran
votcopy -f tabledata
on either this output or the original input then the output would
be identical (apart perhaps from whitespace) to the input table,
since the data are originally in TABLEDATA format.
To generate a VOTable document with the data in external files,
the -href flag is used. We will output in FITS format
this time. Executing:
votcopy -f fits -href cat.vot fcat.vot
results in the error message:
Can't stream, table requires multiple reads for metadata
Try -cache option
- for technical reasons (FITS output requires the input tables to
to be read in two passes to assess the number of rows)
this can't be done in a single stream which is how
votcopy usually works.
So we follow the offered advice and use the -cache flag:
votcopy -f fits -href cat.vot fcat.vot -cache
which writes the following to the file fcat.vot:
...
<DATA>
<FITS>
<STREAM href="fcat-1.fits"/>
</FITS>
</DATA>
...
<DATA>
<FITS>
<STREAM href="fcat-2.fits"/>
</FITS>
</DATA>
...
(the unchanged parts of the document have been skipped here for brevity).
The actual data are written in two additional files in the same
directory as the output file, fcat-1.fits and
fcat-2.fits. These filenames are based on the
main output filename, but can be altered using the -base
flag if required. Note this has also given you FITS binary table
versions of all the tables in the input VOTable document, which can be
operated on by normal FITS-aware software quite separately from the VOTable
if required.