diff options
Diffstat (limited to 'vendor/voclient/doc/votget.man')
| -rw-r--r-- | vendor/voclient/doc/votget.man | 170 |
1 files changed, 170 insertions, 0 deletions
diff --git a/vendor/voclient/doc/votget.man b/vendor/voclient/doc/votget.man new file mode 100644 index 00000000..000c5e9e --- /dev/null +++ b/vendor/voclient/doc/votget.man @@ -0,0 +1,170 @@ +.\" @(#)votget.1 1.0 Feb-2013 MJF +.TH VOTGET 1 "Feb 2013" "VOClient Package" +.SH NAME +votget \- Download URLs or access references in a VOTable + +.SH SYNOPSIS +\fBvotget\fP [\fI<opts>\fP] [ <votable.xml> | <listfile> ] +.br +\fBvotget\fP [\fI<opts>\fP] \--samp # to listen for SAMP messages + +.SH OPTIONS +The \fIvotget\fP task accepts the following options: +.TP 6 +.B \-h, --help +Print a help summary to the terminal and exit. No processing is done +following this flag. + +.TP 6 +.B -b \fIBASE\fP,--base \fIBASE\fP +Base output filename. The \fIBASE\fP name will be appended with a running +(leading zero, 4-digit) number for each downloaded file. +.TP 6 +.B -e [\fIEXTN\fP],--extn [\fIEXTN\fP] +Extension to add to each filename. If no \fIEXTN\fP is provided, a guess +of the file type will be made an an appropriate extension chosen +automatically. +.TP 6 +.B -f,--fmt \fIFILE_TYPE\fP +Download only file of the specified \fITYPE\fP. The \fITYPE\fP 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 \fI-u\fP or +\fI-F\fP flags. +.TP 6 +.B -s,--sum +Use the 32-bit file checksum numbers when appending to the \fIBASE\fP +filename. By default, a sequential file number is used. +.TP 6 +.B -t,--tmp +Input file is temporary, delete it when done. +.TP 6 +.B -u \fIUCD\fP,--ucd \fIUCD\fP +Use ucd to identify access reference column. The VOTable \fI<FIELD>\fP +containing the \fIucd=UCD\fP attribute will identify the access reference +column used when matching the \fITYPE\fR value. + +.TP 6 +.B -o \fINAME\fP,--output \fINAME\fP +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. +.TP 6 +.B -v,--verbose +Verbose output. +.TP 6 +.B -x,--extract +Extract access references only. Files are not downloaded, the access +reference URLs are written to the output file or stderr stream if no +\fI-o\fP output file is given. + +.TP 6 +.B -A \fICOLUMN\fP,--acref \fICOLNUM\fP +Column number (0-indexed) for access reference column. +.TP 6 +.B -B,--bkg +Background the download, i.e. run in a forked child process. +.TP 6 +.B -C,--cache +Cache the downloaded file +.TP 6 +.B -D \fIDIR\fP,--download \fIdir\fP +Specify download directory, i.e. download files to the \fIDIR\fP directory +and not the current working directory. +.TP 6 +.B -F,--fmtcol <colnum\fP +Column number (0-indexed) for image format column. This column value will be +used to match the \fITYPE\fP value given to the \fI-f\fP option. +.TP 6 +.B -N \fINUM\fP,--num \fINUM\fP +Number of simultaneous downloads to process. In cases where multiple files +are requested, the task will create \fINUM\fP separate threads to multiplex +the downloads for greater efficiency. +.TP 6 +.B -S,--samp +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. + +.SH DESCRIPTION +The \fIvotget\fP 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 +\fI'acess references'\fP to data. If no filename is given on the +command-line and the \fI-S\fP 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. +.PP +When processing VOTables, the \fI-A\fP and \fI-F\fP flags can be used to +specify the access reference and image format columns as 0-indexed column +numbers, or the \fI-u\fP and \fI-f\fP 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 \fI-x\fP 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. +.PP +If the \fI-b\fP 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 \fI-s\fP 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 \fI-e\fP 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. +.PP +\fIVOGET\fP will attempt to download multiple files simultaneously, the +number of download threads may be set using the \fI-N\fP option. By setting +the \fI-B\fP option, downloads will proceed in a background child process +allowing control to be returned to the calling shell quickly. + +If no input file is specified the VOTable will be read from the stdin, +results will be written to stdout unless the \fI\-o\fP (or \fI\--output\fP) +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. + +.SH RETURN STATUS +\fIvotget\fP will return a zero for a successful exit, one otherwise. + +.SH EXAMPLES +.TP 4 +1) +Download all files in the VOTable 'results.xml', 3 files at a time: + +.nf + % votget -N 3 results.xml +.fi +.TP 4 +2) +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: + +.nf + % votget -b foo -e fits -S +.fi + +To exit the task, hit the <CR>. +.TP 4 +3) +Download all the urls in the file 'urls.txt': + +.nf + % votget -b foo urls.txt +.fi +.TP 4 +4) +Extract all the access references in a VOTable: + +.nf + % votget -x results.xml +.fi + + +.SH BUGS +No known bugs with this release. +.SH Revision History +Feb 2013 - First public release +.SH Author +Michael Fitzpatrick (fitz@noao.edu), Feb 2013 +.SH "SEE ALSO" +votcnv, votinfo, votpos, votsort, votstat |