diff options
Diffstat (limited to 'xpa/doc/programs.html')
| -rw-r--r-- | xpa/doc/programs.html | 274 |
1 files changed, 274 insertions, 0 deletions
diff --git a/xpa/doc/programs.html b/xpa/doc/programs.html new file mode 100644 index 0000000..b37031f --- /dev/null +++ b/xpa/doc/programs.html @@ -0,0 +1,274 @@ +<HTML> +<HEAD> +<TITLE>XPA Programs</TITLE> +</HEAD> +<BODY> +<H2>XPA Programs</H2> + +<H2>Summary</H2> + +<P> +Use the XPA programs to send/receive data to/from XPA servers from the +command line or from scripts. + +<P> +<PRE> + <data> | xpaset [-h] [-i nsinet] [-m method] [-n] [-p] [-s] [-t sval,lval] [-u users] [-v] <template> [paramlist] + + xpaget [-h] [-i nsinet] [-m method] [-s] [-t sval,lval] [-u users] <template> [paramlist] + + xpainfo [-h] [-i nsinet] [-m method] [-n] [-s] [-t sval,lval] [-u users] <template> [paramlist] + + xpaaccess [-c] [-h] [-i nsinet] [-m method] [-n] [-u users] [-v|-V] <template> [type] +</PRE> + +<!-- =defdoc xpaset xpaset 1 --> + +<!-- =section xpaset NAME --> +<H2><A NAME="xpaset">xpaset: send data to one or more XPA servers</A></H2> + +<!-- =section xpaset SYNOPSIS --> +<B> +<PRE> +<data> | xpaset [-h] [-i nsinet] [-m method] [-n] [-p] [-s] [-t sval,lval] [-u users] [-v] <template|host:port> [paramlist] +</PRE> +</B> + +<!-- =section xpaset OPTIONS --> +<P> +<PRE> + -h print help message + -i access XPA point on different machine (override XPA_NSINET) + -m override XPA_METHOD environment variable + -n don't wait for the status message after server completes + -p don't read (or send) buf data from stdin + -s enter server mode + -t [s,l] set short and long timeouts (override XPA_[SHORT,LONG]_TIMEOUT) + -u [users] XPA points can be from specified users (override XPA_NSUSERS) + -v verify message to stdout + --version display version and exit +</PRE> + +<!-- =section xpaset DESCRIPTION --> +<P> +Data read from stdin will be sent to access points matching the +<A HREF="./template.html">template</A> +or host:port. +A set of qualifying parameters can be appended. +<P> +Normally, xpaset reads data input from stdin until EOF and sends those +data to the XPA target, along with parameters entered on the command +line. For example to send a FITS file to the ds9 image display: +<PRE> + cat foo.fits | xpaset ds9 fits +</PRE> +<P> +Sometimes, however, it is desirable to send only parameters to an XPA +access point, without sending data. For such cases, use the -p switch to +indicate that there is no data being send to stdin. For example, to +change the colormap used by the ds9 image display program, use: +<PRE> + csh> xpaset -p ds9 cmap Heat +</PRE> +Of course, this also can be accomplished by sending EOF to stdin in +any of the usual ways: +<PRE> + csh> echo "" | xpaset ds9 cmap Heat + csh> xpaget ds9 cmap Heat < /dev/null + csh> xpaset ds9 cmap Heat + ^D # Ctl-D signals EOF +</PRE> +<P> +The -s switch puts xpaset into server mode, in which commands and data +can be sent to access points without having to run xpaset multiple times. +(Its not clear if this buys you much!) The syntax for sending commands +in server mode is: +<P> +<PRE> + csh> xpaset -s + xpaset ds9 colormap I8 + ^D + xpaset ds9 regions + circle 200 300 40 + circle 300 400 50 + ^D +etc. +</PRE> +After the required "xpaset" command is specified, optional ASCII data +can be appended (as in the region example). A single data/command set is +delimited by ^D. Note that typing ^D when a command is expected terminates +the program. +<P> +NB: server mode only works from the terminal and only ASCII data can be +sent in this way. +<P> +<B>Examples:</B> +<PRE> + csh> xpaset ds9 file < foo.fits + csh> echo "stop" | xpaset myhost:12345 +</PRE> + +<!-- =defdoc xpaget xpaget 1 --> + +<!-- =section xpaget NAME --> +<H2><A NAME="xpaget">xpaget: retrieve data from one or more XPA servers</A></H2> + +<!-- =section xpaget SYNOPSIS --> +<B> +<PRE> +xpaget [-h] [-i nsinet] [-m method] [-s] [-t sval,lval] [-u users] <template|host:port> [paramlist] +</PRE> +</B> + +<!-- =section xpaget OPTIONS --> +<P> +<PRE> + -h print help message + -i access XPA point on different machine (override XPA_NSINET) + -m override XPA_METHOD environment variable + -n don't wait for the status message after server completes + -s enter server mode + -t [s,l] set short and long timeouts (override XPA_[SHORT,LONG]_TIMEOUT) + -u [users] XPA points can be from specified users (override XPA_NSUSERS) + --version display version and exit +</PRE> + +<!-- =section xpaget DESCRIPTION --> +<P> +Data will be retrieved from access points matching the +<A HREF="./template.html">template</A> +or host:port. +A set of qualifying parameters can be appended. +<P> +<B>Examples:</B> +<PRE> + csh> xpaget ds9 images + csh> xpaget myhost.harvard.edu:12345 +</PRE> + +<!-- =defdoc xpainfo xpainfo 1 --> + +<!-- =section xpainfo NAME --> +<H2><A NAME="xpainfo">xpainfo: send short message to one or more XPA servers</A></H2> + +<!-- =section xpainfo SYNOPSIS --> +<B> +<PRE> +xpainfo [-h] [-i nsinet] [-m method] [-n] [-s] [-t sval,lval] [-u users] <template|host:port> [paramlist] +</PRE> +</B> + +<!-- =section xpainfo OPTIONS --> +<P> +<PRE> + -h print help message + -i access XPA point on different machine (override XPA_NSINET) + -m override XPA_METHOD environment variable + -n don't wait for the status message after server completes + -s enter server mode + -t [s,l] set short and long timeouts (override XPA_[SHORT,LONG]_TIMEOUT) + -u [users] XPA points can be from specified users (override XPA_NSUSERS) + --version display version and exit +</PRE> + +<!-- =section xpainfo DESCRIPTION --> +<P> +Info will be sent to access points matching the +<A HREF="./template.html">template</A> +or host:port. +A set of qualifying parameters can be appended. +<P> +<B>Examples:</B> +<PRE> + csh> xpainfo IMAGE ds9 image +</PRE> + +<!-- =defdoc xpaaccess xpaaccess 1 --> + +<!-- =section xpaaccess NAME --> +<H2><A NAME="xpaaccess">xpaaccess: see if template matches registered XPA access points</A></H2> + +<!-- =section xpaaccess SYNOPSIS --> +<B> +<PRE> +xpaaccess [-c] [-h] [-i nsinet] [-m method] [-n] [-t sval,lval] [-u users] -v <template> [type] +</PRE> +</B> + +<!-- =section xpaaccess OPTIONS --> +<P> +<PRE> + -c contact each access point individually + -h print help message + -i access XPA point on different machine (override XPA_NSINET) + -m override XPA_METHOD environment variable + -n return number of matches instead of "yes" or "no" + -t [s,l] set short and long timeouts (override XPA_[SHORT,LONG]_TIMEOUT) + -u [users] XPA points can be from specified users (override XPA_NSUSERS) + -v print info about each successful access point + -V print info or error about each access point + --version display version and exit +</PRE> + +<!-- =section xpaaccess DESCRIPTION --> +<P> +xpaaccess returns "yes" to stdout (with a return error code if 1) if there are +existing XPA access points that match the +<A HREF="./template.html">template</A> +(and optional access type: g,i,s). Otherwise, it returns "no" (with a +return error code of 0). If -n is specified, the number of matches is +returned instead (both to stdout and in the returned error code). If +-v is specified, each access point is displayed to stdout instead of +the number of matches. + +<P> +By default, xpaaccess simply contacts the xpans name server to find +the list of registered access points that match the specified +template. It also checks to make sure the specified types are +supported by that access point. This is the fastest way to determine +available access points. However, an access point might registered but +not yet available, if, for example, the server program has not entered +its event loop to process XPA requests. To find access points that are +guaranteed to be available for processing, use the -c (contact) +switch. With this switch, xpaaccess contacts each matching XPA server +(rather than the name server) to make sure the registered access point +really is ready for processing. In this mode, if an access point is +registered but not available, xpaaccess will pause for a period of +time equal to the XPA_LONG_TIMEOUT, in order to give the server a +chance to ready itself. By default, this timeout is 30 seconds. You +can shorten the time of delay using the -t "short,long" switch. For +example, to shorten the delay time to 2 seconds, use: +<PRE> + xpaaccess -c -t "2,2" ds9 +</PRE> +The first argument is the short delay value, and is ignored in this +operation. The second is the long delay timeout. + +<P> +Note also that the default xpaaccess method (no -c switch) does not +check access control (acls) but rather only checks whether the access +point is both registered with the xpans name server and provides the +specified type of access. In other words, the default xpaaccess could +return 'yes' when you might not actually have access. This mode also +always returns 'yes' for the xpans name server itself, regardless of +whether the name server is active. The -c (contact) switch, which +contacts the access point directly, can and does check the access +control (only for servers using version 2.1 and above) and also +returns the real status of xpans. + +<!-- =section xpaget SEE ALSO --> +<!-- =text See xpa(n) for a list of XPA help pages --> +<!-- =section xpaset SEE ALSO --> +<!-- =text See xpa(n) for a list of XPA help pages --> +<!-- =section xpainfo SEE ALSO --> +<!-- =text See xpa(n) for a list of XPA help pages --> +<!-- =section xpaaccess SEE ALSO --> +<!-- =text See xpa(n) for a list of XPA help pages --> +<!-- =stop --> + +<P> +<A HREF="./help.html">Go to XPA Help Index</A> + +<H5>Last updated: September 10, 2003</H5> +</BODY> +</HTML> |