diff options
Diffstat (limited to 'vendor/voclient/doc/votget.html')
| -rw-r--r-- | vendor/voclient/doc/votget.html | 244 |
1 files changed, 244 insertions, 0 deletions
diff --git a/vendor/voclient/doc/votget.html b/vendor/voclient/doc/votget.html new file mode 100644 index 00000000..c19b09ed --- /dev/null +++ b/vendor/voclient/doc/votget.html @@ -0,0 +1,244 @@ +Content-type: text/html + +<HTML><HEAD><TITLE>Manpage of VOTGET</TITLE> +</HEAD><BODY> +<H1>VOTGET</H1> +Section: User Commands (1)<BR>Updated: Feb 2013<BR><A HREF="#index">Index</A> +<A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR> + +<A NAME="lbAB"> </A> +<H2>NAME</H2> + +votget - Download URLs or access references in a VOTable +<P> +<A NAME="lbAC"> </A> +<H2>SYNOPSIS</H2> + +<B>votget</B> [<I><opts></I>] [ <votable.xml> | <listfile> ] +<BR> + +<B>votget</B> [<I><opts></I>] --samp # to listen for SAMP messages +<P> +<A NAME="lbAD"> </A> +<H2>OPTIONS</H2> + +The <I>votget</I> task accepts the following options: +<DL COMPACT> +<DT><B>-h, --help</B> + +<DD> +Print a help summary to the terminal and exit. No processing is done +following this flag. +<P> +<DT><B>-b </B><I>BASE</I>,--base <I>BASE</I> + +<DD> +Base output filename. The <I>BASE</I> name will be appended with a running +(leading zero, 4-digit) number for each downloaded file. +<DT><B>-e [</B><I>EXTN</I>],--extn [<I>EXTN</I>] + +<DD> +Extension to add to each filename. If no <I>EXTN</I> is provided, a guess +of the file type will be made an an appropriate extension chosen +automatically. +<DT><B>-f,--fmt </B><I>FILE_TYPE</I> + +<DD> +Download only file of the specified <I>TYPE</I>. The <I>TYPE</I> value is +used in a substring match of the image format column value. The format +column uses a well-known UCD or may be specified using the <I>-u</I> or +<I>-F</I> flags. +<DT><B>-s,--sum </B> + +<DD> +Use the 32-bit file checksum numbers when appending to the <I>BASE</I> +filename. By default, a sequential file number is used. +<DT><B>-t,--tmp </B> + +<DD> +Input file is temporary, delete it when done. +<DT><B>-u </B><I>UCD</I>,--ucd <I>UCD</I> + +<DD> +Use ucd to identify access reference column. The VOTable <I><FIELD></I> +containing the <I>ucd=UCD</I> attribute will identify the access reference +column used when matching the <I>TYPE</I> value. +<P> +<DT><B>-o </B><I>NAME</I>,--output <I>NAME</I> + +<DD> +Output filename (single download only). This option may be used to specify +the name of the downloaded file in cases where only a single file is +requested. +<DT><B>-v,--verbose </B> + +<DD> +Verbose output. +<DT><B>-x,--extract </B> + +<DD> +Extract access references only. Files are not downloaded, the access +reference URLs are written to the output file or stderr stream if no +<I>-o</I> output file is given. +<P> +<DT><B>-A </B><I>COLUMN</I>,--acref <I>COLNUM</I> + +<DD> +Column number (0-indexed) for access reference column. +<DT><B>-B,--bkg</B> + +<DD> +Background the download, i.e. run in a forked child process. +<DT><B>-C,--cache</B> + +<DD> +Cache the downloaded file +<DT><B>-D </B><I>DIR</I>,--download <I>dir</I> + +<DD> +Specify download directory, i.e. download files to the <I>DIR</I> directory +and not the current working directory. +<DT><B>-F,--fmtcol <colnum</B> + +<DD> +Column number (0-indexed) for image format column. This column value will be +used to match the <I>TYPE</I> value given to the <I>-f</I> option. +<DT><B>-N </B><I>NUM</I>,--num <I>NUM</I> + +<DD> +Number of simultaneous downloads to process. In cases where multiple files +are requested, the task will create <I>NUM</I> separate threads to multiplex +the downloads for greater efficiency. +<DT><B>-S,--samp</B> + +<DD> +Start as SAMP listener. If enabled, the task will simply listen for +SAMP messages containing a 'table.load.votable' message type and will +process the requested file automatically. This allows the task to act as a +download client for other applications. +<P> +</DL> +<A NAME="lbAE"> </A> +<H2>DESCRIPTION</H2> + +The <I>votget</I> task can be used to download remote files to the local +machine. If given a filename argument on the command-line, the file may be +either a plain-text file containing a list of URLs (one per line), or a +VOTable (e.g. such as one returned from an SIA or SSA service) containing +<I>'acess references'</I> to data. If no filename is given on the +command-line and the <I>-S</I> flag is used, the task will start as a listener +for SAMP messages containing a 'table.load.votable' request and will process +those VOTable files as they arrive. +<P> + +When processing VOTables, the <I>-A</I> and <I>-F</I> flags can be used to +specify the access reference and image format columns as 0-indexed column +numbers, or the <I>-u</I> and <I>-f</I> options can be used to specify the +access reference UCD and format string respectively. By default, all access +references will be downloaded, if a format parameter is used then only images +of that type will be downloaded. If the <I>-x</I> option is enabled, the +access references will be extracted from the VOTable and the URL written to +the output rather than downloading the referenced file. +<P> + +If the <I>-b</I> option is set the argument should be a base name for the +downloaded files. This name will be appended with a sequential 4-digit +number to make the filenames unique, unless the <I>-s</I> option is set to +indicate the 32-bit file checksum should be used instead. An optional +filename extension (e.g. "fits") can be added to these names by specifying +the <I>-e</I> option to given the extension string. If none of these options +are given, a best-guess of the filename will be made based on the URL. +<P> + +<I>VOGET</I> will attempt to download multiple files simultaneously, the +number of download threads may be set using the <I>-N</I> option. By setting +the <I>-B</I> option, downloads will proceed in a background child process +allowing control to be returned to the calling shell quickly. +<P> +If no input file is specified the VOTable will be read from the stdin, +results will be written to stdout unless the <I>-o</I> (or <I>--output</I>) +names an output file. The task will only process a single VOTable and may +not be used to convert multiple files in a single call. +<P> +<A NAME="lbAF"> </A> +<H2>RETURN STATUS</H2> + +<I>votget</I> will return a zero for a successful exit, one otherwise. +<P> +<A NAME="lbAG"> </A> +<H2>EXAMPLES</H2> + +<DL COMPACT> +<DT>1) <DD> +Download all files in the VOTable 'results.xml', 3 files at a time: +<P> +<PRE> + % votget -N 3 results.xml +</PRE> + +<DT>2) <DD> +Start as a SAMP listener waiting for VOTable events to be broadcast, saved +files will begin with the string 'foo' and contain a 'fits' filename extension: +<P> +<PRE> + % votget -b foo -e fits -S +</PRE> + +<P> +To exit the task, hit the <CR>. +<DT>3) <DD> +Download all the urls in the file 'urls.txt': +<P> +<PRE> + % votget -b foo urls.txt +</PRE> + +<DT>4) <DD> +Extract all the access references in a VOTable: +<P> +<PRE> + % votget -x results.xml +</PRE> + +<P> +<P> +</DL> +<A NAME="lbAH"> </A> +<H2>BUGS</H2> + +No known bugs with this release. +<A NAME="lbAI"> </A> +<H2>Revision History</H2> + +Feb 2013 - First public release +<A NAME="lbAJ"> </A> +<H2>Author</H2> + +Michael Fitzpatrick (<A HREF="mailto:fitz@noao.edu">fitz@noao.edu</A>), Feb 2013 +<A NAME="lbAK"> </A> +<H2>SEE ALSO</H2> + +votcnv, votinfo, votpos, votsort, votstat +<P> + +<HR> +<A NAME="index"> </A><H2>Index</H2> +<DL> +<DT><A HREF="#lbAB">NAME</A><DD> +<DT><A HREF="#lbAC">SYNOPSIS</A><DD> +<DT><A HREF="#lbAD">OPTIONS</A><DD> +<DT><A HREF="#lbAE">DESCRIPTION</A><DD> +<DT><A HREF="#lbAF">RETURN STATUS</A><DD> +<DT><A HREF="#lbAG">EXAMPLES</A><DD> +<DT><A HREF="#lbAH">BUGS</A><DD> +<DT><A HREF="#lbAI">Revision History</A><DD> +<DT><A HREF="#lbAJ">Author</A><DD> +<DT><A HREF="#lbAK">SEE ALSO</A><DD> +</DL> +<HR> +This document was created by +<A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>, +using the manual pages.<BR> +Time: 05:13:26 GMT, April 14, 2013 +</BODY> +</HTML> |