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
|
Content-type: text/html
<HTML><HEAD><TITLE>Manpage of VOSESAME</TITLE>
</HEAD><BODY>
<H1>VOSESAME</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>
vosesame - call the Sesame name resolver service
<P>
<A NAME="lbAC"> </A>
<H2>SYNOPSIS</H2>
<B>vosesame</B> [-<I>adefhinstACHT</I>] [<I>file</I> | <I>target</I> ] [ ... ]
<P>
<A NAME="lbAD"> </A>
<H2>OPTIONS</H2>
The <I>vosesame</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>-q, --quiet</B>
<DD>
Quiet mode (suppress warning output).
<DT><B>-v, --verbose</B>
<DD>
Verbose output. Normally used to print warnings when an object could not be
resolved.
<DT>The following flags may be combined as a single option to indicate the<DD>
desired output fields. The order of the flags implies the order of the
output values, e.g. "-dnt" prints the decimal position, name and type in
that order.
<DT><B>-a, --all</B>
<DD>
Output all available information about the object.
<DT><B>-d, --decimal</B>
<DD>
Output the position as J2000 decimal degrees. This is the default output if
no format flags are specified.
<DT><B>-e, --errors</B>
<DD>
Output the estimated position errors.
<DT><B>-n, --name</B>
<DD>
Output the object name.
<DT><B>-t, --type</B>
<DD>
Output the object type.
<DT><B>-s, --sex</B>
<DD>
Output the position as sexagesimal RA and Dec.
<P>
<DT>Control Flags:<DD>
<DT><B>-f, --force</B>
<DD>
Force the object(s) to be resolved even if it is cached. This option will
cause the task to call the Sesame service rather than output a previously
cached value, however the result will still be cached unless the VOC_NO_CACHE
environment variable is defined.
<DT><B>-o <name> or --output=<name></B>
<DD>
Specify the output file. The default is to write the results to the
standard output.
<DT><B>-p <ra,dec> or --pos=<ra,dec></B>
<DD>
Specify a comma-delimited input position. This option can be used to
convert input sexagesimal or floating-point values using the formatting
options.
<P>
<DT>Formatting Flags:<DD>
<DT><B>-A, --ascii</B>
<DD>
Print the results as a whitespace delimited ascii table.
<DT><B>-C, --csv</B>
<DD>
Print the results as a comma-separated-value (CSV) table.
<DT><B>-F, --format</B>
<DD>
Format ASCII results using fixed-width columns.
<DT><B>-H, --header</B>
<DD>
Print a table header. The table header will be a single line beginning with
a '#' character to indicate a comment, and followed by the name of each
column in the specified format.
<DT><B>-I, --init_cache</B>
<DD>
Initialize the resolver cache directory.
<DT><B>-T, --tsv</B>
<DD>
Print the results as a tab-separated-value (TSV) table.
<P>
</DL>
<A NAME="lbAE"> </A>
<H2>DESCRIPTION</H2>
The <I>vosesame</I> task provides a command-line interface to the
<I>Sesame</I> name
resolver service at CDS that convert a familiar object name to the J2000
coordinates required by VO services. Additional information
such such as the object type is also available. The <I>Sesame</I> service
queries NED, Simbad and Vizier databases for this information. If no
flags are provided, the default output is simply the RA and Dec of the
object in decimal degrees (this is what most VO services expect), however
command-line flags provide a method to specify the desired output and
the order in which they are printed.
<P>
Object names may be specified on the commandline individually (multiple
arguments are allowed), as the name of a file containing a list of
objects to be resolved, or both. If no object or file names are given on
the command line the task will read from the standard input, allowing the
task to be used as a command filter or interactively from the keyboard.
Files containing object names are assumed
to list the name of one object-per-line where whitespace in the object name
is allowed on the line (e.g. "M 51"). From the command line, most shell
interpreters will require that the whitespace be escaped (e.g. "M 51")
so it is interpreted properly. A warning will be printed if an object name
cannot be resolved and the <I>-v</I> verbose flag is set, otherwise no
output will be printed for the failed request.
<P>
The <I>OPTIONS</I> section describes the formatting options available.
For each of these options, the order in which it appears controls the order of
where it appears in the output string for the object. Output format
flags control how the values are printed. Supported formats include
comma-separated-values (CSV, the <I>-C</I> flag), tab-separated-values (TSV,
the <I>-T</I> flag), whitespace-delimited values (the <I>-A</I> default),
and may include an optional head (the <I>-H</I>) flag) that precedes the
output with a line of text listing the output colums where the first
character of the header is a '#' to indicate a comment.
<P>
<A NAME="lbAF"> </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="lbAG"> </A>
<H2>OBJECT CACHING</H2>
The <B>Sesame</B> service at CDS is normally fairly reliable, however there
are times when it is either unavailable, or simply returns a null result
without indicating an error. Additionally, the access time is on the
order of ~1 sec/object and so resolving many objects creates an overhead
for applications using this service.
<P>
The <B>vosesame</B> task's only function is to resolve objects, however it
still uses the object caching capability in the VOClient interface. Once
an object is resolved, it will automatically be cached unless the
<B>VOC_NO_CACHE</B> environment variable is defined. The <I>-f</I>
command-line option can be used to override any existing cached values and
force the Sesame service to be invoked. The object cache may be initialized
completely by deleting the $HOME/.voclient/cache/sesame directory.
<P>
<A NAME="lbAH"> </A>
<H2>RETURN STATUS</H2>
If all objects were successfully resolved the task will exit with a
status code of 0. If one or more of the objects failed to be resolved for
any reason, the exit status will be the number of unresolved objects.
<P>
<P>
<A NAME="lbAI"> </A>
<H2>EXAMPLES</H2>
<P>
<DL COMPACT>
<DT>1)<DD>
Print the coordinates of NGC4456, first in decimal degrees and
then as sexagesimal values:
<P>
<PRE>
% vosesame ngc4456
186.960000 -30.120000
% vosesame -s ngc4456
12:27.8 -30:07
</PRE>
<P>
<DT>2)<DD>
Print the sexagesimal coordinates of multiple objects, include the type:
<P>
<PRE>
% vosesame -st m31 m51 m99
00:42:44.31 +41:16:09.4 LINER
13:29:52.36 +47:11:40.8 Seyfert_2
12:18:49.51 +14:25:00.4 HII_G
</PRE>
<P>
<DT>3)<DD>
Print the decimal coordinates of those same objects listed in
the file 'myobjs.txt', output as CSV, include a header, and print
the id, coords, and type:
<P>
<PRE>
% vosesame -CHndt myobjs.txt
#Name,DRA,DDEC,Type,
m31,10.684625,41.269278,LINER
m51,202.468208,47.194667,Seyfert_2
m99,184.706333,14.416778,HII_G
: : : :
</PRE>
<P>
<DT>4)<DD>
Extract the object names from column 17-25 of a file and pipe the
list to vosesame to create a new table of id, ra and dec:
<P>
<PRE>
% cut -c17-25 data.txt | vosesame -ns
m51 13:29:52.36 +47:11:40.8
m23 17:57:00.00 -18:58:59.9
m67 08:51:17.99 +11:48:00.0
: : :
</PRE>
<P>
<DT>5)<DD>
Interactively resolve coordinates by enterying object names on the
standard input:
<PRE>
% vosesame -a
m98
m98 12:13:48.37 +14:53:57.9 183.45154 14.89944 10.0 10.0 LINER
[EOF]
</PRE>
Type the EOF character (typically Ctrl-D or Ctrl-Z) to quit.
<P>
<P>
<DT>6)<DD>
Print the sexagesimal and decimal values for multiple user coords:
<PRE>
% vosesame -sd -p 12:30:0.0,-45:00:0.0 -p 187.5,2.05
12:30:00.0 -45:00:00.0 12.500000 -45.000000
12:30:00.0 02:03:00.0 187.500000 2.050000
</PRE>
<P>
<P>
</DL>
<A NAME="lbAJ"> </A>
<H2>BUGS</H2>
The Sesame service can sometimes respond without resolving the object. In
this case all values are returned as zero or a null string. <I>Vosesame</I>
will sense this as a non-response and not print a result. If the
<I>verbose</I> flag is set a warning message will be printed.
<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>
voclient, voclientd, voregistry, vodata
<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">VOCLIENT DAEMON PROCESSING</A><DD>
<DT><A HREF="#lbAG">OBJECT CACHING</A><DD>
<DT><A HREF="#lbAH">RETURN STATUS</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: 19:30:04 GMT, April 15, 2013
</BODY>
</HTML>
|
