aboutsummaryrefslogtreecommitdiff
path: root/vendor/voclient/doc/votget.html
blob: c19b09ed0a160b9ae9b9aa7879a408598fc69ef7 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
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">&nbsp;</A>
<H2>NAME</H2>

votget - Download URLs or access references in a VOTable
<P>
<A NAME="lbAC">&nbsp;</A>
<H2>SYNOPSIS</H2>

<B>votget</B> [<I>&lt;opts&gt;</I>] [ &lt;votable.xml&gt; | &lt;listfile&gt; ]
<BR>

<B>votget</B> [<I>&lt;opts&gt;</I>] --samp          # to listen for SAMP messages
<P>
<A NAME="lbAD">&nbsp;</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>&lt;FIELD&gt;</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 &lt;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">&nbsp;</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. &quot;fits&quot;) 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">&nbsp;</A>
<H2>RETURN STATUS</H2>

<I>votget</I> will return a zero for a successful exit, one otherwise.
<P>
<A NAME="lbAG">&nbsp;</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 &lt;CR&gt;.
<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">&nbsp;</A>
<H2>BUGS</H2>

No known bugs with this release.
<A NAME="lbAI">&nbsp;</A>
<H2>Revision History</H2>

Feb 2013 - First public release
<A NAME="lbAJ">&nbsp;</A>
<H2>Author</H2>

Michael Fitzpatrick (<A HREF="mailto:fitz@noao.edu">fitz@noao.edu</A>), Feb 2013
<A NAME="lbAK">&nbsp;</A>
<H2>SEE ALSO</H2>

votcnv, votinfo, votpos, votsort, votstat
<P>

<HR>
<A NAME="index">&nbsp;</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>