.\" @(#)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] [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 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. .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 [...] .in 16 Generalized message send. The 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 \fI\fP parameter refers to any of the arguments necessary for the specifed mtype. The \fI\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 ":". .in 10 .B status .in 16 Print Hub availability. .in 10 .B list .in 16 List all registered clients. .in 10 .B access .in 16 Print availability. The \fIappName\fP may be specified as either the public ID or application name. .in 10 .B handle .in 16 Wait for message to be received. This command will subscribe the task to the specified 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 followed by the message parameters in the form "=". 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 .in 16 Load the image or table given by \fI\fP. The type of file and the appropriate SAMP \fImtype\fP are determined automatically. .in 10 .B loadImage .in 16 Load the named image. The \fIimage.load.fits\fP mtype will be used for the message. .in 10 .B loadVOTable .in 16 Load the named VOTable. The \fItable.load.votable\fP mtype will be used for the message. .in 10 .B loadFITS .in 16 Load the named FITS bintable. The \fItable.load.fits\fP mtype will be used for the message. .in 10 .B loadSpec .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\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 .in 16 Point at given coords. The and parameters are assumed to be ICRS coordinates in decimal degrees, the \fIcoord.pointAt.sky\fP mtype is used. .in 10 .B showRow [] [] .in 16 Highlight specified (zero-indexed). The table may be specified using either a or a table if one was specified at the time the table was loaded, the \fItable.highlight.row\fP mtype is used. .in 10 .B selectRows [] [] .in 16 Select specified rows. (zero-indexed) The table may be specified using either a or a table if one was specified at the time the table was loaded, the \fItable.select.rowList\fP mtype is used. The 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 .in 16 Load the specified bibcode. The \fIbibcode.load\fP mtype is used. .in 10 .B exec .in 16 Execute a client command. The 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 .in 16 Set an environment value. The \fIclient.env.set\fP mtype is used. .in 10 .B getenv .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 .in 16 Set a parameter value. The \fIclient.param.set\fP mtype is used. .in 10 .B getparam .in 16 Get a parameter value. The value of the requested variable is printed. The \fIclient.param.get\fP mtype is used. .SH KEEP-ALIVE CONNECTIONS .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. .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 desktop 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" .PP The description of commonly used SAMP mtypes is gen at .in 9 http://wiki.ivoa.net/twiki/bin/view/IVOA/SampMTypes