In order to minimize the overhead of connecting with the Hub on each command, vosamp 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).
The vosamp task accepts the following commands, specified either on the command-line argument list or in interactive mode:
snoop
Print all received messages.
send <mtype> [<args>...]
Generalized message send. The <mtype> parameter can be either one of
the well-known SAMP mtypes or an ad hoc mtype that can be expected to be
recognized by other apps. The <args> parameter refers
to any of the arguments necessary for the specifed mtype. The <args>
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>".
status
Print Hub availability.
list
List all registered clients.
access <appName>
Print <appName> availability. The appName may be specified as either
the public ID or application name.
handle <mtype>
Wait for <mtype> message to be received. This command will subscribe the task
to the specified <mtype> and when it is received will print the contents of
the message to the stdout stream. If the --verbose 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 --quiet argument will suppress output and simply cause the
task to exit. Use of this command implicitly sets the --nokeepalive
flag.
load <url>
Load the image or table given by <url>. The type of file and the
appropriate SAMP mtype are determined automatically.
loadImage <url>
Load the named image. The image.load.fits mtype will be used for
the message.
loadVOTable <url>
Load the named VOTable. The table.load.votable mtype will be used for
the message.
loadFITS <url>
Load the named FITS bintable. The table.load.fits mtype will be used
for the message.
loadSpec <url>
Load the named spectrum. The spectrum.load.ssa-generic mtype will be
used for the message.
In the above commands, the <url> 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.
pointAt <ra> <dec>
Point at given coords. The <ra> and <dec> parameters are assumed to be ICRS
coordinates in decimal degrees, the coord.pointAt.sky mtype is used.
showRow [<url>] [<id>] <row>
Highlight specified <row> (zero-indexed). The table may be specified using
either a <url> or a table <id> if one was specified at the time the table
was loaded, the table.highlight.row mtype is used.
selectRows [<url>] [<id>] <rows>
Select specified rows. (zero-indexed) The table may be specified using
either a <url> or a table <id> if one was specified at the time the table
was loaded, the table.select.rowList mtype is used. The <rows>
argument is specified as a comma-delimited list of row numbers or ranges,
where ranges are hyphen-delimited strings (e.g. "1,3,5-9,11-15").
bibcode <bibcode>
Load the specified bibcode. The bibcode.load mtype is used.
exec <cmd>
Execute a client command. The <cmd> string is sent to the client unchanged,
it is up to the client to interpret the command properly.
The client.cmd.exec mtype is used.
setenv <name> <value>
Set an environment value. The client.env.set mtype is used.
getenv <name>
Get an environment value. The value of the requested variable is printed.
The client.env.get mtype is used.
setparam <name> <value>
Set a parameter value. The client.param.set mtype is used.
getparam <name>
Get a parameter value. The value of the requested variable is printed.
The client.param.get mtype is used.
In the standard SAMP interaction, and application is required to first register with the Hub 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 -n (or --nokeepalive) 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.
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 -P (or --proxy) flag can be used to specify an alternate proxy to be used; the argument is of the form node [ ':' port ]
where node can be a simple host name, a fully-qualified domain name or and IP address, and port 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 -T flag to specify the timeout in seconds.
% vosamp load /path/example.xml % vosamp load http://foo.edu/example.xml % vosamp load http://foo.edu/query?RA=0.0&DEC=0.0&SR=0.1
% vosamp -t iraf exec "display dev$pix 1"
% vosamp list
set isHub = `vosamp access Hub`
if ($isHub == "no") then
echo "No Hub available, quitting ....."
exit $status
endif
The description of commonly used SAMP mtypes is gen at
http://wiki.ivoa.net/twiki/bin/view/IVOA/SampMTypes