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
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
|
Content-type: text/html
<HTML><HEAD><TITLE>Manpage of VOREGISTRY</TITLE>
</HEAD><BODY>
<H1>VOREGISTRY</H1>
Section: User Commands (1)<BR>Updated: July 2007<BR><A HREF="#index">Index</A>
<A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR>
<A NAME="lbAB"> </A>
<H2>NAME</H2>
voregistry - VO Registry search client
<P>
<A NAME="lbAC"> </A>
<H2>SYNOPSIS</H2>
<B>voregistry</B> [-<I><flags></I>] [ <I><keywords></I> | <<I>term</I>> ] [ ... ]
<P>
<A NAME="lbAD"> </A>
<H2>OPTIONS</H2>
The <I>voregistry</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.
<DT><B>-v, --verbose</B>
<DD>
Verbose output. The output will be more verbose than normal but exactly
what is printed depends on whether other flags are enabled to changed the
basic task behavior.
<DT><B>--vverbose</B>
<DD>
Very-verbose output. Even more output.
<DT>The following flags control the major behavior of the task, i.e. the type<DD>
of output to present.
<DT><B>-c, --count</B>
<DD>
Print a count of matching records. For each of the search terms, a simple
count of matching resources will be printed. A breakdown by service type
will be printed if the verbose flag is enabled.
<DT><B>-e, --exact</B>
<DD>
Match exactly the search term (resolve mode only). The <I>term</I> in this
case will normally be an IVO identifier, this flag can be used to match the
identifier exactly rather than as a potential substring. This option will
return an empty string if no exact match is found.
<DT><B>-l, --list</B>
<DD>
List the full resource record for each matching resource. For each matching
resource, all (well, most) of the information available about a resource
will be printed to the screen. Additional information may be available from
the Registry web interface.
<DT><B>-m, --meta</B>
<DD>
List the metadata for the data services associated with the resource. For
each resource found, the table metadata (i.e. the column UCD values)
associated with the resource will be printed. Currently only those DAL
services supported by VOClient may be queried.
<DT><B>-r, --resolve</B>
<DD>
<I>Resolve</I> the search term to a specified resource. In <I>resolve mode</I>
the search terms are assumed to be either the resource <I>ShortName</I> or
<I>Identifier</I> and the match will be done using only these two fields in
the Registry resource record. The default output is simply the
<I>ServiceURL</I> for all matching records (i.e. resources where the search
string is part of the <I>ShortName</I> or <I>Identifier</I> fields) unless
the <I>-f</I> flag is given to select other fields.
<DT>Shorthand Convenience Options:<DD>
<DT><B>-I, --id</B>
<DD>
Print only the <I>Identifier</I> field for the resolved resource.
<DT><B>-L, --long </B>
<DD>
Suppress the linebreaks imposed for output fields that would wrap around the
normal 80-character output and allow long lines. This allows tasks to parse
the output more predictably.
<DT><B>-R, --Resolve</B>
<DD>
Print the <I>ShortName</I>, <I>ServiceType</I> and <I>Identifier</I> fields for
the resolved resource.
<DT><B>-S, --SName</B>
<DD>
Print only the <I>ShortName</I> field for the resolved resource.
<DT><B>-T, --Title</B>
<DD>
Print only the <I>Title</I> for the resolved resources.
<DT>Constraint Options:<DD>
</DL>
<P>
The list of allowed constraint strings is generally specified in the
<I>Resource Metadata for the Virtual Observatory</I> document available on
the IVOA document repository. These flags provide a convenient method to
limit a result list to resources that explicitly specify a value for the
given constraint.
<DL COMPACT>
<DT><B>-b, --bandpass <bpass></B>
<DD>
Constrain the search to the specified bandpass string.
The text argument following the -f flag
will be matched against the <I>SpectralCoverage</I> field of the resource
record. Registry resources allow a list of values, however only a single
argument may be used to constrain the search. Permitted values include:
"Radio", "Millimeter", "Infrared" (IR), "Optical", "Ultraviolet" (UV),
"X-Ray" (XRay), and "Gamma-Ray" (GR). The match is case insensitive, values
shown in parentheses may be given and will be substituted automatically.
<DT><B>-C, --clevel <content></B>
<DD>
Constrain the search to the specified ContentLevel string. The Registry
may contain data for a variety of intended audiences; Most often this
constraint will be used to limit the results to 'Research' grade data.
<DT><B>-d, --dal</B>
<DD>
Constrain the search to only standard DAL services. A general keyword search will
normally return all resources, including those referring to custom services or
non data-access entries. Use of the <I>-d</I> flag will restrict results to only
those resource records describing a standard VO data-access service.
<DT><B>-g, --group</B>
<DD>
Group the search terms to form a single query.
<DT><B>-s, --subject <subject></B>
<DD>
Constrain the search to the specified Subject string. Note that multi-word
subjects (e.g. "cool stars") must either be quoted or have the space escaped
for the subject to be queried correctly. A substring, case-insensitive search
of the Subject field is performed.
<DT><B>-t, --type <type></B>
<DD>
Constrain the search to the specified ResourceType string. The Registry
records may contain any user-specified string, however unless you know
specifically how a specific resource is defined, this constraint should
use the values 'catalog' (for Cone services), 'image' (for SIAP
services), 'spectra' (for SSAP services), 'table' (for Vizier tables),
or a literal string which appears in the
resource record. Additional aliases will be added as new
data services are supported.
<DT><B>-N, --new <time></B>
<DD>
Constrain the search to those resources that have been newly created during
the specified <time>. By default, <time> is an integer value assumed to be
a number of days, the last character may contain one of the qualifying
characters to change the time period: 'h' for hours, 'd' for days,
refers to the last siz months. If no search term is given, all results
for that period will be returned, otherwise only those results that match
both the search terms and the time constraint will be listed.
<DT><B>-U, --updated <time></B>
<DD>
Constrain the search to those resource records that have been updated during
the specified time period.
<DT>Output Control Options:<DD>
<DT><B>-a, --all</B>
<DD>
Output all matching records (default). When used with the constraint flags
above, this flag will allow those constraint strings to be matched as a
substring, e.g. using "-t siap" will exactly match resources with type
<DT><B>-f, --fields <fields></B>
<DD>
Output the specified fields from the resource record (used in Resolve Mode
only). The list of available fields is given below, an 'INDEF' string is
printed for invalid field names or when no information is available.
<DT><B>-O, --or</B>
<DD>
Logically OR the search terms. By default, all terms will be used when
matching resource records.
<DT><B>-n, --index <index></B>
<DD>
Output only the results for the matchng <I>index</I>. Results are 1-indexed,
i.e. the first result is index 1 (one).
<DT><B>-o, --output <oname></B>
<DD>
Save the results in VOTable format to the file name <I>oname</I>. The
verbose level of the query is increased when using this option.
<DT><B>-B, --samp</B>
<DD>
Broadcast the results as a SAMP message using a <I>table.load.votable</I>
message type.
<DT><B>-V, --votable</B>
<DD>
Write results in VOTable format.
<DT><B>-X, --xml</B>
<DD>
Write results in VOTable format.
<P>
<P>
</DL>
<A NAME="lbAE"> </A>
<H2>DESCRIPTION</H2>
The <I>voregistry</I> task provides a command-line interface to the <I>NVO
Registry</I> at STScI/JHU. The task also provides a basic search capability
for the Registry, as well as a "Resolve Mode" that can be used to lookup
resource records given some familiar name (e.g. 'USNO-B1'). Constraint
parameters allow the search to be restricted to resources declaring a
specific type (the <I>-t</I> flag), spectral coverage (the <I>-b</I> flag), or
content level (the <I>-C</I> flag).
<P>
Search terms may be provided on the
command-line, in a filename specified on the commandline, or read from the
standard input (e.g. redirected from a file or other command). Advanced
users can submit a quoted ADQL string to access specific fields of a resource
record. This is similar to using the "Advanced Search" capability on the
NVO Registry web page. ADQL strings are required to be in double quotes
when given on the command line, the quotes are needed when query strings
come from a file. Standard SQL operators apply for comparison and boolean
operations, the 'like' operator is used to match strings (which must be in
single quotes), one or more '%' metacharacters may be used in the string
to indicate a wildcard match.
<P>
In the default search mode, keywords given on the command line will all be
used to match resource records. The <I>-o</I> flag may be used to logically
OR the keyword terms, e.g. to allow a search of 'galaxy' or 'galaxies'. The
minimal output provides the resource title, type, subject and the 'ShortName'
that can be used in the resolve mode or be passed to other tasks such as
<A HREF="http://localhost/cgi-bin/man/man2html?1+vodata">vodata</A>(1). Additional output can be had with the <I>-v</I> or <I>-vv</I>
verbose flags. A simple count of the resources will be printed if the
<I>-c</I> flag is set (e.g. the command "voregistry -oc chandra spitzer"
will print a count of how many records match each term rather than display
them directly, without the -o flag a count of resources mentioning both
keywords will be printed).
<P>
The "Resolve mode" is activated by the <I>-r</I> flag; In this mode the
keywords will only be matched against the Registry <I>ShortName</I> and
<I>Identifier</I> fields. The default output is simply the <I>ServiceURL</I>,
adding the verbose flags will instead print the ShortName, ResourceType and
Title (with "-v") or Description (with "-vv"). The user can select specific
fields to be printed using the <I>-f</I> flag followed by a comma-delimited
list of fields. The allowed fields are shown with the <I>-h</I> help flag.
<P>
The <I>-list</I> flag implies Resolve Mode and will cause all fields of the
matching resource to be printed. Unless the <I>-a</I> flag is set, the
search term will be matched exactly, otherwise it will be considered to be
a substring of the ShortName or Identifier fields. For example, searching
with the term '2mass' will list only 2MASS image service, but using the
<I>-a</I> flag will list all services where '2mass' appears in the ShortName.
<P>
The <I>-meta</I> flag likewise assumes the command line arg is a resource
ShortName to be resolved and will query the DAL service associated with it
using a <I>FORMAT=METADATA</I> query. The default position will be (0.0,0.0)
with a search size of 0.1 degrees, the response will be a list of the column
UCDs returned by the query (note that adding <I>-v</I> flags will likewise
increase the VERBOSE of the query and may return additional columns).
<P>
<A NAME="lbAF"> </A>
<H2>RETURN STATUS</H2>
The task will exit with a status of 0 if at least one search term could
be successfully resolved, otherwise the status will be 1.
<P>
<A NAME="lbAG"> </A>
<H2>VOCLIENT DAEMON PROCESSING</H2>
All VO-CLI tasks are built upon the VOClient interface an rely on a
separate <I>voclientd</I> process to provide the VO functionality. The
voclientd task is distributed as part of VO-CLI and will be started
automatically by each task if it is not already running. If problems
are encountered, you may want to manually start the voclientd in a separate
window before running the task so you can monitor the output for error
messages.
<P>
<A NAME="lbAH"> </A>
<H2>RESOURCE CACHING</H2>
Registry resolution is a common activity of VO-CLI tasks and so results
will be cached in the $HOME/.voclient/cache/regResolver directory based
on the search term, service type and bandpass parameters. Defining the
<I>VOC_NO_CACHE</I> environment variable will cause the task to ignore the
cache.
<P>
<P>
<A NAME="lbAI"> </A>
<H2>EXAMPLES</H2>
<P>
<DL COMPACT>
<DT>1)<DD>
Get a count of all the SIAP services available in the Registry, then
list more information about each one:
<PRE>
% voregistry -count -t image
142
% voregistry -rv -t image
</PRE>
<DT>2)<DD>
Find all catalog (i.e. Cone) services using the search words 'radio'
and 'galaxies':
<PRE>
% voregistry -t catalog radio galaxies
</PRE>
<DT>3)<DD>
Print the full resource record of the GSC2.2 catalog at STScI:
<PRE>
% voregistry -list GSC2.2
</PRE>
<DT>4)<DD>
Find all services with radio data of Abell clusters. Then print the
full description of the first record associated with one of the matching
Vizier tables:
<PRE>
% voregistry -b radio abell
% voregistry -rvv -n 1 J/A+A/446/97/tab
</PRE>
<DT>5)<DD>
Find all image services that have WFPC data:
<PRE>
% voregistry -v -t image wfpc
</PRE>
<DT>6)<DD>
Print a breakdown of VO services having Keck data:
<PRE>
% voregistry -cv keck
keck 122 (Cat: 2 Tab: 117 SNode: 1 Other: 2)
</PRE>
<DT>7)<DD>
Print a count of services having all of Chandra, HST and Spitzer data,
then break it down by each mission:
<PRE>
% voregistry -c chandra hst spitzer
chandra hst spitzer 3
% voregistry -co chandra hst spitzer
chandra 323
hst 443
spitzer 31
</PRE>
<DT>8)<DD>
Print the column metadata returned by the GSC2.2 service:
<PRE>
% voregistry -meta gsc2.2
</PRE>
<DT>9)<DD>
Use the ADQL query format to find services in which HST was the used,
and not simply a match of 'HST' in the resource record:
<PRE>
% voregistry "Facility like 'HST'"
</PRE>
Note that use assumed knowledge of the Registry being queried, specifically
that there exists a 'Facility' field with this information and that the
syntax of the query requires the string to be in quotes.
<P>
<DT>10) Use the ADQL query format to find services in which 'Keck' appears in<DD>
the Title of the resource:
<PRE>
% voregistry "Title like '%Keck%'"
or
% cat query.txt
Title like '%Keck%'
% cat query.txt | voregistry
</PRE>
Note that here we use the '%' operator around the string so that we perform
a substring match on the entire title. As before, the ADQL string itself
must be enclosed in double quotes.
<P>
<DT>11) Find all resources that are newly registered in the last 3 months, then<DD>
find only those resources dealing with "cool stars", and finally just print
a count of resources updated in the last year:
<PRE>
% voregistry --new 3m
% voregistry --new 3m cool stars
% voregistry --updated 12m --count
</PRE>
<P>
</DL>
<A NAME="lbAJ"> </A>
<H2>BUGS</H2>
Some services don't repond properly to the metadata query and will print
a "no attributes found" message.
<A NAME="lbAK"> </A>
<H2>Revision History</H2>
June 2007 - This task is new.
<A NAME="lbAL"> </A>
<H2>Author</H2>
Michael Fitzpatrick (<A HREF="mailto:fitz@noao.edu">fitz@noao.edu</A>), July 2007
<A NAME="lbAM"> </A>
<H2>SEE ALSO</H2>
<A HREF="http://localhost/cgi-bin/man/man2html?1+voclient">voclient</A>(1), <A HREF="http://localhost/cgi-bin/man/man2html?1+voclientd">voclientd</A>(1), <A HREF="http://localhost/cgi-bin/man/man2html?1+vosesame">vosesame</A>(1), <A HREF="http://localhost/cgi-bin/man/man2html?1+vodata">vodata</A>(1)
<P>
<HR>
<A NAME="index"> </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">VOCLIENT DAEMON PROCESSING</A><DD>
<DT><A HREF="#lbAH">RESOURCE CACHING</A><DD>
<DT><A HREF="#lbAI">EXAMPLES</A><DD>
<DT><A HREF="#lbAJ">BUGS</A><DD>
<DT><A HREF="#lbAK">Revision History</A><DD>
<DT><A HREF="#lbAL">Author</A><DD>
<DT><A HREF="#lbAM">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:24 GMT, April 14, 2013
</BODY>
</HTML>
|
