diff options
Diffstat (limited to 'vendor/voclient/doc/vosamp_session.man')
| -rw-r--r-- | vendor/voclient/doc/vosamp_session.man | 342 |
1 files changed, 342 insertions, 0 deletions
diff --git a/vendor/voclient/doc/vosamp_session.man b/vendor/voclient/doc/vosamp_session.man new file mode 100644 index 00000000..7f7e328e --- /dev/null +++ b/vendor/voclient/doc/vosamp_session.man @@ -0,0 +1,342 @@ +.\" @(#)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 + |