.\" @(#)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