path: root/vendor/voclient/doc/OLD/vosamp.man

." @(#)vosamp.1 1.0 Feb-2013 MJF
.TH VOSAMP 1 "Feb 2013" "VOClient Package"
.SH NAME
vosamp \- command-line SAMP utility task

.SH SYNOPSIS
\fBvosamp\fP [-t to] [-p pattern] [-f file] <cmd> [args ...]

.SH OPTIONS
The \fIvosamp\fP application accepts the following options:
.TP 6
.B \-h, --help
Print a help summary to the terminal and exit.  No processing is done 
following this flag.

.TP 6
.B -i, --interact
Interactive mode.  If enabled, a command prompt will be printed allowing
users to enter commands interactively until an <EOF> is encountered.
.TP 6
.B -m, --many
Handle multiple messages when in listening mode.  If not enabled,
\fIvosamp\fP 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.
.TP 6
.B -s \fISENDER\fP, --sender \fISENDER\fP
Handle only messages from \fIsender\fP.
.TP 6
.B -q, --quiet
Suppress all output.

.TP 6
.B -t \fITO\fP, --to \fITO\fP
Send to specified app (or all apps if not given).  The \fITO\fP argument 
may be given as either an application public ID or the application name.
.TP 6
.B -p \fIPATTERN\fP, --pattern \fIPATTERN\fP
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.
.TP 6
.B -f \fIFILE\fP, --file \fIFILE\fP
Send all commands in the \fIFILE\fP argument.  This mode allows the task to
take command input from a text file to process multiple commands with a 
single invocation.
.TP 6
.B -n, --nokeepalive
Disable \fIkeep_alive\fP feature of the task.  If the \fI-n\fP flag is used,
a separate connection to the SAMP Hub will be made for each command processed.

.TP 6
.B -P \fIIP\fP, --proxy \fIIP\fP
Use specfied IP as the proxy connection.  See the discussion below about the
\fIkeep_alive\fP feature for details on how to use this flag.
.TP 6
.B -T \fIN\fP, --timeout \fIN\fP
Keepalive timeout in seconds.  If no new command is received after \fIN\fP
seconds the application will disconnect from the Hub automatically.
.TP 6
.B -S \fINAME\fP, --session \fINAME\fP
Name of the SAMP session.  See below for a description of sessions.

.SH DESCRIPTION
The \fIvosamp\fP 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
\fI-t\fP (or \fI--to\fP) flag can be used to name a specific receipient by
either the public ID or the application name, the \fI-p\fP flag will accept 
a 'sync' or 'notify' argument to change the default message pattern of 
asynchronous delivery.
.PP
In order to minimize the overhead of connecting with the Hub on each command,
\fIvosamp\fP 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).


.SH COMMAND SUMMARY
.PP
The \fIvosamp\fP task accepts the following commands, specified either on
the command-line argument list or in interactive mode:

.in 10
.B snoop						
.in 16
Print all received messages.

.in 10
.B send <mtype> [<args>...]			
.in 16
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 in the session.  The \fI<args>\fP parameter refers
to any of the arguments necessary for the specifed mtype.  The \fI<args>\fP
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>".

.in 10
.B status						
.in 16
Print Hub availability.

.in 10
.B list							
.in 16
List all registered clients.

.in 10
.B access <appName>				
.in 16
Print <appName> availability.  The \fIappName\fP may be specified as either
the public ID or application name.

.in 10
.B handle <mtype>					
.in 16
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 \fI--verbose\fP 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 \fI--quiet\fP argument will suppress output and simply cause the
task to exit.  Use of this command implicitly sets the \fI--nokeepalive\fP
flag.

.in 10
.B load <url>					
.in 16
Load the image or table given by \fI<url>\fP.  The type of file and the
appropriate SAMP \fImtype\fP are determined automatically.

.in 10
.B loadImage <url>				
.in 16
Load the named image.  The \fIimage.load.fits\fP mtype will be used for 
the message.

.in 10
.B loadVOTable <url>				
.in 16
Load the named VOTable. The \fItable.load.votable\fP mtype will be used for 
the message.

.in 10
.B loadFITS <url>					
.in 16
Load the named FITS bintable. The \fItable.load.fits\fP mtype will be used 
for the message.

.in 10
.B loadSpec <url>					
.in 16
Load the named spectrum.  The \fIspectrum.load.ssa-generic\fP mtype will be
used for the message.

.in 10
In the above commands,  the \fI<url>\fP 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.

.in 10
.B pointAt <ra> <dec>				
.in 16
Point at given coords.  The <ra> and <dec> parameters are assumed to be ICRS
coordinates in decimal degrees, the \fIcoord.pointAt.sky\fP mtype is used.

.in 10
.B showRow [<url>] [<id>] <row>		
.in 16
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 \fItable.highlight.row\fP mtype is used.

.in 10
.B selectRows [<url>] [<id>] <rows>	
.in 16
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 \fItable.select.rowList\fP mtype is used.  The <rows>
argument is specified as a comma-delimited list of row numbers or ranges, 
where \fIranges\fP are hyphen-delimited strings (e.g. "1,3,5-9,11-15").

.in 10
.B bibcode <bibcode>				
.in 16
Load the specified bibcode.  The \fIbibcode.load\fP mtype is used.


.in 10
.B exec <cmd>					
.in 16
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 \fIclient.cmd.exec\fP mtype is used.

.in 10 
.B setenv  <name> <value>			
.in 16
Set an environment value.  The \fIclient.env.set\fP mtype is used.

.in 10 
.B getenv  <name>					
.in 16
Get an environment value.  The value of the requested variable is printed.
The \fIclient.env.get\fP mtype is used.

.in 10
.B setparam <name> <value>			
.in 16
Set a parameter value.  The \fIclient.param.set\fP mtype is used.

.in 10
.B getparam <name>				
.in 16
Get a parameter value.  The value of the requested variable is printed.
The \fIclient.param.get\fP mtype is used.


.in 10
.B session list					
.in 16
List nodes in current session.

.in 10
.B session leave|exit|logout		
.in 16
Leave the current session.

.in 10
.B session <name>					
.in 16
Join the named session.


.SH KEEP-ALIVE CONNECTIONS AND SESSIONS
.PP
In the standard SAMP interaction, and application is required to first 
register with the \fIHub\fP 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 \fI-n\fP (or \fI--nokeepalive\fP) 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.
.PP
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 \fI-P\fP (or \fI--proxy\fP) flag can be used to
specify an alternate proxy to be used;  the argument is of the form
.in 15 
\fInode\fP [ ':' \fIport\fP ]
.PP
where \fInode\fP can be a simple host name, a fully-qualified domain name or
and IP address, and \fIport\fP 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 \fI-T\fP flag
to specify the timeout in seconds.

.PP
SAMP \fISessions\fP are an experimental concept in which \fIvosamp\fP
tasks on separate machines register independently with their local Hub,
but also register with the \fIvosession\fP task running elsewhere.  Commands
which are sent to the local child proxy are also forwarded to the
\fIvosession\fP instance and then on to other vosamp clients registered in
the same session.  The \fIsession\fP commands allow a vosamp client to 
register with a new session, list the other machines involved in the session
and later leave the sessions.  Commands which require a URL will upload
local data to the \fIvosession\fP manager and rewrite the URL appropiately
so it may be served to the other vosamp clients.  Since SAMP is designed
only for local desktop messaging, this approach provides a means to share
messages and data between desktops (e.g. when working collaboratively with
colleagues).  See the \fIvosession\fP man page or contact the author for
further information on using this feature.


.SH RETURN STATUS
On exit the \fBvosamp\fP task will return a zero indicating success, or a
one indicating an error.

.SH EXAMPLES
.TP 4
1)  Load a VOTable to Topcat:

.nf
  % 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
.fi
.TP 4
2)  Send a command string to IRAF:

.nf 
  % vosamp -t iraf exec "display dev$pix 1"
.fi
.TP 4
3)  List all clients in a SAMP session:

.nf 
  % vosamp list
.fi
.TP 4
4)  Check whether a Hub is available from a script:

.nf 
  set isHub = `vosamp access Hub`
  if ($isHub == "no") then
    echo "No Hub available, quitting ....."
    exit $status
  endif
.fi



.SH BUGS
No known bugs with this release.
.SH KNOWN SHORTCOMINGS
No known bugs with this release.
.in 4
- The 'handle' command should allow a command to be executed with message argument substitution.
.in 4
- A flag is needed to change the child proxy port being used

.SH Revision History
Feb 2013 - First public release
.SH Author
Michael Fitzpatrick (fitz@noao.edu), Feb 2013
.SH "SEE ALSO"
vosession
.PP
The description of commonly used SAMP mtypes is gen at

.in 9
http://wiki.ivoa.net/twiki/bin/view/IVOA/SampMTypes