.help votget Mar12 votools
.ih
NAME
votget -- Download data referenced in a VOTable
.ih
USAGE
votget input base
.ih
PARAMETERS
.ls input
The list of input VOTables.
.le
.ls base
The base output filename.
.le
.ls extn = "fits"
Filename extension.  The \fIextn\fR string will be appended to each
downloaded filename.
.le
.ls format
Format to download.  If not a null string and the \fIextn\fR string is a
substring of the value of the column containing the UCD "VOX:Image_Format",
the referenced file will be downloaded.
.le
.ls acref = "VOX:Image_AccessReference"
The UCD of the column containing the image access reference.
.le
.ls col = INDEF
The (one-indexed) column number containing the image access reference.  If
specified, the UCD values will be ignored and the specific column will be
used.
.le
.ls sequential = yes
If enabled, sequential file numbers will be appended to the \fIbase\fR
name for each downloaded file.  Otherwise, an image name will be constructed
from the access URL.  In the latter case, no check is made to prevent 
overwriting of files.
.le
.ls nthreads = 4
Number of simultaneous download threads to execute.
.le
.ls list = no
List access references instead of downloading?  Enabling this option may
be used to extract a list of access URLs from the table.
.le

.ih
DESCRIPTION

The \fIVOTGET\fR task is used to download data referenced in a VOTable
(e.g.  the result of a query to an image or spectral service) to the local
machine.  The \fIinput\fR parameter may be a list of VOTables, in which
case the parameters will apply to all files in input the list.  The
\fIformat\fR parameter is used to select the image format to download from
the file, it is a case-insensitive substring of the VOTable column
containing the UCD "VOC:Image_Format".  If this column does not exist, or
if the \fIformat\fR parameter is the null string, then all images will be
retrieved.  The \fIacref\fR parameter parameter specified the UCD that
identifies the access reference to retrieve (i.e. a table may contain
multiple URLs per row, the UCD uniquely identifies the desired data
column), the default value of "VOX:Image_AccessReference" is the standard
value used for current VO data services.  Alternatively, the \fIcol\fR
parameter may be used to specify the column number (one-indexed) to
retrieve (e.g. to download other URLs in the table).

The \fIbase\fR parameter defines the root part of the saved image name, and
\fIextn\fR provides the extension.  If the \fIsequential\fR parameter is
set then files will be numbered in the order they were retrieved and saved
to a filename of the form "\fI<base><seqno>.<extn>\fR".  Otherwise, a
filename is constructed from the access URL and may or may not be either
unique or helpful.

Data are retrieved using multiple simultaneous threads in order make most
efficient use of the network and data service.  The \fInthreads\fR
parameter determines how many simultaneous downloads will be in progress at
any one time.  Once a download completes, a new thread is started until all
files have been retrieved.

The \fIlist\fR parameter may be used to simply extract a list of URLs from
all of the input tables.  When enabled, the \fIbase\fR paramter is not
required and a list of URLs, one per line, will be printed on the standard
output.


.ih
EXAMPLES
1.  Download all images referenced in the test Simple Image Access service
result table, saved files will

.nf
  votools> votget data$sia.xml test
.fi

2.  Extrace the access URLs from the same table without actually downloading
the files: 

.nf
  votools> votget data$sia.xml list+
.fi

.ih
REVISIONS
.le
.ih
SEE ALSO
votcopy
.endhelp