diff options
Diffstat (limited to 'vendor/voclient/doc/vosamp.html')
| -rw-r--r-- | vendor/voclient/doc/vosamp.html | 405 |
1 files changed, 405 insertions, 0 deletions
diff --git a/vendor/voclient/doc/vosamp.html b/vendor/voclient/doc/vosamp.html new file mode 100644 index 00000000..f68f4b27 --- /dev/null +++ b/vendor/voclient/doc/vosamp.html @@ -0,0 +1,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> |