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
|
Content-type: text/html
<HTML><HEAD><TITLE>Manpage of VOSAMP</TITLE>
</HEAD><BODY>
<H1>VOSAMP</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"> </A>
<H2>NAME</H2>
vosamp - command-line SAMP utility task
<P>
<A NAME="lbAC"> </A>
<H2>SYNOPSIS</H2>
<B>vosamp</B> [-t to] [-p pattern] [-f file] <cmd> [args ...]
<P>
<A NAME="lbAD"> </A>
<H2>OPTIONS</H2>
The <I>vosamp</I> application 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>-i, --interact</B>
<DD>
Interactive mode. If enabled, a command prompt will be printed allowing
users to enter commands interactively until an <EOF> is encountered.
<DT><B>-m, --many</B>
<DD>
Handle multiple messages when in listening mode. If not enabled,
<I>vosamp</I> can be called to wait for a specific message and will exit when
it is received, otherwise the task will continue to run and process
multiple messages.
<DT><B>-s </B><I>SENDER</I>, --sender <I>SENDER</I>
<DD>
Handle only messages from <I>sender</I>.
<DT><B>-q, --quiet</B>
<DD>
Suppress all output.
<P>
<DT><B>-t </B><I>TO</I>, --to <I>TO</I>
<DD>
Send to specified app (or all apps if not given). The <I>TO</I> argument
may be given as either an application public ID or the application name.
<DT><B>-p </B><I>PATTERN</I>, --pattern <I>PATTERN</I>
<DD>
Messaging pattern to use when sending messages. The default mode
is 'async' to send messages asychrnously, other allowed values are 'sync'
for syncronous messages and 'notify' to broadcast without expecting a
response.
<DT><B>-f </B><I>FILE</I>, --file <I>FILE</I>
<DD>
Send all commands in the <I>FILE</I> argument. This mode allows the task to
take command input from a text file to process multiple commands with a
single invocation.
<DT><B>-n, --nokeepalive</B>
<DD>
Disable <I>keep_alive</I> feature of the task. If the <I>-n</I> flag is used,
a separate connection to the SAMP Hub will be made for each command processed.
<P>
<DT><B>-P </B><I>IP</I>, --proxy <I>IP</I>
<DD>
Use specfied IP as the proxy connection. See the discussion below about the
<I>keep_alive</I> feature for details on how to use this flag.
<DT><B>-T </B><I>N</I>, --timeout <I>N</I>
<DD>
Keepalive timeout in seconds. If no new command is received after <I>N</I>
seconds the application will disconnect from the Hub automatically.
<P>
</DL>
<A NAME="lbAE"> </A>
<H2>DESCRIPTION</H2>
The <I>vosamp</I> task may be used to send and receive SAMP (Simple
Application Messaging Protocol) messages from the command-line or within a
script. It provides a user-friendly command interface that hides the details
of the message construction and delivery for common tasks. By default,
a message will be broadcast to all other SAMP-enabled applications, the
<I>-t</I> (or <I>--to</I>) flag can be used to name a specific receipient by
either the public ID or the application name, the <I>-p</I> flag will accept
a 'sync' or 'notify' argument to change the default message pattern of
asynchronous delivery.
<P>
In order to minimize the overhead of connecting with the Hub on each command,
<I>vosamp</I> will spawn a proxy process that remains connected to the Hub and
will process subsequent commands transparently. This proxy process will
timeout after some period of inactivity and may be accessed from remote
machines (see below for more information).
<P>
<P>
<A NAME="lbAF"> </A>
<H2>COMMAND SUMMARY</H2>
<P>
The <I>vosamp</I> task accepts the following commands, specified either on
the command-line argument list or in interactive mode:
<P>
<B>snoop<TT> </TT><TT> </TT><TT> </TT><TT> </TT><TT> </TT><TT> </TT></B>
Print all received messages.<BR>
<P>
<B>send <mtype> [<args>...]<TT> </TT><TT> </TT><TT> </TT></B>
Generalized message send. The <mtype> parameter can be either one of <BR>
the well-known SAMP mtypes or an ad hoc mtype that can be expected to be
recognized by other apps. The <I><args></I> parameter refers
to any of the arguments necessary for the specifed mtype. The <I><args></I>
may be specified as a sequence of values and will be delivered using
parameter names of the form "argN", to send named parameters the argument
must be specified as "<name>:<value>".
<P>
<B>status<TT> </TT><TT> </TT><TT> </TT><TT> </TT><TT> </TT><TT> </TT></B>
Print Hub availability.<BR>
<P>
<B>list<TT> </TT><TT> </TT><TT> </TT><TT> </TT><TT> </TT><TT> </TT><TT> </TT></B>
List all registered clients.<BR>
<P>
<B>access <appName><TT> </TT><TT> </TT><TT> </TT><TT> </TT></B>
Print <appName> availability. The <I>appName</I> may be specified as either<BR>
the public ID or application name.
<P>
<B>handle <mtype><TT> </TT><TT> </TT><TT> </TT><TT> </TT><TT> </TT></B>
Wait for <mtype> message to be received. This command will subscribe the task<BR>
to the specified <mtype> and when it is received will print the contents of
the message to the stdout stream. If the <I>--verbose</I> flag is used the
first value printed will be the sender-id, otherwise the first value will be
the <mtype> followed by the message parameters in the form "<name>=<value>".
Using the <I>--quiet</I> argument will suppress output and simply cause the
task to exit. Use of this command implicitly sets the <I>--nokeepalive</I>
flag.
<P>
<B>load <url><TT> </TT><TT> </TT><TT> </TT><TT> </TT><TT> </TT></B>
Load the image or table given by <I><url></I>. The type of file and the<BR>
appropriate SAMP <I>mtype</I> are determined automatically.
<P>
<B>loadImage <url><TT> </TT><TT> </TT><TT> </TT><TT> </TT></B>
Load the named image. The <I>image.load.fits</I> mtype will be used for <BR>
the message.
<P>
<B>loadVOTable <url><TT> </TT><TT> </TT><TT> </TT><TT> </TT></B>
Load the named VOTable. The <I>table.load.votable</I> mtype will be used for <BR>
the message.
<P>
<B>loadFITS <url><TT> </TT><TT> </TT><TT> </TT><TT> </TT><TT> </TT></B>
Load the named FITS bintable. The <I>table.load.fits</I> mtype will be used <BR>
for the message.
<P>
<B>loadSpec <url><TT> </TT><TT> </TT><TT> </TT><TT> </TT><TT> </TT></B>
Load the named spectrum. The <I>spectrum.load.ssa-generic</I> mtype will be<BR>
used for the message.
<P>
In the above commands, the <I><url></I> may be an explicit URI containing
an 'http' or 'file' prefix, if a filename or directory path is specified
the URL will be constructed internally when sending the message.
<P>
<B>pointAt <ra> <dec><TT> </TT><TT> </TT><TT> </TT><TT> </TT></B>
Point at given coords. The <ra> and <dec> parameters are assumed to be ICRS<BR>
coordinates in decimal degrees, the <I>coord.pointAt.sky</I> mtype is used.
<P>
<B>showRow [<url>] [<id>] <row><TT> </TT><TT> </TT></B>
Highlight specified <row> (zero-indexed). The table may be specified using<BR>
either a <url> or a table <id> if one was specified at the time the table
was loaded, the <I>table.highlight.row</I> mtype is used.
<P>
<B>selectRows [<url>] [<id>] <rows><TT> </TT></B>
Select specified rows. (zero-indexed) The table may be specified using<BR>
either a <url> or a table <id> if one was specified at the time the table
was loaded, the <I>table.select.rowList</I> mtype is used. The <rows>
argument is specified as a comma-delimited list of row numbers or ranges,
where <I>ranges</I> are hyphen-delimited strings (e.g. "1,3,5-9,11-15").
<P>
<B>bibcode <bibcode><TT> </TT><TT> </TT><TT> </TT><TT> </TT></B>
Load the specified bibcode. The <I>bibcode.load</I> mtype is used.<BR>
<P>
<P>
<B>exec <cmd><TT> </TT><TT> </TT><TT> </TT><TT> </TT><TT> </TT></B>
Execute a client command. The <cmd> string is sent to the client unchanged,<BR>
it is up to the client to interpret the command properly.
The <I>client.cmd.exec</I> mtype is used.
<P>
<B>setenv <name> <value><TT> </TT><TT> </TT><TT> </TT></B>
Set an environment value. The <I>client.env.set</I> mtype is used.<BR>
<P>
<B>getenv <name><TT> </TT><TT> </TT><TT> </TT><TT> </TT><TT> </TT></B>
Get an environment value. The value of the requested variable is printed.<BR>
The <I>client.env.get</I> mtype is used.
<P>
<B>setparam <name> <value><TT> </TT><TT> </TT><TT> </TT></B>
Set a parameter value. The <I>client.param.set</I> mtype is used.<BR>
<P>
<B>getparam <name><TT> </TT><TT> </TT><TT> </TT><TT> </TT></B>
Get a parameter value. The value of the requested variable is printed.<BR>
The <I>client.param.get</I> mtype is used.
<P>
<P>
<A NAME="lbAG"> </A>
<H2>KEEP-ALIVE CONNECTIONS</H2>
<P>
In the standard SAMP interaction, and application is required to first
register with the <I>Hub</I> before sending or receiving messages. This
registration can add significant overhead to an application that may only
send a single message, significantly slowing it's use within a scripting
environment. Unless the <I>-n</I> (or <I>--nokeepalive</I>) flag is set,
the first time VOSAMP is started it will execute the specified command
and then fork a child process that stays connected to the Hub. Subsequent
VOSAMP calls will simply forward the command to this child proxy process,
thereby avoiding a new Hub registration.
<P>
The proxy process by default will listen on inet port 3999 (as of this writing
there is no option to change it) for new commands, however there is no
restriction that the only application that can connect to it must be running
on the same host. The <I>-P</I> (or <I>--proxy</I>) flag can be used to
specify an alternate proxy to be used; the argument is of the form
<I>node</I> [ ':' <I>port</I> ]
<P>
where <I>node</I> can be a simple host name, a fully-qualified domain name or
and IP address, and <I>port</I> number number is optional. The proxy will
run for up to an hour if no new commands are received before disconnecting
from the Hub, this timeout value may be changed by using the <I>-T</I> flag
to specify the timeout in seconds.
<P>
<A NAME="lbAH"> </A>
<H2>RETURN STATUS</H2>
On exit the <B>vosamp</B> task will return a zero indicating success, or a
one indicating an error.
<P>
<A NAME="lbAI"> </A>
<H2>EXAMPLES</H2>
<DL COMPACT>
<DT>1) Load a VOTable to Topcat:<DD>
<P>
<PRE>
% vosamp load /path/example.xml
% vosamp load <A HREF="http://foo.edu/example.xml">http://foo.edu/example.xml</A>
% vosamp load <A HREF="http://foo.edu/query?RA=0.0">http://foo.edu/query?RA=0.0</A>&DEC=0.0&SR=0.1
</PRE>
<DT>2) Send a command string to IRAF:<DD>
<P>
<PRE>
% vosamp -t iraf exec "display dev$pix 1"
</PRE>
<DT>3) List all clients in a SAMP desktop session:<DD>
<P>
<PRE>
% vosamp list
</PRE>
<DT>4) Check whether a Hub is available from a script:<DD>
<P>
<PRE>
set isHub = `vosamp access Hub`
if ($isHub == "no") then
echo "No Hub available, quitting ....."
exit $status
endif
</PRE>
<P>
<P>
<P>
</DL>
<A NAME="lbAJ"> </A>
<H2>BUGS</H2>
No known bugs with this release.
<A NAME="lbAK"> </A>
<H2>KNOWN SHORTCOMINGS</H2>
No known bugs with this release.
- The 'handle' command should allow a command to be executed with message argument substitution.
- A flag is needed to change the child proxy port being used
<P>
<A NAME="lbAL"> </A>
<H2>Revision History</H2>
Feb 2013 - First public release
<A NAME="lbAM"> </A>
<H2>Author</H2>
Michael Fitzpatrick (<A HREF="mailto:fitz@noao.edu">fitz@noao.edu</A>), Feb 2013
<A NAME="lbAN"> </A>
<H2>SEE ALSO</H2>
<P>
<P>
The description of commonly used SAMP mtypes is gen at
<P>
<A HREF="http://wiki.ivoa.net/twiki/bin/view/IVOA/SampMTypes">http://wiki.ivoa.net/twiki/bin/view/IVOA/SampMTypes</A>
<P>
<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">COMMAND SUMMARY</A><DD>
<DT><A HREF="#lbAG">KEEP-ALIVE CONNECTIONS</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">KNOWN SHORTCOMINGS</A><DD>
<DT><A HREF="#lbAL">Revision History</A><DD>
<DT><A HREF="#lbAM">Author</A><DD>
<DT><A HREF="#lbAN">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: 06:21:57 GMT, April 26, 2013
</BODY>
</HTML>
|
