Content-type: text/html Manpage of VOTGET

VOTGET

Section: User Commands (1)
Updated: Feb 2013
Index Return to Main Contents

NAME

votget - Download URLs or access references in a VOTable

SYNOPSIS

votget [<opts>] [ <votable.xml> | <listfile> ]
votget [<opts>] --samp # to listen for SAMP messages

OPTIONS

The votget task accepts the following options:

-h, --help: Print a help summary to the terminal and exit. No processing is done following this flag.
-b BASE,--base BASE: Base output filename. The BASE name will be appended with a running (leading zero, 4-digit) number for each downloaded file.
-e [EXTN],--extn [EXTN]: Extension to add to each filename. If no EXTN is provided, a guess of the file type will be made an an appropriate extension chosen automatically.
-f,--fmt FILE_TYPE: Download only file of the specified TYPE. The TYPE 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 -u or -F flags.
-s,--sum: Use the 32-bit file checksum numbers when appending to the BASE filename. By default, a sequential file number is used.
-t,--tmp: Input file is temporary, delete it when done.
-u UCD,--ucd UCD: Use ucd to identify access reference column. The VOTable <FIELD> containing the ucd=UCD attribute will identify the access reference column used when matching the TYPE value.
-o NAME,--output NAME: 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.
-v,--verbose: Verbose output.
-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 -o output file is given.
-A COLUMN,--acref COLNUM: Column number (0-indexed) for access reference column.
-B,--bkg: Background the download, i.e. run in a forked child process.
-C,--cache: Cache the downloaded file
-D DIR,--download dir: Specify download directory, i.e. download files to the DIR directory and not the current working directory.
-F,--fmtcol <colnum: Column number (0-indexed) for image format column. This column value will be used to match the TYPE value given to the -f option.
-N NUM,--num NUM: Number of simultaneous downloads to process. In cases where multiple files are requested, the task will create NUM separate threads to multiplex the downloads for greater efficiency.
-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.

DESCRIPTION

The votget 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 'acess references' to data. If no filename is given on the command-line and the -S 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.

When processing VOTables, the -A and -F flags can be used to specify the access reference and image format columns as 0-indexed column numbers, or the -u and -f 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 -x 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.

If the -b 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 -s 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 -e 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.

VOGET will attempt to download multiple files simultaneously, the number of download threads may be set using the -N option. By setting the -B 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 -o (or --output) 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.

RETURN STATUS

votget will return a zero for a successful exit, one otherwise.

EXAMPLES

1)

Download all files in the VOTable 'results.xml', 3 files at a time:

        % votget -N 3 results.xml

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:

        % votget -b foo -e fits -S

To exit the task, hit the <CR>.

3)

Download all the urls in the file 'urls.txt':

        % votget -b foo urls.txt

4)

Extract all the access references in a VOTable:

        % votget -x results.xml

BUGS

No known bugs with this release.

Revision History

Feb 2013 - First public release

Author

Michael Fitzpatrick (fitz@noao.edu), Feb 2013

This document was created by man2html, using the manual pages.
Time: 05:13:26 GMT, April 14, 2013