diff options
Diffstat (limited to 'xpa/doc')
76 files changed, 0 insertions, 16645 deletions
diff --git a/xpa/doc/Makefile b/xpa/doc/Makefile deleted file mode 100644 index eda8931..0000000 --- a/xpa/doc/Makefile +++ /dev/null @@ -1,51 +0,0 @@ -# -# Makefile for misc programs, not good enough for their own directory -# - -RM = rm -RMFLAGS = -f -MV = mv -MVFLAGS = -f -CP = cp -CPFLAGS = -p - -MANDIR = ../man - -all: dirs files hardcopy - -dirs: - @(if [ ! -d ${MANDIR} ]; then \ - mkdir ${MANDIR}; \ - mkdir ${MANDIR}/man1 ${MANDIR}/man3 ${MANDIR}/mann; \ - fi) - -files: - @(for i in *.html; do \ - echo processing $$i; \ - ./html2man ../man < $$i; \ - done) - -hardcopy: - html2ps -C fb -d -g -n -u -W b -x 1 -o xpa.ps help.html - ps2pdf xpa.ps xpa.pdf - - -# NB: sman.conf must be copied to $HOME or else its not found ... -# we also have to figure out where swish-e is located and hardwire it -index: szlong - @(cd ..; MANPATH=`pwd`/man; export MANPATH; cd doc; \ - SW=`which swish-e`; \ - SZ_LONG=`./szlong`; \ - sed -e 's#@SW@#'$$SW'#g' < sman_conf.tmpl > $${HOME}/sman.conf; \ - sman-update --clearcache; \ - sman-update --verbose --index=./sman/xpa$${SZ_LONG}.index; \ - rm -f $${HOME}/sman.conf szlong) - -szlong: szlong.c - $(CC) $(CFLAGS) -o szlong szlong.c - -clean: - -$(RM) $(RMFLAGS) *.BAK *.bak *.o core errs ,* *~ *.a \ - foo* goo* tags TAGS html2ps.dbg - - diff --git a/xpa/doc/acl.html b/xpa/doc/acl.html deleted file mode 100644 index b1f458d..0000000 --- a/xpa/doc/acl.html +++ /dev/null @@ -1,137 +0,0 @@ -<!-- =defdoc xpaacl xpaacl n --> -<HTML> -<HEAD> -<TITLE>XPA Access Control</TITLE> -</HEAD> -<BODY> - -<!-- =section xpaacl NAME --> -<H2><A NAME="xpaacl">XPAAcl: Access Control for XPA Messaging</A></H2> - -<!-- =section xpaacl SYNOPSIS --> -<H2>Summary</H2> -<P> -XPA supports host-based access control for each XPA access point. You -can enable/disable access control using the XPA_ACL environment -variable. You can specify access to specific XPA access points for -specific machines using the XPA_DEFACL and XPA_ACLFILE environment -variables. By default, an XPA access point is accessible only to -processes running on the same machine (same as X Windows). - -<!-- =section xpaacl DESCRIPTION --> -<H2>Description</H2> -<P> -When INET sockets are in use (the default, as specified by the -<EM>XPA_METHOD</EM> environment variable), XPA supports a host-based -access control mechanism for individual access points. This mean that -access can be specified for get, set, or info operations for each -access point on a machine by machine basis. For LOCAL sockets, access -is restricted (by definition) to the host machine. - -<P> -XPA access control is enabled by default, but can be turned off by -setting the <EM>XPA_ACL</EM> environment variable to <EM>false</EM>. -In this case, any process can access any XPA server. - -<P> -Assuming that access control is turned on, the ACL for an individual -XPA access point is set up when that access point is registered -(although it can be changed later on; see below). This can be done in -one of two ways: - -Firstly, the <EM>XPA_ACLFILE</EM> environment variable can defined to -point to a file of access controls for individual access points. The format -of this file is: -<pre> - class:name ip acl -</pre> -The first argument is a template that specifies the class:name of the -access point covered by this ACL. See -<A HREF="./template.html">XPA Access Points and Templates</A> -for more information about xpa templates. - -<P> -The second argument is the IP address (in human-readable format) of -the machine which is being given access. This argument can be -<EM>*</EM> to match all IP addresses. It also can be <EM>$host</EM> -to match the IP address of the current host. - -<P> -The third argument is a string combination of <EM>s</EM>, <EM>g</EM>, -or <EM>i</EM> to allow <EM>xpaset</EM>, <EM>xpaget</EM>, or -<EM>xpainfo</EM> access respectively. The ACL argument can be -<EM>+</EM> to give <EM>sgi</EM> access or it can be <EM>-</EM> to turn -off all access. - -<P> -For example, -<PRE> - *:xpa1 somehost sg - *:xpa1 myhost + - * * g -</PRE> -will allow processes on the machine somehost to make xpaget and xpaset calls, -allow processes on myhost to make any call, and allow all other hosts to -make xpaget (but not xpaset) calls. - -Secondly, if the <EM>XPA_ACLFILE</EM> does not exist, then a single -default value for all access points can be specified using the -<EM>XPA_DEFACL</EM> environment variable. The default value for this -variable is: -<PRE> - #define XPA_DEFACL "*:* $host +" -</PRE> -meaning that all access points are fully accessible to all processes -on the current host. Thus, in the absence of any ACL environment variables, -processes on the current host have full access to all access points -created on that host. This parallels the X11 xhost mechanism. - -<P> -Access to an individual XPA access point can be changed using the -acl -parameter for that access point. For example: -<PRE> - xpaset -p xpa1 -acl "somehost -" -</PRE> -will turn off all access control for somehost to the xpa1 access point, while: -<PRE> - xpaset -p XPA:xpa1 -acl "beberly gs" -</PRE> -will give beberly xpaget and xpaset access to the access point whose -class is XPA and whose name is xpa1. -<P> -Similarly, the current ACL for a given access point can be retrieved using: -<PRE> - xpaget xpa1 -acl -</PRE> -Of course, you must have xpaget access to this XPA access point to -retrieve its ACL. - -<P> -Note that the XPA access points registered in the <EM>xpans</EM> -program also behave according to the ACL rules. That is, you cannot -use xpaget to view the access points registered with xpans unless -you have the proper ACL. - -<P> -Note also when a client request is made to an XPA server, the access -control is checked when the initial connection is established. This -access in effect at this time remains in effect so long as the client -connection is maintained, regardless of whether the access fro that -XPA is changed later on. - -<P> -We recognize that host-based access control is only relatively secure -and will consider more stringent security (e.g., private key) in the -future if the community requires such support. - -<!-- =section xpaacl 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> diff --git a/xpa/doc/changelog.html b/xpa/doc/changelog.html deleted file mode 100644 index c7b146a..0000000 --- a/xpa/doc/changelog.html +++ /dev/null @@ -1,806 +0,0 @@ -<HTML> -<HEAD> -<TITLE>XPA ChangeLog</TITLE> -</HEAD> -<BODY> -<H2>XPA ChangeLog</H2> - -<P> -This ChangeLog covers the XPA 2 implementation. It will be updated -as we continue to develop and improve XPA. The up-to-date version can be -found <A HREF="http://hea-www.harvard.edu/RD/xpa/changelog.html">here</A>. - -<H2> Public Release 2.1.16 (TBD)</H2> -<ul> -<li> Ensure that mingw utilizes Windows error codes instead of *nix codes -</ul> - -<H2> Public Release 2.1.15 (July 23, 2013)</H2> -<ul> -<p> -<li> Added support for large data transfers -<P> -<li> XPAGet and XPASet now pass size_t instead of int for lengths -<p> -<li> Send and receive callbacks now pass size_t instead of int for lengths -<p> -<li> Port to mingw (Windows) -</ul> - - -<H2> Public Release 2.1.14 (June 7, 2012)</H2> -<ul> -<P> -<li> Fixed several memory leaks in the Tcl wrappers (tcl.c). -<P> -<li> Use Tcl stubs library for linking shared Tcl, if available. -</ul> - -<H2> Public Release 2.1.13 (April 14, 2011)</H2> -<ul> -<P> -<li> An atexit handler is no longer installed automatically (it crashes -Tcl 8.5.8 applications). Call XPAAtExit(void) to install the handler. -<p> -<li> Removed permission checking from Find() on cygwin systems. This was broken -by Windows 7. -<p> -<li> Removed addition of -no-cpp-precomp flag from gcc 4.2 and beyond (Mac). -</ul> - -<H2> Public Release 2.1.12 (January 26, 2010)</H2> -<ul> -<p> -<li> Added XPA_HOST environment variable to allow users to specify -the hostname (and hence, ip) component of the INET method id. This is -useful, for example, if you want to register an access point using a -VPN-generated IP instead of the canonical IP. -<p> -<li> Fix typo in Tcl binding to xpainfo causing a crash after 2 invocations. -</ul> - -<H2> Public Release 2.1.11 (December 7, 2009)</H2> -<ul> -<p> -<li> Generalized XPANSKeepAlive() to send messages to xpans, proxy xpans, or -both. The default is to send just to proxies (e.g. chandra-ed). -<p> -<li> Changed XPANSKeepAlive() to send an in-band new-line char to -xpans, changed xpans to handle an in-band new-line as a keep-alive -message. Necessitated by Cisco routers that clear the URG flag in -a TCP packet, breaking OOB data transfer for the whole Internet, as -well as the OOB-based keep-alive implemented in xpans. -<p> -<li> In xpans, print warning when the keep-alive option switch is used. -<p> -<li> Port to mingw (thanks to B.Schoenhammer) -<p> -<li> Change OOB character sent by xpans keepalive to a space, trying to working around cisco routers that force OOB data into the inbound stream. -<p> -<li> fix gcc fprintf warning in xpans.c -</ul> - -<H2> Public Release 2.1.10 (September 1, 2009)</H2> -<ul> -<p> -<li> Update mklib and configure.ac to support 64-bit builds on Macs. -<p> -<li> Fixed bug in XPAAccess() in which the returned names could have an extra -(bogus) character when the target is an explicit ip:port or local socket file. -<p> -<li> Add setjmp/longjmp support to xalloc. -<p> -<li> Add XPASaveJmp(void *env) as a high-level interface to xalloc_savejmp(); -</ul> - -<H2> Internal Release 2.1.9</H2> -<ul> -<p> -<li> Fixed a bug that prevented an access point starting with a number -from being recognized peoperly. NB: a pure number still signifies a -port on the current machine. Also num:num signifies ip:port, where ip -can be a pure hex value or the canonical form vvv.xxx.yyy.zzz. -<p> -<li> Modified internal Launch() routine to use posix_spawn(), if necessary. -This is required for OS X 10.5 (leopard), which frowns upon use of fork() -and exec(). Also modified zprocess routines to use Launch(). -<p> -<li> Added XPASetFree(xpa, void (*myfree)(void *)) routine to allow callbacks -to specify a free routine other than malloc free (e.g. Perl garbage collection). -<p> -<li> XPACmdAdd() now checks to ensure that it was passed an XPA struct created -by XPACmdNew(). -<p> -<li> Change launch.h to xlaunch.h to avoid conflict with OS X. -</ul> - -<H2> Public Release 2.1.8 (1 November 2007)</H2> -<ul> -<p> -<li> A public release to complete current XPA development work. -</ul> - -<H2> Patch Release 2.1.7b[1,2] (Feb 22, 2006; March 8, 2007)</H2> -<ul> - -<p> -<li> Added a convenience null to the end of the buffers returned by XPAGet. - -<p> -<li> Added code to avoid calling atexit routine if a fork'ed child -calls exit() instead of _exit(). - -<p> -<li> Added XPA_CLIENT_DOXPA environment variable to turn off client -processing of xpa server requests. - -<p> -<li> Added --version to xpaset, xpaget, xpainfo, xpaaccess, xpans to -display XPA version and exit. - -<p> -<li> Added support for integrating XPA into a Gtk loop. - -<p> -<li> xpaaccess now returns its answer in the error code as well as to stdout -(without the -n switch, it returns 1 for a match, with the -n switch, -the number of matches is returned). - -<p> -<li> Fixed bug which prevented xpans from being started up automatically -by an xpa server if its pathname contained a space character. - -<p> -<li> Fixed bug in MINGW port of xpans in which an XPA server that -terminated via an interrupt was not being properly removed from the -list of registered access points. - -<p> -<li> Added XPA_LOGNAME to override LOGNAME when registering username - -<p> -<li> Upgraded swish-e indexing code to 2.4.5. - -</ul> - -<H2> Patch Release 2.1.6 (4 May 2005)</H2> -<ul> - -<p> -<li> Added -P switch to xpans to enable experimental proxy support -(default is disabled). An argument of 1 processes proxy requests in -the same thread as xpans requests, while an argument of 2 processes -proxy requests in a separate thread. (The latter is recommended to -avoid xpans timeouts, since xpa callback processing can take a long -time.) - -<p> -<li> Added ability to build shared libraries (done automatically with -configure --enable-shared) with compilers other than gcc. - -<p> -<li> Made yet another attempt to build shared libraries under OS X. - -<p> -<li> Fixed a server bug in Tcl support under Windows (introduced early -in 2.1.6) which caused an occasional SEGV. - -<p> -<li> Fixed race condition in cases where 2 or more servers makes client calls -to one another. - -<p> -<li> Fixed bug in the XPA handler routine in which an access point was -turned off if an error occurred in that routine (as opposed to the -user-defined callback routine). - -<p> -<li> Fixed race condition when "ack=false" flag (or -n) is used with XPASet() -(or xpaset). - -<p> -<li> Added defensive code to XPA handler to ensure that the passed XPA record -is valid. - -<p> -<li> Tcl/XPA servers such as ds9 were not turning off select() on the -xpa channels inside an xpa callback, as required. This is now fixed. - -<p> -<li> Added timestamps to most server and client error messages if the -XPA_TIMESTAMP_ERRORS variable is set. This is useful when XPA errors are -being logged in an error log (e.g. Web/CGI use). - -<p> -<li> Generated PostScript and PDF versions of the help pages. - -<p> -<li> Moved OPTIONS section before (often-lengthy) DESCRIPTION section in -man pages. - -<p> -<li> All memory allocation now performs error checking on the result. - -<p> -<li> Removed some compiler warnings that surfaced when using gcc -O2. - -<p> -<li> Updated configure.ac to better support Tcl in Panther with Apple -Frameworks. - -</ul> - -<H2> Patch Release 2.1.5 (12 January 2004)</H2> -<ul> - -<p> -<li> Fixed bug in XPAPoll(). Erroneously, no requests were being -processed when maxreq==0. Now, all pending events are processed, as -per the documentation. - -<p> -<li> Added ack=false to XPAInfo() (and corresponding -n to xpainfo) -so that client does not wait for a response from the server. This is -essential in cases where XPA servers wish to send info messages to -one another without causing a race condition. - -<p> -<li> Generated man pages from the html pages. These are installed -automatically at build time. - -<p> -<li> The xpans program with Unix sockets now uses a lock file to signal -that it is running, in order to avoid a potential (but rare) race -condition at startup. - -<p> -<li> Code that calls Unix-type bind() now manipulate umask() to ensure that -all users have write permissions to the socket file (OS X apparently uses -these permissions while previous platforms ignore them). - -<p> -<li> Configure now checks for socklen_t type (OS X does not define it). - -<p> -<li> Added an atexit function to run XPAFree. The aim here is to delete Unix -socket files on exiting. - -<p> -<li> Under Windows, the Tcl event-handling code now blocks for 1/1000 of a -second instead of not blocking at all (which inadvertently used 100% of cpu). - -<p> -<li> Upgraded Tcl/Tk support to 8.4. - -<p> -<li> Made another round of checks was made through all instances of -strcat, strcpy, etc. to look for potential buffer overflows. Changed -all instances of sprintf() to snprintf(). - -<p> -<li> Class and name designators are now limited to 1024 characters, for -no particular reason. - -<p> -<li> The obsolete $SAORD_BIN variable was being added to the path when -searching for xpans. This is no longer the case. - -<p> -<li> Fixed non-ANSI compiler errors in both xpa.c and xpans.c. - -<p> -<li> Fixed minor problems to support compilation with g++. - -<p> -<li> Ported to Intel icc and gcc 3.3 compilers. - -<p> -<li> Upgraded autoconf to 2.57. Included in this upgrade is a change that -makes gcc the default compiler (use "configure CC=cc" to change this). -Also, by default, the Tcl shared object is no longer automatically built -if the Tcl libraries are used. Use the --enable-tclshlib switch in -configure to enable this feature. - -<p> -<li> Changed license from public domain to GNU GPL. - -</ul> - -<H2> Patch Release 2.1.4 (24 March 2003)</H2> -<ul> - -<p> -<li> Made inet method unique, even when hosts are behind a firewall using -the same ports (on different local machines). - -<p> -<li> The initial connection from an xpa server to a local xpans now is -controlled by a timeout (default 5 sec, controlled by XPA_CONNECT_TIMEOUT -variable). This should prevent a hang on connect() if the network -is not set up correctly. - -<p> -<li> Fixed rare race condition when an XPA server callback performed its own -XPAGet or XPASet call to another XPA server. - -<p> -<li> Use POSIX O_NONBLOCK for non-blocking I/O in fcntl call if it -exists, instead of O_NDELAY. - -</ul> - -<H2> Patch Release 2.1.3 (26 September 2002)</H2> -<ul> - -<p> -<li> Added -k [sec] switch to xpans to support sending one-byte keepalive -messages from xpans to registered xpa servers. - -<p> -<li> Added XPANSKeepAlive routine (and Tcl equivalent) to allow -xpa servers to send a one-byte keepalive message to xpans. - -</ul> - -<H2> Patch Release 2.1.2 (18 July 2002)</H2> -<ul> - -<p> -<li> The "-help" reserved command now also displays the XPA version, if -no explicit sub-commands are specified. - -<p> -<li> Change internal state of xpans proxy to save ip:port value of a -server behind a NAT firewall. This is required to give some hope of -distinguishing multiple instances of ds9 running behind NAT. - -</ul> - -<H2> Patch Release 2.1.1 (20 June 2002)</H2> -<ul> - -<p> -<li> Added a version check between xpans and an access point, -performed when it gets registered by an XPA server. If the server -has a version greater than the xpans version, a warning is issued by -both programs. - -<p> -<li> Added a boolean XPA_NSREGISTER environment variable to allow an -XPA server to skip xpans registration. The default is to register with -the name server. If set to "false", the access point still is set up -but it is not registered with an xpans. It can be registered later on -(using -remote or -proxy, for example). - -<p> -<li> Fixed bug in which xpans was still listening on any interface when -XPA_METHOD was localhost (instead of just listening on localhost). - -</ul> - -<H2> Public Release 2.1.0 (22 April 2002)</H2> - -<P> -New features include: - -<ul> -<p> -<li> Support for proxy access to XPA servers (e.g. ds9) situated -behind a firewall (useful for NVO-type applications). - -<p> -<li> Improved support for allowing remote machines access rights to the -XPA access points (useful for NVO-type applications). - -<p> -<li> Ability for XPAAccess() routine and xpaaccess program to contact XPA - directly. - -<p> -<li> Support for a clipboard access point that allows clients to store ASCII -state information in an XPA-enabled server. - -<p> -<li> Improved support for Windows platform, as well as new support for Mac OSX. -</ul> - -<H2> Pre-Release 2.1.0e (2 April 2002)</H2> -<UL> - -<P> -<LI> Removed the environment variable generated by each XPA access -point (of the form XPA_name=method). The putenv() call was causing ds9 -to crash under both Linux and LinuxPPC during a socket operation. We -suspect a bug in putenv but cannot prove it and this feature is not -essential, so ... - -</UL> - -<H2> Pre-Release 2.1.0e (1 April 2002)</H2> -<UL> - -<P> -<LI> Fixed an uninitialized variable in xpamb which prevented it from -working at all on some systems. - -<P> -<LI> Changed xpamb switch from "-add" to "-data" (to store named data). - -<P> -<LI> Changed how xpamb works with xpaget so that xpamb can return data -from XPA access points as well as from stored data. (Previous versions -only returned stored data.) Now, you can retrieve stored data -explicitly using the -info and/or -data switches. For example: -<PRE> - xpaget xpamb -info foo -</PRE> -will return info about the previously stored data named foo. If -neither switch is present, then the name is assumed to be an XPA access -point. -</UL> - -<H2> Pre-Release 2.1.0e (25 March 2002)</H2> -<UL> - -<P> -<LI> Changed symbol for default port from "*" to "$port" to avoid -a syntactical conflict between class:* and machine:* when processing an -XPA access point class:name specification. Thus, the default inet -method now is '$host:$port' instead of '$host:*'. - -</UL> - -<H2> Pre-Release 2.1.0e (19 March 2002)</H2> -<UL> - -<P> -<LI> Removed timeout check when reading data (in clients using xpaget -and servers filling the data buffer). We have more and more cases -where we need to wait a long time to retrieve data (e.g., slow -networks or receiving data being compressed on the fly). - -<P> -<LI> Moved call to sigaction(SIGCHLD,...) out of XPAOpen(), so that it -is only executed when needed by XPAGet()/XPASet() routines called from -within xpans/proxy. But then changed logic to use a double fork() instead -of sigaction() to prevent zombies (Stevens Adv. Programming p 202). - -<P> -<LI> Each XPA access point now generates an environment variable of the -form XPA_name=method so that children can communicate with the parent access -point more easily. - -<P> -<LI> Added version option to Tcl xparec: -<PRE> - if [catch { xparec "" version } version] { - puts "pre-2.1.0e" - } else { - puts [split $version .] - } -</PRE> -to help differentiate between XPA versions within Tcl code. - -</UL> - -<H2> Pre-Release 2.1.0e (14 February 2002)</H2> -<UL> -<P> -<LI> Fixed client handling of out-of-sync messages. -</UL> - -<H2> Pre-Release 2.1.0e (11 February 2002)</H2> -<UL> - -<P> -<LI> Fixed client.c/xopen() so that it does not open an extra socket. - -<P> -<LI> Fixed xpainfo/xopen() to prevent client from hanging waiting for ack. - -<P> -<LI> Modified stest to generate xpaaccess points xpa, xpa1, c_xpa, and -i_xpa (or more generally, <name>, <name>1, c_<name>, i<name>) to allow -more flexible testing of templates. Also added -a for testing XPAAccess(). - -</UL> - -<H2> Beta Release 2.1.0b10 (31 January 2002)</H2> -<UL> - -<P> -<LI> Added support for Mac OSX/Darwin to configure file. - -</UL> - -<H2> Beta Release 2.1.0b9 (26 January 2002)</H2> -<UL> - -<P> -<LI> Fixed bug in client library that caused XPAAccess() call to hang. - -</UL> - -<H2> Beta Release 2.1.0b8 (4 January 2002)</H2> -<UL> - -<P> -<LI> Made modifications to Makefile.in to make releases easier. - -<P> -<LI> Added instructions to Makefile.in so that xpa.h will always have -correct #defines for XPA_VERSION, XPA_MAJOR_VERSION, XPA_MINOR_VERSION, -and XPA_PATCH_LEVEL. - -</UL> - -<H2> Beta Release 2.1.0b7 (21 December 2001)</H2> -<UL> - -<P> -<LI> Added -proxy switch to -remote sub-command to allow remote access -through a firewall, using xpans as a proxy server. The support for proxy -processing required a change to the client/server protocol. This means -that new xpa servers will not work with old xpa clients (although new -xpa clients will work with old xpa servers). For details about proxy -firewall support, see http://hea-www.harvard.edu/RD/xpa/inet.html. - -<P> -<LI> Fixed Tcl support for XPA under Windows/Cygwin by re-writing -the code used to add XPA to the Tcl event loop. This fix makes ds9 -support for XPA much more stable under Windows. - -<P> -<LI> Added the shutdown() call to XPA under Cygwin/Windows before -closing send() sockets. It appears that a Cygwin recv() socket call -does not always sense when the other end closes the socket using -close(). This measure must be considered a hack, since the actual -problem was never resolved. - -<P> -<LI> Added code to protect accept() and select() calls from interrupts. - -<P> -<LI> Extended syntax of the environment variable XPA_NSINET to: -<PRE> - setenv XPA_NSINET host:port[,port[,port]] -</PRE> -to allow specification of the XPA access point port for xpans, -as well as the proxy data port. - -<P> -<LI> Modified xpans log file so that it contains the xpaset commands -required to reconnect with xpa servers. - -<P> -<LI> xpans now deletes its Unix socket files. - -</UL> - -<H2> Beta Release 2.1.0b6 (29 October 2001)</H2> -<UL> - -<P> -<LI> Implemented a reserve public access point named -clipboard so -that clients can store ASCII state information on any number of named -clipboards. Clipboards of the same name created by clients on -different machines are kept separate. The syntax for creating a -clipboard is: -<PRE> - [data] | xpaset [server] -clipboard add|append [clipboard_name] - xpaset -p [server] -clipboard delete [clipboard_name] - xpaget [server] -clipboard [clipboard_name] -</PRE> -Use "add" to create a new clipboard or replace the contents of an existing -one. Use "append" to append to an existing clipboard. - -</UL> - -<H2> Beta Release 2.1.0b5 (22 October 2001)</H2> -<UL> - -<P> -<LI> Use FD_SETSIZE instead of getdtablesize() to determine how many files -to check during select(); - -<P> -<LI> Under Cygwin, the launch() routine now uses the Cygwin spawnvp() -instead of fork()/exec() where possible (i.e., if no stdfiles are -being redirected). This is recommended by Cygwin's (skimpy) on-line -documentation and seems to fix the problems ds9 had when starting xpans -automatically. - -<P> -<LI> Added error check to select() call in xpans. - -</UL> - -<H2> Beta Release 2.1.0b4 (24 September 2001)</H2> -<UL> - -<P> -<LI> The launch() now can return an error code if the execv() system -call fails (something system() does not do). - -<P> -<LI> INET socket calls between xpa clients and servers now will use -localhost if they are on the same machine. This protects against -Linux systems where the hostname is hardwired (wrongly) in a DHCP -environment. - -</UL> - -<H2> Beta Release 2.1.0b3 (6 September 2001)</H2> -<UL> - -<P> -<LI> Modified xpans so that, in the case of a firewall, it tries to -correct the specified ip:port by matching against the ip found in -the socket packet at accept() time. - -<P> -<LI> Replaced system() call used to start xpans automatically with -a special launch() call, which performs execvp() directly without going -through sh. (launch() works under DOS and has fewer security problems.) - -<P> -<LI> Fixed bug in xpans in which its xpa port was always being set to 14286. - -</UL> - -<H2> Beta Release 2.1.0b2 (17 August 2001)</H2> -<UL> - -<P> -<LI>Added support for -remote command, which registers the access -point in the XPA name server of the specified remote server, and gives -the remote server access rights to the access point. This is used, for -example, to give data servers xpa access to ds9 so that data can be -sent to ds9 as a result of a CGI-based Web query. - -<P> -<LI>Reserved commands (except "-help" and "-version") now can only be -executed on the machine on which the xpa service is running (not -through -remote servers). - -<P> -<LI>Fixed bug in xpans in which a bad telnet command could hang the program. - -<P> -<LI>Added -s [security file] to xpans to allow logging of all external -connections. - -</UL> - -<H2> Beta Release 2.1.0b1 (6 August 2001)</H2> -<UL> -<P> -<LI> The xpaaccess client program and XPAAccess() client subroutine -were modified so that an access-type query can directly contact the -xpa servers matching the requested xpa template, instead of just -querying the name server for registered access points. This avoid the -race condition in which an access point is registered but is not yet -available, perhaps because the server has not yet entered its event -loop. Note that the calling sequence of the XPAAccess() routine was -changed to return all matching access points and their availability -status (instead of just returning the number of registered access -points). Because of this, we are calling this a minor release instead -of a patch. - -<P> -<LI> Added support for XPA_PORT and XPA_PORTFILE environment variables -to allow specification of the port to be used by the command channel -(and data channel, if an optional second port is specified) for a given -access point. - -<P> -<LI> Added -m switch to xpaget, xpaset, xpainfo, xpaaccess to allow -override of the XPA_METHOD environment variable. - -<P> -<LI> Changed the default name of the ACL file from xpa.acl to acls.xpa. - -<P> -<LI> Fixed bug in which it was not possible to send a "set ACL" -command to an XPA server which did not have a receive callback (i.e., -did not allow xpaset). The xpans program is one such server. It now is -possible to set the ACL on xpans. - -<P> -<LI> We have discovered that Tcl support for datachan and cmdchan is -broken under Windows due to an unexplained incompatibility between -Cygwin sockets and Win32 sockets. We therefore have removed datachan -and cmdchan from the Windows/Tcl support until further notice. - -<P> -<LI> Extended the behavior of the XPA_DEFACL environment variable so that -it can support more than one acl, using a list of semi-colon delimited -controls such as: setenv XPA_DEFACL '*:* $host +; *:foo1 otherhost +'. - -<P> -<LI> Fixed bug in which the class:name specifier "*:*" was erroneously -trying to access the xpans name server, instead of accessing all -access points. - -<P> -<LI> Support TMPDIR and TMP environment variables as well as XPA_TMPDIR. - -</UL> - -<H2> Patch Release 2.0.5 (10 November 2000)</H2> -<UL> -<P> -<LI> Added support for Tcl on Windows where there is no select()-based -event loop (i.e., where there is no Tcl_CreateFileHandler call in Tcl) -<P> -<LI> Minor fixes in Makefile for installing on Windows -<P> -<LI> Minor compiler fixes from gcc -Wall. -</UL> - -<H2> Patch Release 2.0.4 (20 September 2000) </H2> -<UL> -<P> -<LI> Removed extraneous include of varargs.h from find.c. -<P> -<LI> Ported to SGI C compiler, which caught lots of unused variables, etc. -<P> -<LI> Ported to Cygwin/Windows, which required that we change socket read() -and write() calls to recv() and send() respectively. Also had to ensure that -we only did socket I/O on sockets (no fileio). -</UL> - -<H2> Patch Release 2.0.3 (15 June 2000) </H2> -<UL> -<P> -<LI> Fixed the client XPASet() and XPASetFd() calls to handle the specified -max number of connections (they were ignoring this argument, leading to -memory overwrites). -<P> -<LI> Fixed Makefile.in so that CFLAGS and LDFLAGS are not hard-wired values. -<P> -<LI> Fixed word.h to load malloc.h and stdlib.h only if they exist. -<P> -<LI> Documentation fixes to programs.html (in xpaaccess) and client.html -(XPANSLookup). -<P> -<LI> Added explicit typecast to strlen() argument to MAX #define in -XPAClientStart (strlen() is unsigned in Linux, which can break MAX). -<P> -<LI> Removed bogus Imakefile from directory. -<P> -<LI> Changed directory name to include patch level (i.e., xpa-2.0.3). -</UL> - -<H2> Patch Release 2.0.2 (9 September 1999)</H2> -<UL> -<P> -<LI> Fixed server mode (-s) in the xpaset program by properly cleaning up -the input buffers (sending commands and data in server mode was broken). -</UL> - -<H2> Patch Release 2.0.1 (6 August 1999)</H2> -<UL> -<P> -<LI> Fixed the Tcl binding code (tcl.c) for 64-bit machines (Dec Alpha) -(erroneously used %x instead of %p when converting pointers to ASCII). -<P> -<LI> Got rid of a few compiler warnings on 64-bit machines (a few are -unavoidable since we must cast int to void * and back when passing around -client data). -</UL> - -<H2> Public Release 2.0 (27 May 1999)</H2> -<UL> -<P> -<LI> "a new day with no mistakes ... yet" -</UL> - -<HR> -<P> -<A HREF="./help.html">Index to the XPA Help Pages</A> - -<HR> -<H5>Last updated: 22 April 2002</H5> -</BODY> -</HTML> diff --git a/xpa/doc/changes.html b/xpa/doc/changes.html deleted file mode 100644 index 8488985..0000000 --- a/xpa/doc/changes.html +++ /dev/null @@ -1,69 +0,0 @@ -<!-- =defdoc xpachanges xpachanges 1 --> -<HTML> -<HEAD> -<TITLE>Changes For Users from XPA 1.0 and 2.0</TITLE> -</HEAD> -<BODY> - -<!-- =section xpachanges NAME --> -<H2><A NAME="xpachanges">XPA Changes: Changes For Users from XPA 1.0 and 2.0</A></H2> - -<!-- =section xpachanges SYNOPSIS --> -<H2>Summary</H2> -<P> -This document describes changes that will affect users who migrate -from XPA 1.0 to XPA 2.0. - -<!-- =section xpachanges DESCRIPTION --> -<H2>Description</H2> -<P> -There have been a few changes that affect users who upgrade XPA -from version 1.0 to version 2.0. These changes are detailed below. -<UL> -<P> -<LI>XPA commands no longer have a resolver routine (this is open to -negotiations, but we decided the idea was dumb). For the SAOtng -program, this means that you must explicitly specify the access -point, i.e.,: -<PRE> - cat foo.fits | xpaset SAOtng fits -</PRE> - -<P> -instead of: -<PRE> - cat foo.fits | xpaset SAOtng -</PRE> -<P> -<LI>By default, xpaset, xpaget, etc. now wait for the server callback to -complete; i.e., the old -W is implied (and the switch is ignored). -This allows support for better error handling. If you want xpaset, etc. -to return before the callback is complete, use -n switch: -<PRE> - echo "file foo.fits" | xpaset -n SAOtng -</PRE> -<P> -<LI>The old -w switch in xpaset and xpaget is no longer necessary (and is -ignored), since you can have more than one process communicating with -an xpa access point at one time. - -<P> -<LI>The new -p switch on xpaset means you need not read from stdout: -<PRE> - xpaset -p SAOtng colormap I8 -</PRE> -<P> -will send the paramlist to the SAOtng callback without reading from stdin. - -</UL> - -<!-- =section xpachanges 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> diff --git a/xpa/doc/client.html b/xpa/doc/client.html deleted file mode 100644 index 5648d85..0000000 --- a/xpa/doc/client.html +++ /dev/null @@ -1,898 +0,0 @@ -<!-- =defdoc xpaclient xpaclient 3 --> -<HTML> -<HEAD> -<TITLE>XPA Client API</TITLE> -</HEAD> -<BODY> - -<!-- =section xpaclient NAME --> -<H2><A NAME="xpaclient">XPAClient: The XPA Client-side Programming Interface</A></H2> - -<!-- =section xpaclient SYNOPSIS --> -<H2>Summary</H2> -A description of the XPA client-side programming interface. - -<!-- =section xpaclient DESCRIPTION --> -<H2><A NAME="intro">Introduction to XPA Client Programming</H2></A> -<P> -Sending/receiving data to/from an XPA access point is easy: you -generally only need to call the XPAGet() or XPASet() subroutines. -<PRE> - #include <xpa.h> - - int <A HREF="./client.html#xpaget">XPAGet</A>(XPA xpa, - char *template, char *paramlist, char *mode, - char **bufs, size_t *lens, char **names, char **messages, int n); - - int <A HREF="./client.html#xpaset">XPASet</A>(XPA xpa, - char *template, char *paramlist, char *mode, - char *buf, size_t len, char **names, char **messages, int n); - - int <A HREF="./client.html#xpainfo">XPAInfo</A>(XPA xpa, - char *template, char *paramlist, char *mode, - char **names, char **messages, int n); - - int <A HREF="./client.html#xpaaccess">XPAAccess</A>(XPA xpa, - char *template, char *paramlist, char *mode, - char **names, char **messages, int n); - - int <A HREF="./client.html#xpagetfd">XPAGetFd</A>(XPA xpa, - char *template, char *paramlist, char *mode, - int *fds, char **names, char **messages, int n); - - int <A HREF="./client.html#xpasetfd">XPASetFd</A>(XPA xpa, - char *template, char *paramlist, char *mode, - int fd, char **names, char **messages, int n); - - XPA <A HREF="./client.html#xpaopen">XPAOpen</A>(char *mode); - - void <A HREF="./client.html#xpaclose">XPAClose</A>(XPA xpa); - - int <A HREF="./client.html#xpanslookup">XPANSLookup</A>(XPA xpa, - char *template, char *type, - char ***classes, char ***names, char ***methods, char ***infos); -</PRE> - -<H2>Introduction</H2> - -To use the XPA application programming interface, a software developer -generally will include the xpa.h definitions file: -<PRE> - #include <xpa.h> -</PRE> -in the software module that defines or accesses an XPA access point and -then will link against the libxpa.a library: -<PRE> - gcc -o foo foo.c libxpa.a -</PRE> -XPA has been compiled using both C and C++ compilers. -<P> -Client communication with XPA public access points generally is -accomplished using XPAGet() or XPASet() within a program (or xpaget -and xpaset at the command line). Both routines require specification -of the name of the access point. If a <A HREF="./template.html">template</A> -is used to specify the access point name (e.g., "ds9*"), then -communication will take place with all servers matching that template. - -<!-- =defdoc xpaget xpaget 3 --> - -<!-- =section xpaget NAME --> -<H2><A NAME="xpaget">XPAGet: retrieve data from one or more XPA servers</A></H2> - -<!-- =section xpaget SYNOPSIS --> -<B> -<PRE> - #include <xpa.h> - - int XPAGet(XPA xpa, - char *template, char *paramlist, char *mode, - char **bufs, size_t *lens, char **names, char **messages, - int n); -</PRE> -</B> - -<!-- =section xpaget DESCRIPTION --> -<P> -Retrieve data from one or more XPA servers whose class:name identifier -matches the specified template. - -<P> -A -<A HREF="./template.html">template</A> -of the form "class1:name1" is sent to the -XPA name server, which returns a list of at most n matching XPA -servers. A connection is established with each of these servers and -the paramlist string is passed to the server as the data transfer -request is initiated. If an XPA struct is passed to the call, then the -persistent connections are updated as described above. Otherwise, -temporary connections are made to the servers (which will be closed -when the call completes). - -<P> -The XPAGet() routine then retrieves data from at most n XPA servers, -places these data into n allocated buffers and places the buffer -pointers in the bufs array. The length of each buffer is stored in the -lens array. A string containing the class:name and ip:port is stored -in the name array. If a given server returned an error or the server -callback sends a message back to the client, then the message will be -stored in the associated element of the messages array. NB: if -specified, the name and messages arrays must be of size n or greater. - -<p> -The returned message string will be of the form: -<PRE> - XPA$ERROR error-message (class:name ip:port) -</PRE> -or -<PRE> - XPA$MESSAGE message (class:name ip:port) -</PRE> -<P> -Note that when there is an error stored in an messages entry, the -corresponding bufs and lens entry may or may not be NULL and 0 -(respectively), depending on the particularities of the server. - -<P> -The return value will contain the actual number of servers that were -processed. This value thus will hold the number of valid entries in -the bufs, lens, names, and messages arrays, and can be used to loop -through these arrays. In names and/or messages is NULL, no information is -passed back in that array. - -<P> -The bufs, names, and messages arrays should be freed upon completion (if -they are not NULL); - -<P> -The mode string is of the form: "key1=value1,key2=value2,..." -The following keywords are recognized: -<PRE> - key value default explanation - ------ -------- -------- ----------- - ack true/false true if false, don't wait for ack from server (after callback completes) - doxpa true/false true client processes xpa requests -</PRE> -<P> -The ack keyword is not very useful, since the server completes the callback -in order to return the data anyway. It is here for completion (and perhaps -for future usefulness). - -<p> -Normally, an XPA client will process incoming XPA server requests -while awaiting the completion of the client request. Setting this -variable to "false" will prevent XPA server requests from being -processed by the client. - -<P> -<B>Example:</B> -<PRE> - #include <xpa.h> - - #define NXPA 10 - int i, got; - size_t lens[NXPA]; - char *bufs[NXPA]; - char *names[NXPA]; - char *messages[NXPA]; - got = XPAGet(NULL, "ds9", "file", NULL, bufs, lens, names, messages, - NXPA); - for(i=0; i<got; i++){ - if( messages[i] == NULL ){ - /* process buf contents */ - ProcessImage(bufs[i], ...); - free(bufs[i]); - } - else{ - /* error processing */ - fprintf(stderr, "ERROR: %s (%s)\n", messages[i], names[i]); - } - if( names[i] ) - free(names[i]); - if( messages[i] ) - free(messages[i]); - } -</PRE> - -<!-- =defdoc xpaset xpaset 3 --> - -<!-- =section xpaset NAME --> -<H2><A NAME="xpaset">XPASet: send data to one or more XPA servers</A></H2> - -<!-- =section xpaset SYNOPSIS --> -<B> -<PRE> - #include <xpa.h> - - int XPASet(XPA xpa, - char *template, char *paramlist, char *mode, - char *buf, size_t len, char **names, char **messages, - int n); -</PRE> -</B> - -<!-- =section xpaset DESCRIPTION --> -<P> -Send data to one or more XPA servers whose class:name identifier -matches the specified template. - -<P> -A -<A HREF="./template.html">template</A> -of the form "class1:name1" is sent to the -XPA name server, which returns a list of at most n matching XPA -servers. A connection is established with each of these servers and -the paramlist string is passed to the server as the data transfer -request is initiated. If an XPA struct is passed to the call, the -persistent connections are updated as described above. Otherwise, -temporary connections are made to the servers (which will be closed -when the call completes). - -<P> -The XPASet() routine transfers data from buf to the XPA servers. -The length of buf (in bytes) should be placed in the len variable. - -<P> -A string containing the class:name and ip:port of each of these server -is returned in the name array. If a given server returned an error or -the server callback sends a message back to the client, then the -message will be stored in the associated element of the messages -array. NB: if specified, the name and messages arrays must be of size -n or greater. - -<p> -The returned message string will be of the form: - -<PRE> - XPA$ERROR [error] (class:name ip:port) -</PRE> -or -<PRE> - XPA$MESSAGE [message] (class:name ip:port) -</PRE> -<P> -The return value will contain the actual number of servers that were -processed. This value thus will hold the number of valid entries in -the names and messages arrays, and can be used to loop through these -arrays. In names and/or messages is NULL, no information is passed back -in that particular array. - -<P> -The mode string is of the form: "key1=value1,key2=value2,..." -The following keywords are recognized: -<PRE> - key value default explanation - ------ -------- -------- ----------- - ack true/false true if false, don't wait for ack from server (after callback completes) - verify true/false false send buf from XPASet[Fd] to stdout - doxpa true/false true client processes xpa requests -</PRE> -<P> -The ack keyword is useful in cases where one does not want to wait for -the server to complete, e.g. if a lot of processing needs to be done -by the server on the passed data or when the success of the server -operation is not relevant to the client. - -<p> -Normally, an XPA client will process incoming XPA server requests -while awaiting the completion of the client request. Setting this -variable to "false" will prevent XPA server requests from being -processed by the client. - -<P> -<B>Example:</B> -<PRE> - #include <xpa.h> - - #define NXPA 10 - int i, got; - size_t len; - char *buf; - char *names[NXPA]; - char *messages[NXPA]; - ... - [fill buf with data and set len to the length, in bytes, of the data] - ... - /* send data to all access points */ - got = XPASet(NULL, "ds9", "fits", NULL, buf, len, names, messages, NXPA); - /* error processing */ - for(i=0; i<got; i++){ - if( messages[i] ){ - fprintf(stderr, "ERROR: %s (%s)\n", messages[i], names[i]); - } - if( names[i] ) free(names[i]); - if( messages[i] ) free(messages[i]); - } -</PRE> - -<!-- =defdoc xpainfo xpainfo 3 --> - -<!-- =section xpainfo NAME --> -<H2><A NAME="xpainfo">XPAInfo: send short message to one or more XPA servers</A></H2> - -<!-- =section xpainfo SYNOPSIS --> -<B> -<PRE> - #include <xpa.h> - - int XPAInfo(XPA xpa, - char *template, char *paramlist, char *mode, - char **names, char **messages, int n); -</PRE> -</B> - -<!-- =section xpainfo DESCRIPTION --> -<P> -Send a short paramlist message to one or more XPA servers whose -class:name identifier matches the specified -<A HREF="./template.html">template</A>. - -<P> -A -<A HREF="./template.html">template</A> -of the form "class1:name1" is sent to the -XPA name server, which returns a list of at most n matching XPA -servers. A connection is established with each of these servers and -the paramlist string is passed to the server as the data transfer -request is initiated. If an XPA struct is passed to the call, then the -persistent connections are updated as described above. Otherwise, -temporary connections are made to the servers (which will be closed -when the call completes). - -<P> -The XPAInfo() routine does not send data from a buf to the XPA -servers. Only the paramlist is sent. The semantics of the paramlist -is not formalized, but at a minimum is should tell the server how to -get more information. For example, it might contain the class:name -of the XPA access point from which the server (acting as a client) -can obtain more info using XPAGet. - -<P> -A string containing the class:name and ip:port of each server is -returned in the name array. If a given server returned an error or -the server callback sends a message back to the client, then the -message will be stored in the associated element of the messages -array. The returned message string will be of the form: -<PRE> - XPA$ERROR error-message (class:name ip:port) -</PRE> -or -<PRE> - XPA$MESSAGE message (class:name ip:port) -</PRE> -<P> -The return value will contain the actual number of servers that were -processed. This value thus will hold the number of valid entries in -the names and messages arrays, and can be used to loop through these -arrays. In names and/or messages is NULL, no information is passed back -in that array. - -<P> -The following keywords are recognized: -<PRE> - key value default explanation - ------ -------- -------- ----------- - ack true/false true if false, don't wait for ack from server -</PRE> -<P> -When ack is false, XPAInfo() will not wait for an error return from the XPA -server. This means, in effect, that XPAInfo will send its paramlist string -to the XPA server and then exit: no information will be sent from the server -to the client. This UDP-like behavior is essential to avoid race -conditions in cases where XPA servers are sending info messages to -other servers. If two servers try to send each other an info message -at the same time and then wait for an ack, a race condition will result and -one or both will time out. - -<P> -<B>Example:</B> -<PRE> - (void)XPAInfo(NULL, "IMAGE", "ds9 image", NULL, NULL, NULL, 0); -</PRE> - -<!-- =defdoc xpagetfd xpagetfd 3 --> - -<!-- =section xpagetfd NAME --> -<H2><A NAME="xpagetfd">XPAGetFd: retrieve data from one or more XPA servers and write to files</A></H2> - -<!-- =section xpagetfd SYNOPSIS --> -<B> -<PRE> - #include <xpa.h> - - int XPAGetFd(XPA xpa, - char *template, char *paramlist, char *mode, - int *fds, char **names, char **messages, int n); -</PRE> -</B> - -<!-- =section xpagetfd DESCRIPTION --> -<P> -Retrieve data from one or more XPA servers whose class:name identifier -matches the specified -<A HREF="./template.html">template</A> -and write it to files associated with -one or more standard I/O fds (i.e, handles returned by open()). - -<P> -A -<A HREF="./template.html">template</A> -of the form "class1:name1" is sent to the -XPA name server, which returns a list of at most ABS(n) matching XPA -servers. A connection is established with each of these servers and -the paramlist string is passed to the server as the data transfer -request is initiated. If an XPA struct is passed to the call, then the -persistent connections are updated as described above. Otherwise, -temporary connections are made to the servers (which will be closed -when the call completes). - -<P> -The XPAGetFd() routine then retrieves data from the XPA servers, -and write these data to the fds associated with one or more fds -(i.e., results from open). Is n is positive, then there will be n fds -and the data from each server will be sent to a separate fd. If n is -negative, then there is only 1 fd and all data is sent to this single -fd. (The latter is how xpaget is implemented.) - -<P> -A string containing the class:name and ip:port is stored in the name -array. If a given server returned an error or the server callback -sends a message back to the client, then the message will be stored in -the associated element of the messages array. NB: if specified, the -name and messages arrays must be of size n or greater. - -<P> -The returned message string will be of the form: -<PRE> - XPA$ERROR error-message (class:name ip:port) -</PRE> -or -<PRE> - XPA$MESSAGE message (class:name ip:port) -</PRE> -<P> -Note that when there is an error stored in an messages entry, the -corresponding bufs and lens entry may or may not be NULL and 0 -(respectively), depending on the particularities of the server. - -<P> -The return value will contain the actual number of servers that were -processed. This value thus will hold the number of valid entries in -the bufs, lens, names, and messages arrays, and can be used to loop -through these arrays. In names and/or messages is NULL, no information is -passed back in that array. - -<P> -The mode string is of the form: "key1=value1,key2=value2,..." -The following keywords are recognized: -<PRE> - key value default explanation - ------ -------- -------- ----------- - ack true/false true if false, don't wait for ack from server (after callback completes) -</PRE> -<P> -The ack keyword is not very useful, since the server completes the callback -in order to return the data anyway. It is here for completion (and perhaps -for future usefulness). - -<P> -<B>Example:</B> -<PRE> - #include <xpa.h> - #define NXPA 10 - int i, got; - int fds[NXPA]; - char *names[NXPA]; - char *messages[NXPA]; - for(i=0; i<NXPA; i++) - fds[i] = open(...); - got = XPAGetFd(NULL, "ds9", "file", NULL, fds, names, messages, NXPA); - for(i=0; i<got; i++){ - if( messages[i] != NULL ){ - /* error processing */ - fprintf(stderr, "ERROR: %s (%s)\n", messages[i], names[i]); - } - if( names[i] ) - free(names[i]); - if( messages[i] ) - free(messages[i]); - } -</PRE> - -<!-- =defdoc xpasetfd xpasetfd 3 --> - -<!-- =section xpasetfd NAME --> -<H2><A NAME="xpasetfd">XPASetFd: send data from stdin to one or more XPA servers</A></H2> - -<!-- =section xpasetfd SYNOPSIS --> -</B> -<PRE> - #include <xpa.h> - - int XPASetFd(XPA xpa, - char *template, char *paramlist, char *mode, - int fd, char **names, char **messages, int n) -</PRE> -</B> - -<!-- =section xpasetfd DESCRIPTION --> -<P> -Read data from a standard I/O fd and send it to one or more XPA -servers whose class:name identifier matches the specified -<A HREF="./template.html">template. - -<P> -A -<A HREF="./template.html">template</A> -of the form "class1:name1" is sent to the -XPA name server, which returns a list of at most n matching XPA -servers. A connection is established with each of these servers and -the paramlist string is passed to the server as the data transfer -request is initiated. If an XPA struct is passed to the call, then the -persistent connections are updated as described above. Otherwise, -temporary connections are made to the servers (which will be closed -when the call completes). - -<P> -The XPASetFd() routine then reads bytes from the specified fd -until EOF and sends these bytes to the XPA servers. -The final parameter n specifies the maximum number of servers to contact. -A string containing the class:name and ip:port of each server is returned in -the name array. If a given server returned an error, then the error -message will be stored in the associated element of the messages array. -NB: if specified, the name and messages arrays must be of size n or greater. - -<P> -The return value will contain the actual number of servers that were -processed. This value thus will hold the number of valid entries in -the names and messages arrays, and can be used to loop through these -arrays. In names and/or messages is NULL, no information is passed back -in that array. - -<P> -The mode string is of the form: "key1=value1,key2=value2,..." -The following keywords are recognized: -<PRE> - key value default explanation - ------ -------- -------- ----------- - ack true/false true if false, don't wait for ack from server (after callback completes) - verify true/false false send buf from XPASet[Fd] to stdout -</PRE> -<P> -The ack keyword is useful in cases where one does not want to wait for -the server to complete, e.g. is a lot of processing needs to be done -on the passed data or when the success of the server operation is not -relevant to the client. - -<P> -<B>Example:</B> -<PRE> - #include <xpa.h> - - #define NXPA 10 - int i, got; - int fd; - char *names[NXPA]; - char *messages[NXPA]; - fd = open(...); - got = XPASetFd(NULL, "ds9", "fits", NULL, fd, names, messages, NXPA); - for(i=0; i<got; i++){ - if( messages[i] != NULL ){ - /* error processing */ - fprintf(stderr, "ERROR: %s (%s)\n", messages[i], names[i]); - } - if( names[i] ) - free(names[i]); - if( messages[i] ) - free(messages[i]); - } -</PRE> - -<!-- =defdoc xpaopen xpaopen 3 --> - -<!-- =section xpaopen NAME --> -<H2><A NAME="xpaopen">XPAOpen: allocate a persistent client handle</A></H2> - -<!-- =section xpaopen SYNOPSIS --> -<B> -<PRE> - #include <xpa.h> - - XPA XPAOpen(char *mode); -</PRE> -</B> - -<!-- =section xpaopen DESCRIPTION --> -<P> -XPAOpen() allocates a persistent XPA struct that can be used with -calls to XPAGet(), XPASet(), XPAInfo(), XPAGetFd(), and -XPASetFd(). Persistence means that a connection to an XPA server is -not closed when one of the above calls is completed but will be -re-used on successive calls. Using XPAOpen() therefore saves the time -it takes to connect to a server, which could be significant with slow -connections or if there will be a large number of exchanges with a -given access point. The mode argument currently is ignored ("reserved -for future use"). - -<P> -An XPA struct is returned if XPAOpen() was successful; otherwise NULL -is returned. This returned struct can be passed as the first argument -to XPAGet(), etc. Those calls will update the list of active XPA -connections. Already connected servers (from a previous call) are -left connected and new servers also will be connected. Old servers -(from a previous call) that are no longer needed are disconnected. -The connected servers will remain connected when the next call to -XPAGet() is made and connections are once again updated. - -<P> -<B>Example:</B> -<PRE> - #include <xpa.h> - - XPA xpa; - xpa = XPAOpen(NULL); -</PRE> - -<!-- =defdoc xpaclose xpaclose 3 --> - -<!-- =section xpaclose NAME --> -<H2><A NAME="xpaclose">XPAClose: close a persistent XPA client handle</A></H2> - -<!-- =section xpaclose SYNOPSIS --> -<B> -<PRE> - #include <xpa.h> - - void XPAClose(XPA xpa); -</PRE> -</B> - -<!-- =section xpaclose DESCRIPTION --> -<P> -XPAClose closes the persistent connections associated with this XPA struct -and frees all allocated space. It also closes the open sockets connections -to all XPA servers that were opened using this handle. - -<P> -<B>Example:</B> -<PRE> - #include <xpa.h> - - XPA xpa; - XPAClose(xpa); -</PRE> - -<!-- =defdoc xpanslookup xpanslookup 3 --> - -<!-- =section xpanslookup NAME --> -<H2><A NAME="xpanslookup">XPANSLookup: lookup registered XPA access points</A></H2> - -<!-- =section xpanslookup SYNOPSIS --> -<B> -<PRE> - #include <xpa.h> - - int XPANSLookup(XPA xpa, - char *template, char type, - char ***classes, char ***names, - char ***methods, char ***infos) -</PRE> -</B> - -<!-- =section xpanslookup DESCRIPTION --> -<P> -XPA routines act on a class:name identifier in such a way -that all access points that match the identifier are processed. It is -sometimes desirable to choose specific access points from the -candidates that match the -<A HREF="./template.html">template</A>. In order to do this, the -XPANSLookup routine can be called to return a list of matches, so that -specific class:name instances can then be fed to XPAGet(), XPASet(), etc. - -<P> The first argument is an optional XPA struct. If non-NULL, the -existing name server connection associated with the specified xpa is -used to query the xpans name server for matching templates. Otherwise, -a new (temporary) connection is established with the name server. - -<P> -The second argument to XPANSLookup is the class:name -<A HREF="./template.html">template</A> -to match. - -<P> -The third argument for XPANSLookup() is the type of access and can be -any combination of: -<PRE> - type explanation - ------ ----------- - g xpaget calls can be made on this access point - s xpaset calls can be made on this access point - i xpainfo calls can be made on this access point -</PRE> -<P> -The call typically specifies only one of these at a time. - -<P> -The final arguments are pointers to arrays that will be filled -in and returned by the name server. The name server will allocate and -return arrays filled with the classes, names, and methods of all XPA -access points that match the <A HREF="./template.html">template</A> -and have the specified type. Also returned are info strings, which -generally are used internally by the client routines. These can be -ignored (but the strings must be freed). The function returns the -number of matches. The returned value can be used to loop through the -matches: - -<B>Example:</B> -<PRE> - #include <xpa.h> - - char **classes; - char **names; - char **methods; - char **infos; - int i, n; - n = XPANSLookup(NULL, "foo*", "g", &classes, &names, &methods, &infos); - for(i=0; i<n; i++){ - [more specific checks on possibilities ...] - [perhaps a call to XPAGet for those that pass, etc. ...] - /* don't forget to free alloc'ed strings when done */ - free(classes[i]); - free(names[i]); - free(methods[i]); - free(infos[i]); - } - /* free up arrays alloc'ed by names server */ - if( n > 0 ){ - free(classes); - free(names); - free(methods); - free(infos); - } -</PRE> -<P> -The specified -<A HREF="./template.html">template</A> -also can be a host:port specification, for example: -<PRE> - myhost:12345 -</PRE> -<P> -In this case, no connection is made to the name server. Instead, the -call will return one entry such that the ip array contains the ip for -the specified host and the port array contains the port. The class -and name entries are set to the character "?", since the class and -name of the access point are not known. - -<!-- =defdoc xpaaccess xpaaccess 3 --> - -<!-- =section xpaaccess NAME --> -<H2><A NAME="xpaaccess">XPAAccess: return XPA access points matching -template (XPA 2.1 and above)</A></H2> - -<!-- =section xpaaccess SYNOPSIS --> -<B> -<PRE> - #include <xpa.h> - - int XPAAccess(XPA xpa, - char *template, char *paramlist, char *mode, - char **names, char **messages, int n); -</PRE> -</B> - -<!-- =section xpaaccess DESCRIPTION --> -<P> -The XPAAccess routine returns the public access points that match the -specified second argument <A HREF="./template.html">template</A> and -have the specified access type. - -<P> -A -<A HREF="./template.html">template</A> -of the form "class1:name1" is sent to the -XPA name server, which returns a list of at most n matching XPA -servers. A connection is established with each of these servers and -the paramlist string is passed to the server as the data transfer -request is initiated. If an XPA struct is passed to the call, then the -persistent connections are updated as described above. Otherwise, -temporary connections are made to the servers (which will be closed -when the call completes). - -<P> -The XPAAccess() routine retrieves names from at most n XPA servers -that match the specified template and that were checked for access -using the specified mode. The return string contains both the -class:name and ip:port. If a given server returned an error or the -server callback sends a message back to the client, then the message -will be stored in the associated element of the messages array. -NB: if specified, the name and messages arrays must be of size n or greater. - -<P> -The returned message string will be of the form: -<PRE> - XPA$ERROR error-message (class:name ip:port) -</PRE> -<P> -Note that names of matching registered access points are always -returned but may not be valid; it is not sufficient to assume that the -returned number of access points is the number of valid access points. -Rather, it is essential to check the messages array for error -messages. Any string in the messages array is an error message and -indicated that the associated access point is not available. - -<P> -For example, assume that a server registers a number of access points -but delays entering its event loop. If a call to XPAAccess() is made -before the event loop is entered, the call will timeout (after waiting -for the long timeout period) and return an error of the form: -<PRE> - XPA$ERROR: timeout waiting for server authentication (XPA:xpa1) -</PRE> -The error means that the XPA access point has been registered but is -not yet available (because events are not being processed). When the -server finally enters its event loop, subsequent calls to XPAAccess() -will return successfully. - -<P> -NB: This routine only works with XPA servers built with XPA 2.1.x and later. -Servers with older versions of XPA will return the error message: - - XPA$ERROR invalid xpa command in initialization string - -If you get this error message, then the old server actually is ready -for access, since it got to the point of fielding the query! The -xpaaccess program, for example, ignores this message in order to work -properly with older servers. - -<P> -The third argument for XPAAccess() is the type of access and can be -any combination of: -<PRE> - type explanation - ------ ----------- - g xpaget calls can be made on this access point - s xpaset calls can be made on this access point - i xpainfo calls can be made on this access point -</PRE> -<P> -The mode string argument is of the form: "key1=value1,key2=value2,..." -The following keywords are recognized: -<PRE> - key value default explanation - ------ -------- -------- ----------- - ack true/false true if false, don't wait for ack from server (after callback completes) -</PRE> -<P> -The ack keyword is not very useful, since the server completes the callback -in order to return the data anyway. It is here for completion (and perhaps -for future usefulness). - -<!-- =section xpaclient SEE ALSO --> -<!-- =text See xpa(n) for a list of XPA help pages --> -<!-- =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 xpagetfd SEE ALSO --> -<!-- =text See xpa(n) for a list of XPA help pages --> -<!-- =section xpasetfd SEE ALSO --> -<!-- =text See xpa(n) for a list of XPA help pages --> -<!-- =section xpaopen SEE ALSO --> -<!-- =text See xpa(n) for a list of XPA help pages --> -<!-- =section xpaclose SEE ALSO --> -<!-- =text See xpa(n) for a list of XPA help pages --> -<!-- =section xpanslookup 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: March 10, 2007</H5> - -</BODY> -</HTML> diff --git a/xpa/doc/convert.html b/xpa/doc/convert.html deleted file mode 100644 index a8d0dd2..0000000 --- a/xpa/doc/convert.html +++ /dev/null @@ -1,146 +0,0 @@ -<!-- =defdoc xpaconvert xpaconvert n --> -<HTML> -<HEAD> -<TITLE>Converting the XPA API to 2.0</TITLE> -</HEAD> -<BODY> - -<!-- =section xpaconvert NAME --> -<H2><A NAME="xpaconvert">XPAConvert: Converting the XPA API to 2.0</A></H2> - -<!-- =section xpaconvert SYNOPSIS --> -<H2>Summary</H2> -<P> -This document describes tips for converting from xpa 1.0 (Xt-based -xpa) to xpa 2.0 (socket-based xpa). - -<!-- =section xpaconvert DESCRIPTION --> -<H2>Description</H2> -<P> -The following are tips for converting from xpa 1.0 (Xt-based xpa) to -xpa 2.0 (socket-based xpa). The changes are straight-forward and -almost can be done automatically (we used editor macros for most of -the conversion). -<UL> -<P> -<LI>The existence of the cpp XPA_VERSION directive to distinguish between 1.0 -(where it is not defined) and 2.0 (where it is defined). - -<P> -<LI>Remove the first widget argument from all send and receive server -callbacks. Also change first 2 arguments from XtPointer to void -*. For example: -<PRE> -#ifdef XPA_VERSION -static void XPAReceiveFile(client_data, call_data, paramlist, buf, len) - void *client_data; - void *call_data; - char *paramlist; - char *buf; - int len; -#else -static void XPAReceiveFile(w, client_data, call_data, paramlist, buf, len) - Widget w; - XtPointer client_data; - XtPointer call_data; - char *paramlist; - char *buf; - int len; -#endif -</PRE> -<P> -<LI>Server callbacks should be declared as returning int instead -of void. They now should return 0 for no errors, -1 for error. - -<P> -<LI> The mode flags have changed when defining XPA server callbacks. -The old <EM>S</EM> flag (save buffer) is replaced by <EM>freebuf=false</EM>. -The old <EM>E</EM> flag (empty buffer is OK) is no longer used (it -was an artifact of the X implementation). - -<P> -<LI>Change NewXPACommand() to XPAcmdNew(), with the new calling sequence: -<PRE> - xpa = NewXPACommand(toplevel, NULL, prefix, NULL); -</PRE> -is changed to: -<PRE> - xpa = XPACmdNew(xclass, name); -</PRE> -<P> -<LI>Change the AddXPACommand() subroutine name to XPACmdAdd (with the same -calling sequence): -<PRE> - AddXPACommand(xpa, "file", - "\tdisplay a new file\n\t\t requires: filename", - NULL, NULL, NULL, XPAReceiveFile, text, NULL); -</PRE> -is changed to: -<PRE> - XPACmdAdd(xpa, "file", - "\tdisplay a new file\n\t\t requires: filename", - NULL, NULL, NULL, XPAReceiveFile, text, NULL); -</PRE> -<P> -<LI>The XPAXtAppInput() routine should be called just before XtAppMainLoop() -to add xpa fds to the Xt event loop: -<PRE> - /* add the xpas to the Xt loop */ - XPAXtAddInput(app, NULL); - - /* process events */ - XtAppMainLoop(app); -</PRE> -<P> -<LI>Change NewXPA() to XPANew() and call XPAXtAddInput() if the XtAppMainLoop -routine already has been entered: -<PRE> - xpa = NewXPA(saotng->xim->toplevel, prefix, xparoot, - "FITS data or image filename\n\t\t options: file type", - XPASendData, new, NULL, - XPAReceiveData, new, "SE"); -</PRE> -is changed to: -<PRE> - sprintf(tbuf, "%s.%s", prefix, xparoot); - xpa = XPANew("SAOTNG", tbuf, - "FITS data or image filename\n\t\t options: file type", - XPASendData, new, NULL, - XPAReceiveData, new, "SE"); - XPAXtAddInput(XtWidgetToApplicationContext(saotng->xim->toplevel), xpa); -</PRE> -<P> -<LI>Change XPAInternalReceiveCommand() to XPACmdInternalReceive() -remove first argument in the calling sequence): -<PRE> - XPAInternalReceiveCommand(im->saotng->xim->toplevel, - im->saotng, im->saotng->commands, - "zoom reset", NULL, 0); -</PRE> -is changed to: -<PRE> - XPACmdInternalReceive(im->saotng, im->saotng->commands, - "zoom reset", NULL, 0); -</PRE> -<P> -<LI>Change DestroyXPA to XPAFree: -<PRE> - DestroyXPA(im->dataxpa); -</PRE> -is changed to: -<PRE> - XPAFree(im->dataxpa); -</PRE> -</UL> - -<!-- =section xpaconvert 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> diff --git a/xpa/doc/env.html b/xpa/doc/env.html deleted file mode 100644 index 4a71e80..0000000 --- a/xpa/doc/env.html +++ /dev/null @@ -1,371 +0,0 @@ -<!-- =defdoc xpaenv xpaenv n --> -<HTML> -<HEAD> -<TITLE>The XPA Environment</TITLE> -</HEAD> -<BODY> - -<!-- =section xpaenv NAME --> -<H2><A NAME="xpaenvl">XPAEnv: Environment Variables for XPA Messaging</A></H2> - -<!-- =section xpaenv SYNOPSIS --> -<H2>Summary</H2> -Describes the environment variables which can be used to tailor the overall -XPA environment. - -<!-- =section xpaenv DESCRIPTION --> -<H2>Description</H2> -<P> -The following environment variables are supported by XPA: -<DL> -<P> -<DT><B>XPA_ACL</B> -<DD> If <EM>XPA_ACL</EM> is <EM>true</EM>, then -host-based <A HREF="./acl.html">XPA Access Control</A> -is turned on and only specified machines can access specified access -points. If <EM>false</EM>, then access control is turned off and any -machine can access point. The default is turn turn access control on. - -<P> -<DT><B>XPA_ACLFILE</B> -<DD> If -<A HREF="./acl.html">XPA Access Control</A> -is turned on, this variable specifies the name of the file containing -access control information for all access points started by this user. -The default file name is: <EM>$HOME/acls.xpa</EM>. - -<P> -<DT><B>XPA_CONNECT_TIMEOUT</B> -<DD> When an XPA server first starts up, it immediately tries to -connect to the XPA name server program (xpans) on the host specified by -the <em>XPA_NSINET</em> variable. (If this connection fails on the -local host, and if xpans can be found in the path, then the name -server is started automatically.) Unfortunately, a mis-configured -network can cause this connect attempt to hang for many seconds while -the connect() system call times out. Therefore, an alarm is started -to interrupt the connect() call and prevent a long hang. The initial -value of the alarm timeout is 10 seconds, but can be changed by setting -this environment variable. If you want to disable the alarm and allow -the initial connect() to time out, set the value of this variable to -0. Normally, users would not change this variable at all. - -<P> -<DT><B>XPA_CLIENT_DOXPA</B> -<DD> Normally, an XPA client (xpaget, xpaset, etc.) will process incoming -XPA server requests while awaiting the completion of the client request. -Setting this variable to "false" will prevent XPA server requests from -being processed by the client. - -<P> -<DT><B>XPA_DEFACL</B> -<DD> If -<A HREF="./acl.html">XPA Access Control</A> -is turned on, this variable specifies the default access control -condition for all access points, if the <EM>XPA_ACLFILE</EM> file does -not exist. The default acl is: <EM>$host:* $host +</EM>, meaning that -all processes on the host machine have full access to all access points. - -<P> -<DT><B>XPA_HOST</B> -<DD> -For the INET socket method, XPA utilizes the canonical hostname (as -returned by the gethostname() routine) to construct the IP part of the -method id. Under some circumstances, this might not be a correct choice -of name and IP. For example, if an XPA server is started on a machine -running VPN, you might want to use the VPN name and IP instead of the -canonical host name, so that other machines in the VPN network can -access the server. In this case, you can set the XPA_HOST to be -the VPN name (if resolvable) or, more easily, the VPN IP. - -<P> -<DT><B>XPA_IOCALLSXPA</B> -<DD> -Setting this variable causes all XPA socket IO calls to process -outstanding XPA requests whenever the primary socket is not ready for -IO. This means that a server making a client call will (recursively) -process incoming server requests while waiting for client completion. -This inter-IO XPA processing avoids a rare -<A HREF="./server.html#race">XPA Race Condition</A>: two or more -XPA servers sending messages to one another using an XPA client -routine such as XPASet() can deadlock while each waits for the other -server to respond. This can happen, for example, if the servers call -XPAPoll() with a time limit, and send messages in between the polling call. - -<P> -By default, this option is turned off, because we judge that the added -code complication and overhead involved will not be justified by the -amount of its use. Moreover, processing XPA requests within socket IO -can lead to non-intuitive results, since incoming server requests will -not necessarily be processed to completion in the order in which they -are received. - -<P> -<DT><B>XPA_LOGNAME</B> -<DD> -XPA preferentially uses the de facto standard environment variable -LOGNAME to determine the username when registering an access point in -the name server. If this environment variable has been used for -something other than the actual user name (such as a log file name), -unexpected results can ensue. In such cases, use the XPA_LOGNAME -variable to set the user name. (If neither exists, then getpwuid(geteuid()) -is used as a last resort). - -<P> -<DT><B>XPA_LONG_TIMEOUT</B> -<DD> XPA is designed to allow data to be sent from one process to -another over a long period of time (i.e., a program that generates -image data sends that data to an image display, but slowly) but it -also seeks to prevent hangs. This is done by supporting 2 timeout -periods: a <EM>short</EM> timeout for protocol communication -and a <EM>long</EM> for data communication. -<P> -The <EM>XPA_LONG_TIMEOUT</EM> variable controls the <EM>long</EM> -timeout and is used to prevent hangs in cases where communication -between the client and server that is <EM>not</EM> controlled by the -XPA interface itself. Transfer of data between client and server, or a -client's wait for a status message after completion of the server -callback, are two examples of this sort of communication. By default, -the <EM>long</EM> timeout is set to 180 seconds. -Setting the value to -1 will disable <EM>long</EM> timeouts and allow -an infinite amount of time. - -<P> -<DT><B>XPA_MAXHOSTS</B> -<DD> The maximum number of access points that the programs -<EM>xpaset</EM>, <EM>xpaget</EM>, and <EM>xpainfo</EM> will -communicate with at one time. The default is 64, meaning, for -example, that the <EM>xpaset</EM> program will not send a message -to more than 100 access points at one time and <EM>xpaget</EM> will -not retrieve from more than 100 access points at one time. - -<P> -<DT><B>XPA_METHOD</B> -<DD> -Determines the socket connection method used by this session of XPA. -The choices are: <EM>inet</EM> (to use INET or Internet-based -sockets), <EM>localhost</EM> (to use the machines localhost inet -socket), or <EM>local (unix)</EM> (to use UNIX sockets). The default -is <EM>INET</EM>. Using the <EM>inet</EM> method will allow access -from other machines (subject to access controls) but using -<EM>localhost</EM> or <EM>local</EM> will not. Localhost is most useful -for private access and when the machine in question is not connected -to the Internet. The unix method also can be used for private access -and non-Internet connections (Unix platforms only). -<P> -Once defined, the first registration of an XPA access point will -ensure that an instance of the -<A HREF="./xpans.html">XPA Name Server (xpans)</A> -is running that handles that connection method. All new access points -will use the new connection method but existing access points will use -the original method. - -<P> -<DT><B>XPA_NSINET</B> -<DD> For the <EM>inet</EM> method of socket connection, this variable -specifies the host and port on which the -<A HREF="./xpans.html">XPA Name Server (xpans)</A> -is listens for new access points. The default is <EM>$host:$port</EM>, -meaning that the default XPA port (14285) on the current machine -(as returned by gethostname()) is used. If several machines were all -accessing the same XPA access points, you would use this variable to -specify that they all use the same name server to find out about these -access points. For example, a value of <EM>myhost:$port</EM> would -mean that the xpans name server is running on myhost and uses the -default port 12345. All machines would then get the XPA access points -registered with that name server, subject to access controls. -<P> -The port used by xpans to register its XPA access point normally is -taken to be one greater than the port on which it receives new access -points from XPA servers. You can specify a specific access point port -using the syntax machine:port1,port2, i.e., the access point port is -specified after the comma. For example, $host:12345,23456 will listen -for new access ports on 12345 and will accept XPA commands on 23456. - -<P> -<DT><B>XPA_NSREGISTER</B> -<DD> -This boolean variable specifies whether a server registers its XPA -access point with the specified xpans name server. The default is -<em>true</em>. If set to <em>false</em>, the access point still is -set up but it is not registered with xpans and therefore cannot be -accessed by name. (It can be accessed by method, if the latter is -known.) Note that an access point can be registered later on (using --remote or -proxy, for example). This variable mainly is useful in -cases where the Internet configuration is broken (so that registration -causes a DNS hang) but you still wish to and can use the server with a -remote xpans (e.g., ds9's Virtual Observatory capability). - -<P> -<DT><B>XPA_NSUNIX</B> -<DD> For the <EM>local</EM> method of socket connection, this variable -specifies the name of the Unix file that will be used to access the -<A HREF="./xpans.html">XPA Name Server (xpans)</A>. The default is -<EM>xpans_unix</EM>. This variable is not usually needed. Note that -is the <EM>local</EM> socket method is used, then remote machines will -not be able to access the xpans name server or the registered XPA access -points. - -<P> -<DT><B>XPA_NSUSERS</B> -<DD> -This variable specifies whether other users' access points will be -returned by the -<A HREF="./xpans.html">XPA Name Server (xpans)</A> for use by -<EM>xpaget</EM>, <EM>xpaset</EM>, etc. -Generally speaking, it is sufficient to run one xpans name server per -machine and register the access points for all users with that xpans. -This means, for example, that if you request information from -ds9 by running: -<PRE> - xpaget ds9 colormap -</PRE> -you might get information from your own ds9 as well as -from another user running ds9 on the same machine. The -<EM>XPA_NSUSERS</EM> variable controls whether you want such access -to the access points of other users. -By default, only your own access points are returned, so -that, in the example above, you would only get the colormap information -from the ds9 you registered. If, however, you had set the value of the -<EM>XPA_NSUSERS</EM> variable to <EM>eric,fred</EM>, then you would be -able to communicate with both eric and fred's access points. Note that -this variable can be overridden using the <EM>-u</EM> switch on the -<EM>xpaget</EM>, <EM>xpaset</EM>, and <EM>xpainfo</EM> programs. - -<P> -<DT><B>XPA_PORT</B> -<DD> -A semi-colon delimited list of user specified ports to use for specific -XPA access points. The format is each specification is: -<PRE> -class:template port1[ port2] -</PRE> -where <B>port1</B> is the main (command) port for the access point and -<B>port2</B> is the (secondary) data port. If port2 is not specified, -it defaults to a value of 0 (meaning the system assigns the port). - -<P> -Specification of specific ports is useful, for example, when a machine -outside a firewall needs to communicate with a machine inside a -firewall. In such a case, the firewall should be configured to allow -socket connections to both the command and data port from the outside -machine, and the inside XPA program should be started up with the -outside machine in its ACL list. Then, when the inside program is -started with specified ports, outside XPA programs can use -"machine:port" to contact the inside access points, instead of the -access point names. That is, the machine outside the firewall does not -need access to the XPA name server: -<PRE> -export XPA_PORT="DS9:ds9 12345 12346" # on machine "inside" -cat foo.fits | xpaset inside:12345 fits # on machine "outside" -</PRE> -Note that 2 ports are required for full XPA communication and -therefore 2 ports should be specified to go through a firewall. The -second port assignment is not important if you simply are assigning -the command port in order to communicate commands with a known -port (e.g., to bypass the xpans name server). If only one (command) -port is specified, the system will negotiate a random data port and -everything will work properly. - -<P> -This support is somewhat experimental. If you run into problems, please -let us know. - -<P> -<DT><B>XPA_PORTFILE</B> -<DD> -A list of user-specified port to use for specific xpa access points. -The format of the file is: -<PRE> -class:template port1 [port2] -</PRE> -where <B>port1</B> is the main port for the access point and -<B>port2</B> is the data port. If port2 is not specified, it defaults -to a value of 0 (meaning the system assigns the port). See -<B>XPA_PORT</B> above for an explanation of user-specified ports. - -<P> -<DT><B>XPA_SHORT_TIMEOUT</B> -<DD> XPA is designed to allow data to be sent from one process to -another over a long period of time (i.e., a program that generates -image data sends that data to an image display, but slowly) but it -also seeks to prevent hangs. This is done by supporting 2 timeout -periods: a <EM>short</EM> timeout for protocol communication -and a <EM>long</EM> for data communication. -<P> -The <EM>XPA_SHORT_TIMEOUT</EM> variable -controls the <EM>short</EM> timeout and is used to prevent hangs -in cases where the XPA protocol requires internal communication between -the client and server that is controlled by the XPA interface -itself. Authentication is an example of this sort of communication, -as is the establishment of a data channel between the two processes. -The default value for the <EM>short</EM> is 30 seconds (which is -a pretty long time, actually). Setting the value to -1 will disable -<EM>short</EM> timeouts and allow an infinite amount of time. - -<P> -<DT><B>XPA_SIGUSR1</B> -<DD> If the value of this variable is <EM>true</EM>, then XPA will -catch SIGUSR1 signals when performing an I/O operation in order to -curtail that operation. This facility allows users to send a SIGUSR1 -signal to an XPA server if a client is hanging up the server by -sending or receiving data too slowly (timeouts also can be used -- see -above). When enabled in this way, the SIGUSR1 signal is ignored at all other -times, so that its safe to send the signal at any time. If the -variable is set to <EM>false</EM>, then SIGUSR1 is not used at -all. Turning off SIGUSR1 would be desired in cases there the program -uses SIGUSR1 for some other reason and does not want XPA interfering. -The default is to use the signal. - -<P> -<DT><B>XPA_TIMESTAMP_ERRORS</B> -<DD> If <EM>XPA_TIMESTAMP_ERRORS</EM> is <EM>true</EM>, then error -messages will include a date/time string. This can be useful when -XPA errors are being saved in an error log (e.g. Web/CGI use). The -default is false. -</DL> - -<P> -<DT><B>XPA_TMPDIR</B> -<DD> This variable specifies the directory into which XPA logs, Unix -socket files (when <EM>XPA_METHOD</EM> is <EM>local</EM>), etc. are -stored. The default is <EM>/tmp/.xpa</EM>. - -<P> -<DT><B>XPA_VERBOSITY</B> -<DD> Specify the verbosity level of error messages. If the value is -set to <EM>0</EM>, <EM>false</EM>, or <EM>off</EM>, then no error -messages are printed to stderr. If the value is <EM>1</EM>, then -important XPA error messages will be output. If the value is -set to <EM>2</EM>, XPA warnings about out-of-sync messages will also -be output. These latter almost always can be ignored. - -<P> -<DT><B>XPA_VERSIONCHECK</B> -<DD> Specify whether a new access point should check its major and minor XPA -version number against the version used by the xpans name server at -registration time. The default is <EM>true</EM>. When checking is -performed, a warning is issued if the server major version is found to -be greater than the xpans version. Note that the check is performed -both by the XPA server and by the xpans process and warnings will be -issued by each. Also, instead of the values of <EM>true</EM> or -<em>false</em>, you can give this variable an integer value n. In this -case, each version checking process (i.e., the XPA-enabled server or -xpans) will print out a maximum of n warning messages (after which -version warnings are silently swallowed). -<P> -In general, it is a bad idea to run an XPA-enabled server program -using a version of XPA newer than the basic xpaset, xpaget, xpaaccess, -xpans programs. This sort of mismatch usually will not work due to -protocol changes. - -<!-- =section xpaenv 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: December 23, 2009</H5> - -</BODY> -</HTML> diff --git a/xpa/doc/examples.html b/xpa/doc/examples.html deleted file mode 100644 index 0bd68d4..0000000 --- a/xpa/doc/examples.html +++ /dev/null @@ -1,64 +0,0 @@ -<!-- =defdoc xpacode xpacode n --> -<HTML> -<HEAD> -<TITLE>Where to Find Example/Test Code</TITLE> -</HEAD> -<BODY> - -<!-- =section xpacode NAME --> -<H2><A NAME="xpacode">XPACode: Where to Find Example/Test Code</A></H2> - -<!-- =section xpacode SYNOPSIS --> -<H2>Summary</H2> -<P> -The XPA source code directory contains two test programs, -<EM>stest.c</EM>, and <EM>ctest.c</EM> that can serve as -examples for writing XPA servers and clients, respectively. -They also can be used to test various features of XPA. - -<!-- =section xpacode DESCRIPTION --> -<H2>Description</H2> -<P> -To build the XPA test programs, execute: -<PRE> - make All -</PRE> -in the XPA source directory to generate the <EM>stest</EM> and -<EM>ctest</EM> programs. (NB: this should work on all platforms, -although we have had problems with unresolved externals on one -Sun/Solaris machine, for reasons still unknown.) -<P> -The stest program can be executed with no arguments to start -an XPA server that contains the access points: xpa, xpa1, -c_xpa (containing sub-commands cmd1 and cmd2), and i_xpa. -You then can use xpaset and xpaget to interact with these access points: -<PRE> - cat xpa.c | xpaset xpa # send to xpa - cat xpa.c | xpaset "xpa*" # send to xpa and xpa1 - xpaget xpa # receive from xpa - xpaget xpa* # receive from xpa and xpa1 -</PRE> -etc. You also can use ctest to do the same thing, or to iterate: -<PRE> - ctest -s -l 100 xpa # send to xpa 100 times - ctest -s -l 100 "xpa*" # send to xpa and xpa1 100 times - ctest -g -l 100 xpa # receive from xpa 100 times - ctest -g -l 100 "xpa*" # receive from xpa and xpa1 100 times -</PRE> -More options are available: see the stest.c and ctest.c code itself, which -were used extensively to debug XPA. - -<P> -The file test.tcl in the XPA source directory gives examples for using the -<A HREF="./tcl.html">XPATcl</A>Interface. - -<!-- =section xpacode 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> diff --git a/xpa/doc/help.html b/xpa/doc/help.html deleted file mode 100644 index dfe51f9..0000000 --- a/xpa/doc/help.html +++ /dev/null @@ -1,162 +0,0 @@ -<!-- =defdoc xpa xpa n --> -<HTML> -<HEAD> -<TITLE>The XPA Help Facility</TITLE> -</HEAD> -<BODY> - -<!-- =section xpa NAME --> -<H2><A NAME="xpa">XPA: Public Access to Data and Algorithms</A></H2> - -<!-- =section xpa SYNOPSIS --> -<H2>Summary</H2> -This document is the Table of Contents for XPA. - -<!-- =section xpa DESCRIPTION --> -<H2>Description</H2> -<P> -The XPA messaging system provides seamless communication between many -kinds of Unix programs, including X programs and Tcl/Tk programs. It -also provides an easy way for users to communicate with XPA-enabled -programs by executing XPA client commands in the shell or by utilizing -such commands in scripts. Because XPA works both at the programming -level and the shell level, it is a powerful tool for unifying any -analysis environment: users and programmers have great flexibility in -choosing the best level or levels at which to access XPA services, and -client access can be extended or modified easily at any time. - -<P> -A program becomes an XPA-enabled server by defining named points of -public access through which data and commands can be exchanged with -other client programs (and users). Using standard TCP sockets as a -transport mechanism, XPA supports both single-point and broadcast -messaging to and from these servers. It supports direct communication -between clients and servers, or indirect communication via an -intermediate message bus emulation program. Host-based access control -is implemented, as is as the ability to communicate with XPA servers -across a network. - -<P> -XPA implements a layered interface that is designed to be useful both -to software developers and to users. The interface consists of a -library of XPA client and server routines for use in C/C++ programs and -a suite of high-level user programs built on top of these libraries. -Using the XPA library, access points can be added to Tcl/Tk programs, -Xt programs, or to Unix programs that use the XPA event loop or any -event loop based on select(). Client access subroutines can be added -to any Tcl/Tk, Xt, or Unix program. Client access also is supported at -the command line via a suite of high-level programs. - -<P> -Choose from the following topics: - -<UL> -<LI><A HREF="./intro.html">Introduction to XPA</A> -<!-- =text [xpaintro(n)] --> -<LI><A HREF="./template.html">Access Point Names and Templates</A> -<!-- =text [xpatemplate(n)] --> -<LI><A HREF="./info.html">Getting Common Information About Access Points</A> -<!-- =text [xpacommon(n)] --> -<LI><A HREF="./method.html">Communication Methods</A> -<!-- =text [xpamethod(n)] --> -<LI><A HREF="./inet.html">Communication Between Hosts</A> -<!-- =text [xpainet(n)] --> -<LI><A HREF="./users.html">Distinguishing Users</A> -<!-- =text [xpausers(n)] --> - -<LI><A HREF="./programs.html">XPA User Programs</A> -<UL> -<LI><A HREF="./programs.html#xpaget">xpaget: get data and info</A> -<!-- =text [xpaget(1)] --> -<LI><A HREF="./programs.html#xpaset">xpaset: send data and info</A> -<!-- =text [xpaset(1)] --> -<LI><A HREF="./programs.html#xpainfo">xpainfo: send info alert</A> -<!-- =text [xpainfo(1)] --> -<LI><A HREF="./programs.html#xpaaccess">xpaaccess: get access point info</A> -<!-- =text [xpaaccess(1)] --> -<LI><A HREF="./xpamb.html">xpamb: message bus emulation</A> -<!-- =text [xpamb(1)] --> -<LI><A HREF="./xpans.html">xpans: the XPA name server</A> -<!-- =text [xpans(1)] --> -</UL> - -<LI><A HREF="./server.html">XPA Server Routines</A> -<UL> -<LI><A HREF="./server.html#xpanew">XPANew: define a new access point</A> -<!-- =text [xpanew(3)] --> -<LI><A HREF="./server.html#xpacmdnew">XPACmdNew: define a new command access point</A> -<!-- =text [xpacmdnew(3)] --> -<LI><A HREF="./server.html#xpacmdadd">XPACmdAdd: add a command</A> -<!-- =text [xpacmdadd(3)] --> -<LI><A HREF="./server.html#xpacmddel">XPACmdDel: delete a command</A> -<!-- =text [xpacmddel(3)] --> -<LI><A HREF="./server.html#xpainfonew">XPAInfoNew: define an info access point</A> -<!-- =text [xpainfonew(3)] --> -<LI><A HREF="./server.html#xpafree">XPAFree: free an access point</A> -<!-- =text [xpafree(3)] --> -<LI><A HREF="./server.html#xpamainloop">XPAMainLoop: event loop for select server</A> -<!-- =text [xpamainloop(3)] --> -<LI><A HREF="./server.html#xpapoll">XPAPoll: poll for XPA events</A> -<!-- =text [xpapoll(3)] --> -<LI><A HREF="./server.html#xpacleanup">XPACleanup: release reserved XPA memory</A> -<!-- =text [xpacleanup(3)] --> -<LI><A HREF="./server.html#macros">XPA Server Macros: accessing structure internals</A> -<!-- =text [xpamacros(3)] --> -<LI><A HREF="./server.html#race">XPA Race Conditions: how to avoid them</A> -<!-- =text [xparace(3)] --> -<LI><A HREF="./oom.html">XPA Out of Memory (OOM) errors</A> -<!-- =text [xpaoom(3)] --> -</UL> - -<LI><A HREF="./client.html">XPA Client Routines</A> -<UL> -<LI><A HREF="./client.html#xpaopen">XPAOpen: open a persistent client connection</A> -<!-- =text [xpaopen(3)] --> -<LI><A HREF="./client.html#xpaclose">XPAClose: close persistent client connection</A> -<!-- =text [xpaclose(3)] --> -<LI><A HREF="./client.html#xpaget">XPAGet: get data</A> -<!-- =text [xpaget(3)] --> -<LI><A HREF="./client.html#xpaset">XPASet: send data or commands</A> -<!-- =text [xpaset(3)] --> -<LI><A HREF="./client.html#xpainfo">XPAInfo: send an info alert</A> -<!-- =text [xpainfo(3)] --> -<LI><A HREF="./client.html#xpagetfd">XPAGetFd: get data and write to an fd</A> -<!-- =text [xpagetfd(3)] --> -<LI><A HREF="./client.html#xpasetfd">XPASetFd: read data from and fd and send</A> -<!-- =text [xpasetfd(3)] --> -<LI><A HREF="./client.html#xpanslookup">XPANSLookup: look up an access point</A> -<!-- =text [xpanslookup(3)] --> -<LI><A HREF="./client.html#xpaaccess">XPAAccess: get access info</A> -<!-- =text [xpaaccess(3)] --> -<LI><A HREF="./xt.html">The XPA/Xt Interface: Xt interface to XPA</A> -<!-- =text [xpaxt(n)] --> -<LI><A HREF="./tcl.html">The XPA/Tcl Interface: Tcl interface to XPA</A> -<!-- =text [xpatcl(n)] --> -</UL> - -<LI> Tailoring the XPA Environment -<UL> -<LI><A HREF="./env.html">Environment Variables</A> -<!-- =text [xpaenv(n)] --> -<LI><A HREF="./acl.html">Access Control</A> -<!-- =text [xpaacl(n)] --> -</UL> - -<LI> Miscellaneous -<UL> -<!-- =stop --> -<LI><A HREF="./changelog.html">XPA ChangeLog</A> -<!-- =cont --> -<LI><A HREF="./examples.html">Where to Find Example/Test Code</A> -<LI><A HREF="./changes.html">User Changes Between XPA 1.0 and 2.0</A> -<LI><A HREF="./convert.html">API Changes Between XPA 1.0 and 2.0</A> -<LI><A HREF="./name.html">What Does XPA Stand For, Anyway?</A> -</UL> - -</UL> - -<!-- =stop --> - -<H5>Last updated: September 10, 2003</H5> -</BODY> -</HTML> diff --git a/xpa/doc/html2man b/xpa/doc/html2man deleted file mode 100755 index 4e60799..0000000 --- a/xpa/doc/html2man +++ /dev/null @@ -1,258 +0,0 @@ -#!/usr/bin/perl -# -# See COPYRIGHT -# -# Script to generate a pod file from an html source (the same one as for text files too) -# and later this pod file it passed through pod2man -# -# Use: -# html2man [ <man-dir> [<version-dir>] ] <file.html -# -# <Man-dir> is the directory where the man pages will be created -# (current directory by default). If a file name is given instead of -# directory then the directory of that file is used. -# <Version-dir> is the directory containing the ttf2pt1 files version.h -# and CHANGES.html which are used to generate the release name and date -# for the man page (by default looks in current directory and then in up to -# 5 ancestor directories). -# If the version files can not be found then the release defaults to -# "current" and the date defaults to today. -# -# Special formatting in the html file is: -# All controls are hidden within HTML comments that must occupy a whole separate line -# Such a line looks like: -# <!-- =<html2man_directive> <arguments> --> -# <!-- ==<pod_directive> <arguments> --> -# Any sort of directive must be followed by a space. The pod directives are -# automatically surrounded by empty lines in the output file. -# The html2man directives are: -# -# <!-- =defdoc <docid> <file> <section> --> -# Define a man page. Multiple man pages can be defined in the same HTML -# file. <Docid> is a short name by which this man page will be referred in the -# other directives. <File> is the name of the man page, and <section> is the -# section of the manual (do not confuse with sections within a man page). -# -# <!-- =section <docid> <page_section_name> --> -# All the text following this directive is copied (with translation) -# into the specified section of the specified man page. The sections -# may appear in arbitrary order, they will be rearranged to the standard -# order before output. Only standard section names are permitted (see @stdsect -# below). The pod directives which occur outside of man sections are ignored, -# just like the common text. The translation of HTML tags is: -# -# <br> - to paragraph break -# <b> - to B<> -# <i> - to I<> -# <tt> - to C<> -# <a href> - to F<> -# <ul>, <li>, </ul> - to =over 2, =item *, =back -# , &, <, > - to their symbols, appropriately encoded -# -# The rest of HTML tags is removed -# -# If the same section is started more than once, the text from the -# second appearance will be added to the first, etc. -# -# <!-- =stop --> -# Stop copying text to the man page. -# -# <!-- =cont --> -# Continue copying text to the man page, same section as before. -# -# <!-- =text <text> --> -# Insert this <text> into the man page (works only when copying is enabled). -# Characters <, >, & are converted as usual. - -@mons = qw(January February March April May June July August September October November December); - -$dir = $ARGV[0]; -$maindir = $ARGV[1]; - -if($dir eq "") { - $dir = "."; -} elsif( ! -d $dir ) { - if( ! ($dir =~ s|\/[^/]*$||) ) { - $dir = "."; - } -} -if($maindir eq "") { - $maindir = "."; - for($i=0; $i<5; $i++) { - if(-f "$maindir/version.h") { - last; - } - $maindir = "../$maindir"; - } -} - -if( open(VERFILE, "<$maindir/version.h") ) { - while(<VERFILE>) { - if( /^\s*\#define\s+TTF2PT1_VERSION\s+\"(.*)\"/ ) { - $release = "version $1"; - } - } - close(VERFILE); - if( $release =~ /SNAP-([0-9][0-9])([0-9][0-9])([0-9][0-9])/ ) { - $date = sprintf("%s %d, 20%02d", $mons[$2-1], $3, $1); - } elsif( open(CFILE, "<$maindir/CHANGES.html") ) { - while(<CFILE>) { - if( /\<H4\>/) { - last; - } - } - $_ = <CFILE>; - chomp; - if( $_ =~ s/^.*?-- // ) { - $date = $_; - } - close(CFILE); - } -} - -if($release eq "") { - if( open(VERFILE, "<../Makefile") ) { - while(<VERFILE>) { - if( /^VERSION\s+=\s+(.*)/ ) { - $release = "version $1"; - } - } - close(VERFILE); - } -} - -if($release eq "") { - $release = "current"; -} -if($date eq "") { - @lt = localtime(time); - $date = sprintf("%s %d, %d", $mons[$lt[4]], $lt[3], 1900+$lt[5]); -} - -#printf(STDERR "date=%s release=%s\n", $date, $release); - -$writemode = 0; - -while(<STDIN>) { - if( s/^\<\!\-\- \=(\S+)\s+//) { - $cmd = $1; - s/\s*\-\-\>\s*$//; - #printf(STDERR "cmd=%s args=%s\n", $cmd, $_); - if($cmd =~ /^=/) { - if($writemode) { - $text{$tosect} .= "\n\n$cmd $_\n\n"; - } - } elsif($cmd eq "defdoc") { - @sl = split; - push(@allids, $sl[0]); - $file{$sl[0]} = $sl[1]; - $mansect{$sl[0]} = $sl[2]; - } elsif($cmd eq "section") { - # tosect includes the file id - $tosect = $_; - $text{$tosect} .= "\n\n"; - $writemode = 1; - } elsif($cmd eq "stop") { - $writemode = 0; - $text{$tosect} .= "\n"; - } elsif($cmd eq "cont") { - $writemode = 1; - } elsif($cmd eq "text") { - if($writemode) { - s/\<\;/</gi; - s/\>\;/>/gi; - s/\&\;/\&/gi; - $text{$tosect} .= "$_\n"; - } - } - } elsif($writemode) { -# s/^\s+//; - - s/\{/\&lbr;/g; - s/\}/\&rbr;/g; - - s/\<br\>/\n\n/gi; - #s/\<blockquote\>/\n\n=over 4\n\n/gi; - #s/\<\/blockquote\>/\n\n=back\n\n/gi; - s/\<ul\>/\n\n=over 4\n\n/gi; - s/\<\/ul\>/\n\n=back\n\n/gi; - s/\<li\>\s*/\n\n=item \*\n\n/gi; - - s/\<dl\>/\n\n=over 4\n\n/gi; - s/\<\/dl\>/\n\n=back\n\n/gi; - s/\<dt\>\s*/\n\n=item \*\n\n/gi; - s/\<dd\>\s*/\n\n/gi; - - s/\<i\>(.*?)\<\/i\>/I\{\1\}/gi; - s/\<em\>(.*?)\<\/em\>/I\{\1\}/gi; - s/\<b\>(.*?)\<\/b\>/B\{\1\}/gi; - s/\<tt\>(.*?)\<\/tt\>/C\{\1\}/gi; - s/\<a href\=\.*?\>(.*?)\<\/a\>/F\{\1\}/gi; - s/\<h2\>summary\<\/h2\>//gi; - s/\<h2\>description\<\/h2\>//gi; - s/\<h2\>examples\<\/h2\>//gi; - s/\<h2\>options\<\/h2\>//gi; - s/\<h2\>(.*?)\<\/h2\>/B\{\1\}/gi; - s/\<.*?\>//g; - s/\{/\</g; - s/\}/\>/g; - - s/\ \;/S< >/gi; - s/\&\;/\&/gi; -# s/\<\;/E<lt>/gi; -# s/\>\;/E<gt>/gi; - s/\<\;/\</gi; - s/\>\;/\>/gi; - #s/\|/E<verbar>/g; - #s/\//E<sol>/g; - s/\&lbr\;/\{/g; - s/\&rbr\;/\}/g; - - #printf(STDERR "section=%s add=%s", $tosect, $_); - $text{$tosect} .= $_; - } -} - -@stdsect = ( - "NAME", - "SYNOPSIS", - "OPTIONS", - "DESCRIPTION", - "RETURN VALUE", - "ERRORS", - "EXAMPLES", - "ENVIRONMENT", - "FILES", - "SEE ALSO", - "NOTES", - "CAVEATS", - "DIAGNOSTICS", - "BUGS", - "RESTRICTIONS", - "AUTHOR", - "HISTORY" ); - -#printf(STDERR "allids= @allids\n"); -for $id (@allids) { - print(STDERR "creating man page $id $file{$id} $mansect{$id}\n\n"); - die "Unable to create pod file $dir/$file{$id}.pod" - unless open(PODF, ">./pod/$file{$id}.pod"); - print(PODF "=pod\n\n"); - for $sect (@stdsect) { - $sid = "$id $sect"; - #printf(STDERR "trying %s\n", $sid); - if(defined $text{$sid}) { - #printf(STDERR " section %s\n", $sid); - print(PODF "=head1 $sect\n\n$text{$sid}\n\n"); - } - } - print(PODF "=cut\n"); - close(PODF); - die "Unable to generate the man page $dir/$file{$id}.1" - if system("pod2man --section=\"$mansect{$id}\" --release=\"$release\" " - . "--center=\"SAORD Documentation\" --date=\"$date\" " - . "--name=\"$file{$id}\" " - . "./pod/$file{$id}.pod > $dir/man$mansect{$id}/$file{$id}.$mansect{$id}"); - - unlink("$dir/$file{$id}.pod"); -} diff --git a/xpa/doc/html2ps.dbg b/xpa/doc/html2ps.dbg deleted file mode 100644 index 2c7bc86..0000000 --- a/xpa/doc/html2ps.dbg +++ /dev/null @@ -1,94 +0,0 @@ -***** html2ps version 1.0 beta5 -***** Command: /proj/rd/linux64/bin/html2ps -C fb -d -g -n -u -W b -x 1 -o xpa.ps help.html -***** Perl: 5.010001 -***** HTML2PSPATH= -***** Global file /proj/rd/linux64/lib/html2ps/html2psrc: -/* Global configuration file for html2ps */ - -@html2ps { - package { - ImageMagick: 1; - djpeg: 1; - TeX: 1; - dvips: 1; - Ghostscript: 1; - libwww-perl: 1; - path: "/usr/bin"; - } - paper { - type: letter; - } - hyphenation { - en { - file: "/proj/rd/linux64/lib/html2ps/hyphen.tex"; - } - } -} -***** -html2ps version 1.0 beta5 -Reading help.html -Link: intro.html -Link: template.html -Link: info.html -Link: method.html -Link: inet.html -Link: users.html -Link: programs.html -Link: xpamb.html -Link: xpans.html -Link: server.html -Link: oom.html -Link: client.html -Link: xt.html -Link: tcl.html -Link: env.html -Link: acl.html -Link: changelog.html -Link: examples.html -Link: changes.html -Link: convert.html -Link: name.html -At least 21 documents remaining -Reading intro.html -At least 20 documents remaining -Reading template.html -At least 19 documents remaining -Reading info.html -At least 18 documents remaining -Reading method.html -At least 17 documents remaining -Reading inet.html -At least 16 documents remaining -Reading users.html -At least 15 documents remaining -Reading programs.html -At least 14 documents remaining -Reading xpamb.html -At least 13 documents remaining -Reading xpans.html -At least 12 documents remaining -Reading server.html -At least 11 documents remaining -Reading oom.html -At least 10 documents remaining -Reading client.html -At least 9 documents remaining -Reading xt.html -At least 8 documents remaining -Reading tcl.html -At least 7 documents remaining -Reading env.html -At least 6 documents remaining -Reading acl.html -At least 5 documents remaining -Reading changelog.html -At least 4 documents remaining -Reading examples.html -At least 3 documents remaining -Reading changes.html -At least 2 documents remaining -Reading convert.html -At least 1 document remaining -Reading name.html -Inserting cross references - diff --git a/xpa/doc/inet.html b/xpa/doc/inet.html deleted file mode 100644 index 3155885..0000000 --- a/xpa/doc/inet.html +++ /dev/null @@ -1,260 +0,0 @@ -<!-- =defdoc xpainet xpainet n --> -<HTML> -<HEAD> -<TITLE>XPA Communication Between Hosts</TITLE> -</HEAD> -<BODY> - -<!-- =section xpainet NAME --> -<H2><A NAME="xpainet">XPAInet: XPA Communication Between Hosts</A></H2> - -<!-- =section xpainet SYNOPSIS --> -<H2>Summary</H2> -XPA uses standard inet sockets to support communication between two or -more host computers. - -<!-- =section xpainet DESCRIPTION --> -<H2>Description</H2> -<P> -When the <A HREF="./method.html">Communication Method</A> is set to -<B>inet</B> (as it is by default), XPA can be used to communicate -between different computers on the Internet. INET sockets utilize the -IP address of the given machine and a (usually random) port number to -communicate between processes on the same machine or between different -machines on the Internet. These standard Internet sockets are also -used by programs such as Netscape, ftp. etc. - -<P> -XPA supports a host-based <A HREF="./acl.html">Access Control</A> mechanism -to prevent unauthorized access of XPA access points by other computers -on the Net. By default, only the machine on which the XPA server is -running can access XPA services. Therefore, setting up communication -between a local XPA server machine and a remote client machine -requires a two-part registration process: - -<UL> -<LI> the XPA service on the local machine must be made known to the -remote machine -<LI> the remote machine must be given permission to access the local -XPA service -</UL> - -Three methods by which this remote registration can be accomplished -are described below. - -<H2>Manual Registration</H2> - -The first method is the most basic and does not require the remote -client to have xpans running. To use it, the local server simply -gives a remote client machine access to one or more XPA access points -using xpaset and the <B>-acl</B> sub-command. For example, -consider the XPA test program "stest" running on a local machine. By -default the access control for the access point named "xpa" is -restricted to that machine: -<PRE> - [sh]$ xpaget xpa -acl - *:* 123.456.78.910 gisa - *:* localhost gisa -</PRE> -Using xpaset and the <B>-acl</B> sub-command, a remote client -machine can be given permission to perform xpaget, xpaset, xpaaccess, -or xpainfo operations. For example, to allow the xpaget operation, the -following command can be issued on the local machine: -<PRE> - [sh]$ xpaset -p xpa -acl "remote_machine g" -</PRE> -This results in the following access permissions on the local machine: -<PRE> - [sh]$ xpaget xpa -acl - XPA:xpa 234.567.89.012 g - *:* 123.456.78.910 gisa - *:* localhost gisa -</PRE> - -The remote client can now use the local server's xpans name server to -establish communication with the local XPA service. This can be done -on a call-by-call basis using the <B>-i</B> switch on xpaset, xpaget, etc: -<PRE> - [sh]$ xpaget -i "local_machine:12345" xpa - class: XPA - name: xpa - method: 88877766:2778 - sendian: little - cendian: big -</PRE> -Alternatively, the XPA_NSINET variable on the remote machine can be -set to point directly to xpans on the local machine, removing -the need to override this value each time an XPA program is run: -<PRE> - [csh]$ setenv XPA_NSINET 'karapet:$port' - [csh]$ xpaget xpa - class: XPA - name: xpa - method: 88877766:2778 - sendian: little - cendian: big -</PRE> -Here, '$port' means to use the default XPA name service port (14285). -not a port environment variable. - -<p> -Access permission for remote client machines can be stored in a file -on the local machine pointed to by the <B>XPA_ACLFILE</B> environment -variable or using the <B>XPA_DEFACL</B> environment variable. See <A -HREF="./acl.html">XPA Access Control</A> for more information. - -<H2>Remote Registration</H2> - -If xpans is running on the remote client machine, then a local xpaset -command can be used with the <B>-remote</B> sub-command to -register the local XPA service in the remote name service, while at -the same time giving the remote machine permission to access the local -service. For example, assume again that "stest" is running on the -local machine and that xpans is also running on the remote machine. -To register access of this local xpa on the remote machine, use -the xpaset and the <B>-remote</B> sub-command: -<PRE> - [sh]$ ./xpaset -p xpa -remote 'remote_machine:$port' + -</PRE> -To register the local xpa access point on the remote machine with xpaget -access only, execute: -<PRE> - [sh]$ ./xpaset -p xpa -remote 'remote_machine:$port' g -</PRE> -Once the remote registration command is executed, the remote client -machine will have an entry such as the following in its own xpans name -service: -<PRE> - [csh]$ xpaget xpans - XPA xpa gs 88877766:2839 eric -</PRE> -The xpa access point can now be utilized on the remote machine without -further setup: -<PRE> - [csh]$ xpaget xpa - class: XPA - name: xpa - method: 838e2f68:2839 - sendian: little - cendian: big -</PRE> -To unregister remote access from the local machine, use the same -command but with a '-' argument: -<PRE> - [sh]$ xpaset -p xpa -remote 'remote_machine:$port' - -</PRE> -The benefit of using remote registration is that communication with -remote access points can be mixed with that of other access points -on the remote machine. Using <A HREF="./template.html">Access Point -Names and Templates</A>, one XPA command can be used to send or -receive messages to the remote and local services. - -<H2>XPANS Proxy Registration</H2> - -The two methods described above are useful when the local and remote -machines are able to communicate freely to one another. This would be -the case on most Local Area Networks (LANs) where all machines are -behind the same firewall and there is no port blocking between -machines on the same LAN. The situation is more complicated when the -XPA server is behind a firewall, where outgoing connections are -allowed, but incoming port blocking is implemented to prevent machines -outside the firewall from connecting to machines inside the -firewall. Such incoming port blocking will prevent xpaset and xpaget -from connecting to an XPA server inside a firewall. - -<P> -To allow locally fire-walled XPA services to register with remote -machines, we have implemented a proxy service within the xpans name -server. To register remote proxy service, xpaset and the -<B>-remote</B> sub-command is again used, but with an additional -<B>-proxy</B> argument added to the end of the command: -<PRE> - [sh]$ ./xpaset -p xpa -remote 'remote_machine:$port' g -proxy -</PRE> -Once a remote proxy registration command is executed, the remote -machine will have an entry such as the following in its own xpans name -service: -<PRE> - [csh]$ xpaget xpans - XPA xpa gs @88877766:2839 eric -</PRE> -The '@' sign in the name service entry indicates that xpans proxy -processing is being used for this access point. Other than that, from -the user's point of view, there is no difference in how this XPA -access point is contacted using XPA programs (xpaset, xpaget, etc.) or -libraries: -<PRE> - [csh]$ xpaget xpa - class: XPA - name: xpa - method: 88877766:3053 - sendian: little - cendian: big -</PRE> -<P> -Of course, the underlying processing of the XPA requests is very much -different when xpans proxy is involved. Instead of an XPA program such -contacting the XPA service directly, it contacts the local xpans. -Acting as a proxy server, xpans communicates with the XPA service -using the command channel established at registration time. Commands -(including establishing a new data channel) are sent between xpans and -the XPA service to set up a new message transfer, and then data is fed -to/from the xpa request, through xpans, from/to the XPA service. In -this way, it can be arranged so that connections between the -fire-walled XPA service and the remote client are always initiated by -the XPA service itself. Thus, incoming connections that would be -blocked by the firewall are avoided. Note that there is a performance -penalty for using the xpans/proxy service. Aside from extra overhead -to set up proxy communication, all data must be sent through the -intermediate proxy process. - -<P> -The xpans proxy scheme requires that the remote client allow the local -XPA server machine to connect to the remote xpans/proxy server. If the -remote client machine also is behind a port-blocking firewall, such -connections will be disallowed. In this case, the only solution is to -open up some ports on the remote client machine to allow incoming -connections to xpans/proxy. Two ports must be opened (for command and -data channel connections). By default, these two ports are 14285 and -14287. The port numbers can be changed using the <B>XPA_NSINET</B> -environment variable. This variable takes the form: -<PRE> - setenv XPA_NSINET machine:port1[,port2[,port3]] -</PRE> -where port1 is the main connecting port, port2 is the XPA access port, -and port3 is the secondary data connecting port. The second and third -ports are optional and default to port1+1 and port1+2, respectively. -It is port1 and port3 that must be left open for incoming connections. - -<P> -For example, to change the port assignments so that xpans listens -for registration commands on port 12345 and data commands on port 28573: -<PRE> - setenv XPA_NSINET myhost:12345 -</PRE> -Alternatively, all three ports can be assigned explicitly: -<PRE> - setenv XPA_NSINET remote:12345,3000,12346 -</PRE> -In this case 12345 and 12346 should be open for incoming connections. -The XPA access port (which need not be open to the outside -world) is set to 3000. - -<P> -Finally, note that we currently have no mechanism to cope with -Internet proxy servers (such as SOCKS servers). If an XPA service is -running on a machine that cannot connect directly to outside machines, -but goes through a proxy server instead, there currently is no way to -register that XPA service with a remote machine. We hope to implement -support for SOCKS proxy in a future release. - -<!-- =section xpainet 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> diff --git a/xpa/doc/info.html b/xpa/doc/info.html deleted file mode 100644 index 75837bd..0000000 --- a/xpa/doc/info.html +++ /dev/null @@ -1,193 +0,0 @@ -<!-- =defdoc xpacommon xpacommon n --> -<HTML> -<HEAD> -<TITLE>Getting Common Information About Access Points</TITLE> -</HEAD> -<BODY> - -<!-- =section xpacommon NAME --> -<H2><A NAME="xpacommon">XPACommon: Getting Common Information About Access Points</A></H2> - -<!-- =section xpacommon SYNOPSIS --> -<H2>Summary</H2> -<P> -There are various kinds of generic information you can retrieve about -an XPA access point by using the xpaget command. - -<!-- =section xpacommon DESCRIPTION --> -<H2>Description</H2> -<P> -You can find out which XPA access points have been registered with -the currently running -<A HREF="./xpans.html">XPA name server</A> -by executing the -<A HREF="./programs.html#xpaget">xpaget</A> -command to retrieve info from the XPA name server: -<PRE> - xpaget xpans -</PRE> -If, for example, the -<A HREF="./examples.html">stest</A> test server program -is running, the following XPA access points will be returned (the specifics -of the returned info will vary for different machines and users): -<PRE> - XPA xpa gs 838e2f67:1262 eric - XPA xpa1 gs 838e2f67:1266 eric - XPA c_xpa gs 838e2f67:1267 eric - XPA i_xpa i 838e2f67:1268 eric -</PRE> -Note that access to this information is subject to the usual -<A HREF="./acl.html">XPA Access Control</A> restrictions. - -<P> -Each XPA access point supports a number of reserved sub-commands that provide -access to different kinds of information, e.g. the access control for -that access point. These sub-commands can be executed by using -<A HREF="./programs.html#xpaset">xpaset</A> -or -<A HREF="./programs.html#xpaget">xpaget</A> -at the command line, or -<A HREF="./client.html#xpaget">XPAGet()</A> -or -<A HREF="./client.html#xpaset">XPASet()</A> -in programs, e.g: -<PRE> - xpaget ds9 -acl - xpaget ds9 -help - xpaget ds9 env FOO - - xpaset -p ds9 env FOO foofoo -</PRE> -With the exception of <B>-help</B> and <B>-version</B>, reserved -sub-commands are available only on the machine on which the XPA server -itself is running. - -The following reserved sub-commands are defined for all access points: -<DL> - -<P> -<DT><B>-acl</B> get (set) the access control list [options: host type acl, for set] -<DD> -The 'xpaset' option allows you to add a new acl for a given host, or change -the acl for an existing host. See -<A HREF="./acl.html">XPA Access Control</A> -for more information. -This access point is available only on the server machine. - -<P> -<DT><B>-env</B> get (set) an environment variable [options: name (value, for set)] -<DD> -The 'xpaget' option will return the value of the named environment -variable. The 'xpaset' option will set the value of the names -variable to the specified value. -This access point is available only on the server machine. -(Please be advised that we have had problems setting environment -variables in static Tcl/Tk programs such as ds9 running under Linux.) - -<P> -<DT> <B>-clipboard</B> set(get) information on a named clipboard -<DD> Clients can store ASCII state information on any number of named -clipboards. Clipboards of the same name created by clients on -different machines are kept separate. The syntax for creating a -clipboard is: -<PRE> - [data] | xpaset [server] -clipboard add|append [clipboard_name] - xpaset -p [server] -clipboard delete [clipboard_name] -</PRE> -Use "add" to create a new clipboard or replace the contents of an existing -one. Use "append" to append to an existing clipboard. -<P> -Information on a named clipboard is retrieved using: -<PRE> - xpaget [server] -clipboard [clipboard_name] -</PRE> -<P> -<DT><B>-exec</B> set: execute commands from buffer [options: none] -<DD> -If -exec is specified in the paramlist of an 'xpaset' call, then further -sub-commands will be retrieved from the data buffer. - -<P> -<DT><B>-help</B> get: return help string for this XPA or sub-command [options: name (for sub-commands)] -<DD> -Each XPA access point and each XPA sub-command can have a help string -associated with it that is specified when the access point is defined. -The -help option will return this help string. For XPA access points -that contain user-defined sub-commands, you can get the help string -for a particular sub-command by specifying its name, or else get the -help strings for all sub-commands if not name is specified. - -<P> -<DT><B>-ltimeout</B> get (set) the long timeout value [options: seconds|reset] -<DD> -The 'xpaget' option will return the value of the long timeout (in seconds). -The 'xpaset' option will set the value of the long timeout. If "reset" is -specified, then the timeout value will be reset to the default value. - -<P> -<DT><B>-nsconnect</B> set: re-establish name server connection to all XPA's [options: none] -<DD> -If the -<A HREF="./xpans.html">XPA Name Server (xpans)</A> -process has terminated unexpectedly and then re-started, this -sub-command can be used to re-establish the connection. You use it by -sending the command to the [name:port] or [file] of the access point -instead of to the XPA name (since the latter requires the xpans -connection!): -<PRE> - xpaset -p 838e2f67:1268 -nsconnect -</PRE> -See <A HREF="./xpans.html">xpans</A> for more information. - -<P> -<DT><B>-nsdisconnect</B> set: break name server connection to all XPA's [options: none] -<DD> -This sub-command will terminate the connection to the -<A HREF="./xpans.html">XPA Name Server (xpans)</A>, thereby making -all access points inaccessible except through their underlying [name:port] -or [file] identifiers. I forget why we added it, it seems pretty useless. - -<P> -<DT><B>-stimeout</B> get (set) the short timeout value [options: seconds|reset] -<DD> -The 'xpaget' option will return the value of the short timeout (in seconds). -The 'xpaset' option will set the value of the short timeout. If "reset" is -specified, then the timeout value will be reset to the default value. - -<P> -<DT><B>-remote</B> set: register xpa with remote server [options: host[:port] [acl]] [-proxy] -<DD> -This sub-command will register the XPA access point with the XPA name -server (xpans) on the specified host (which must already be running). -The specified host also is given access control to the access point, -using the specified acl or the default acl of "+" (meaning the remote -host can xpaset, xpaget, xpainfo or xpaaccess). If the acl is -specified as "-", then the access point is unregistered. -See <A HREF="./inet.html">Communication Between Machines</A> -for more information on how this sub-command is used. - -<P> -<DT><B>-version</B> get: return XPA version string [options: none] -<DD> -The version refers to the version of XPA used to define this access point -(currently something like 2.0). - -</DL> - -<P> -You can add your own reserved commands to all XPA access points by using the -<A HREF="./server.html#xpacmdadd">XPACmdAdd()</A> -routine, passing the XPA handle returned by <EM>XPA XPAGetReserved(void)</EM> -as the first argument. Note again that these will only be available on the -machine where the XPA service is running. - -<!-- =section xpacommon 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> diff --git a/xpa/doc/intro.html b/xpa/doc/intro.html deleted file mode 100644 index f9c9947..0000000 --- a/xpa/doc/intro.html +++ /dev/null @@ -1,148 +0,0 @@ -<!-- =defdoc xpaintro xpaintro n --> -<HTML> -<HEAD> -<TITLE>Introduction to XPA</TITLE> -</HEAD> -<BODY> - -<!-- =section xpaintro NAME --> -<H2><A NAME="xpaintro">XPAIntro: Introduction to the XPA Messaging System</A></H2> - -<!-- =section xpaintro SYNOPSIS --> -<H2>Summary</H2> -<P> -A brief introduction to the XPA messaging system, which provides -seamless communication between all kinds of Unix event-driven -programs, including X programs, Tcl/Tk programs, and Perl programs. - -<!-- =section xpaintro DESCRIPTION --> -<H2>Description</H2> -<P> -The XPA messaging system provides seamless communication between all -kinds of Unix programs, including X programs, Tcl/Tk programs, and -Perl programs. It also provides an easy way for users to communicate -with these XPA-enabled programs by executing XPA client commands in -the shell or by utilizing such commands in scripts. Because XPA works -both at the programming level and the shell level, it is a powerful -tool for unifying any analysis environment: users and programmers have -great flexibility in choosing the best level or levels at which to -access XPA services, and client access can be extended or modified -easily at any time. - -<P> -A program becomes an XPA-enabled server by defining named points of -public access through which data and commands can be exchanged with -other client programs (and users). Using standard TCP sockets as -a transport mechanism, XPA supports both single-point and broadcast -messaging to and from these servers. It supports direct communication -between clients and servers, or indirect communication via an -intermediate message bus emulation program. Host-based access control -is implemented, as is as the ability to communicate with XPA servers -across a network. - -<P> -XPA implements a layered interface that is designed to be useful both -to software developers and to users. The interface consists of a -library of XPA client and server routines for use in programs and a -suite of high-level user programs built on top of these libraries. -Using the XPA library, access points can be added to -<A HREF="./tcl.html#">Tcl/Tk</A> -programs, -<A HREF="./xt.html#">Xt</A> -programs, or to Unix programs that use the XPA event loop or any -event loop based on select(). Client access subroutines can be added -to any Tcl/Tk or Unix program. Client access also is supported at the -command line via a suite of high-level programs. - -<P> -The major components of the XPA layered interface are: -<UL> -<LI> -A set of XPA server routines, centered on -<A HREF="./server.html#xpanew">XPANew(),</A> -which are used by XPA server programs to tag public access points with -string identifiers and to register send and receive callbacks for -these access points. - -<LI> -A set of XPA client routines, centered on the -<A HREF="./client.html#xpaset">XPASet()</A> -and -<A HREF="./client.html#xpaget">XPAGet(),</A> -which are used by external client applications to exchange data and -commands with an XPA server. - -<LI> -High-level programs, centered on -<A HREF="./programs.html#xpaset">xpaset</A> -and -<A HREF="./programs.html#xpaget">xpaget,</A> -which allow data -and information to be exchanged with XPA server programs from the -command line and from scripts. These programs have the command syntax: -<PRE> - [data] | xpaset <XPA name> [qualifiers ...] - xpaget <XPA name> [qualifiers ...] -</PRE> -<LI> -An XPA name server program, -<A HREF="./xpans.html">xpans,</A> -through which XPA access point names are -registered by servers and distributed to clients. -</UL> - -<P> -Defining an XPA access point is easy: a server application calls -<A HREF="./server.html#xpanew">XPANew(),</A> -<A HREF="./server.html#xpacmdnew">XPACmdNew(),</A> -or the experimental -<A HREF="./server.html#xpainfonew">XPAInfoNew()</A> -routine to -create a named public access point. An XPA service can specify "send" -and "receive" callback procedures (or an "info" procedure in the case -of XPAInfoNew()) to be executed by the program when an external -process either sends data or commands to this access point or requests -data or information from this access point. Either of the callbacks -can be omitted, so that a particular access point can be specified as -read-only, read-write, or write-only. Application-specific client -data can be associated with these callbacks. Having defined one or -more public access points in this way, an XPA server program enters -its usual event loop (or uses the standard XPA event loop). - -<P> -Clients communicate with these XPA public access points -using programs such as -<A HREF="./programs.html#xpaget">xpaget</A>, -<A HREF="./programs.html#xpaset">xpaset</A>, and -<A HREF="./programs.html#xpainfo">xpainfo</A> -(at the command line), -or routines such as -<A HREF="./client.html#xpaget">XPAGet(),</A> -<A HREF="./client.html#xpaset">XPASet(),</A> -and -<A HREF="./client.html#xpainfo">XPAInfo()</A> -within a program. Both methods require specification of the name of -the access point. The xpaget program returns data or other -information from an XPA server to its standard output, while the -xpaset program sends data or commands from its standard input to an -XPA application. The corresponding API routines set/get data to/from -memory, returning error messages and other info as needed. If a -<A HREF="./template.html">template</A> -is used to specify the access point name (e.g., "ds9*"), then -communication will take place with all servers matching that template. - -<p> -Please note that XPA currently is not thread-safe. All XPA calls must be -in the same thread. - -<!-- =section xpaintro 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: March 10, 2007</H5> -</BODY> -</HTML> - diff --git a/xpa/doc/method.html b/xpa/doc/method.html deleted file mode 100644 index d85fc89..0000000 --- a/xpa/doc/method.html +++ /dev/null @@ -1,90 +0,0 @@ -<!-- =defdoc xpamethod xpamethod n --> -<HTML> -<HEAD> -<TITLE>XPA Communication Methods</TITLE> -</HEAD> -<BODY> - -<!-- =section xpamethod NAME --> -<H2><A NAME="xpamethod">XPAMethod: </A>XPA Communication Methods</H2> - -<!-- =section xpamethod SYNOPSIS --> -<H2>Summary</H2> -<P> -XPA supports both inet and unix (local) socket communication. - -<!-- =section xpamethod DESCRIPTION --> -<H2>Description</H2> -<P> -XPA uses sockets for communication between processes. It supports -three methods of socket communication: inet, localhost, and unix. In -general, the same method should be employed for all XPA processes in a -session and the global environment variable XPA_METHOD should be used -to set up the desired method. By default, the preferred method is -"inet", which is appropriate for most users. You can set up a -different method by typing something like: -<PRE> - setenv XPA_METHOD local # unix csh - XPA_METHOD=local; export XPA_METHOD # unix sh, bash, windows/cygwin - set XPA_METHOD=localhost # dos/windows -</PRE> -The options for XPA_METHOD are: <B>inet</B>, <B>unix</B> (or -<B>local</B>), and <B>localhost</B>. On Unix machines, this -environment setup command can be placed in your shell init file -(.cshrc, .profile, .bashrc, etc.) On Windows platforms, it can be -placed in your AUTOEXEC.BAT file (I think!). - -<P> -By default, <B>inet</B> sockets are used by XPA. These are the standard -Internet sockets that are used by programs such as Netscape, -ftp. etc. Inet sockets utilize the IP address of the given machine and -a (usually random) port number to communicate between processes on the -same machine or between different machines on the Internet. (Note that -XPA has an <A HREF="./acl.html">Access Control</A> mechanism to -prevent unauthorized access of XPA access points by other computers on -the Net). For users connected to the Internet, this usually is the -appropriate communication method. For more information about setting -up XPA communication between machines, see -<A HREF="./inet.html">Communication Between Machines</A>. - -<P> -In you are using XPA on a machine without an Internet connection, then -inet sockets are not appropriate. In fact, an XPA process often will -hang for many seconds while waiting for a response from the Domain -Name Service (DNS) when using inet sockets. Instead of inet sockets, -users on Unix platforms can also use <B>unix</B> sockets (also known -as local sockets). These sockets are based on the local file system -and do not make use of the DNS. They generally are considered to be -faster than inet sockets, but they are not implemented under -Windows. Use local sockets as a first resort if you are on a Unix -machine that is not connected to the Internet. - -<P> -Users not connected to the Internet also can use <B>localhost</B> -sockets. These are also inet-type sockets but the IP address used for -the local machine is the <B>localhost</B> address, 0x7F000001, instead -of the real IP of the machine. Depending on how sockets are set up for -a given platform, communication with the DNS usually is not required in -this case (though of course, XPA cannot interact with other machines). -The localhost method will generally work on both Unix and Windows -platforms, but whether the DNS is required or not is subject to -individual configurations. - -<P> -A final warning/reminder: if your XPA-enabled server hangs at startup -time and your XPA_METHOD is <B>inet</B>, the problem probably is -related to an incorrect Internet configuration. This can be confirmed -by using the <B>unix</B> method or (usually) the <B>localhost</B> -method. You can use these alternate methods if other hosts do not need -access to the XPA server. - -<!-- =section xpamethod 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> diff --git a/xpa/doc/name.html b/xpa/doc/name.html deleted file mode 100644 index 5269378..0000000 --- a/xpa/doc/name.html +++ /dev/null @@ -1,48 +0,0 @@ -<!-- =defdoc xpaname xpaname n --> -<HTML> -<HEAD> -<TITLE>What does XPA stand for?</TITLE> -</HEAD> -<BODY> - -<!-- =section xpaname NAME --> -<H2><A NAME="xpaname">XPAName: What does XPA stand for?</A></H2> - -<!-- =section xpaname SYNOPSIS --> -<H2>Summary</H2> -<P> -What does XPA stand for? Who knows anymore! - -<!-- =section xpaname DESCRIPTION --> -<H2>Description</H2> -<P> -What does XPA stand for? Dunno! The XPA messaging system originally -was built on top of the X Window System and XPA was the mnemonic for -<EM>X Public Access</EM>, to emphasize that we were providing public -access to previously private data and algorithms in Xt programs. Now -that XPA no longer is tied to X, it can be argued that we ought to -change the name (how about <EM>SPAM: simple public access mechanism -</EM>), but XPA is in wide-spread use in the astronomical community of -its birth, and the name has taken on a life of its own. If anyone can -think of what XPA now means, please let us know. - -<P> -If you think this is bad, consider the MMT Telescope on Mount Hopkins, -Arizona. When first installed twenty years ago, it featured an array -of six 72-inch diameter mirrors. from which came its name: the -<EM>Multiple Mirror Telescope</EM>. In spring of 1999, these mirrors -were replaced by a single 21 and 1/2 -foot diameter primary mirror, -the largest single-piece glass reflector on the North American -continent. And now MMT stands for ... MMT! - -<!-- =section xpaname 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> - diff --git a/xpa/doc/oom.html b/xpa/doc/oom.html deleted file mode 100644 index 360740e..0000000 --- a/xpa/doc/oom.html +++ /dev/null @@ -1,52 +0,0 @@ -<!-- =defdoc xpaoom xpaoom n --> -<HTML> -<HEAD> -<TITLE>Out of Memory</TITLE> -</HEAD> -<BODY> - -<!-- =section xpaoom NAME --> -<H2><A NAME="xpaoom">Xpaoom: What happens when XPA runs out of memory?</A></H2> - -<!-- =section xpaoom SYNOPSIS --> -<H2>Summary</H2> -<P> -When XPA can't allocate memory, it exits. You can arrange to have it call -longjmp() instead. - -<!-- =section xpaoom DESCRIPTION --> -<H2>Description</H2> -<P> -When an XPA server or client cannot allocate memory, it will attempt to -output an error message and then exit. If this is not satisfactory (e.g., -perhaps your program is interactive and can recover from OOM errors), you -can tell XPA to call longjmp() to go to a recovery branch. To pass the -requisite jmp_buf variable to XPA, make the following call: -<PRE> - XPASaveJmp(void *env); -</PRE> -The value of env is the address of a jmp_buf variable that was previously -passed to setjmp(). For example: -<PRE> - jmp_buf env; - ... - if( setjmp(jmp_buf) != 0 ){ - /* out of memory -- take corrective action, if possible */ - } else { - /* save env for XPA */ - XPASaveJmp((void *)&jmp_buf); - } - // enter main loop ... -</PRE> - -<!-- =section xpaoom 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: April 7, 2009</H5> -</BODY> -</HTML> - diff --git a/xpa/doc/pod/xpa.pod b/xpa/doc/pod/xpa.pod deleted file mode 100644 index 7787d4b..0000000 --- a/xpa/doc/pod/xpa.pod +++ /dev/null @@ -1,399 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPA: Public Access to Data and Algorithms> - - - -=head1 SYNOPSIS - - - - -This document is the Table of Contents for XPA. - - - -=head1 DESCRIPTION - - - - - -The XPA messaging system provides seamless communication between many -kinds of Unix programs, including X programs and Tcl/Tk programs. It -also provides an easy way for users to communicate with XPA-enabled -programs by executing XPA client commands in the shell or by utilizing -such commands in scripts. Because XPA works both at the programming -level and the shell level, it is a powerful tool for unifying any -analysis environment: users and programmers have great flexibility in -choosing the best level or levels at which to access XPA services, and -client access can be extended or modified easily at any time. - - -A program becomes an XPA-enabled server by defining named points of -public access through which data and commands can be exchanged with -other client programs (and users). Using standard TCP sockets as a -transport mechanism, XPA supports both single-point and broadcast -messaging to and from these servers. It supports direct communication -between clients and servers, or indirect communication via an -intermediate message bus emulation program. Host-based access control -is implemented, as is as the ability to communicate with XPA servers -across a network. - - -XPA implements a layered interface that is designed to be useful both -to software developers and to users. The interface consists of a -library of XPA client and server routines for use in C/C++ programs and -a suite of high-level user programs built on top of these libraries. -Using the XPA library, access points can be added to Tcl/Tk programs, -Xt programs, or to Unix programs that use the XPA event loop or any -event loop based on select(). Client access subroutines can be added -to any Tcl/Tk, Xt, or Unix program. Client access also is supported at -the command line via a suite of high-level programs. - - -Choose from the following topics: - - - -=over 4 - - - - -=item * - -Introduction to XPA -[xpaintro(n)] - - -=item * - -Access Point Names and Templates -[xpatemplate(n)] - - -=item * - -Getting Common Information About Access Points -[xpacommon(n)] - - -=item * - -Communication Methods -[xpamethod(n)] - - -=item * - -Communication Between Hosts -[xpainet(n)] - - -=item * - -Distinguishing Users -[xpausers(n)] - - - -=item * - -XPA User Programs - - -=over 4 - - - - -=item * - -xpaget: get data and info -[xpaget(1)] - - -=item * - -xpaset: send data and info -[xpaset(1)] - - -=item * - -xpainfo: send info alert -[xpainfo(1)] - - -=item * - -xpaaccess: get access point info -[xpaaccess(1)] - - -=item * - -xpamb: message bus emulation -[xpamb(1)] - - -=item * - -xpans: the XPA name server -[xpans(1)] - - -=back - - - - - -=item * - -XPA Server Routines - - -=over 4 - - - - -=item * - -XPANew: define a new access point -[xpanew(3)] - - -=item * - -XPACmdNew: define a new command access point -[xpacmdnew(3)] - - -=item * - -XPACmdAdd: add a command -[xpacmdadd(3)] - - -=item * - -XPACmdDel: delete a command -[xpacmddel(3)] - - -=item * - -XPAInfoNew: define an info access point -[xpainfonew(3)] - - -=item * - -XPAFree: free an access point -[xpafree(3)] - - -=item * - -XPAMainLoop: event loop for select server -[xpamainloop(3)] - - -=item * - -XPAPoll: poll for XPA events -[xpapoll(3)] - - -=item * - -XPACleanup: release reserved XPA memory -[xpacleanup(3)] - - -=item * - -XPA Server Macros: accessing structure internals -[xpamacros(3)] - - -=item * - -XPA Race Conditions: how to avoid them -[xparace(3)] - - -=item * - -XPA Out of Memory (OOM) errors -[xpaoom(3)] - - -=back - - - - - -=item * - -XPA Client Routines - - -=over 4 - - - - -=item * - -XPAOpen: open a persistent client connection -[xpaopen(3)] - - -=item * - -XPAClose: close persistent client connection -[xpaclose(3)] - - -=item * - -XPAGet: get data -[xpaget(3)] - - -=item * - -XPASet: send data or commands -[xpaset(3)] - - -=item * - -XPAInfo: send an info alert -[xpainfo(3)] - - -=item * - -XPAGetFd: get data and write to an fd -[xpagetfd(3)] - - -=item * - -XPASetFd: read data from and fd and send -[xpasetfd(3)] - - -=item * - -XPANSLookup: look up an access point -[xpanslookup(3)] - - -=item * - -XPAAccess: get access info -[xpaaccess(3)] - - -=item * - -The XPA/Xt Interface: Xt interface to XPA -[xpaxt(n)] - - -=item * - -The XPA/Tcl Interface: Tcl interface to XPA -[xpatcl(n)] - - -=back - - - - - -=item * - -Tailoring the XPA Environment - - -=over 4 - - - - -=item * - -Environment Variables -[xpaenv(n)] - - -=item * - -Access Control -[xpaacl(n)] - - -=back - - - - - -=item * - -Miscellaneous - - -=over 4 - - - - - -=item * - -Where to Find Example/Test Code - - -=item * - -User Changes Between XPA 1.0 and 2.0 - - -=item * - -API Changes Between XPA 1.0 and 2.0 - - -=item * - -What Does XPA Stand For, Anyway? - - -=back - - - - - -=back - - - - - - -=cut diff --git a/xpa/doc/pod/xpaaccess.pod b/xpa/doc/pod/xpaaccess.pod deleted file mode 100644 index ab34b9b..0000000 --- a/xpa/doc/pod/xpaaccess.pod +++ /dev/null @@ -1,102 +0,0 @@ -=pod - -=head1 NAME - - - -B<xpaaccess: see if template matches registered XPA access points> - - - -=head1 SYNOPSIS - - - - - -xpaaccess [-c] [-h] [-i nsinet] [-m method] [-n] [-t sval,lval] [-u users] -v <template> [type] - - - - - -=head1 OPTIONS - - - - - - -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 - - - - -=head1 DESCRIPTION - - - - -xpaaccess returns "yes" to stdout (with a return error code if 1) if there are -existing XPA access points that match the -template -(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. - - -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: - - xpaaccess -c -t "2,2" ds9 - -The first argument is the short delay value, and is ignored in this -operation. The second is the long delay timeout. - - -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. - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - - -=cut diff --git a/xpa/doc/pod/xpaacl.pod b/xpa/doc/pod/xpaacl.pod deleted file mode 100644 index 3be9d4c..0000000 --- a/xpa/doc/pod/xpaacl.pod +++ /dev/null @@ -1,145 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPAAcl: Access Control for XPA Messaging> - - - -=head1 SYNOPSIS - - - - - -XPA supports host-based access control for each XPA access point. You -can enable/disable access control using the XPA_ACL environment -variable. You can specify access to specific XPA access points for -specific machines using the XPA_DEFACL and XPA_ACLFILE environment -variables. By default, an XPA access point is accessible only to -processes running on the same machine (same as X Windows). - - - -=head1 DESCRIPTION - - - - - -When INET sockets are in use (the default, as specified by the -I<XPA_METHOD> environment variable), XPA supports a host-based -access control mechanism for individual access points. This mean that -access can be specified for get, set, or info operations for each -access point on a machine by machine basis. For LOCAL sockets, access -is restricted (by definition) to the host machine. - - -XPA access control is enabled by default, but can be turned off by -setting the I<XPA_ACL> environment variable to I<false>. -In this case, any process can access any XPA server. - - -Assuming that access control is turned on, the ACL for an individual -XPA access point is set up when that access point is registered -(although it can be changed later on; see below). This can be done in -one of two ways: - -Firstly, the I<XPA_ACLFILE> environment variable can defined to -point to a file of access controls for individual access points. The format -of this file is: - - class:name ip acl - -The first argument is a template that specifies the class:name of the -access point covered by this ACL. See -XPA Access Points and Templates -for more information about xpa templates. - - -The second argument is the IP address (in human-readable format) of -the machine which is being given access. This argument can be -I<*> to match all IP addresses. It also can be I<$host> -to match the IP address of the current host. - - -The third argument is a string combination of I<s>, I<g>, -or I<i> to allow I<xpaset>, I<xpaget>, or -I<xpainfo> access respectively. The ACL argument can be -I<+> to give I<sgi> access or it can be I<-> to turn -off all access. - - -For example, - - *:xpa1 somehost sg - *:xpa1 myhost + - * * g - -will allow processes on the machine somehost to make xpaget and xpaset calls, -allow processes on myhost to make any call, and allow all other hosts to -make xpaget (but not xpaset) calls. - -Secondly, if the I<XPA_ACLFILE> does not exist, then a single -default value for all access points can be specified using the -I<XPA_DEFACL> environment variable. The default value for this -variable is: - - #define XPA_DEFACL "*:* $host +" - -meaning that all access points are fully accessible to all processes -on the current host. Thus, in the absence of any ACL environment variables, -processes on the current host have full access to all access points -created on that host. This parallels the X11 xhost mechanism. - - -Access to an individual XPA access point can be changed using the -acl -parameter for that access point. For example: - - xpaset -p xpa1 -acl "somehost -" - -will turn off all access control for somehost to the xpa1 access point, while: - - xpaset -p XPA:xpa1 -acl "beberly gs" - -will give beberly xpaget and xpaset access to the access point whose -class is XPA and whose name is xpa1. - -Similarly, the current ACL for a given access point can be retrieved using: - - xpaget xpa1 -acl - -Of course, you must have xpaget access to this XPA access point to -retrieve its ACL. - - -Note that the XPA access points registered in the I<xpans> -program also behave according to the ACL rules. That is, you cannot -use xpaget to view the access points registered with xpans unless -you have the proper ACL. - - -Note also when a client request is made to an XPA server, the access -control is checked when the initial connection is established. This -access in effect at this time remains in effect so long as the client -connection is maintained, regardless of whether the access fro that -XPA is changed later on. - - -We recognize that host-based access control is only relatively secure -and will consider more stringent security (e.g., private key) in the -future if the community requires such support. - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - - -=cut diff --git a/xpa/doc/pod/xpaatexit.pod b/xpa/doc/pod/xpaatexit.pod deleted file mode 100644 index 4310835..0000000 --- a/xpa/doc/pod/xpaatexit.pod +++ /dev/null @@ -1,41 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPAAtExit: install exit handler> - - - -=head1 SYNOPSIS - - - - - - #include <xpa.h> - - void XPAAtExit(void); - - - - - -=head1 DESCRIPTION - - - - -XPAAtExit() will install an exit handler using atexit() to run XPAFree on all -XPA access points. This might be useful in cases where Unix sockets are being -used: if an explicit call to XPAFree() is not made by the program, the Unix -socket file will not be deleted immediately without an atexit handler. (NB: this -call should not be made in a Tcl/Tk application. Accessing the Tcl native file -system after Tcl has shut down all file systems causes the Tcl/Tl program to -crash). - - - - -=cut diff --git a/xpa/doc/pod/xpachanges.pod b/xpa/doc/pod/xpachanges.pod deleted file mode 100644 index bce7be0..0000000 --- a/xpa/doc/pod/xpachanges.pod +++ /dev/null @@ -1,102 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPA Changes: Changes For Users from XPA 1.0 and 2.0> - - - -=head1 SYNOPSIS - - - - - -This document describes changes that will affect users who migrate -from XPA 1.0 to XPA 2.0. - - - -=head1 DESCRIPTION - - - - - -There have been a few changes that affect users who upgrade XPA -from version 1.0 to version 2.0. These changes are detailed below. - - -=over 4 - - - - - -=item * - -XPA commands no longer have a resolver routine (this is open to -negotiations, but we decided the idea was dumb). For the SAOtng -program, this means that you must explicitly specify the access -point, i.e.,: - - cat foo.fits | xpaset SAOtng fits - - - -instead of: - - cat foo.fits | xpaset SAOtng - - - - -=item * - -By default, xpaset, xpaget, etc. now wait for the server callback to -complete; i.e., the old -W is implied (and the switch is ignored). -This allows support for better error handling. If you want xpaset, etc. -to return before the callback is complete, use -n switch: - - echo "file foo.fits" | xpaset -n SAOtng - - - - -=item * - -The old -w switch in xpaset and xpaget is no longer necessary (and is -ignored), since you can have more than one process communicating with -an xpa access point at one time. - - - - -=item * - -The new -p switch on xpaset means you need not read from stdout: - - xpaset -p SAOtng colormap I8 - - -will send the paramlist to the SAOtng callback without reading from stdin. - - - -=back - - - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - - -=cut diff --git a/xpa/doc/pod/xpacleanup.pod b/xpa/doc/pod/xpacleanup.pod deleted file mode 100644 index 2d55e5a..0000000 --- a/xpa/doc/pod/xpacleanup.pod +++ /dev/null @@ -1,47 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPACleanup: release reserved XPA memory> - - - -=head1 SYNOPSIS - - - - - - #include <xpa.h> - - void XPACleanup(void); - - - - - -=head1 DESCRIPTION - - - - -When XPA is initialized, it allocates a small amount of memory for the -access control list, temp directory path, and reserved commands. This -memory is found by valgrind to be "still reachable", meaning that "your -program didn't free some memory it could have". Calling the -XPACleanup() routine before exiting the program will free this memory -and make valgrind happy. - - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - -=cut diff --git a/xpa/doc/pod/xpaclient.pod b/xpa/doc/pod/xpaclient.pod deleted file mode 100644 index 858a8a8..0000000 --- a/xpa/doc/pod/xpaclient.pod +++ /dev/null @@ -1,95 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPAClient: The XPA Client-side Programming Interface> - - - -=head1 SYNOPSIS - - - - -A description of the XPA client-side programming interface. - - - -=head1 DESCRIPTION - - - -B<Introduction to XPA Client Programming> - -Sending/receiving data to/from an XPA access point is easy: you -generally only need to call the XPAGet() or XPASet() subroutines. - - #include <xpa.h> - - int XPAGet(XPA xpa, - char *template, char *paramlist, char *mode, - char **bufs, size_t *lens, char **names, char **messages, int n); - - int XPASet(XPA xpa, - char *template, char *paramlist, char *mode, - char *buf, size_t len, char **names, char **messages, int n); - - int XPAInfo(XPA xpa, - char *template, char *paramlist, char *mode, - char **names, char **messages, int n); - - int XPAAccess(XPA xpa, - char *template, char *paramlist, char *mode, - char **names, char **messages, int n); - - int XPAGetFd(XPA xpa, - char *template, char *paramlist, char *mode, - int *fds, char **names, char **messages, int n); - - int XPASetFd(XPA xpa, - char *template, char *paramlist, char *mode, - int fd, char **names, char **messages, int n); - - XPA XPAOpen(char *mode); - - void XPAClose(XPA xpa); - - int XPANSLookup(XPA xpa, - char *template, char *type, - char ***classes, char ***names, char ***methods, char ***infos); - - -B<Introduction> - -To use the XPA application programming interface, a software developer -generally will include the xpa.h definitions file: - - #include <xpa.h> - -in the software module that defines or accesses an XPA access point and -then will link against the libxpa.a library: - - gcc -o foo foo.c libxpa.a - -XPA has been compiled using both C and C++ compilers. - -Client communication with XPA public access points generally is -accomplished using XPAGet() or XPASet() within a program (or xpaget -and xpaset at the command line). Both routines require specification -of the name of the access point. If a template -is used to specify the access point name (e.g., "ds9*"), then -communication will take place with all servers matching that template. - - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - -=cut diff --git a/xpa/doc/pod/xpaclose.pod b/xpa/doc/pod/xpaclose.pod deleted file mode 100644 index 7148752..0000000 --- a/xpa/doc/pod/xpaclose.pod +++ /dev/null @@ -1,53 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPAClose: close a persistent XPA client handle> - - - -=head1 SYNOPSIS - - - - - - #include <xpa.h> - - void XPAClose(XPA xpa); - - - - - -=head1 DESCRIPTION - - - - -XPAClose closes the persistent connections associated with this XPA struct -and frees all allocated space. It also closes the open sockets connections -to all XPA servers that were opened using this handle. - - -B<Example:> - - #include <xpa.h> - - XPA xpa; - XPAClose(xpa); - - - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - -=cut diff --git a/xpa/doc/pod/xpacmdadd.pod b/xpa/doc/pod/xpacmdadd.pod deleted file mode 100644 index 31859e5..0000000 --- a/xpa/doc/pod/xpacmdadd.pod +++ /dev/null @@ -1,69 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPACmdAdd: add a command to an XPA command public access point> - - - -=head1 SYNOPSIS - - - - - - #include <xpa.h> - - XPACmd XPACmdAdd(XPA xpa, char *name, char *help, - int (*send_callback)(), - void *send_data, char *send_mode, - int (*rec_callback)(), - void *rec_data, char *rec_mode); - - - - - -=head1 DESCRIPTION - - - - -Add a command to an XPA command access point. The XPA argument specifies the -XPA struct returned by a call to XPANewCmd(). The name argument is the -name of the command. The other arguments function identically to the -arguments in the XPANew() command, i.e., the send_callback and rec_callback -routines have identical calling sequences to their XPANew() counterparts, -with the exceptions noted below. - - -When help is requested for a command access point using: - - xpaget -h class:name - - -all of the command help strings are listed. To get help for a given -command, use: - - xpaget -h class:name cmd - - -Also, the acl keyword in the send_mode and receive_mode strings is -global to the access point, not local to the command. Thus, the value -for the acl mode should be the same in all send_mode (or receive_mode) -strings for each command in a command access point. (The acl for -send_mode need not be the same as the acl for receive_mode, though). - - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - -=cut diff --git a/xpa/doc/pod/xpacmddel.pod b/xpa/doc/pod/xpacmddel.pod deleted file mode 100644 index 95c545d..0000000 --- a/xpa/doc/pod/xpacmddel.pod +++ /dev/null @@ -1,43 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPACmdDel: remove a command from an XPA command public access point> - - - -=head1 SYNOPSIS - - - - - - #include <xpa.h> - - void XPACmdDel(XPA xpa, XPACmd cmd); - - - - - -=head1 DESCRIPTION - - - - -This routine removes a command from the list of available commands in -a given XPA. That command will no longer be available for processing. - - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - -=cut diff --git a/xpa/doc/pod/xpacmdnew.pod b/xpa/doc/pod/xpacmdnew.pod deleted file mode 100644 index 429972b..0000000 --- a/xpa/doc/pod/xpacmdnew.pod +++ /dev/null @@ -1,90 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPACmdNew: create a new XPA public access point for commands> - - - -=head1 SYNOPSIS - - - - - - #include <xpa.h> - - XPA XPACmdNew(char *class, char *name); - - - - - -=head1 DESCRIPTION - - - - -Create a new XPA public access point for commands that will share a -common identifier class:name. Enter this access point into the XPA -name server, so that it can be accessed by external processes. -XPACmdNew() returns an XPA struct. - - -It often is more convenient to have one public access point that can -manage a number of commands, rather than having individual access -points for each command. For example, it is easier to command the -ds9 image display using: - - echo "colormap I8" | xpaset ds9 - echo "scale log" | xpaset ds9 - echo "file foo.fits" | xpaset ds9 - - -then to use: - - echo "I8" | xpaset ds9_colormap - echo "log" | xpaset ds9_scale - echo "foo.fits" | xpaset ds9_file - - -In the first case, the commands remain the same regardless of the -target XPA name. In the second case, the command names must change -for each instance of ds9. That is, if a second instance of ds9 -called DS9 were running, it would be commanded either as: - - echo "colormap I8" | xpaset DS9 - echo "scale log" | xpaset DS9 - echo "file foo.fits" | xpaset DS9 - - -or as: - - echo "I8" | xpaset DS9_colormap - echo "log" | xpaset DS9_scale - echo "foo.fits" | xpaset DS9_file - - -Thus, in cases where a program is going to manage many commands, it -generally is easier to define them as commands associated with the -XPACmdNew() routine, rather than as separate access points using -XPANew(). - - -When XPACmdNew() is called, only the class:name identifier is -specified. Each sub-command is subsequently defined using the -XPACmdAdd() routine. - - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - -=cut diff --git a/xpa/doc/pod/xpacode.pod b/xpa/doc/pod/xpacode.pod deleted file mode 100644 index c5ea647..0000000 --- a/xpa/doc/pod/xpacode.pod +++ /dev/null @@ -1,73 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPACode: Where to Find Example/Test Code> - - - -=head1 SYNOPSIS - - - - - -The XPA source code directory contains two test programs, -I<stest.c>, and I<ctest.c> that can serve as -examples for writing XPA servers and clients, respectively. -They also can be used to test various features of XPA. - - - -=head1 DESCRIPTION - - - - - -To build the XPA test programs, execute: - - make All - -in the XPA source directory to generate the I<stest> and -I<ctest> programs. (NB: this should work on all platforms, -although we have had problems with unresolved externals on one -Sun/Solaris machine, for reasons still unknown.) - -The stest program can be executed with no arguments to start -an XPA server that contains the access points: xpa, xpa1, -c_xpa (containing sub-commands cmd1 and cmd2), and i_xpa. -You then can use xpaset and xpaget to interact with these access points: - - cat xpa.c | xpaset xpa # send to xpa - cat xpa.c | xpaset "xpa*" # send to xpa and xpa1 - xpaget xpa # receive from xpa - xpaget xpa* # receive from xpa and xpa1 - -etc. You also can use ctest to do the same thing, or to iterate: - - ctest -s -l 100 xpa # send to xpa 100 times - ctest -s -l 100 "xpa*" # send to xpa and xpa1 100 times - ctest -g -l 100 xpa # receive from xpa 100 times - ctest -g -l 100 "xpa*" # receive from xpa and xpa1 100 times - -More options are available: see the stest.c and ctest.c code itself, which -were used extensively to debug XPA. - - -The file test.tcl in the XPA source directory gives examples for using the -XPATclInterface. - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - - -=cut diff --git a/xpa/doc/pod/xpacommon.pod b/xpa/doc/pod/xpacommon.pod deleted file mode 100644 index 9fc9746..0000000 --- a/xpa/doc/pod/xpacommon.pod +++ /dev/null @@ -1,266 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPACommon: Getting Common Information About Access Points> - - - -=head1 SYNOPSIS - - - - - -There are various kinds of generic information you can retrieve about -an XPA access point by using the xpaget command. - - - -=head1 DESCRIPTION - - - - - -You can find out which XPA access points have been registered with -the currently running -XPA name server -by executing the -xpaget -command to retrieve info from the XPA name server: - - xpaget xpans - -If, for example, the -stest test server program -is running, the following XPA access points will be returned (the specifics -of the returned info will vary for different machines and users): - - XPA xpa gs 838e2f67:1262 eric - XPA xpa1 gs 838e2f67:1266 eric - XPA c_xpa gs 838e2f67:1267 eric - XPA i_xpa i 838e2f67:1268 eric - -Note that access to this information is subject to the usual -XPA Access Control restrictions. - - -Each XPA access point supports a number of reserved sub-commands that provide -access to different kinds of information, e.g. the access control for -that access point. These sub-commands can be executed by using -xpaset -or -xpaget -at the command line, or -XPAGet() -or -XPASet() -in programs, e.g: - - xpaget ds9 -acl - xpaget ds9 -help - xpaget ds9 env FOO - - xpaset -p ds9 env FOO foofoo - -With the exception of B<-help> and B<-version>, reserved -sub-commands are available only on the machine on which the XPA server -itself is running. - -The following reserved sub-commands are defined for all access points: - - -=over 4 - - - - - - -=item * - -B<-acl> get (set) the access control list [options: host type acl, for set] - - -The 'xpaset' option allows you to add a new acl for a given host, or change -the acl for an existing host. See -XPA Access Control -for more information. -This access point is available only on the server machine. - - - - -=item * - -B<-env> get (set) an environment variable [options: name (value, for set)] - - -The 'xpaget' option will return the value of the named environment -variable. The 'xpaset' option will set the value of the names -variable to the specified value. -This access point is available only on the server machine. -(Please be advised that we have had problems setting environment -variables in static Tcl/Tk programs such as ds9 running under Linux.) - - - - -=item * - -B<-clipboard> set(get) information on a named clipboard - - -Clients can store ASCII state information on any number of named -clipboards. Clipboards of the same name created by clients on -different machines are kept separate. The syntax for creating a -clipboard is: - - [data] | xpaset [server] -clipboard add|append [clipboard_name] - xpaset -p [server] -clipboard delete [clipboard_name] - -Use "add" to create a new clipboard or replace the contents of an existing -one. Use "append" to append to an existing clipboard. - -Information on a named clipboard is retrieved using: - - xpaget [server] -clipboard [clipboard_name] - - - - -=item * - -B<-exec> set: execute commands from buffer [options: none] - - -If -exec is specified in the paramlist of an 'xpaset' call, then further -sub-commands will be retrieved from the data buffer. - - - - -=item * - -B<-help> get: return help string for this XPA or sub-command [options: name (for sub-commands)] - - -Each XPA access point and each XPA sub-command can have a help string -associated with it that is specified when the access point is defined. -The -help option will return this help string. For XPA access points -that contain user-defined sub-commands, you can get the help string -for a particular sub-command by specifying its name, or else get the -help strings for all sub-commands if not name is specified. - - - - -=item * - -B<-ltimeout> get (set) the long timeout value [options: seconds|reset] - - -The 'xpaget' option will return the value of the long timeout (in seconds). -The 'xpaset' option will set the value of the long timeout. If "reset" is -specified, then the timeout value will be reset to the default value. - - - - -=item * - -B<-nsconnect> set: re-establish name server connection to all XPA's [options: none] - - -If the -XPA Name Server (xpans) -process has terminated unexpectedly and then re-started, this -sub-command can be used to re-establish the connection. You use it by -sending the command to the [name:port] or [file] of the access point -instead of to the XPA name (since the latter requires the xpans -connection!): - - xpaset -p 838e2f67:1268 -nsconnect - -See xpans for more information. - - - - -=item * - -B<-nsdisconnect> set: break name server connection to all XPA's [options: none] - - -This sub-command will terminate the connection to the -XPA Name Server (xpans), thereby making -all access points inaccessible except through their underlying [name:port] -or [file] identifiers. I forget why we added it, it seems pretty useless. - - - - -=item * - -B<-stimeout> get (set) the short timeout value [options: seconds|reset] - - -The 'xpaget' option will return the value of the short timeout (in seconds). -The 'xpaset' option will set the value of the short timeout. If "reset" is -specified, then the timeout value will be reset to the default value. - - - - -=item * - -B<-remote> set: register xpa with remote server [options: host[:port] [acl]] [-proxy] - - -This sub-command will register the XPA access point with the XPA name -server (xpans) on the specified host (which must already be running). -The specified host also is given access control to the access point, -using the specified acl or the default acl of "+" (meaning the remote -host can xpaset, xpaget, xpainfo or xpaaccess). If the acl is -specified as "-", then the access point is unregistered. -See Communication Between Machines -for more information on how this sub-command is used. - - - - -=item * - -B<-version> get: return XPA version string [options: none] - - -The version refers to the version of XPA used to define this access point -(currently something like 2.0). - - - -=back - - - - -You can add your own reserved commands to all XPA access points by using the -XPACmdAdd() -routine, passing the XPA handle returned by I<XPA XPAGetReserved(void)> -as the first argument. Note again that these will only be available on the -machine where the XPA service is running. - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - - -=cut diff --git a/xpa/doc/pod/xpaconvert.pod b/xpa/doc/pod/xpaconvert.pod deleted file mode 100644 index 75597a7..0000000 --- a/xpa/doc/pod/xpaconvert.pod +++ /dev/null @@ -1,202 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPAConvert: Converting the XPA API to 2.0> - - - -=head1 SYNOPSIS - - - - - -This document describes tips for converting from xpa 1.0 (Xt-based -xpa) to xpa 2.0 (socket-based xpa). - - - -=head1 DESCRIPTION - - - - - -The following are tips for converting from xpa 1.0 (Xt-based xpa) to -xpa 2.0 (socket-based xpa). The changes are straight-forward and -almost can be done automatically (we used editor macros for most of -the conversion). - - -=over 4 - - - - - -=item * - -The existence of the cpp XPA_VERSION directive to distinguish between 1.0 -(where it is not defined) and 2.0 (where it is defined). - - - - -=item * - -Remove the first widget argument from all send and receive server -callbacks. Also change first 2 arguments from XtPointer to void -*. For example: - -#ifdef XPA_VERSION -static void XPAReceiveFile(client_data, call_data, paramlist, buf, len) - void *client_data; - void *call_data; - char *paramlist; - char *buf; - int len; -#else -static void XPAReceiveFile(w, client_data, call_data, paramlist, buf, len) - Widget w; - XtPointer client_data; - XtPointer call_data; - char *paramlist; - char *buf; - int len; -#endif - - - - -=item * - -Server callbacks should be declared as returning int instead -of void. They now should return 0 for no errors, -1 for error. - - - - -=item * - -The mode flags have changed when defining XPA server callbacks. -The old I<S> flag (save buffer) is replaced by I<freebuf=false>. -The old I<E> flag (empty buffer is OK) is no longer used (it -was an artifact of the X implementation). - - - - -=item * - -Change NewXPACommand() to XPAcmdNew(), with the new calling sequence: - - xpa = NewXPACommand(toplevel, NULL, prefix, NULL); - -is changed to: - - xpa = XPACmdNew(xclass, name); - - - - -=item * - -Change the AddXPACommand() subroutine name to XPACmdAdd (with the same -calling sequence): - - AddXPACommand(xpa, "file", - "\tdisplay a new file\n\t\t requires: filename", - NULL, NULL, NULL, XPAReceiveFile, text, NULL); - -is changed to: - - XPACmdAdd(xpa, "file", - "\tdisplay a new file\n\t\t requires: filename", - NULL, NULL, NULL, XPAReceiveFile, text, NULL); - - - - -=item * - -The XPAXtAppInput() routine should be called just before XtAppMainLoop() -to add xpa fds to the Xt event loop: - - /* add the xpas to the Xt loop */ - XPAXtAddInput(app, NULL); - - /* process events */ - XtAppMainLoop(app); - - - - -=item * - -Change NewXPA() to XPANew() and call XPAXtAddInput() if the XtAppMainLoop -routine already has been entered: - - xpa = NewXPA(saotng->xim->toplevel, prefix, xparoot, - "FITS data or image filename\n\t\t options: file type", - XPASendData, new, NULL, - XPAReceiveData, new, "SE"); - -is changed to: - - sprintf(tbuf, "%s.%s", prefix, xparoot); - xpa = XPANew("SAOTNG", tbuf, - "FITS data or image filename\n\t\t options: file type", - XPASendData, new, NULL, - XPAReceiveData, new, "SE"); - XPAXtAddInput(XtWidgetToApplicationContext(saotng->xim->toplevel), xpa); - - - - -=item * - -Change XPAInternalReceiveCommand() to XPACmdInternalReceive() -remove first argument in the calling sequence): - - XPAInternalReceiveCommand(im->saotng->xim->toplevel, - im->saotng, im->saotng->commands, - "zoom reset", NULL, 0); - -is changed to: - - XPACmdInternalReceive(im->saotng, im->saotng->commands, - "zoom reset", NULL, 0); - - - - -=item * - -Change DestroyXPA to XPAFree: - - DestroyXPA(im->dataxpa); - -is changed to: - - XPAFree(im->dataxpa); - - - -=back - - - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - - -=cut diff --git a/xpa/doc/pod/xpaenv.pod b/xpa/doc/pod/xpaenv.pod deleted file mode 100644 index a1d095f..0000000 --- a/xpa/doc/pod/xpaenv.pod +++ /dev/null @@ -1,517 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPAEnv: Environment Variables for XPA Messaging> - - - -=head1 SYNOPSIS - - - - -Describes the environment variables which can be used to tailor the overall -XPA environment. - - - -=head1 DESCRIPTION - - - - - -The following environment variables are supported by XPA: - - -=over 4 - - - - - -=item * - -B<XPA_ACL> - - -If I<XPA_ACL> is I<true>, then -host-based XPA Access Control -is turned on and only specified machines can access specified access -points. If I<false>, then access control is turned off and any -machine can access point. The default is turn turn access control on. - - - - -=item * - -B<XPA_ACLFILE> - - -If -XPA Access Control -is turned on, this variable specifies the name of the file containing -access control information for all access points started by this user. -The default file name is: I<$HOME/acls.xpa>. - - - - -=item * - -B<XPA_CONNECT_TIMEOUT> - - -When an XPA server first starts up, it immediately tries to -connect to the XPA name server program (xpans) on the host specified by -the I<XPA_NSINET> variable. (If this connection fails on the -local host, and if xpans can be found in the path, then the name -server is started automatically.) Unfortunately, a mis-configured -network can cause this connect attempt to hang for many seconds while -the connect() system call times out. Therefore, an alarm is started -to interrupt the connect() call and prevent a long hang. The initial -value of the alarm timeout is 10 seconds, but can be changed by setting -this environment variable. If you want to disable the alarm and allow -the initial connect() to time out, set the value of this variable to -0. Normally, users would not change this variable at all. - - - - -=item * - -B<XPA_CLIENT_DOXPA> - - -Normally, an XPA client (xpaget, xpaset, etc.) will process incoming -XPA server requests while awaiting the completion of the client request. -Setting this variable to "false" will prevent XPA server requests from -being processed by the client. - - - - -=item * - -B<XPA_DEFACL> - - -If -XPA Access Control -is turned on, this variable specifies the default access control -condition for all access points, if the I<XPA_ACLFILE> file does -not exist. The default acl is: I<$host:* $host +>, meaning that -all processes on the host machine have full access to all access points. - - - - -=item * - -B<XPA_HOST> - - -For the INET socket method, XPA utilizes the canonical hostname (as -returned by the gethostname() routine) to construct the IP part of the -method id. Under some circumstances, this might not be a correct choice -of name and IP. For example, if an XPA server is started on a machine -running VPN, you might want to use the VPN name and IP instead of the -canonical host name, so that other machines in the VPN network can -access the server. In this case, you can set the XPA_HOST to be -the VPN name (if resolvable) or, more easily, the VPN IP. - - - - -=item * - -B<XPA_IOCALLSXPA> - - -Setting this variable causes all XPA socket IO calls to process -outstanding XPA requests whenever the primary socket is not ready for -IO. This means that a server making a client call will (recursively) -process incoming server requests while waiting for client completion. -This inter-IO XPA processing avoids a rare -XPA Race Condition: two or more -XPA servers sending messages to one another using an XPA client -routine such as XPASet() can deadlock while each waits for the other -server to respond. This can happen, for example, if the servers call -XPAPoll() with a time limit, and send messages in between the polling call. - - -By default, this option is turned off, because we judge that the added -code complication and overhead involved will not be justified by the -amount of its use. Moreover, processing XPA requests within socket IO -can lead to non-intuitive results, since incoming server requests will -not necessarily be processed to completion in the order in which they -are received. - - - - -=item * - -B<XPA_LOGNAME> - - -XPA preferentially uses the de facto standard environment variable -LOGNAME to determine the username when registering an access point in -the name server. If this environment variable has been used for -something other than the actual user name (such as a log file name), -unexpected results can ensue. In such cases, use the XPA_LOGNAME -variable to set the user name. (If neither exists, then getpwuid(geteuid()) -is used as a last resort). - - - - -=item * - -B<XPA_LONG_TIMEOUT> - - -XPA is designed to allow data to be sent from one process to -another over a long period of time (i.e., a program that generates -image data sends that data to an image display, but slowly) but it -also seeks to prevent hangs. This is done by supporting 2 timeout -periods: a I<short> timeout for protocol communication -and a I<long> for data communication. - -The I<XPA_LONG_TIMEOUT> variable controls the I<long> -timeout and is used to prevent hangs in cases where communication -between the client and server that is I<not> controlled by the -XPA interface itself. Transfer of data between client and server, or a -client's wait for a status message after completion of the server -callback, are two examples of this sort of communication. By default, -the I<long> timeout is set to 180 seconds. -Setting the value to -1 will disable I<long> timeouts and allow -an infinite amount of time. - - - - -=item * - -B<XPA_MAXHOSTS> - - -The maximum number of access points that the programs -I<xpaset>, I<xpaget>, and I<xpainfo> will -communicate with at one time. The default is 64, meaning, for -example, that the I<xpaset> program will not send a message -to more than 100 access points at one time and I<xpaget> will -not retrieve from more than 100 access points at one time. - - - - -=item * - -B<XPA_METHOD> - - -Determines the socket connection method used by this session of XPA. -The choices are: I<inet> (to use INET or Internet-based -sockets), I<localhost> (to use the machines localhost inet -socket), or I<local (unix)> (to use UNIX sockets). The default -is I<INET>. Using the I<inet> method will allow access -from other machines (subject to access controls) but using -I<localhost> or I<local> will not. Localhost is most useful -for private access and when the machine in question is not connected -to the Internet. The unix method also can be used for private access -and non-Internet connections (Unix platforms only). - -Once defined, the first registration of an XPA access point will -ensure that an instance of the -XPA Name Server (xpans) -is running that handles that connection method. All new access points -will use the new connection method but existing access points will use -the original method. - - - - -=item * - -B<XPA_NSINET> - - -For the I<inet> method of socket connection, this variable -specifies the host and port on which the -XPA Name Server (xpans) -is listens for new access points. The default is I<$host:$port>, -meaning that the default XPA port (14285) on the current machine -(as returned by gethostname()) is used. If several machines were all -accessing the same XPA access points, you would use this variable to -specify that they all use the same name server to find out about these -access points. For example, a value of I<myhost:$port> would -mean that the xpans name server is running on myhost and uses the -default port 12345. All machines would then get the XPA access points -registered with that name server, subject to access controls. - -The port used by xpans to register its XPA access point normally is -taken to be one greater than the port on which it receives new access -points from XPA servers. You can specify a specific access point port -using the syntax machine:port1,port2, i.e., the access point port is -specified after the comma. For example, $host:12345,23456 will listen -for new access ports on 12345 and will accept XPA commands on 23456. - - - - -=item * - -B<XPA_NSREGISTER> - - -This boolean variable specifies whether a server registers its XPA -access point with the specified xpans name server. The default is -I<true>. If set to I<false>, the access point still is -set up but it is not registered with xpans and therefore cannot be -accessed by name. (It can be accessed by method, if the latter is -known.) Note that an access point can be registered later on (using --remote or -proxy, for example). This variable mainly is useful in -cases where the Internet configuration is broken (so that registration -causes a DNS hang) but you still wish to and can use the server with a -remote xpans (e.g., ds9's Virtual Observatory capability). - - - - -=item * - -B<XPA_NSUNIX> - - -For the I<local> method of socket connection, this variable -specifies the name of the Unix file that will be used to access the -XPA Name Server (xpans). The default is -I<xpans_unix>. This variable is not usually needed. Note that -is the I<local> socket method is used, then remote machines will -not be able to access the xpans name server or the registered XPA access -points. - - - - -=item * - -B<XPA_NSUSERS> - - -This variable specifies whether other users' access points will be -returned by the -XPA Name Server (xpans) for use by -I<xpaget>, I<xpaset>, etc. -Generally speaking, it is sufficient to run one xpans name server per -machine and register the access points for all users with that xpans. -This means, for example, that if you request information from -ds9 by running: - - xpaget ds9 colormap - -you might get information from your own ds9 as well as -from another user running ds9 on the same machine. The -I<XPA_NSUSERS> variable controls whether you want such access -to the access points of other users. -By default, only your own access points are returned, so -that, in the example above, you would only get the colormap information -from the ds9 you registered. If, however, you had set the value of the -I<XPA_NSUSERS> variable to I<eric,fred>, then you would be -able to communicate with both eric and fred's access points. Note that -this variable can be overridden using the I<-u> switch on the -I<xpaget>, I<xpaset>, and I<xpainfo> programs. - - - - -=item * - -B<XPA_PORT> - - -A semi-colon delimited list of user specified ports to use for specific -XPA access points. The format is each specification is: - -class:template port1[ port2] - -where B<port1> is the main (command) port for the access point and -B<port2> is the (secondary) data port. If port2 is not specified, -it defaults to a value of 0 (meaning the system assigns the port). - - -Specification of specific ports is useful, for example, when a machine -outside a firewall needs to communicate with a machine inside a -firewall. In such a case, the firewall should be configured to allow -socket connections to both the command and data port from the outside -machine, and the inside XPA program should be started up with the -outside machine in its ACL list. Then, when the inside program is -started with specified ports, outside XPA programs can use -"machine:port" to contact the inside access points, instead of the -access point names. That is, the machine outside the firewall does not -need access to the XPA name server: - -export XPA_PORT="DS9:ds9 12345 12346" # on machine "inside" -cat foo.fits | xpaset inside:12345 fits # on machine "outside" - -Note that 2 ports are required for full XPA communication and -therefore 2 ports should be specified to go through a firewall. The -second port assignment is not important if you simply are assigning -the command port in order to communicate commands with a known -port (e.g., to bypass the xpans name server). If only one (command) -port is specified, the system will negotiate a random data port and -everything will work properly. - - -This support is somewhat experimental. If you run into problems, please -let us know. - - - - -=item * - -B<XPA_PORTFILE> - - -A list of user-specified port to use for specific xpa access points. -The format of the file is: - -class:template port1 [port2] - -where B<port1> is the main port for the access point and -B<port2> is the data port. If port2 is not specified, it defaults -to a value of 0 (meaning the system assigns the port). See -B<XPA_PORT> above for an explanation of user-specified ports. - - - - -=item * - -B<XPA_SHORT_TIMEOUT> - - -XPA is designed to allow data to be sent from one process to -another over a long period of time (i.e., a program that generates -image data sends that data to an image display, but slowly) but it -also seeks to prevent hangs. This is done by supporting 2 timeout -periods: a I<short> timeout for protocol communication -and a I<long> for data communication. - -The I<XPA_SHORT_TIMEOUT> variable -controls the I<short> timeout and is used to prevent hangs -in cases where the XPA protocol requires internal communication between -the client and server that is controlled by the XPA interface -itself. Authentication is an example of this sort of communication, -as is the establishment of a data channel between the two processes. -The default value for the I<short> is 30 seconds (which is -a pretty long time, actually). Setting the value to -1 will disable -I<short> timeouts and allow an infinite amount of time. - - - - -=item * - -B<XPA_SIGUSR1> - - -If the value of this variable is I<true>, then XPA will -catch SIGUSR1 signals when performing an I/O operation in order to -curtail that operation. This facility allows users to send a SIGUSR1 -signal to an XPA server if a client is hanging up the server by -sending or receiving data too slowly (timeouts also can be used -- see -above). When enabled in this way, the SIGUSR1 signal is ignored at all other -times, so that its safe to send the signal at any time. If the -variable is set to I<false>, then SIGUSR1 is not used at -all. Turning off SIGUSR1 would be desired in cases there the program -uses SIGUSR1 for some other reason and does not want XPA interfering. -The default is to use the signal. - - - - -=item * - -B<XPA_TIMESTAMP_ERRORS> - - -If I<XPA_TIMESTAMP_ERRORS> is I<true>, then error -messages will include a date/time string. This can be useful when -XPA errors are being saved in an error log (e.g. Web/CGI use). The -default is false. - - -=back - - - - - - -=item * - -B<XPA_TMPDIR> - - -This variable specifies the directory into which XPA logs, Unix -socket files (when I<XPA_METHOD> is I<local>), etc. are -stored. The default is I</tmp/.xpa>. - - - - -=item * - -B<XPA_VERBOSITY> - - -Specify the verbosity level of error messages. If the value is -set to I<0>, I<false>, or I<off>, then no error -messages are printed to stderr. If the value is I<1>, then -important XPA error messages will be output. If the value is -set to I<2>, XPA warnings about out-of-sync messages will also -be output. These latter almost always can be ignored. - - - - -=item * - -B<XPA_VERSIONCHECK> - - -Specify whether a new access point should check its major and minor XPA -version number against the version used by the xpans name server at -registration time. The default is I<true>. When checking is -performed, a warning is issued if the server major version is found to -be greater than the xpans version. Note that the check is performed -both by the XPA server and by the xpans process and warnings will be -issued by each. Also, instead of the values of I<true> or -I<false>, you can give this variable an integer value n. In this -case, each version checking process (i.e., the XPA-enabled server or -xpans) will print out a maximum of n warning messages (after which -version warnings are silently swallowed). - -In general, it is a bad idea to run an XPA-enabled server program -using a version of XPA newer than the basic xpaset, xpaget, xpaaccess, -xpans programs. This sort of mismatch usually will not work due to -protocol changes. - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - - -=cut diff --git a/xpa/doc/pod/xpafree.pod b/xpa/doc/pod/xpafree.pod deleted file mode 100644 index 4071fb2..0000000 --- a/xpa/doc/pod/xpafree.pod +++ /dev/null @@ -1,49 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPAFree: remove an XPA public access point> - - - -=head1 SYNOPSIS - - - - - - #include <xpa.h> - - int XPAFree(XPA xpa); - - - - - -=head1 DESCRIPTION - - - - -Remove the specified XPA public access point from the name server and -free all associated storage. Note that removal from the name server -happens automatically when the process terminates, so this call is not -generally needed. It is used when public access points are being -defined temporarily and then destroyed when no longer needed. For -example, ds9 temporarily creates a public access point when it -loads a new image for display and destroys it when the image is -unloaded. - - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - -=cut diff --git a/xpa/doc/pod/xpaget.pod b/xpa/doc/pod/xpaget.pod deleted file mode 100644 index 77e771b..0000000 --- a/xpa/doc/pod/xpaget.pod +++ /dev/null @@ -1,67 +0,0 @@ -=pod - -=head1 NAME - - - -B<xpaget: retrieve data from one or more XPA servers> - - - -=head1 SYNOPSIS - - - - - -xpaget [-h] [-i nsinet] [-m method] [-s] [-t sval,lval] [-u users] <template|host:port> [paramlist] - - - - - -=head1 OPTIONS - - - - - - -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 - - - - -=head1 DESCRIPTION - - - - -Data will be retrieved from access points matching the -template -or host:port. -A set of qualifying parameters can be appended. - -B<Examples:> - - csh> xpaget ds9 images - csh> xpaget myhost.harvard.edu:12345 - - - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - -=cut diff --git a/xpa/doc/pod/xpagetfd.pod b/xpa/doc/pod/xpagetfd.pod deleted file mode 100644 index 5be9cfc..0000000 --- a/xpa/doc/pod/xpagetfd.pod +++ /dev/null @@ -1,133 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPAGetFd: retrieve data from one or more XPA servers and write to files> - - - -=head1 SYNOPSIS - - - - - - #include <xpa.h> - - int XPAGetFd(XPA xpa, - char *template, char *paramlist, char *mode, - int *fds, char **names, char **messages, int n); - - - - - -=head1 DESCRIPTION - - - - -Retrieve data from one or more XPA servers whose class:name identifier -matches the specified -template -and write it to files associated with -one or more standard I/O fds (i.e, handles returned by open()). - - -A -template -of the form "class1:name1" is sent to the -XPA name server, which returns a list of at most ABS(n) matching XPA -servers. A connection is established with each of these servers and -the paramlist string is passed to the server as the data transfer -request is initiated. If an XPA struct is passed to the call, then the -persistent connections are updated as described above. Otherwise, -temporary connections are made to the servers (which will be closed -when the call completes). - - -The XPAGetFd() routine then retrieves data from the XPA servers, -and write these data to the fds associated with one or more fds -(i.e., results from open). Is n is positive, then there will be n fds -and the data from each server will be sent to a separate fd. If n is -negative, then there is only 1 fd and all data is sent to this single -fd. (The latter is how xpaget is implemented.) - - -A string containing the class:name and ip:port is stored in the name -array. If a given server returned an error or the server callback -sends a message back to the client, then the message will be stored in -the associated element of the messages array. NB: if specified, the -name and messages arrays must be of size n or greater. - - -The returned message string will be of the form: - - XPA$ERROR error-message (class:name ip:port) - -or - - XPA$MESSAGE message (class:name ip:port) - - -Note that when there is an error stored in an messages entry, the -corresponding bufs and lens entry may or may not be NULL and 0 -(respectively), depending on the particularities of the server. - - -The return value will contain the actual number of servers that were -processed. This value thus will hold the number of valid entries in -the bufs, lens, names, and messages arrays, and can be used to loop -through these arrays. In names and/or messages is NULL, no information is -passed back in that array. - - -The mode string is of the form: "key1=value1,key2=value2,..." -The following keywords are recognized: - - key value default explanation - ------ -------- -------- ----------- - ack true/false true if false, don't wait for ack from server (after callback completes) - - -The ack keyword is not very useful, since the server completes the callback -in order to return the data anyway. It is here for completion (and perhaps -for future usefulness). - - -B<Example:> - - #include <xpa.h> - #define NXPA 10 - int i, got; - int fds[NXPA]; - char *names[NXPA]; - char *messages[NXPA]; - for(i=0; i<NXPA; i++) - fds[i] = open(...); - got = XPAGetFd(NULL, "ds9", "file", NULL, fds, names, messages, NXPA); - for(i=0; i<got; i++){ - if( messages[i] != NULL ){ - /* error processing */ - fprintf(stderr, "ERROR: %s (%s)\n", messages[i], names[i]); - } - if( names[i] ) - free(names[i]); - if( messages[i] ) - free(messages[i]); - } - - - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - -=cut diff --git a/xpa/doc/pod/xpainet.pod b/xpa/doc/pod/xpainet.pod deleted file mode 100644 index 40793a0..0000000 --- a/xpa/doc/pod/xpainet.pod +++ /dev/null @@ -1,285 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPAInet: XPA Communication Between Hosts> - - - -=head1 SYNOPSIS - - - - -XPA uses standard inet sockets to support communication between two or -more host computers. - - - -=head1 DESCRIPTION - - - - - -When the Communication Method is set to -B<inet> (as it is by default), XPA can be used to communicate -between different computers on the Internet. INET sockets utilize the -IP address of the given machine and a (usually random) port number to -communicate between processes on the same machine or between different -machines on the Internet. These standard Internet sockets are also -used by programs such as Netscape, ftp. etc. - - -XPA supports a host-based Access Control mechanism -to prevent unauthorized access of XPA access points by other computers -on the Net. By default, only the machine on which the XPA server is -running can access XPA services. Therefore, setting up communication -between a local XPA server machine and a remote client machine -requires a two-part registration process: - - - -=over 4 - - - - -=item * - -the XPA service on the local machine must be made known to the -remote machine - - -=item * - -the remote machine must be given permission to access the local -XPA service - - -=back - - - -Three methods by which this remote registration can be accomplished -are described below. - -B<Manual Registration> - -The first method is the most basic and does not require the remote -client to have xpans running. To use it, the local server simply -gives a remote client machine access to one or more XPA access points -using xpaset and the B<-acl> sub-command. For example, -consider the XPA test program "stest" running on a local machine. By -default the access control for the access point named "xpa" is -restricted to that machine: - - [sh]$ xpaget xpa -acl - *:* 123.456.78.910 gisa - *:* localhost gisa - -Using xpaset and the B<-acl> sub-command, a remote client -machine can be given permission to perform xpaget, xpaset, xpaaccess, -or xpainfo operations. For example, to allow the xpaget operation, the -following command can be issued on the local machine: - - [sh]$ xpaset -p xpa -acl "remote_machine g" - -This results in the following access permissions on the local machine: - - [sh]$ xpaget xpa -acl - XPA:xpa 234.567.89.012 g - *:* 123.456.78.910 gisa - *:* localhost gisa - - -The remote client can now use the local server's xpans name server to -establish communication with the local XPA service. This can be done -on a call-by-call basis using the B<-i> switch on xpaset, xpaget, etc: - - [sh]$ xpaget -i "local_machine:12345" xpa - class: XPA - name: xpa - method: 88877766:2778 - sendian: little - cendian: big - -Alternatively, the XPA_NSINET variable on the remote machine can be -set to point directly to xpans on the local machine, removing -the need to override this value each time an XPA program is run: - - [csh]$ setenv XPA_NSINET 'karapet:$port' - [csh]$ xpaget xpa - class: XPA - name: xpa - method: 88877766:2778 - sendian: little - cendian: big - -Here, '$port' means to use the default XPA name service port (14285). -not a port environment variable. - - -Access permission for remote client machines can be stored in a file -on the local machine pointed to by the B<XPA_ACLFILE> environment -variable or using the B<XPA_DEFACL> environment variable. See <A -HREF="./acl.html">XPA Access Control for more information. - -B<Remote Registration> - -If xpans is running on the remote client machine, then a local xpaset -command can be used with the B<-remote> sub-command to -register the local XPA service in the remote name service, while at -the same time giving the remote machine permission to access the local -service. For example, assume again that "stest" is running on the -local machine and that xpans is also running on the remote machine. -To register access of this local xpa on the remote machine, use -the xpaset and the B<-remote> sub-command: - - [sh]$ ./xpaset -p xpa -remote 'remote_machine:$port' + - -To register the local xpa access point on the remote machine with xpaget -access only, execute: - - [sh]$ ./xpaset -p xpa -remote 'remote_machine:$port' g - -Once the remote registration command is executed, the remote client -machine will have an entry such as the following in its own xpans name -service: - - [csh]$ xpaget xpans - XPA xpa gs 88877766:2839 eric - -The xpa access point can now be utilized on the remote machine without -further setup: - - [csh]$ xpaget xpa - class: XPA - name: xpa - method: 838e2f68:2839 - sendian: little - cendian: big - -To unregister remote access from the local machine, use the same -command but with a '-' argument: - - [sh]$ xpaset -p xpa -remote 'remote_machine:$port' - - -The benefit of using remote registration is that communication with -remote access points can be mixed with that of other access points -on the remote machine. Using Access Point -Names and Templates, one XPA command can be used to send or -receive messages to the remote and local services. - -B<XPANS Proxy Registration> - -The two methods described above are useful when the local and remote -machines are able to communicate freely to one another. This would be -the case on most Local Area Networks (LANs) where all machines are -behind the same firewall and there is no port blocking between -machines on the same LAN. The situation is more complicated when the -XPA server is behind a firewall, where outgoing connections are -allowed, but incoming port blocking is implemented to prevent machines -outside the firewall from connecting to machines inside the -firewall. Such incoming port blocking will prevent xpaset and xpaget -from connecting to an XPA server inside a firewall. - - -To allow locally fire-walled XPA services to register with remote -machines, we have implemented a proxy service within the xpans name -server. To register remote proxy service, xpaset and the -B<-remote> sub-command is again used, but with an additional -B<-proxy> argument added to the end of the command: - - [sh]$ ./xpaset -p xpa -remote 'remote_machine:$port' g -proxy - -Once a remote proxy registration command is executed, the remote -machine will have an entry such as the following in its own xpans name -service: - - [csh]$ xpaget xpans - XPA xpa gs @88877766:2839 eric - -The '@' sign in the name service entry indicates that xpans proxy -processing is being used for this access point. Other than that, from -the user's point of view, there is no difference in how this XPA -access point is contacted using XPA programs (xpaset, xpaget, etc.) or -libraries: - - [csh]$ xpaget xpa - class: XPA - name: xpa - method: 88877766:3053 - sendian: little - cendian: big - - -Of course, the underlying processing of the XPA requests is very much -different when xpans proxy is involved. Instead of an XPA program such -contacting the XPA service directly, it contacts the local xpans. -Acting as a proxy server, xpans communicates with the XPA service -using the command channel established at registration time. Commands -(including establishing a new data channel) are sent between xpans and -the XPA service to set up a new message transfer, and then data is fed -to/from the xpa request, through xpans, from/to the XPA service. In -this way, it can be arranged so that connections between the -fire-walled XPA service and the remote client are always initiated by -the XPA service itself. Thus, incoming connections that would be -blocked by the firewall are avoided. Note that there is a performance -penalty for using the xpans/proxy service. Aside from extra overhead -to set up proxy communication, all data must be sent through the -intermediate proxy process. - - -The xpans proxy scheme requires that the remote client allow the local -XPA server machine to connect to the remote xpans/proxy server. If the -remote client machine also is behind a port-blocking firewall, such -connections will be disallowed. In this case, the only solution is to -open up some ports on the remote client machine to allow incoming -connections to xpans/proxy. Two ports must be opened (for command and -data channel connections). By default, these two ports are 14285 and -14287. The port numbers can be changed using the B<XPA_NSINET> -environment variable. This variable takes the form: - - setenv XPA_NSINET machine:port1[,port2[,port3]] - -where port1 is the main connecting port, port2 is the XPA access port, -and port3 is the secondary data connecting port. The second and third -ports are optional and default to port1+1 and port1+2, respectively. -It is port1 and port3 that must be left open for incoming connections. - - -For example, to change the port assignments so that xpans listens -for registration commands on port 12345 and data commands on port 28573: - - setenv XPA_NSINET myhost:12345 - -Alternatively, all three ports can be assigned explicitly: - - setenv XPA_NSINET remote:12345,3000,12346 - -In this case 12345 and 12346 should be open for incoming connections. -The XPA access port (which need not be open to the outside -world) is set to 3000. - - -Finally, note that we currently have no mechanism to cope with -Internet proxy servers (such as SOCKS servers). If an XPA service is -running on a machine that cannot connect directly to outside machines, -but goes through a proxy server instead, there currently is no way to -register that XPA service with a remote machine. We hope to implement -support for SOCKS proxy in a future release. - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - - -=cut diff --git a/xpa/doc/pod/xpainfo.pod b/xpa/doc/pod/xpainfo.pod deleted file mode 100644 index 65fdb3e..0000000 --- a/xpa/doc/pod/xpainfo.pod +++ /dev/null @@ -1,66 +0,0 @@ -=pod - -=head1 NAME - - - -B<xpainfo: send short message to one or more XPA servers> - - - -=head1 SYNOPSIS - - - - - -xpainfo [-h] [-i nsinet] [-m method] [-n] [-s] [-t sval,lval] [-u users] <template|host:port> [paramlist] - - - - - -=head1 OPTIONS - - - - - - -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 - - - - -=head1 DESCRIPTION - - - - -Info will be sent to access points matching the -template -or host:port. -A set of qualifying parameters can be appended. - -B<Examples:> - - csh> xpainfo IMAGE ds9 image - - - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - -=cut diff --git a/xpa/doc/pod/xpainfonew.pod b/xpa/doc/pod/xpainfonew.pod deleted file mode 100644 index ae54f54..0000000 --- a/xpa/doc/pod/xpainfonew.pod +++ /dev/null @@ -1,92 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPAInfoNew: define an XPA info public access point> - - - -=head1 SYNOPSIS - - - - - - #include <xpa.h> - - XPA XPAInfoNew(char *class, char *name, - int (*info_callback)(), - void *info_data, char *info_mode); - - - - - -=head1 DESCRIPTION - - - - -[NB: this is an experimental interface, new to XPA 2.0, whose value -and best use is evolving.] - - -A program can register interest in receiving a short message about a -particular topic from any other process that cares to send such a -message. Neither has to be an XPA server. For example, if a user -starts to work with a new image file called new.fits, she might -wish to alert interested programs about this new file by sending a -short message using xpainfo: - - xpainfo IMAGEFILE /data/new.fits - - - -In this example, each process that has used the XPAInfoNew() call to -register interest in messages associated with the identifier IMAGEFILE -will have its info_callback() executed with the following calling -sequence: - - int info_cb(void *info_data, void *call_data, char *paramlist) - { - XPA xpa = (XPA)call_data; - } - - -The arguments passed to this routine are equivalent to those sent in -the send_callback() routine. The main difference is that there is no -buf sent to the info callback: this mechanism is meant for short -announcement of messages of interest to many clients. - - -The mode string is of the form: "key1=value1,key2=value2,..." -The following keywords are recognized: - - key value default explanation - ------ -------- -------- ----------- - acl true/false true enable access control - - -Because no buf is passed to this callback, the usual buf-related keywords -are not applicable here. - - -The information sent in the parameter list is arbitrary. However, we -envision sending information such as file names or XPA access points -from which to collect more data. Note that the xpainfo program and -the XPAInfo() routine that cause the info_callback to execute do not -wait for the callback to complete before returning. - - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - -=cut diff --git a/xpa/doc/pod/xpaintro.pod b/xpa/doc/pod/xpaintro.pod deleted file mode 100644 index 31ce14f..0000000 --- a/xpa/doc/pod/xpaintro.pod +++ /dev/null @@ -1,176 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPAIntro: Introduction to the XPA Messaging System> - - - -=head1 SYNOPSIS - - - - - -A brief introduction to the XPA messaging system, which provides -seamless communication between all kinds of Unix event-driven -programs, including X programs, Tcl/Tk programs, and Perl programs. - - - -=head1 DESCRIPTION - - - - - -The XPA messaging system provides seamless communication between all -kinds of Unix programs, including X programs, Tcl/Tk programs, and -Perl programs. It also provides an easy way for users to communicate -with these XPA-enabled programs by executing XPA client commands in -the shell or by utilizing such commands in scripts. Because XPA works -both at the programming level and the shell level, it is a powerful -tool for unifying any analysis environment: users and programmers have -great flexibility in choosing the best level or levels at which to -access XPA services, and client access can be extended or modified -easily at any time. - - -A program becomes an XPA-enabled server by defining named points of -public access through which data and commands can be exchanged with -other client programs (and users). Using standard TCP sockets as -a transport mechanism, XPA supports both single-point and broadcast -messaging to and from these servers. It supports direct communication -between clients and servers, or indirect communication via an -intermediate message bus emulation program. Host-based access control -is implemented, as is as the ability to communicate with XPA servers -across a network. - - -XPA implements a layered interface that is designed to be useful both -to software developers and to users. The interface consists of a -library of XPA client and server routines for use in programs and a -suite of high-level user programs built on top of these libraries. -Using the XPA library, access points can be added to -Tcl/Tk -programs, -Xt -programs, or to Unix programs that use the XPA event loop or any -event loop based on select(). Client access subroutines can be added -to any Tcl/Tk or Unix program. Client access also is supported at the -command line via a suite of high-level programs. - - -The major components of the XPA layered interface are: - - -=over 4 - - - - -=item * - -A set of XPA server routines, centered on -XPANew(), -which are used by XPA server programs to tag public access points with -string identifiers and to register send and receive callbacks for -these access points. - - - -=item * - -A set of XPA client routines, centered on the -XPASet() -and -XPAGet(), -which are used by external client applications to exchange data and -commands with an XPA server. - - - -=item * - -High-level programs, centered on -xpaset -and -xpaget, -which allow data -and information to be exchanged with XPA server programs from the -command line and from scripts. These programs have the command syntax: - - [data] | xpaset [qualifiers ...] - xpaget [qualifiers ...] - - - -=item * - -An XPA name server program, -xpans, -through which XPA access point names are -registered by servers and distributed to clients. - - -=back - - - - -Defining an XPA access point is easy: a server application calls -XPANew(), -XPACmdNew(), -or the experimental -XPAInfoNew() -routine to -create a named public access point. An XPA service can specify "send" -and "receive" callback procedures (or an "info" procedure in the case -of XPAInfoNew()) to be executed by the program when an external -process either sends data or commands to this access point or requests -data or information from this access point. Either of the callbacks -can be omitted, so that a particular access point can be specified as -read-only, read-write, or write-only. Application-specific client -data can be associated with these callbacks. Having defined one or -more public access points in this way, an XPA server program enters -its usual event loop (or uses the standard XPA event loop). - - -Clients communicate with these XPA public access points -using programs such as -xpaget, -xpaset, and -xpainfo -(at the command line), -or routines such as -XPAGet(), -XPASet(), -and -XPAInfo() -within a program. Both methods require specification of the name of -the access point. The xpaget program returns data or other -information from an XPA server to its standard output, while the -xpaset program sends data or commands from its standard input to an -XPA application. The corresponding API routines set/get data to/from -memory, returning error messages and other info as needed. If a -template -is used to specify the access point name (e.g., "ds9*"), then -communication will take place with all servers matching that template. - - -Please note that XPA currently is not thread-safe. All XPA calls must be -in the same thread. - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - - -=cut diff --git a/xpa/doc/pod/xpamacros.pod b/xpa/doc/pod/xpamacros.pod deleted file mode 100644 index 786e04b..0000000 --- a/xpa/doc/pod/xpamacros.pod +++ /dev/null @@ -1,76 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPA Server Callback Macros> - - - -=head1 SYNOPSIS - - - - - - #include <xpa.h> - - xpa_class, xpa_name, xpa_method, xpa_cmdfd, xpa_datafd, - xpa_sendian, xpa_cendian - - - - - -=head1 DESCRIPTION - - - - -Server routines have access to information about the XPA being called via -the following macros (each of which takes the xpa handle as an argument): - - macro explanation - ------ ----------- - xpa_class class of this xpa - xpa_name name of this xpa - xpa_method method string (inet or local connect info) - xpa_cmdfd fd of command socket - xpa_datafd fd of data socket - xpa_sendian endian-ness of server ("little" or "big") - xpa_cendian endian-ness of client ("little" or "big" - - -The argument to these macros is the call_data pointer that is passed -to the server procedure. This pointer should be type case to XPA -in the server routine: - - XPA xpa = (XPA)call_data; - - - -The most important of these macros is xpa_datafd(). A server routine -that sets "fillbuf=false" in receive_mode or send_mode can use this -macro to perform I/O directly to/from the client, rather than using -buf. - - -The xpa_cendian and xpa_sendian macros can be used together to determine -if the data transferred from the client is byte swapped with respect -to the server. Values for these macros are: "little", "big", or "?". -In order to do a proper conversion, you still need to know the format -of the data (i.e., byte swapping is dependent on the size of the data -element being converted). - - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - -=cut diff --git a/xpa/doc/pod/xpamainloop.pod b/xpa/doc/pod/xpamainloop.pod deleted file mode 100644 index 4fabf8e..0000000 --- a/xpa/doc/pod/xpamainloop.pod +++ /dev/null @@ -1,108 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPAMainLoop: optional main loop for XPA> - - - -=head1 SYNOPSIS - - - - - - #include <xpa.h> - - void XPAMainLoop(); - - - - - -=head1 DESCRIPTION - - - - -Once XPA access points have been defined, a program must enter an -event loop to watch for requests from external programs. This can be -done in a variety of ways, depending on whether the event loop is -processing events other than XPA events. In cases where there are no -non-XPA events to be processed, the program can simply call the -XPAMainLoop() event loop. This loop is implemented essentially as -follows (error checking is simplified in this example): - - FD_ZERO(&readfds); - while( XPAAddSelect(NULL, &readfds) ){ - if( sgot = select(swidth, &readfds, NULL, NULL, NULL) >0 ) - XPAProcessSelect(&readfds, 0); - else - break; - FD_ZERO(&readfds); - } - - -The XPAAddSelect() routine sets up the select() readfds variable so -that select() will wait for I/O on all the active XPA channels. It -returns the number of XPAs that are active; the loop will end when -there are no active XPAs. The standard select() routine is called to -wait for an external I/O request. Since no timeout struct is passed -in argument 5, the select() call hangs until there is an external -request. When an external I/O request is made, the XPAProcessSelect() -routine is executed to process the pending requests. In this routine, -the maxreq value determines how many requests will be processed: if -maxreq <=0, then all currently pending requests will be processed. -Otherwise, up to maxreq requests will be processed. (The most usual -values for maxreq is 0 to process all requests.) - - -If a program has its own Unix select() loop, then XPA access points can -be added to it by using a variation of the standard XPAMainLoop: - - XPAAddSelect(xpa, &readfds); - [app-specific ...] - if( select(width, &readfds, ...) ){ - XPAProcessSelect(&readfds, maxreq); - [app-specific ...] - FD_ZERO(&readfds); - } - - -XPAAddSelect() is called before select() to add the access points. -If the first argument is NULL, then all active XPA access points -are added. Otherwise only the specified access point is added. -After select() is called, the XPAProcessSelect() routine can be called -to process XPA requests. Once again, the maxreq value determines how -many requests will be processed: if maxreq <=0, then all currently -pending requests will be processed. Otherwise, up to maxreq requests -will be processed. - - -XPA access points can be added to -Xt event loops (using XtAppMainLoop()) -and -Tcl/Tk event loops (using vwait and the Tk loop). -When using XPA with these event loops, you only need to call: - -int XPAXtAddInput(XtAppContext app, XPA xpa) - -or - - int XPATclAddInput(XPA xpa) - -respectively before entering the loop. - - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - -=cut diff --git a/xpa/doc/pod/xpamb.pod b/xpa/doc/pod/xpamb.pod deleted file mode 100644 index fb8ef7c..0000000 --- a/xpa/doc/pod/xpamb.pod +++ /dev/null @@ -1,249 +0,0 @@ -=pod - -=head1 NAME - - - -B<xpamb: the XPA Message Bus> - - - -=head1 SYNOPSIS - - - - - -The xpamb program can act as a "classical" message bus interface -between clients and servers. A client can send a data request to -the message bus, which then interfaces with multiple servers and -returns the data back to the client. - - - -=head1 OPTIONS - - - - - -For xpaset, several optional switches are used to save data and -manipulate the stored data: - - -=over 4 - - - - - - -=item * - -B<-data [name]> - - -Add the supplied data buffer to a pool of stored data buffers, -using the specified name as a unique identifier for later retrieval. -An error occurs if the name already exists (use either B<replace> -or B<del> to rectify this). The B<-add> switch is supported -for backwards compatibility with xpa 2.0. - - - - -=item * - -B<-replace [name]> - - -Replace previously existing stored data having the same unique name -with new data. This essentially is a combination of the B<del> -and B<data> commands. - - - - -=item * - -B<-info ["'info string'"]> - - -When adding a data buffer, you can specify an informational -string to be stored with that data. This string will be returned -by xpaget: - - xpaget xpamb foo -info - -(along with other information such as the date/time of storage and the size of -the data buffer) if the -info switch is specified. If the info string contains -spaces, you must enclose it in B<two> sets of quotes: - - cat foo | xpaset xpamb -data foo -info "'this is info on foo'" - -The first set of quotes is removed by the shell while the second is used to -delineate the info string. - - - - -=item * - -B<-send [name]> - - -Broadcast the stored data buffer to the named template. - - - - -=item * - -B<-del [name]> - - -Delete the named data buffer and free all allocated space. - - -=back - - - - -Switches can be used in any combination that makes sense. For example: - - cat foo.fits | xpaset xpamb -data foo -info "FITS" "DS9:*" fits foo.fits - -will broadcast the foo.fits image to all access points of class -B<DS9>. In addition, the foo.fits file will be stored under the -name of B<foo> for later manipulation such as: - - xpaset -p xpamb -send foo "DS9:*" fits foo.fits - -will re-broadcast the foo.fits image to all access points of class "DS9". - - - -=head1 DESCRIPTION - - - - - -A "classical" message bus (such as ToolTalk) consists of servers and -clients, along with a mediating program that transfers data between -different processes. XPA takes a slightly different approach in that -communication between clients and servers is direct. This generally -is the correct technique when there is only one connection (or even a -small number of connections), but can become inefficient for the -serving program if a large amount of data is being transferred to many -clients. For example, if a real-time data acquisition program is -broadcasting a FITS image to several clients, it would need to -transmit that image to each client individually. This might interfere -with its own processing cycles. The preferable mechanism would be to -pass the image off to an intermediate program that can then broadcast -the data to the several clients. - -The B<xpamb> program can alleviate such problems by functioning -as a message bus in cases where such an intermediary process is -wanted. It pre-defines a single access point named -B<XPAMB:xpamb> to which data can be sent for re-broadcast. You -also can tell B<xpamb> to save the data, and associate with that -data a new access point, so that it can be retrieved later on. - - -All interaction with B<xpamb> is performed through -B<xpaset> and B<xpaget> (or the corresponding API -routines, B<XPASet()> and B<XPAGet()>) to the -B<XPAMB:xpamb> access point. That is, B<xpamb> is just -another XPA-enabled program that responds to requests from -clients. The paramlist is used to specify the targets to which -the data will be for re-broadcast, as well as the re-broadcast paramlist: - - data | xpaset xpamb [switches] broadcast-target broadcast-paramlist - -Optional switches are used to store data, and manipulate stored data, -and are described below. - - -In its simplest form, you can, for example, send a FITS image to xpamb for -broadcasting to all ds9 image simply by executing: - - cat foo.fits | xpaset xpamb "DS9:*" fits foo.fits - -Since B<DS9> is the class name for the ds9 image display -program, this will result in the FITS image being re-sent to all fits -access points for all active image display programs. - - -You can send stored data and new data to the same set of access points at -the same time. The stored data always is sent first, followed by the new -data: - - cat foo2.fits | xpaset xpamb -send foo "DS9:*" fits foo.fits - -will first send the foo.fits file, and then the foo2.fits file to all -access points of class B<DS9>. Notice that in this example, -the foo2.fits file is not stored, but it could be stored by using the -B<-store [name]> switch on the command line. - - -The B<xpaget> command can be used to retrieve a data from XPA -access points or from a stored data buffer, or retrieve information -about a stored data buffer. If no arguments are given: - - xpaget xpamb - -then information about all currently stored data buffers is returned. This -information includes the data and time at which the data was stored, the -size in bytes of the data, and the supplied info string. - - -If arguments are specified, they will be in the form: - - xpaget xpamb [-info] [-data] [name [paramlist]] - -If the optional B<-info> and/or B<-data> switches are specified, then -information and/or data will be returned for the named data buffer -following the switches. You can use either or both of these switches -in a single command. For example, if the -info switch is used: - - xpaget xpamb -info foo - -then the info about that stored data buffer will be returned. -If the -data is used with a specific name: - - xpaget xpamb -data foo - -then the stored data itself will be returned. If both are used: - - xpaget xpamb -info -data foo - -then the info will be returned, followed by the data. Note that it is an -error to specify one of these switches without a data buffer name and that -the paramlist will be ignored. - - -If neither the B<-info> or B<-data> switch is specified, then -the name refers to an XPA access point (with an optional paramlist -following). -For example: - - xpaget xpamb ds9 file - -is equivalent to: - - xpaget ds9 file - - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - - -=cut diff --git a/xpa/doc/pod/xpamethod.pod b/xpa/doc/pod/xpamethod.pod deleted file mode 100644 index 038ac4e..0000000 --- a/xpa/doc/pod/xpamethod.pod +++ /dev/null @@ -1,99 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPAMethod: XPA Communication Methods> - - - -=head1 SYNOPSIS - - - - - -XPA supports both inet and unix (local) socket communication. - - - -=head1 DESCRIPTION - - - - - -XPA uses sockets for communication between processes. It supports -three methods of socket communication: inet, localhost, and unix. In -general, the same method should be employed for all XPA processes in a -session and the global environment variable XPA_METHOD should be used -to set up the desired method. By default, the preferred method is -"inet", which is appropriate for most users. You can set up a -different method by typing something like: - - setenv XPA_METHOD local # unix csh - XPA_METHOD=local; export XPA_METHOD # unix sh, bash, windows/cygwin - set XPA_METHOD=localhost # dos/windows - -The options for XPA_METHOD are: B<inet>, B<unix> (or -B<local>), and B<localhost>. On Unix machines, this -environment setup command can be placed in your shell init file -(.cshrc, .profile, .bashrc, etc.) On Windows platforms, it can be -placed in your AUTOEXEC.BAT file (I think!). - - -By default, B<inet> sockets are used by XPA. These are the standard -Internet sockets that are used by programs such as Netscape, -ftp. etc. Inet sockets utilize the IP address of the given machine and -a (usually random) port number to communicate between processes on the -same machine or between different machines on the Internet. (Note that -XPA has an Access Control mechanism to -prevent unauthorized access of XPA access points by other computers on -the Net). For users connected to the Internet, this usually is the -appropriate communication method. For more information about setting -up XPA communication between machines, see -Communication Between Machines. - - -In you are using XPA on a machine without an Internet connection, then -inet sockets are not appropriate. In fact, an XPA process often will -hang for many seconds while waiting for a response from the Domain -Name Service (DNS) when using inet sockets. Instead of inet sockets, -users on Unix platforms can also use B<unix> sockets (also known -as local sockets). These sockets are based on the local file system -and do not make use of the DNS. They generally are considered to be -faster than inet sockets, but they are not implemented under -Windows. Use local sockets as a first resort if you are on a Unix -machine that is not connected to the Internet. - - -Users not connected to the Internet also can use B<localhost> -sockets. These are also inet-type sockets but the IP address used for -the local machine is the B<localhost> address, 0x7F000001, instead -of the real IP of the machine. Depending on how sockets are set up for -a given platform, communication with the DNS usually is not required in -this case (though of course, XPA cannot interact with other machines). -The localhost method will generally work on both Unix and Windows -platforms, but whether the DNS is required or not is subject to -individual configurations. - - -A final warning/reminder: if your XPA-enabled server hangs at startup -time and your XPA_METHOD is B<inet>, the problem probably is -related to an incorrect Internet configuration. This can be confirmed -by using the B<unix> method or (usually) the B<localhost> -method. You can use these alternate methods if other hosts do not need -access to the XPA server. - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - - -=cut diff --git a/xpa/doc/pod/xpaname.pod b/xpa/doc/pod/xpaname.pod deleted file mode 100644 index 7c0ea8d..0000000 --- a/xpa/doc/pod/xpaname.pod +++ /dev/null @@ -1,56 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPAName: What does XPA stand for?> - - - -=head1 SYNOPSIS - - - - - -What does XPA stand for? Who knows anymore! - - - -=head1 DESCRIPTION - - - - - -What does XPA stand for? Dunno! The XPA messaging system originally -was built on top of the X Window System and XPA was the mnemonic for -I<X Public Access>, to emphasize that we were providing public -access to previously private data and algorithms in Xt programs. Now -that XPA no longer is tied to X, it can be argued that we ought to -change the name (how about SPAM: simple public access mechanism -), but XPA is in wide-spread use in the astronomical community of -its birth, and the name has taken on a life of its own. If anyone can -think of what XPA now means, please let us know. - - -If you think this is bad, consider the MMT Telescope on Mount Hopkins, -Arizona. When first installed twenty years ago, it featured an array -of six 72-inch diameter mirrors. from which came its name: the -I<Multiple Mirror Telescope>. In spring of 1999, these mirrors -were replaced by a single 21 and 1/2 -foot diameter primary mirror, -the largest single-piece glass reflector on the North American -continent. And now MMT stands for ... MMT! - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - - -=cut diff --git a/xpa/doc/pod/xpanew.pod b/xpa/doc/pod/xpanew.pod deleted file mode 100644 index 1a3800f..0000000 --- a/xpa/doc/pod/xpanew.pod +++ /dev/null @@ -1,243 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPANew: create a new XPA access point> - - - -=head1 SYNOPSIS - - - - - - #include <xpa.h> - - XPA XPANew(char *class, char *name, char *help, - int (*send_callback)(), - void *send_data, char *send_mode, - int (*rec_callback)(), - void *rec_data, char *rec_mode); - - - - - -=head1 DESCRIPTION - - - - -Create a new XPA public access point with the class:name -identifier template -and enter this access point into the XPA name server, so that it -can be accessed by external processes. XPANew() returns an XPA struct. -Note that the length of the class and name designations must be less -than or equal to 1024 characters each. - - -The XPA name server daemon, xpans, will be started automatically if it -is not running already (assuming it can be found in the path). The -program's ip address and listening port are specified by the -environment variable XPA_NSINET, which takes the form :. If -no such environment variable exists, then xpans is started on the -current machine listening on port 14285. It also uses 14286 as a -known port for its public access point (so that routines do not have -to go to the name server to find the name server ip and port!) -As of XPA 2.1.1, version information is exchanged between the xpans -process and the new access point. If the access point uses an XPA -major/minor version newer than xpans, a warning is issued by both processes, -since mixing of new servers and old xpa programs (xpaset, xpaget, -xpans, etc.) is not likely to work. You can turn off the warning -message by setting the XPA_VERSIONCHECK environment variable to "false". - - -The help string is meant to be returned by a request from xpaget: - - xpaget class:name -help - - -A send_callback and/or a receive_callback can be specified; at -least one of them must be specified. - - -A send_callback can be specified that will be executed in response to -an external request from the xpaget program, the XPAGet() routine, or -XPAGetFd() routine. This callback is used to send data to the -requesting client. - - -The calling sequence for send_callback() is: - - int send_callback(void *send_data, void *call_data, - char *paramlist, char **buf, size_t *len) - { - XPA xpa = (XPA)call_data; - ... - return(stat); - } - - -The send_mode string is of the form: "key1=value1,key2=value2,..." -The following keywords are recognized: - - key value default explanation - ------ -------- -------- ----------- - acl true/false true enable access control - freebuf true/false true free buf after callback completes - - -The call_data should be recast to the XPA struct as shown. In -addition, client-specific data can be passed to the callback in -send_data. - - -The paramlist will be supplied by the client as qualifying parameters -for the callback. There are two ways in which the send_callback() -routine can send data back to the client: - - -1. The send_callback() routine can fill in a buffer and pass back a -pointer to this buffer. An integer len also is returned to specify the -number of bytes of data in buf. XPA will send this buffer to the -client after the callback is complete. - - -2. The send_callback can send data directly to the client by writing -to the fd pointed by the macro: - - xpa_datafd(xpa) - - -Note that this fd is of the kind returned by socket() or open(). - - -If a buf has been allocated by a standard malloc routine, filled, and -returned to XPA, then freebuf generally is set so that the buffer will -be freed automatically when the callback is completed and data has -been sent to the client. If a static buf is returned, freebuf should -be set to false to avoid a system error when freeing static storage. -Note that default value for freebuf implies that the callback will -allocate a buffer rather than use static storage. - - -On the other hand, if buf is dynamically allocated using a method -other than a standard malloc/calloc/realloc routine (e.g. using Perl's -memory allocation and garbage collection scheme), then it is necessary -to tell XPA how to free the allocated buffer. To do this, use the -XPASetFree() routine within your callback: - - void XPASetFree(XPA xpa, void (*myfree)(void *), void *myfree_ptr); - -The first argument is the usual XPA handle. The second argument is the -special routine to call to free your allocated memory. The third -argument is an optional pointer. If not NULL, the specified free -routine is called with that pointer as its sole argument. If NULL, the -free routine is called with the standard buf pointer as its sole -argument. This is useful in cases where there is a mapping between the -buffer pointer and the actual allocated memory location, and the -special routine is expecting to be passed the former. - - -If, while the callback performs its processing, an error occurs that -should be communicated to the client, then the routine XPAError should be -called: - - XPAError(XPA xpa, char *s); - - -where s is an arbitrary error message. The returned error message -string will be of the form: - - XPA$ERROR [error] (class:name ip:port) - - -If the callback wants to send a specific acknowledgment message back -to the client, the routine XPAMessage can be called: - - XPAMessage(XPA xpa, char *s); - - -where s is an arbitrary error message. The returned error message -string will be of the form: - - XPA$MESSAGE [message] (class:name ip:port) - - -Otherwise, a standard acknowledgment is sent back to the client -after the callback is completed. - - -The callback routine should return 0 if no error occurs, or -1 to -signal an error. - - -A receive_callback can be specified that will be executed in response -to an external request from the xpaset program, or the XPASet (or -XPASetFd()) routine. This callback is used to process data received -from an external process. - - -The calling sequence for receive_callback is: - - int receive_callback(void *receive_data, void *call_data, - char *paramlist, char *buf, size_t len) - { - XPA xpa = (XPA)call_data; - ... - return(stat); - } - - -The mode string is of the form: "key1=value1,key2=value2,..." -The following keywords are recognized: - - key value default explanation - ------ -------- -------- ----------- - acl true/false true enable access control - buf true/false true server expects data bytes from client - fillbuf true/false true read data into buf before executing callback - freebuf true/false true free buf after callback completes - - -The call_data should be recast to the XPA struct as shown. In -addition, client-specific data can be passed to the callback in -receive_data. - - -The paramlist will be supplied by the client. In addition, if the -receive_mode keywords buf and fillbuf are true, then on entry into the -receive_callback() routine, buf will contain the data sent by the -client. If buf is true but fillbuf is false, it becomes the callback's -responsibility to retrieve the data from the client, using the data fd -pointed to by the macro xpa_datafd(xpa). If freebuf is true, then buf -will be freed when the callback is complete. - - -If, while the callback is performing its processing, an error occurs -that should be communicated to the client, then the routine XPAError -can be called: - - XPAError(XPA xpa, char *s); - - -where s is an arbitrary error message. - - -The callback routine should return 0 if no error occurs, or -1 to -signal an error. - - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - -=cut diff --git a/xpa/doc/pod/xpans.pod b/xpa/doc/pod/xpans.pod deleted file mode 100644 index 071dd68..0000000 --- a/xpa/doc/pod/xpans.pod +++ /dev/null @@ -1,226 +0,0 @@ -=pod - -=head1 NAME - - - -B<xpans: the XPA Name Server> - - - -=head1 SYNOPSIS - - - - - - xpans [-h] [-e] [-k sec] [-p port] [-l log] [-s security log] [-P n] - - - - -=head1 OPTIONS - - - - - - -h print help message - -e exit when there are no more XPA connections - -k send keepalive messages every n sec - -l log data base entries to specified file - -p listen for connections on specified port - -s log security info for each connection to specified file - -P accept proxy requests (P=1) using separate thread (P=2) - --version display version and exit - - - - -=head1 DESCRIPTION - - - - -The xpans name server is an XPA-enabled program that is used to -manage the names and ports of XPA access points. It is started -automatically when an XPA access point is registered. You can access -the name server using xpaget to get a list of registered access points. - -The I<xpans> name server provides a crucial link between XPA -clients and servers. When an XPA server defines an access point using -XPANew(), XPACmdNew(), or XPAInfoNew(), the name of the access point -is registered in the name service, along with connection information. -The name server then matches class:name templates passed to it by XPA -clients with these registered entries, so that the clients can -communicate with the appropriate servers. - - -The socket connection between an XPA-enabled program and -I<xpans> is kept open until the former exits (or explicitly -closes the connection). Apparently, some Internet equipment (e.g. DSL -modems) can cause such a connection to time-out after a period of -inactivity. To prevent this from happening, you can use the -k -[sec] switch to send a short keep-alive message to each open -connection after the specified time delay. (Note that this -application level use of keep-alive is necessary only if you are -serving XPA-enabled clients over the Internet and have to deal with -long-term connections involving DSL or similar equipment. XPA uses -the ordinary socket-level keep-alive, which works for all other cases.) -NB (12/2/2009): Out-of-band (URG) TCP data, used by xpans -keep-alive, is changed by some Cisco routers into in-band data. -Encountering such a router will break the keep-alive function and may -break your XPA server as well. Proceed with caution! - - -The I<xpans> program will be started automatically (assuming it -can be found in the user's path) when the first XPA access point is -registered. It therefore need not be started explicitly. However, -when started automatically, the I<-e> switch is used, so that -the name server will exit when there are no more XPA access points -registered. If you wish to keep the name server running continually, -simply start it manually without the I<-e> switch. - - -The name server will keep a log of registered access points if the -I<-l [log]> switch is used on the command line (this is the -case for automatic start-up). The log contains enough name and connection -information to allow you to re-register all XPA access points in case -the name server process is terminated prematurely. For example, after -the ds9 access point is registered,the log will contain the entry: - - add 838e2f67:1863 ds9 ds9 gs eric - -If I<xpans> is terminated but ds9 still is running, you -can re-register both access points for the ds9 process by running: - - xpaset -p 838e2f67:1863 -nsconnect - -Notice that the ip:port specifier is used with I<xpaset> to bypass -the need for contacting the name server (which does not have the name -registered yet!) - - -The name server will keep a log of security information if the -s -[security log] switch is used on the command line. For each -accepted connection, (including connections via the I<xpaget> -command), information will be logged about the host issuing the -command and the parameters passed into the program. This is most -useful when I<xpans> is accepting connections from untrusted -machines. - - -When an XPA access point is removed by a server using I<XPAFree()>, -the access information is removed from the name server. If an -XPA-enabled process is terminated, all names registered by that process -will be removed automatically. The log file is always updated to -reflect the currently registered access points. - - -The name server itself has an XPA access point names I<xpans> -registered through which you can find out information about currently -registered access points (assuming you have access to the name server; -see XPA Access Control for more information). -For each registered access point, the following information is returned: - - class # class of the access point - name # name of the access point - access # allowed access (g=xpaget,s=xpaset,i=xpainfo) - id # socket access method (host:port for inet, file for local/unix) - user # user name of access point owner - - - -For example, to display all currently registered access points, simply execute: - - xpaget xpans - -Continuing the example of ds9 above, this will return: - - DS9 ds9 gs 838e2f67:1863 eric - -If the same program has been started with different XPA access names, -you can look up only names matching a specified template. For example, -assume that ds9 has been started up using: - - ds9 & - ds9 -title ds9-1-eric & - ds9 -title ds9-2-eric & - -To lookup all ds9 access points which end in ".eric" and which can -be accessed using I<xpaset>, use: - - xpaget xpans "DS9:*.eric" "s" "*" - -This will return: - - DS9 ds9-2-eric gs 838e29d3:42102 eric - DS9 ds9-1-eric gs 838e29d3:42105 eric - -The third argument "*" requests all access points from all users. -You also can specify a specific user name and only access points -registered by that user will be returned. - - -The name server uses the I<XPA_METHOD> environment variable -to determine whether it should listen for requests on INET or LOCAL -sockets. Since XPA access points also use this environment variable, -the choice of socket method will be consistent. Note that, when INET -sockets are used, a local server can be accessed from remote machines -if the I<XPA_NSINET> environment variable is set to point to -the local machine. See -XPA Environment Variables -for more information. - - -An experimental feature of xpans is its ability to act as a proxy to -XPA servers behind firewalls that want to communicate with external -processes. The basic idea is the following: an XPA server (call it -"foo") on host1, possibly behind a firewall, makes a remote connection -to a proxy-enabled xpans program on host2 (specifying host2's XPA method). -For example: - - xpaset -p foo -remote 'host2:28571' + -proxy # on host1 - -When this is done, host2 can use xpaset, xpaget, and xpainfo calls to -communicate with the XPA server foo. All command communication is -performed via the xpans socket connection between foo on host1 and -xpans on host2 (which was initiated by foo from inside the firewall). -Data communication is similarly performed using a socket connection -initiated on host1 (usually with a port value two greater than the -port value of the main xpans socket connection). An xpaset or xpaget -call on host2 contacts xpans, which performs an XPASet() or XPAGet() -call to foo, passing commands and data back and forth between the two -programs. - - -By default, proxy connections are not allowed by xpans. If the -P switch is -specified with a value of 1, proxy connection are allowed, but all proxy -communication is performed in the same thread as xpans processing. If -a value of 2 is specified, the proxy processing is performed in a -separate thread (assuming pthreads are supported on your system). -Because xpa callback processing of any type can take a long time and -therefore can interfere with normal xpans processing, threaded proxy -connections (-P 2) are recommended. When using proxy connections, it -might also be useful to set the XPA_IOCALLSXPA environment variable, so -that multiple proxy requests can be handled at the same time, instead of -serially. - - -Note that this proxy interface to xpans is experimental. It is used -to provide remote data analysis capabilities on the Chandra-Ed system -using ds9. (See http://chandra-ed.cfa.harvard.edu and -http://hea-www.harvard.edu/saord/ds9 for more details). As always, please -contact us if you have problems or questions. - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - - -=cut diff --git a/xpa/doc/pod/xpanslookup.pod b/xpa/doc/pod/xpanslookup.pod deleted file mode 100644 index e0f4cdc..0000000 --- a/xpa/doc/pod/xpanslookup.pod +++ /dev/null @@ -1,126 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPANSLookup: lookup registered XPA access points> - - - -=head1 SYNOPSIS - - - - - - #include <xpa.h> - - int XPANSLookup(XPA xpa, - char *template, char type, - char ***classes, char ***names, - char ***methods, char ***infos) - - - - - -=head1 DESCRIPTION - - - - -XPA routines act on a class:name identifier in such a way -that all access points that match the identifier are processed. It is -sometimes desirable to choose specific access points from the -candidates that match the -template. In order to do this, the -XPANSLookup routine can be called to return a list of matches, so that -specific class:name instances can then be fed to XPAGet(), XPASet(), etc. - - The first argument is an optional XPA struct. If non-NULL, the -existing name server connection associated with the specified xpa is -used to query the xpans name server for matching templates. Otherwise, -a new (temporary) connection is established with the name server. - - -The second argument to XPANSLookup is the class:name -template -to match. - - -The third argument for XPANSLookup() is the type of access and can be -any combination of: - - type explanation - ------ ----------- - g xpaget calls can be made on this access point - s xpaset calls can be made on this access point - i xpainfo calls can be made on this access point - - -The call typically specifies only one of these at a time. - - -The final arguments are pointers to arrays that will be filled -in and returned by the name server. The name server will allocate and -return arrays filled with the classes, names, and methods of all XPA -access points that match the template -and have the specified type. Also returned are info strings, which -generally are used internally by the client routines. These can be -ignored (but the strings must be freed). The function returns the -number of matches. The returned value can be used to loop through the -matches: - -B<Example:> - - #include <xpa.h> - - char **classes; - char **names; - char **methods; - char **infos; - int i, n; - n = XPANSLookup(NULL, "foo*", "g", &classes, &names, &methods, &infos); - for(i=0; i<n; i++){ - [more specific checks on possibilities ...] - [perhaps a call to XPAGet for those that pass, etc. ...] - /* don't forget to free alloc'ed strings when done */ - free(classes[i]); - free(names[i]); - free(methods[i]); - free(infos[i]); - } - /* free up arrays alloc'ed by names server */ - if( n > 0 ){ - free(classes); - free(names); - free(methods); - free(infos); - } - - -The specified -template -also can be a host:port specification, for example: - - myhost:12345 - - -In this case, no connection is made to the name server. Instead, the -call will return one entry such that the ip array contains the ip for -the specified host and the port array contains the port. The class -and name entries are set to the character "?", since the class and -name of the access point are not known. - - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - -=cut diff --git a/xpa/doc/pod/xpaoom.pod b/xpa/doc/pod/xpaoom.pod deleted file mode 100644 index b8b2431..0000000 --- a/xpa/doc/pod/xpaoom.pod +++ /dev/null @@ -1,60 +0,0 @@ -=pod - -=head1 NAME - - - -B<Xpaoom: What happens when XPA runs out of memory?> - - - -=head1 SYNOPSIS - - - - - -When XPA can't allocate memory, it exits. You can arrange to have it call -longjmp() instead. - - - -=head1 DESCRIPTION - - - - - -When an XPA server or client cannot allocate memory, it will attempt to -output an error message and then exit. If this is not satisfactory (e.g., -perhaps your program is interactive and can recover from OOM errors), you -can tell XPA to call longjmp() to go to a recovery branch. To pass the -requisite jmp_buf variable to XPA, make the following call: - - XPASaveJmp(void *env); - -The value of env is the address of a jmp_buf variable that was previously -passed to setjmp(). For example: - - jmp_buf env; - ... - if( setjmp(jmp_buf) != 0 ){ - /* out of memory -- take corrective action, if possible */ - } else { - /* save env for XPA */ - XPASaveJmp((void *)&jmp_buf); - } - // enter main loop ... - - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - - -=cut diff --git a/xpa/doc/pod/xpaopen.pod b/xpa/doc/pod/xpaopen.pod deleted file mode 100644 index d88df02..0000000 --- a/xpa/doc/pod/xpaopen.pod +++ /dev/null @@ -1,69 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPAOpen: allocate a persistent client handle> - - - -=head1 SYNOPSIS - - - - - - #include <xpa.h> - - XPA XPAOpen(char *mode); - - - - - -=head1 DESCRIPTION - - - - -XPAOpen() allocates a persistent XPA struct that can be used with -calls to XPAGet(), XPASet(), XPAInfo(), XPAGetFd(), and -XPASetFd(). Persistence means that a connection to an XPA server is -not closed when one of the above calls is completed but will be -re-used on successive calls. Using XPAOpen() therefore saves the time -it takes to connect to a server, which could be significant with slow -connections or if there will be a large number of exchanges with a -given access point. The mode argument currently is ignored ("reserved -for future use"). - - -An XPA struct is returned if XPAOpen() was successful; otherwise NULL -is returned. This returned struct can be passed as the first argument -to XPAGet(), etc. Those calls will update the list of active XPA -connections. Already connected servers (from a previous call) are -left connected and new servers also will be connected. Old servers -(from a previous call) that are no longer needed are disconnected. -The connected servers will remain connected when the next call to -XPAGet() is made and connections are once again updated. - - -B<Example:> - - #include <xpa.h> - - XPA xpa; - xpa = XPAOpen(NULL); - - - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - -=cut diff --git a/xpa/doc/pod/xpapoll.pod b/xpa/doc/pod/xpapoll.pod deleted file mode 100644 index 1f26ee1..0000000 --- a/xpa/doc/pod/xpapoll.pod +++ /dev/null @@ -1,58 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPAPoll: execute existing XPA requests> - - - -=head1 SYNOPSIS - - - - - - #include <xpa.h> - - int XPAPoll(int msec, int maxreq); - - - - - -=head1 DESCRIPTION - - - - -It is sometimes desirable to implement a polling loop, i.e., where one -checks for and processes XPA requests without blocking. For this -situation, use the XPAPoll() routine: - - XPAPoll(int msec, int maxreq); - - -The XPAPoll() routine will perform XPAAddSelect() and select(), but with a -timeout specified in millisecs by the msec argument. If one or more -XPA requests are made before the timeout expires, the XPAProcessSelect() -routine is called to process those requests. The maxreq value determines -how many requests will be processed: if maxreq < 0, then no events are -processed, but instead, the return value indicates the number of events -that are pending. If maxreq == 0, then all currently pending requests -will be processed. Otherwise, up to maxreq requests will be processed. -(The most usual values for maxreq are 0 to process all requests and 1 -to process one request). - - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - -=cut diff --git a/xpa/doc/pod/xparace.pod b/xpa/doc/pod/xparace.pod deleted file mode 100644 index 418b8a0..0000000 --- a/xpa/doc/pod/xparace.pod +++ /dev/null @@ -1,89 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPA Race Conditions> - - - -=head1 SYNOPSIS - - - -Potential XPA race conditions and how to avoid them. - - - -=head1 DESCRIPTION - - - - -Currently, there is only one known circumstance in which XPA can get -(temporarily) deadlocked in a race condition: if two or more XPA -servers send messages to one another using an XPA client routine such -as XPASet(), they can deadlock while each waits for the other server -to respond. (This can happen if the servers call XPAPoll() with a -time limit, and send messages in between the polling call.) The -reason this happens is that both client routines send a string to the -other server to establish the handshake and then wait for the server -response. Since each client is waiting for a response, neither is able -to enter its event-handling loop and respond to the other's -request. This deadlock will continue until one of the timeout periods -expire, at which point an error condition will be triggered and the -timed-out server will return to its event loop. - - -Starting with version 2.1.6, this rare race condition can be -avoided by setting the XPA_IOCALLSXPA environment variable for servers -that will make client calls. Setting this variable causes all XPA -socket IO calls to process outstanding XPA requests whenever the -primary socket is not ready for IO. This means that a server making a -client call will (recursively) process incoming server requests while -waiting for client completion. It also means that a server callback -routine can handle incoming XPA messages if it makes its own XPA call. -The semi-public routine oldvalue=XPAIOCallsXPA(newvalue) can be used -to turn this behavior off and on temporarily. Passing a 0 will turn -off IO processing, 1 will turn it back on. The old value is returned -by the call. - - -By default, the XPA_IOCALLSXPA option is turned off, because we judge -that the added code complication and overhead involved will not be -justified by the amount of its use. Moreover, processing XPA requests -within socket IO can lead to non-intuitive results, since incoming -server requests will not necessarily be processed to completion in the -order in which they are received. - - -Aside from setting XPA_IOCALLSXPA, the simplest way to avoid this race -condition is to multi-process: when you want to send a client message, -simply start a separate process to call the client routine, so that -the server is not stopped. It probably is fastest and easiest to use -fork() and then have the child call the client routine and exit. But -you also can use either the system() or popen() routine to start one -of the command line programs and do the same thing. Alternatively, you -can use XPA's internal launch() routine instead of system(). Based on -fork() and exec(), this routine is more secure than system() because -it does not call /bin/sh. - - -Starting with version 2.1.5, you also can send an XPAInfo() message with -the mode string "ack=false". This will cause the client to send a message -to the server and then exit without waiting for any return message from -the server. This UDP-like behavior will avoid the server deadlock when -sending short XPAInfo messages. - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - - -=cut diff --git a/xpa/doc/pod/xpaserver.pod b/xpa/doc/pod/xpaserver.pod deleted file mode 100644 index 275defd..0000000 --- a/xpa/doc/pod/xpaserver.pod +++ /dev/null @@ -1,96 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPAServer: The XPA Server-side Programming Interface> - - - -=head1 SYNOPSIS - - - - -A description of the XPA server-side programming interface. - - - -=head1 DESCRIPTION - - - -B<Introduction to XPA Server Programming> - -Creating an XPA server is easy: you generally only need to call the -XPANew() subroutine to define a named XPA access point and set up the -send and receive callback routines. You then enter an event loop such -as XPAMainLoop() to field XPA requests. - - #include <xpa.h> - - XPA XPANew(char *class, char *name, char *help, - int (*send_callback)(), void *send_data, char *send_mode, - int (*rec_callback)(), void *rec_data, char *rec_mode); - - XPA XPACmdNew(char *class, char *name); - - XPACmd XPACmdAdd(XPA xpa, - char *name, char *help, - int (*send_callback)(), void *send_data, char *send_mode, - int (*rec_callback)(), void *rec_data, char *rec_mode); - - void XPACmdDel(XPA xpa, XPACmd cmd); - - XPA XPAInfoNew(char *class, char *name, - int (*info_callback)(), void *info_data, char *info_mode); - - int XPAFree(XPA xpa); - - void XPAMainLoop(void); - - int XPAPoll(int msec, int maxreq); - - void XPAAtExit(void); - - void XPACleanup(void); - - - -B<Introduction> - -To use the XPA application programming interface, a software developer -generally will include the xpa.h definitions file: - - #include <xpa.h> - -in the software module that defines or accesses an XPA access point, and -then will link against the libxpa.a library: - - gcc -o foo foo.c libxpa.a - -XPA has been compiled using both C and C++ compilers. - - -A server program generally defines an XPA access point by calling the -XPANew() routine and specifies "send" and/or "receive" callback -procedures to be executed by the program when an external process -either sends data or commands to this access point or requests data or -information from this access point. A program also can define several -sub-commands for a single access point by calling XPACmdNew() and -XPACmdAdd() instead. Having defined one or more public access points -in this way, an XPA server program enters its usual event loop (or -uses the standard XPA event loop). - - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - -=cut diff --git a/xpa/doc/pod/xpaset.pod b/xpa/doc/pod/xpaset.pod deleted file mode 100644 index 19c2dbe..0000000 --- a/xpa/doc/pod/xpaset.pod +++ /dev/null @@ -1,115 +0,0 @@ -=pod - -=head1 NAME - - - -B<xpaset: send data to one or more XPA servers> - - - -=head1 SYNOPSIS - - - - - -<data> | xpaset [-h] [-i nsinet] [-m method] [-n] [-p] [-s] [-t sval,lval] [-u users] [-v] <template|host:port> [paramlist] - - - - - -=head1 OPTIONS - - - - - - -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 - - - - -=head1 DESCRIPTION - - - - -Data read from stdin will be sent to access points matching the -template -or host:port. -A set of qualifying parameters can be appended. - -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: - - cat foo.fits | xpaset ds9 fits - - -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: - - csh> xpaset -p ds9 cmap Heat - -Of course, this also can be accomplished by sending EOF to stdin in -any of the usual ways: - - csh> echo "" | xpaset ds9 cmap Heat - csh> xpaget ds9 cmap Heat < /dev/null - csh> xpaset ds9 cmap Heat - ^D # Ctl-D signals EOF - - -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: - - - csh> xpaset -s - xpaset ds9 colormap I8 - ^D - xpaset ds9 regions - circle 200 300 40 - circle 300 400 50 - ^D -etc. - -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. - -NB: server mode only works from the terminal and only ASCII data can be -sent in this way. - -B<Examples:> - - csh> xpaset ds9 file < foo.fits - csh> echo "stop" | xpaset myhost:12345 - - - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - -=cut diff --git a/xpa/doc/pod/xpasetfd.pod b/xpa/doc/pod/xpasetfd.pod deleted file mode 100644 index 6a49684..0000000 --- a/xpa/doc/pod/xpasetfd.pod +++ /dev/null @@ -1,113 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPASetFd: send data from stdin to one or more XPA servers> - - - -=head1 SYNOPSIS - - - - - - #include <xpa.h> - - int XPASetFd(XPA xpa, - char *template, char *paramlist, char *mode, - int fd, char **names, char **messages, int n) - - - - - -=head1 DESCRIPTION - - - - -Read data from a standard I/O fd and send it to one or more XPA -servers whose class:name identifier matches the specified -template. - - -A -template -of the form "class1:name1" is sent to the -XPA name server, which returns a list of at most n matching XPA -servers. A connection is established with each of these servers and -the paramlist string is passed to the server as the data transfer -request is initiated. If an XPA struct is passed to the call, then the -persistent connections are updated as described above. Otherwise, -temporary connections are made to the servers (which will be closed -when the call completes). - - -The XPASetFd() routine then reads bytes from the specified fd -until EOF and sends these bytes to the XPA servers. -The final parameter n specifies the maximum number of servers to contact. -A string containing the class:name and ip:port of each server is returned in -the name array. If a given server returned an error, then the error -message will be stored in the associated element of the messages array. -NB: if specified, the name and messages arrays must be of size n or greater. - - -The return value will contain the actual number of servers that were -processed. This value thus will hold the number of valid entries in -the names and messages arrays, and can be used to loop through these -arrays. In names and/or messages is NULL, no information is passed back -in that array. - - -The mode string is of the form: "key1=value1,key2=value2,..." -The following keywords are recognized: - - key value default explanation - ------ -------- -------- ----------- - ack true/false true if false, don't wait for ack from server (after callback completes) - verify true/false false send buf from XPASet[Fd] to stdout - - -The ack keyword is useful in cases where one does not want to wait for -the server to complete, e.g. is a lot of processing needs to be done -on the passed data or when the success of the server operation is not -relevant to the client. - - -B<Example:> - - #include <xpa.h> - - #define NXPA 10 - int i, got; - int fd; - char *names[NXPA]; - char *messages[NXPA]; - fd = open(...); - got = XPASetFd(NULL, "ds9", "fits", NULL, fd, names, messages, NXPA); - for(i=0; i<got; i++){ - if( messages[i] != NULL ){ - /* error processing */ - fprintf(stderr, "ERROR: %s (%s)\n", messages[i], names[i]); - } - if( names[i] ) - free(names[i]); - if( messages[i] ) - free(messages[i]); - } - - - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - -=cut diff --git a/xpa/doc/pod/xpatcl.pod b/xpa/doc/pod/xpatcl.pod deleted file mode 100644 index 008a4f3..0000000 --- a/xpa/doc/pod/xpatcl.pod +++ /dev/null @@ -1,258 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPATcl: the XPA Interface to the Tcl/Tk Environment> - - - -=head1 SYNOPSIS - - - - - - -Tcl/Tk programs can act as XPA clients and/or servers using the Tcl -interface to XPA that is contained in the libtclxpa.so shared object. - -B<Server Routines> - - - set xpa [xpanew class name help sproc sdata smode rproc rdata rmode] - xpafree xpa - set xpa [xpanew class name help iproc idata imode] - set xpa [xpacmdnew class name] - xpacmdadd xpa name help sproc sdata smode rproc rdata rmode - xpacmddel xpa cmd - set val [xparec xpa option] - options: name, class, method, cmdfd, datafd, cmdchan, datachan - xpasetbuf xpa buf len - xpaerror xpa message - xpamessage xpa message - - -B<Client Routines> - - - set xpa [xpaopen mode] - xpaclose xpa - set got [xpaget xpa template paramlist mode bufs lens names errs n] - set got [xpaget xpa template paramlist mode chans names errs n] - set got [xpaset xpa template paramlist mode buf len names errs n] - set got [xpasetfd xpa template paramlist mode chan names errs n] - set got [xpainfo xpa template paramlist mode names errs n] - # NB: 2.1 calling sequence change - # set got [xpaaccess template type] (2.0.5) - set got [xpaaccess xpa template paramlist mode names errs n] - set got [xpanslookup template type classes names methods] - - - - -=head1 DESCRIPTION - - - - - -You can call XPANew(), XPACmdNew(), or XPAInfoNew() within a C -routine to add C-based XPA server callbacks to a TCL/Tk program that -uses a Tcl/Tk event loop (either vwait() or the Tk event loop); -Such a program does not need or want to use the XPA event loop. -Therefore, in order to add XPA access points to the Tcl/Tk loop, the -following routine should be called beforehand: - - int XPATclAddInput(XPA xpa); - - -Normally, the xpa argument is NULL, meaning that all current XPA -access points are registered with the event loop. However, if a -single XPA access point is to be added (i.e., after the event loop is -started) then the handle of that XPA access point can be passed to -this routine. - - -The significance of the XPA/TCL interface goes beyond the support for -using XPA inside C code. The interface allows you to write XPA -servers and to make calls to the XPA client interface within the Tcl -environment using the Tcl language directly. The XPA/Tcl -interface can be loaded using the following package command: - - package require tclxpa 2.0 - -Alternatively, you can load the shared object (called libtclxpa.so ) directly: - - load .../libtclxpa.so tclxpa - - -Once the tclxpa package is loaded, you can use Tcl versions of XPA -routines to define XPA servers or make client XPA calls. The -interface for these routines is designed to match the Unix XPA -interface as nearly as possible. Please refer to -XPA Servers -and -XPA Clients -for general information about these routines. - - -The file test.tcl in the XPA source directory gives examples for using the -XPA/Tcl interface. - - -The following notes describe the minor differences between the interfaces. - -B<XPANew> - - - set xpa [xpanew class name help sproc sdata smode rproc rdata rmode] - - - -rproc and sproc routines are routines. The calling sequence of the -rproc routine is identical to its C counterpart: - - proc rec_cb { xpa client_data paramlist buf len } { ... } - - -The sproc routine, however is slightly different from its C counterpart -because of the difficulty of passing data back from the callback to C: - - proc sendcb { xpa client_data paramlist } { ... } - - -Note that the C-based server's char **buf and int *len arguments are -missing from the Tcl callback. This is because we did not know how to -fill buf with data and pass it back to the C routines for communication -with the client. Instead, the Tcl server callback uses the following -routine to set buf and len: - - xpasetbuf xpa buf len - -where: - - arg explanation - ------ ----------- - xpa the first argument of the server callback - buf the data to be returned to the client - len data length in bytes, (if absent, use length of the buf object) - - -When this routine is called, a copy of buf is saved for transmission to -the client. - - -The fact that buf is duplicated means that TCL server writers might wish to -perform the I/O directly within the callback, rather than have XPA do it -automatically at the end of the routine. To do this, set: - - fillbuf=false - - -in the xpanew smode and then perform I/O through the Tcl channel -obtained from: - - set dchan [xparec $xpa datachan] - - -where: - - arg explanation - ------ ----------- - xpa the first argument of the server callback - datachan literal string "datachan" that returns the data channel - len data length in bytes, (if absent, use length of the buf object) - - - -NB: datachan and cmdchan are not available under Windows. It is -necessary to use the "raw" equivalents: datafd and cmdfd. - - - -The same considerations apply to the rproc for receive servers: a copy -of the incoming data is generated to pass to the receive callback. This -copy again can be avoided by using "fillbuf=false" in the rmode and then -reading the incoming data from datachan. - - -The send and receive callback routines can use the xpaerror and xpamessage -routines to send errors and messages back to the client. If you also -want tcl itself to field an error condition, use the standard return call: - - return ?-code c? ?-errorinfo i? ?-errorcode ec? string - - -See the Tcl man page for more info. - -B<XPARec> - -The Tcl xparec procedure supplies server routines with access to information -that is available via macros in the C interface: - - set val [xparec xpa <option>] - - -where option is: name, class, method, cmdfd, datafd, cmdchan, -datachan. Note that two additional identifiers, cmdchan and datachan, -have been added to to provide Tcl channels corresponding to datafd and -cmdfd. (These latter might still be retrieved in Tcl and passed back -to a C routines.) An additional option called "version" can be used to -determine the XPA version used to build the Tcl interface. Note that -the standard options require a valid XPA handle, but "version" does -not (since it simply reports the value of the XPA_VERSION definition -in the XPA source include file). - - - -NB: datachan and cmdchan are not available under Windows. It is -necessary to use the "raw" equivalents: datafd and cmdfd. - - - macro explanation - ------ ----------- - class class of this xpa - name name of this xpa - method method string (inet or local connect info) - cmdchan Tcl channel of command socket - datachan Tcl channel of data socket - cmdfd fd of command socket - datafd fd of data socket - sendian endian-ness of server ("little" or "big") - cendian endian-ness of client ("little" or "big" - version XPA version used to build this code - - - -Under Windows, the Tcl event handler cannot automatically sense when an -XPA socket is ready for IO (i.e. Tcl_CreateFileHandler() is not available -under Windows). The Windows Tcl event handler therefore must be awakened -occasionally for check for XPA events. This is done using the standard -Tcl_SetMaxBlockTime() call. The time parameter is defined in tclloop.c -and is currently set to 1000 microseconds (1/1000 of a second). - - -The version option can be used to differentiate between source code versions. -It was created to support legacy Tcl code that needs to maintain the 2.0.5 -calling sequence for xpaaccess. You can use a version test such as: - - if [catch { xparec "" version } version] { - puts "pre-2.1.0e" - } else { - puts [split $version .] - } - - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - - -=cut diff --git a/xpa/doc/pod/xpatemplate.pod b/xpa/doc/pod/xpatemplate.pod deleted file mode 100644 index 1524934..0000000 --- a/xpa/doc/pod/xpatemplate.pod +++ /dev/null @@ -1,120 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPATemplate: Access Point Names and Templates> - - -=head1 SYNOPSIS - - - - - -XPA access points are composed of two parts: a general class and a -specific name. Both parts accept template characters so that you -can send/retrieve data to/from multiple servers at one time. - - - -=head1 DESCRIPTION - - - - - -When XPA servers call -XPANew(), -or -XPACmdNew() -to define XPA access points, they specify a string identifier composed of a -class and a name. When clients communicate with XPA access points, -they specify which access points to communicate with using -an identifier of the form: - - class:name - -All registered XPA access points that match the specified identifier -will be available for communication (subject to access control rules, -etc.) - - -As of XPA 2.1.5, the length of both the class and name designations are -limited to 1024 characters. - - -The XPA class:name identifier actually is a template: it accepts wild -cards in its syntax, so a single specifier can match more than one XPA -access point. (Note that the class is optional and defaults to "*".) -The allowed syntax for clients to specify the class:name template is -of the form shown below. (Note that "*" is used to denote a generic -wild card, but other wild cards characters are supported, as described -below). - - template explanation - -------- ----------- - class:name exact match of class and name - name match any class with this name - *:name match any class with this name - class:* match any name of this class - *:* match any access point - - -In general, the following wild-cards can be applied to class and name: - - wildcard explanation - -------- ----------- - ? match any character, but there must be one - * match anything, or nothing - [...] match an inclusive set - - -Although the class:name template normally is used to refer to XPA -access points, these also can be specified using their individual -socket identifiers. For inet sockets, the socket identifier is -B<ip:port>, where ip can be the DNS-registered name, -the ASCII IP number (e.g. 123.45.67.890) or the hex IP number -(e.g. 838f3a60). For unix sockets, the identifier is the socket file -name. These socket identifiers are displayed as the fourth argument -in the xpans display of registered access points. For example, -consider the ds9 program started using inet sockets. The xpans name -server will register something like this: - - csh> xpaget xpans - DS9 ds9 gs saord.harvard.edu:3236 eric - -You can access ds9 using ip:3236 in any of the three forms: - - csh> xpaget saord:3236 file - /home/eric/data/snr.ev - - csh> xpaget 123.45.67.890:3236 file - /home/eric/data/snr.ev - - csh> xpaget 838f3a60:3236 file - /home/eric/data/snr.ev - -In the case of unix sockets, the socket identifier is a file: - - csh> xpaget xpans - DS9 ds9 gs /tmp/.xpa/DS9_ds9.2631 eric - - csh> xpaget /tmp/.xpa/DS9_ds9.2631 file - /home/eric/data/snr.ev - -This feature can be useful in distinguishing between multiple -instances of a program that all have the same class:name designation. - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - - -=cut diff --git a/xpa/doc/pod/xpausers.pod b/xpa/doc/pod/xpausers.pod deleted file mode 100644 index 4c3353b..0000000 --- a/xpa/doc/pod/xpausers.pod +++ /dev/null @@ -1,76 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPAUsers: Distinguishing Users> - - - -=head1 SYNOPSIS - - - - - -XPA normally distinguishes between users on a given host, but it is possible -to send data to access points belonging to other users. - - - -=head1 DESCRIPTION - - - - - -A single XPA name service typically serves all users on a given -machine. Two users can register the same XPA access points on the -same machine without conflict, because the user's username is -registered with each access point and, by default, programs such as -xpaget and xpaset only process access points of the appropriate user. -For example: - - XPA xpa1 gs 838e2f67:1262 eric - XPA xpa2 gs 838e2f67:1266 eric - XPA xpa1 gs 838e2f67:2523 john - XPA xpa2 gs 838e2f67:2527 john - -Here the users "eric" and "john" both have registered the access -points xpa1 and xpa2. When either "john" or "eric" retrieves -information from xpa1, they will process only the access point -registered in their user name. - - -If you want to access another user's XPA access points on a single -machine, use the -u [user] option on xpaset, xpaget, etc. For example, -if eric executes: - - xpaget -u john xpa1 - -he will access John's xpa1 access point.Use "*" to access all users -on a given machine: - - xpaget -u "*" xpa1 - -Note that the XPA Environment Variable -XPA_NSUSERS can be used to specify the default list of users to -process: - - setenv XPA_NSUSERS "eric,john" - -will cause access points from both "eric" and "john" to be processed -by default. - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - - -=cut diff --git a/xpa/doc/pod/xpaxt.pod b/xpa/doc/pod/xpaxt.pod deleted file mode 100644 index 34e1049..0000000 --- a/xpa/doc/pod/xpaxt.pod +++ /dev/null @@ -1,56 +0,0 @@ -=pod - -=head1 NAME - - - -B<XPAXt: the XPA Interface to Xt (X Windows)> - - - -=head1 SYNOPSIS - - - - -Describes how XPA access points can be added to X Toolkit (Xt) programs. - - - -=head1 DESCRIPTION - - - - - -XPA supports Xt programs: you can call XPANew(), XPACmdNew(), or -XPAInfoNew() within any C routine to add XPA server callbacks to an Xt -program. Since an Xt program has its own event loop call (i.e., -XtAppMainLoop()), it therefore does not need or want to use the XPA -even loop. Thus, in order to add XPA access points to the standard Xt -event loop, the following routine should be called before entering the -loop: - - int XPAXtAddInput(XtAppContext app, XPA xpa) - - -The XPAAddAddInput() routine will add XPA access points to the Xt event -loop by making calls to the standard XtAppAddInput() routine. (If the -XtAppContext argument is NULL, then the alternate XtAddInput() routine -is used instead.) If the xpa argument is NULL, then all active XPA -access points are added to the loop. If xpa is not NULL, then only -the specified access point is added. The latter type of call is used -to add new access points from within a callback, after the program has -entered the XtAppMainLoop() even loop. - - - -=head1 SEE ALSO - - - -See xpa(n) for a list of XPA help pages - - - -=cut diff --git a/xpa/doc/programs.html b/xpa/doc/programs.html deleted file mode 100644 index b37031f..0000000 --- a/xpa/doc/programs.html +++ /dev/null @@ -1,274 +0,0 @@ -<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> diff --git a/xpa/doc/server.html b/xpa/doc/server.html deleted file mode 100644 index 2e10b11..0000000 --- a/xpa/doc/server.html +++ /dev/null @@ -1,833 +0,0 @@ -<!-- =defdoc xpaserver xpaserver 3 --> -<HTML> -<HEAD> -<TITLE>XPA Server API</TITLE> -</HEAD> -<BODY> - -<!-- =section xpaserver NAME --> -<H2><A NAME="xpaserver">XPAServer: The XPA Server-side Programming Interface</A></H2> - -<!-- =section xpaserver SYNOPSIS --> -<H2>Summary</H2> -A description of the XPA server-side programming interface. - -<!-- =section xpaserver DESCRIPTION --> -<H2><A NAME="intro">Introduction to XPA Server Programming</H2></A> -<P> -Creating an XPA server is easy: you generally only need to call the -XPANew() subroutine to define a named XPA access point and set up the -send and receive callback routines. You then enter an event loop such -as XPAMainLoop() to field XPA requests. -<PRE> - #include <xpa.h> - - XPA <A HREF="./server.html#xpanew">XPANew</A>(char *class, char *name, char *help, - int (*send_callback)(), void *send_data, char *send_mode, - int (*rec_callback)(), void *rec_data, char *rec_mode); - - XPA <A HREF="./server.html#xpacmdnew">XPACmdNew</A>(char *class, char *name); - - XPACmd <A HREF="./server.html#xpacmdadd">XPACmdAdd</A>(XPA xpa, - char *name, char *help, - int (*send_callback)(), void *send_data, char *send_mode, - int (*rec_callback)(), void *rec_data, char *rec_mode); - - void <A HREF="./server.html#xpacmddel">XPACmdDel</A>(XPA xpa, XPACmd cmd); - - XPA <A HREF="./server.html#xpainfonew">XPAInfoNew</A>(char *class, char *name, - int (*info_callback)(), void *info_data, char *info_mode); - - int <A HREF="./server.html#xpafree">XPAFree</A>(XPA xpa); - - void <A HREF="./server.html#xpamainloop">XPAMainLoop</A>(void); - - int <A HREF="./server.html#xpapoll">XPAPoll</A>(int msec, int maxreq); - - void <A HREF="./server.html#xpaatexit">XPAAtExit</A>(void); - - void <A HREF="./server.html#xpacleanup">XPACleanup</A>(void); - -</PRE> - -<H2>Introduction</H2> - -To use the XPA application programming interface, a software developer -generally will include the xpa.h definitions file: -<PRE> - #include <xpa.h> -</PRE> -in the software module that defines or accesses an XPA access point, and -then will link against the libxpa.a library: -<PRE> - gcc -o foo foo.c libxpa.a -</PRE> -XPA has been compiled using both C and C++ compilers. - -<P> -A server program generally defines an XPA access point by calling the -XPANew() routine and specifies "send" and/or "receive" callback -procedures to be executed by the program when an external process -either sends data or commands to this access point or requests data or -information from this access point. A program also can define several -sub-commands for a single access point by calling XPACmdNew() and -XPACmdAdd() instead. Having defined one or more public access points -in this way, an XPA server program enters its usual event loop (or -uses the standard XPA event loop). - -<!-- =defdoc xpanew xpanew 3 --> - -<!-- =section xpanew NAME --> -<H2><A NAME="xpanew">XPANew: create a new XPA access point</A></H2> - -<!-- =section xpanew SYNOPSIS --> -<B> -<PRE> - #include <xpa.h> - - XPA XPANew(char *class, char *name, char *help, - int (*send_callback)(), - void *send_data, char *send_mode, - int (*rec_callback)(), - void *rec_data, char *rec_mode); -</PRE> -</B> - -<!-- =section xpanew DESCRIPTION --> -<P> -Create a new XPA public access point with the class:name -identifier <A HREF="./template.html">template</A> -and enter this access point into the XPA name server, so that it -can be accessed by external processes. XPANew() returns an XPA struct. -Note that the length of the class and name designations must be less -than or equal to 1024 characters each. - -<P> -The XPA name server daemon, xpans, will be started automatically if it -is not running already (assuming it can be found in the path). The -program's ip address and listening port are specified by the -environment variable XPA_NSINET, which takes the form <ip>:<port>. If -no such environment variable exists, then xpans is started on the -current machine listening on port 14285. It also uses 14286 as a -known port for its public access point (so that routines do not have -to go to the name server to find the name server ip and port!) -As of XPA 2.1.1, version information is exchanged between the xpans -process and the new access point. If the access point uses an XPA -major/minor version newer than xpans, a warning is issued by both processes, -since mixing of new servers and old xpa programs (xpaset, xpaget, -xpans, etc.) is not likely to work. You can turn off the warning -message by setting the XPA_VERSIONCHECK environment variable to "false". - -<P> -The help string is meant to be returned by a request from xpaget: -<PRE> - xpaget class:name -help -</PRE> -<P> -A send_callback and/or a receive_callback can be specified; at -least one of them must be specified. - -<P> -A send_callback can be specified that will be executed in response to -an external request from the xpaget program, the XPAGet() routine, or -XPAGetFd() routine. This callback is used to send data to the -requesting client. - -<P> -The calling sequence for send_callback() is: -<PRE> - int send_callback(void *send_data, void *call_data, - char *paramlist, char **buf, size_t *len) - { - XPA xpa = (XPA)call_data; - ... - return(stat); - } -</PRE> -<P> -The send_mode string is of the form: "key1=value1,key2=value2,..." -The following keywords are recognized: -<PRE> - key value default explanation - ------ -------- -------- ----------- - acl true/false true enable access control - freebuf true/false true free buf after callback completes -</PRE> -<P> -The call_data should be recast to the XPA struct as shown. In -addition, client-specific data can be passed to the callback in -send_data. - -<P> -The paramlist will be supplied by the client as qualifying parameters -for the callback. There are two ways in which the send_callback() -routine can send data back to the client: - -<P> -1. The send_callback() routine can fill in a buffer and pass back a -pointer to this buffer. An integer len also is returned to specify the -number of bytes of data in buf. XPA will send this buffer to the -client after the callback is complete. - -<P> -2. The send_callback can send data directly to the client by writing -to the fd pointed by the macro: -<PRE> - xpa_datafd(xpa) -</PRE> -<P> -Note that this fd is of the kind returned by socket() or open(). - -<P> -If a buf has been allocated by a standard malloc routine, filled, and -returned to XPA, then freebuf generally is set so that the buffer will -be freed automatically when the callback is completed and data has -been sent to the client. If a static buf is returned, freebuf should -be set to false to avoid a system error when freeing static storage. -Note that default value for freebuf implies that the callback will -allocate a buffer rather than use static storage. - -<P> -On the other hand, if buf is dynamically allocated using a method -other than a standard malloc/calloc/realloc routine (e.g. using Perl's -memory allocation and garbage collection scheme), then it is necessary -to tell XPA how to free the allocated buffer. To do this, use the -XPASetFree() routine within your callback: -<PRE> - void XPASetFree(XPA xpa, void (*myfree)(void *), void *myfree_ptr); -</PRE> -The first argument is the usual XPA handle. The second argument is the -special routine to call to free your allocated memory. The third -argument is an optional pointer. If not NULL, the specified free -routine is called with that pointer as its sole argument. If NULL, the -free routine is called with the standard buf pointer as its sole -argument. This is useful in cases where there is a mapping between the -buffer pointer and the actual allocated memory location, and the -special routine is expecting to be passed the former. - -<P> -If, while the callback performs its processing, an error occurs that -should be communicated to the client, then the routine XPAError should be -called: -<PRE> - XPAError(XPA xpa, char *s); -</PRE> -<P> -where s is an arbitrary error message. The returned error message -string will be of the form: -<PRE> - XPA$ERROR [error] (class:name ip:port) -</PRE> -<P> -If the callback wants to send a specific acknowledgment message back -to the client, the routine XPAMessage can be called: -<PRE> - XPAMessage(XPA xpa, char *s); -</PRE> -<P> -where s is an arbitrary error message. The returned error message -string will be of the form: -<PRE> - XPA$MESSAGE [message] (class:name ip:port) -</PRE> -<P> -Otherwise, a standard acknowledgment is sent back to the client -after the callback is completed. - -<P> -The callback routine should return 0 if no error occurs, or -1 to -signal an error. - -<P> -A receive_callback can be specified that will be executed in response -to an external request from the xpaset program, or the XPASet (or -XPASetFd()) routine. This callback is used to process data received -from an external process. - -<P> -The calling sequence for receive_callback is: -<PRE> - int receive_callback(void *receive_data, void *call_data, - char *paramlist, char *buf, size_t len) - { - XPA xpa = (XPA)call_data; - ... - return(stat); - } -</PRE> -<P> -The mode string is of the form: "key1=value1,key2=value2,..." -The following keywords are recognized: -<PRE> - key value default explanation - ------ -------- -------- ----------- - acl true/false true enable access control - buf true/false true server expects data bytes from client - fillbuf true/false true read data into buf before executing callback - freebuf true/false true free buf after callback completes -</PRE> -<P> -The call_data should be recast to the XPA struct as shown. In -addition, client-specific data can be passed to the callback in -receive_data. - -<P> -The paramlist will be supplied by the client. In addition, if the -receive_mode keywords buf and fillbuf are true, then on entry into the -receive_callback() routine, buf will contain the data sent by the -client. If buf is true but fillbuf is false, it becomes the callback's -responsibility to retrieve the data from the client, using the data fd -pointed to by the macro xpa_datafd(xpa). If freebuf is true, then buf -will be freed when the callback is complete. - -<P> -If, while the callback is performing its processing, an error occurs -that should be communicated to the client, then the routine XPAError -can be called: -<PRE> - XPAError(XPA xpa, char *s); -</PRE> -<P> -where s is an arbitrary error message. - -<P> -The callback routine should return 0 if no error occurs, or -1 to -signal an error. - -<!-- =defdoc xpacmdnew xpacmdnew 3 --> - -<!-- =section xpacmdnew NAME --> -<H2><A NAME="xpacmdnew">XPACmdNew: create a new XPA public access point for commands</A></H2> - -<!-- =section xpacmdnew SYNOPSIS --> -<B> -<PRE> - #include <xpa.h> - - XPA XPACmdNew(char *class, char *name); -</PRE> -</B> - -<!-- =section xpacmdnew DESCRIPTION --> -<P> -Create a new XPA public access point for commands that will share a -common identifier class:name. Enter this access point into the XPA -name server, so that it can be accessed by external processes. -XPACmdNew() returns an XPA struct. - -<P> -It often is more convenient to have one public access point that can -manage a number of commands, rather than having individual access -points for each command. For example, it is easier to command the -ds9 image display using: -<PRE> - echo "colormap I8" | xpaset ds9 - echo "scale log" | xpaset ds9 - echo "file foo.fits" | xpaset ds9 -</PRE> -<P> -then to use: -<PRE> - echo "I8" | xpaset ds9_colormap - echo "log" | xpaset ds9_scale - echo "foo.fits" | xpaset ds9_file -</PRE> -<P> -In the first case, the commands remain the same regardless of the -target XPA name. In the second case, the command names must change -for each instance of ds9. That is, if a second instance of ds9 -called DS9 were running, it would be commanded either as: -<PRE> - echo "colormap I8" | xpaset DS9 - echo "scale log" | xpaset DS9 - echo "file foo.fits" | xpaset DS9 -</PRE> -<P> -or as: -<PRE> - echo "I8" | xpaset DS9_colormap - echo "log" | xpaset DS9_scale - echo "foo.fits" | xpaset DS9_file -</PRE> -<P> -Thus, in cases where a program is going to manage many commands, it -generally is easier to define them as commands associated with the -XPACmdNew() routine, rather than as separate access points using -XPANew(). - -<P> -When XPACmdNew() is called, only the class:name identifier is -specified. Each sub-command is subsequently defined using the -XPACmdAdd() routine. - -<!-- =defdoc xpacmdadd xpacmdadd 3 --> - -<!-- =section xpacmdadd NAME --> -<H2><A NAME="xpacmdadd">XPACmdAdd: add a command to an XPA command public access point</A></H2> - -<!-- =section xpacmdadd SYNOPSIS --> -<B> -<PRE> - #include <xpa.h> - - XPACmd XPACmdAdd(XPA xpa, char *name, char *help, - int (*send_callback)(), - void *send_data, char *send_mode, - int (*rec_callback)(), - void *rec_data, char *rec_mode); -</PRE> -</B> - -<!-- =section xpacmdadd DESCRIPTION --> -<P> -Add a command to an XPA command access point. The XPA argument specifies the -XPA struct returned by a call to XPANewCmd(). The name argument is the -name of the command. The other arguments function identically to the -arguments in the XPANew() command, i.e., the send_callback and rec_callback -routines have identical calling sequences to their XPANew() counterparts, -with the exceptions noted below. - -<P> -When help is requested for a command access point using: -<PRE> - xpaget -h class:name -</PRE> -<P> -all of the command help strings are listed. To get help for a given -command, use: -<PRE> - xpaget -h class:name cmd -</PRE> -<P> -Also, the acl keyword in the send_mode and receive_mode strings is -global to the access point, not local to the command. Thus, the value -for the acl mode should be the same in all send_mode (or receive_mode) -strings for each command in a command access point. (The acl for -send_mode need not be the same as the acl for receive_mode, though). - -<!-- =defdoc xpacmddel xpacmddel 3 --> - -<!-- =section xpacmddel NAME --> -<H2><A NAME="xpacmddel">XPACmdDel: remove a command from an XPA command public access point</A></H2> - -<!-- =section xpacmddel SYNOPSIS --> -<B> -<PRE> - #include <xpa.h> - - void XPACmdDel(XPA xpa, XPACmd cmd); -</PRE> -</B> - -<!-- =section xpacmddel DESCRIPTION --> -<P> -This routine removes a command from the list of available commands in -a given XPA. That command will no longer be available for processing. - -<!-- =defdoc xpainfonew xpainfonew 3 --> - -<!-- =section xpainfonew NAME --> -<H2><A NAME="xpainfonew">XPAInfoNew: define an XPA info public access point</A></H2> - -<!-- =section xpainfonew SYNOPSIS --> -<B> -<PRE> - #include <xpa.h> - - XPA XPAInfoNew(char *class, char *name, - int (*info_callback)(), - void *info_data, char *info_mode); -</PRE> -</B> - -<!-- =section xpainfonew DESCRIPTION --> -<P> -[NB: this is an experimental interface, new to XPA 2.0, whose value -and best use is evolving.] - -<P> -A program can register interest in receiving a short message about a -particular topic from any other process that cares to send such a -message. Neither has to be an XPA server. For example, if a user -starts to work with a new image file called new.fits, she might -wish to alert interested programs about this new file by sending a -short message using xpainfo: -<PRE> - xpainfo IMAGEFILE /data/new.fits -</PRE> - -<P> -In this example, each process that has used the XPAInfoNew() call to -register interest in messages associated with the identifier IMAGEFILE -will have its info_callback() executed with the following calling -sequence: -<PRE> - int info_cb(void *info_data, void *call_data, char *paramlist) - { - XPA xpa = (XPA)call_data; - } -</PRE> -<P> -The arguments passed to this routine are equivalent to those sent in -the send_callback() routine. The main difference is that there is no -buf sent to the info callback: this mechanism is meant for short -announcement of messages of interest to many clients. - -<P> -The mode string is of the form: "key1=value1,key2=value2,..." -The following keywords are recognized: -<PRE> - key value default explanation - ------ -------- -------- ----------- - acl true/false true enable access control -</PRE> -<P> -Because no buf is passed to this callback, the usual buf-related keywords -are not applicable here. - -<P> -The information sent in the parameter list is arbitrary. However, we -envision sending information such as file names or XPA access points -from which to collect more data. Note that the xpainfo program and -the XPAInfo() routine that cause the info_callback to execute do not -wait for the callback to complete before returning. - -<!-- =defdoc xpafree xpafree 3 --> - -<!-- =section xpafree NAME --> -<H2><A NAME="xpafree">XPAFree: remove an XPA public access point</A></H2> - -<!-- =section xpafree SYNOPSIS --> -<PRE> -<B> - #include <xpa.h> - - int XPAFree(XPA xpa); -</B> -</PRE> - -<!-- =section xpafree DESCRIPTION --> -<P> -Remove the specified XPA public access point from the name server and -free all associated storage. Note that removal from the name server -happens automatically when the process terminates, so this call is not -generally needed. It is used when public access points are being -defined temporarily and then destroyed when no longer needed. For -example, ds9 temporarily creates a public access point when it -loads a new image for display and destroys it when the image is -unloaded. - -<!-- =defdoc xpamainloop xpamainloop 3 --> - -<!-- =section xpamainloop NAME --> -<H2><A NAME="xpamainloop">XPAMainLoop: optional main loop for XPA</A></H2> - -<!-- =section xpamainloop SYNOPSIS --> -<B> -<PRE> - #include <xpa.h> - - void XPAMainLoop(); -</PRE> -</B> - -<!-- =section xpamainloop DESCRIPTION --> -<P> -Once XPA access points have been defined, a program must enter an -event loop to watch for requests from external programs. This can be -done in a variety of ways, depending on whether the event loop is -processing events other than XPA events. In cases where there are no -non-XPA events to be processed, the program can simply call the -XPAMainLoop() event loop. This loop is implemented essentially as -follows (error checking is simplified in this example): -<PRE> - FD_ZERO(&readfds); - while( XPAAddSelect(NULL, &readfds) ){ - if( sgot = select(swidth, &readfds, NULL, NULL, NULL) >0 ) - XPAProcessSelect(&readfds, 0); - else - break; - FD_ZERO(&readfds); - } -</PRE> -<P> -The XPAAddSelect() routine sets up the select() readfds variable so -that select() will wait for I/O on all the active XPA channels. It -returns the number of XPAs that are active; the loop will end when -there are no active XPAs. The standard select() routine is called to -wait for an external I/O request. Since no timeout struct is passed -in argument 5, the select() call hangs until there is an external -request. When an external I/O request is made, the XPAProcessSelect() -routine is executed to process the pending requests. In this routine, -the maxreq value determines how many requests will be processed: if -maxreq <=0, then all currently pending requests will be processed. -Otherwise, up to maxreq requests will be processed. (The most usual -values for maxreq is 0 to process all requests.) - -<P> -If a program has its own Unix select() loop, then XPA access points can -be added to it by using a variation of the standard XPAMainLoop: -<PRE> - XPAAddSelect(xpa, &readfds); - [app-specific ...] - if( select(width, &readfds, ...) ){ - XPAProcessSelect(&readfds, maxreq); - [app-specific ...] - FD_ZERO(&readfds); - } -</PRE> -<P> -XPAAddSelect() is called before select() to add the access points. -If the first argument is NULL, then all active XPA access points -are added. Otherwise only the specified access point is added. -After select() is called, the XPAProcessSelect() routine can be called -to process XPA requests. Once again, the maxreq value determines how -many requests will be processed: if maxreq <=0, then all currently -pending requests will be processed. Otherwise, up to maxreq requests -will be processed. - -<P> -XPA access points can be added to -<A HREF="./xt.html">Xt event loops</A> (using XtAppMainLoop()) -and -<A HREF="./tcl.html">Tcl/Tk event loops</A> (using vwait and the Tk loop). -When using XPA with these event loops, you only need to call: -<PRE> -int XPAXtAddInput(XtAppContext app, XPA xpa) -</PRE> -or -<PRE> - int XPATclAddInput(XPA xpa) -</PRE> -respectively before entering the loop. - -<!-- =defdoc xpapoll xpapoll 3 --> - -<!-- =section xpapoll NAME --> -<H2><A NAME="xpapoll">XPAPoll: execute existing XPA requests</A></H2> - -<!-- =section xpapoll SYNOPSIS --> -<B> -<PRE> - #include <xpa.h> - - int XPAPoll(int msec, int maxreq); -</PRE> -</B> - -<!-- =section xpapoll DESCRIPTION --> -<P> -It is sometimes desirable to implement a polling loop, i.e., where one -checks for and processes XPA requests without blocking. For this -situation, use the XPAPoll() routine: -<PRE> - XPAPoll(int msec, int maxreq); -</PRE> -<P> -The XPAPoll() routine will perform XPAAddSelect() and select(), but with a -timeout specified in millisecs by the msec argument. If one or more -XPA requests are made before the timeout expires, the XPAProcessSelect() -routine is called to process those requests. The maxreq value determines -how many requests will be processed: if maxreq < 0, then no events are -processed, but instead, the return value indicates the number of events -that are pending. If maxreq == 0, then all currently pending requests -will be processed. Otherwise, up to maxreq requests will be processed. -(The most usual values for maxreq are 0 to process all requests and 1 -to process one request). - -<!-- =defdoc xpaatexit xpaatexit 3 --> - -<!-- =section xpaatexit NAME --> -<H2><A NAME="xpaatexit">XPAAtExit: install exit handler</A></H2> - -<!-- =section xpaatexit SYNOPSIS --> -<PRE> -<B> - #include <xpa.h> - - void XPAAtExit(void); -</B> -</PRE> - -<!-- =section xpaatexit DESCRIPTION --> -<P> -XPAAtExit() will install an exit handler using atexit() to run XPAFree on all -XPA access points. This might be useful in cases where Unix sockets are being -used: if an explicit call to XPAFree() is not made by the program, the Unix -socket file will not be deleted immediately without an atexit handler. (NB: this -call should not be made in a Tcl/Tk application. Accessing the Tcl native file -system after Tcl has shut down all file systems causes the Tcl/Tl program to -crash). - -<!-- =defdoc xpacleanup xpacleanup 3 --> - -<!-- =section xpacleanup NAME --> -<H2><A NAME="xpacleanup">XPACleanup: release reserved XPA memory</A></H2> - -<!-- =section xpacleanup SYNOPSIS --> -<PRE> -<B> - #include <xpa.h> - - void XPACleanup(void); -</B> -</PRE> - -<!-- =section xpacleanup DESCRIPTION --> -<P> -When XPA is initialized, it allocates a small amount of memory for the -access control list, temp directory path, and reserved commands. This -memory is found by valgrind to be "still reachable", meaning that "your -program didn't free some memory it could have". Calling the -XPACleanup() routine before exiting the program will free this memory -and make valgrind happy. - -<!-- =defdoc xpamacros xpamacros 3 --> - -<!-- =section xpamacros NAME --> -<H2><A NAME="macros">XPA Server Callback Macros</A></H2> - -<!-- =section xpamacros SYNOPSIS --> -<B> -<PRE> - #include <xpa.h> - - xpa_class, xpa_name, xpa_method, xpa_cmdfd, xpa_datafd, - xpa_sendian, xpa_cendian -</PRE> -</B> - -<!-- =section xpamacros DESCRIPTION --> -<P> -Server routines have access to information about the XPA being called via -the following macros (each of which takes the xpa handle as an argument): -<PRE> - macro explanation - ------ ----------- - xpa_class class of this xpa - xpa_name name of this xpa - xpa_method method string (inet or local connect info) - xpa_cmdfd fd of command socket - xpa_datafd fd of data socket - xpa_sendian endian-ness of server ("little" or "big") - xpa_cendian endian-ness of client ("little" or "big" -</PRE> -<P> -The argument to these macros is the call_data pointer that is passed -to the server procedure. This pointer should be type case to XPA -in the server routine: -<PRE> - XPA xpa = (XPA)call_data; -</PRE> - -<P> -The most important of these macros is xpa_datafd(). A server routine -that sets "fillbuf=false" in receive_mode or send_mode can use this -macro to perform I/O directly to/from the client, rather than using -buf. - -<P> -The xpa_cendian and xpa_sendian macros can be used together to determine -if the data transferred from the client is byte swapped with respect -to the server. Values for these macros are: "little", "big", or "?". -In order to do a proper conversion, you still need to know the format -of the data (i.e., byte swapping is dependent on the size of the data -element being converted). - -<!-- =defdoc xparace xparace 3 --> - -<!-- =section xparace NAME --> -<H2><A NAME="race">XPA Race Conditions</A></H2> - -<!-- =section xparace SYNOPSIS --> -Potential XPA race conditions and how to avoid them. - -<!-- =section xparace DESCRIPTION --> -<P> -Currently, there is only one known circumstance in which XPA can get -(temporarily) deadlocked in a race condition: if two or more XPA -servers send messages to one another using an XPA client routine such -as XPASet(), they can deadlock while each waits for the other server -to respond. (This can happen if the servers call XPAPoll() with a -time limit, and send messages in between the polling call.) The -reason this happens is that both client routines send a string to the -other server to establish the handshake and then wait for the server -response. Since each client is waiting for a response, neither is able -to enter its event-handling loop and respond to the other's -request. This deadlock will continue until one of the timeout periods -expire, at which point an error condition will be triggered and the -timed-out server will return to its event loop. - -<P> -Starting with version 2.1.6, this rare race condition can be -avoided by setting the XPA_IOCALLSXPA environment variable for servers -that will make client calls. Setting this variable causes all XPA -socket IO calls to process outstanding XPA requests whenever the -primary socket is not ready for IO. This means that a server making a -client call will (recursively) process incoming server requests while -waiting for client completion. It also means that a server callback -routine can handle incoming XPA messages if it makes its own XPA call. -The semi-public routine oldvalue=XPAIOCallsXPA(newvalue) can be used -to turn this behavior off and on temporarily. Passing a 0 will turn -off IO processing, 1 will turn it back on. The old value is returned -by the call. - -<P> -By default, the XPA_IOCALLSXPA option is turned off, because we judge -that the added code complication and overhead involved will not be -justified by the amount of its use. Moreover, processing XPA requests -within socket IO can lead to non-intuitive results, since incoming -server requests will not necessarily be processed to completion in the -order in which they are received. - -<P> -Aside from setting XPA_IOCALLSXPA, the simplest way to avoid this race -condition is to multi-process: when you want to send a client message, -simply start a separate process to call the client routine, so that -the server is not stopped. It probably is fastest and easiest to use -fork() and then have the child call the client routine and exit. But -you also can use either the system() or popen() routine to start one -of the command line programs and do the same thing. Alternatively, you -can use XPA's internal launch() routine instead of system(). Based on -fork() and exec(), this routine is more secure than system() because -it does not call /bin/sh. - -<P> -Starting with version 2.1.5, you also can send an XPAInfo() message with -the mode string "ack=false". This will cause the client to send a message -to the server and then exit without waiting for any return message from -the server. This UDP-like behavior will avoid the server deadlock when -sending short XPAInfo messages. - -<!-- =section xpaserver SEE ALSO --> -<!-- =text See xpa(n) for a list of XPA help pages --> -<!-- =section xpanew SEE ALSO --> -<!-- =text See xpa(n) for a list of XPA help pages --> -<!-- =section xpacmdnew SEE ALSO --> -<!-- =text See xpa(n) for a list of XPA help pages --> -<!-- =section xpacmdadd SEE ALSO --> -<!-- =text See xpa(n) for a list of XPA help pages --> -<!-- =section xpacmddel SEE ALSO --> -<!-- =text See xpa(n) for a list of XPA help pages --> -<!-- =section xpainfonew SEE ALSO --> -<!-- =text See xpa(n) for a list of XPA help pages --> -<!-- =section xpafree SEE ALSO --> -<!-- =text See xpa(n) for a list of XPA help pages --> -<!-- =section xpacleanup SEE ALSO --> -<!-- =text See xpa(n) for a list of XPA help pages --> -<!-- =section xpamainloop SEE ALSO --> -<!-- =text See xpa(n) for a list of XPA help pages --> -<!-- =section xpapoll SEE ALSO --> -<!-- =text See xpa(n) for a list of XPA help pages --> -<!-- =section xpamacros SEE ALSO --> -<!-- =text See xpa(n) for a list of XPA help pages --> -<!-- =section xparace 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> diff --git a/xpa/doc/sman/xpa4.index b/xpa/doc/sman/xpa4.index Binary files differdeleted file mode 100644 index 7c5a98a..0000000 --- a/xpa/doc/sman/xpa4.index +++ /dev/null diff --git a/xpa/doc/sman/xpa4.index.prop b/xpa/doc/sman/xpa4.index.prop Binary files differdeleted file mode 100644 index 0d0dd69..0000000 --- a/xpa/doc/sman/xpa4.index.prop +++ /dev/null diff --git a/xpa/doc/sman/xpa4.index.version b/xpa/doc/sman/xpa4.index.version deleted file mode 100644 index accb620..0000000 --- a/xpa/doc/sman/xpa4.index.version +++ /dev/null @@ -1,2 +0,0 @@ -SMAN_DATA_VERSION 1.2 -VERSION 1.01 diff --git a/xpa/doc/sman/xpa8.index b/xpa/doc/sman/xpa8.index Binary files differdeleted file mode 100644 index e9f998c..0000000 --- a/xpa/doc/sman/xpa8.index +++ /dev/null diff --git a/xpa/doc/sman/xpa8.index.prop b/xpa/doc/sman/xpa8.index.prop Binary files differdeleted file mode 100644 index 54b3108..0000000 --- a/xpa/doc/sman/xpa8.index.prop +++ /dev/null diff --git a/xpa/doc/sman/xpa8.index.version b/xpa/doc/sman/xpa8.index.version deleted file mode 100644 index accb620..0000000 --- a/xpa/doc/sman/xpa8.index.version +++ /dev/null @@ -1,2 +0,0 @@ -SMAN_DATA_VERSION 1.2 -VERSION 1.01 diff --git a/xpa/doc/sman_conf.tmpl b/xpa/doc/sman_conf.tmpl deleted file mode 100644 index abac8e4..0000000 --- a/xpa/doc/sman_conf.tmpl +++ /dev/null @@ -1,96 +0,0 @@ -# $Id: sman-defaults.conf,v 1.33 2006/05/02 02:09:18 joshr Exp $ -# by Josh Rabinowitz, 2005-2006. <joshr> -# this is the default sman configuration file. -# if you need to make changes, copy this file to -# /usr/local/etc/sman.conf and make changes to that file. -# NOTE: if you do use a custom sman.conf you may need to manually -# NOTE: merge changes from this file to your configuration file -# NOTE: after upgrading sman versions - -# See 'perldoc sman.conf' for more documentation - -# sman-defaults.conf -# holds the defaults for sman. -# the directive names are case-insensitive - -SWISHECMD @SW@ -v 0 - -# MANCMD specifies how to manually convert the manpages to -# ASCII. For 'manual' parsing. -# %F is the quoted full [F]ilename of the manpage (ie, '/usr/share/man/man1/ls.1.gz) -# %S is the quoted [S]ection of the manpage (ie, '1') -# %C is the quoted (apparent) [C]ommand of the manpage (ie, 'ls') - -# NOTE: lack of a MANCMD (or a value of AUTOCONFIG) causes sman-update -# to autoconfigure the value of MANCMD. It will most likely choose -# one of the below: - -# this works for most linuxes we've tested. ie 'man /man/man1/ls.1' -# MANCMD man -c %F -# this works for freebsd 4.4 and Mac OS X. ie 'man 1 ls' -#MANCMD man -c %S %C -# -c means reparse man page sources (for line re-wrapping) - -# works for Solaris and OS X -MANCMD man -s %S %C - -# the COL program is used to strip out backspaces and -# such from the MAN output. - -COLCMD col -b - -# all vars starting with ENV_ get set in the -# environment, sans the ENV_ prefix. - -# Try to make MAN wrap lines at 256 chars (not 80!) -ENV_MANWIDTH 256 - -# where to put sman's temp files. -# (Use SWISHE_TMPDIR to set affect SWISH-E at index time) - -TMPDIR /tmp - -# meta and property aliases. If your XML has different tags. -# refentrytitle, manvolnum and refpurpose are the names from rman -# each ALIASES line turns into 2 lines for SWISH-E like this: -#MetaNameAlias swishtitle refentrytitle -#PropertyNameAlias swishtitle refentrytitle - -TITLEALIASES RefEntryTitle -SECALIASES ManVolNum -DESCALIASES RefPurpose -#MANPAGEALIASES swishdefault - -# All parameters beginning with SWISHE_ have the SWISHE_ prefix stripped -# and are written into a tmp config file for SWISH-E at index time. - -# SWISHE_IndexFile is also used by sman as which index to search. - -# SWISHE_IndexFile specifies which index to create and search -# NOTE: if the containing dir (ie, /var/lib/sman) is owned by an unprivileged -# user, then sman-update can be run as that user. - -SWISHE_IndexFile /var/lib/sman/sman.index - -# these have 'SWISHE_' stripped off and are used -# when indexing the man pages. - -SWISHE_IndexComments no - # don't index text in comments - -# These are important! You probably don't want to mess with these. -SWISHE_IndexPointer "format=%V;" - # for future use. %V becomes $Sman::SMAN_DATA_VERSION -#SWISHE_FuzzyIndexingMode Stem - # above was deprecated in 2.4.3, does not work in 2.4.4 -SWISHE_FuzzyIndexingMode Stemming_en2 -SWISHE_MetaNames desc sec swishtitle manpage digest -SWISHE_PropertyNames desc sec manpage digest - -# SWISHE_IgnoreWords File: ./stopwords/english.txt -# allow _ and : but not / -# .'s in middle of word are word chars, for files like 'named.conf'. -SWISHE_WordCharacters 0123456789abcdefghijklmnopqrstuvwxyz_:. -SWISHE_BeginCharacters 0123456789abcdefghijklmnopqrstuvwxyz_: -SWISHE_EndCharacters 0123456789abcdefghijklmnopqrstuvwxyz_: -SWISHE_IgnoreTotalWordCountWhenRanking 0 diff --git a/xpa/doc/szlong.c b/xpa/doc/szlong.c deleted file mode 100644 index b0e84bc..0000000 --- a/xpa/doc/szlong.c +++ /dev/null @@ -1,8 +0,0 @@ -#include <stdio.h> - -int main(int argc, char **argv) -{ - fprintf(stdout, "%d\n", (int)sizeof(long)); - return 0; -} - diff --git a/xpa/doc/tcl.html b/xpa/doc/tcl.html deleted file mode 100644 index 8feb46a..0000000 --- a/xpa/doc/tcl.html +++ /dev/null @@ -1,249 +0,0 @@ -<!-- =defdoc xpatcl xpatcl n --> -<HTML> -<HEAD> -<TITLE>XPA/Tcl Interface</TITLE> -</HEAD> -<BODY> - -<!-- =section xpatcl NAME --> -<H2><A NAME="xpatcl">XPATcl: the XPA Interface to the Tcl/Tk Environment</A></H2> - -<!-- =section xpatcl SYNOPSIS --> -<H2>Summary</H2> - -<P> -Tcl/Tk programs can act as XPA clients and/or servers using the Tcl -interface to XPA that is contained in the libtclxpa.so shared object. - -<H2>Server Routines</H2> - -<PRE> - set xpa [xpanew class name help sproc sdata smode rproc rdata rmode] - xpafree xpa - set xpa [xpanew class name help iproc idata imode] - set xpa [xpacmdnew class name] - xpacmdadd xpa name help sproc sdata smode rproc rdata rmode - xpacmddel xpa cmd - set val [xparec xpa option] - options: name, class, method, cmdfd, datafd, cmdchan, datachan - xpasetbuf xpa buf len - xpaerror xpa message - xpamessage xpa message -</PRE> - -<H2>Client Routines</H2> - -<PRE> - set xpa [xpaopen mode] - xpaclose xpa - set got [xpaget xpa template paramlist mode bufs lens names errs n] - set got [xpaget xpa template paramlist mode chans names errs n] - set got [xpaset xpa template paramlist mode buf len names errs n] - set got [xpasetfd xpa template paramlist mode chan names errs n] - set got [xpainfo xpa template paramlist mode names errs n] - # NB: 2.1 calling sequence change - # set got [xpaaccess template type] (2.0.5) - set got [xpaaccess xpa template paramlist mode names errs n] - set got [xpanslookup template type classes names methods] -</PRE> - -<!-- =section xpatcl DESCRIPTION --> -<H2>Description</H2> -<P> -You can call XPANew(), XPACmdNew(), or XPAInfoNew() within a C -routine to add C-based XPA server callbacks to a TCL/Tk program that -uses a Tcl/Tk event loop (either vwait() or the Tk event loop); -Such a program does not need or want to use the XPA event loop. -Therefore, in order to add XPA access points to the Tcl/Tk loop, the -following routine should be called beforehand: -<PRE> - int XPATclAddInput(XPA xpa); -</PRE> -<P> -Normally, the xpa argument is NULL, meaning that all current XPA -access points are registered with the event loop. However, if a -single XPA access point is to be added (i.e., after the event loop is -started) then the handle of that XPA access point can be passed to -this routine. - -<P> -The significance of the XPA/TCL interface goes beyond the support for -using XPA inside C code. The interface allows you to write XPA -servers and to make calls to the XPA client interface within the Tcl -environment using the Tcl language directly. The XPA/Tcl -interface can be loaded using the following package command: -<PRE> - package require tclxpa 2.0 -</PRE> -Alternatively, you can load the shared object (called libtclxpa.so ) directly: -<PRE> - load .../libtclxpa.so tclxpa -</PRE> -<P> -Once the tclxpa package is loaded, you can use Tcl versions of XPA -routines to define XPA servers or make client XPA calls. The -interface for these routines is designed to match the Unix XPA -interface as nearly as possible. Please refer to -<A HREF="./server.html">XPA Servers</A> -and -<A HREF="./client.html">XPA Clients</A> -for general information about these routines. - -<P> -The file test.tcl in the XPA source directory gives examples for using the -XPA/Tcl interface. - -<P> -The following notes describe the minor differences between the interfaces. - -<H2><A NAME="xpanew">XPANew</A></H2> -<PRE> -<B> - set xpa [xpanew class name help sproc sdata smode rproc rdata rmode] -</B> -</PRE> -<P> -rproc and sproc routines are routines. The calling sequence of the -rproc routine is identical to its C counterpart: -<PRE> - proc rec_cb { xpa client_data paramlist buf len } { ... } -</PRE> -<P> -The sproc routine, however is slightly different from its C counterpart -because of the difficulty of passing data back from the callback to C: -<PRE> - proc sendcb { xpa client_data paramlist } { ... } -</PRE> -<P> -Note that the C-based server's char **buf and int *len arguments are -missing from the Tcl callback. This is because we did not know how to -fill buf with data and pass it back to the C routines for communication -with the client. Instead, the Tcl server callback uses the following -routine to set buf and len: -<PRE> - xpasetbuf xpa buf len -</PRE> -where: -<PRE> - arg explanation - ------ ----------- - xpa the first argument of the server callback - buf the data to be returned to the client - len data length in bytes, (if absent, use length of the buf object) -</PRE> -<P> -When this routine is called, a copy of buf is saved for transmission to -the client. - -<P> -The fact that buf is duplicated means that TCL server writers might wish to -perform the I/O directly within the callback, rather than have XPA do it -automatically at the end of the routine. To do this, set: -<PRE> - fillbuf=false -</PRE> -<P> -in the xpanew smode and then perform I/O through the Tcl channel -obtained from: -<PRE> - set dchan [xparec $xpa datachan] -</PRE> -<P> -where: -<PRE> - arg explanation - ------ ----------- - xpa the first argument of the server callback - datachan literal string "datachan" that returns the data channel - len data length in bytes, (if absent, use length of the buf object) -</PRE> -<P> -<B> -NB: datachan and cmdchan are not available under Windows. It is -necessary to use the "raw" equivalents: datafd and cmdfd. -</B> - -<P> -The same considerations apply to the rproc for receive servers: a copy -of the incoming data is generated to pass to the receive callback. This -copy again can be avoided by using "fillbuf=false" in the rmode and then -reading the incoming data from datachan. - -<P> -The send and receive callback routines can use the xpaerror and xpamessage -routines to send errors and messages back to the client. If you also -want tcl itself to field an error condition, use the standard return call: -<PRE> - return ?-code c? ?-errorinfo i? ?-errorcode ec? string -</PRE> -<P> -See the Tcl man page for more info. - -<H2><A NAME="xpanew">XPARec</A></H2> -<P> -The Tcl xparec procedure supplies server routines with access to information -that is available via macros in the C interface: -<PRE> - set val [xparec xpa <option>] -</PRE> -<P> -where option is: name, class, method, cmdfd, datafd, cmdchan, -datachan. Note that two additional identifiers, cmdchan and datachan, -have been added to to provide Tcl channels corresponding to datafd and -cmdfd. (These latter might still be retrieved in Tcl and passed back -to a C routines.) An additional option called "version" can be used to -determine the XPA version used to build the Tcl interface. Note that -the standard options require a valid XPA handle, but "version" does -not (since it simply reports the value of the XPA_VERSION definition -in the XPA source include file). - -<P> -<B> -NB: datachan and cmdchan are not available under Windows. It is -necessary to use the "raw" equivalents: datafd and cmdfd. -</B> -<PRE> - macro explanation - ------ ----------- - class class of this xpa - name name of this xpa - method method string (inet or local connect info) - cmdchan Tcl channel of command socket - datachan Tcl channel of data socket - cmdfd fd of command socket - datafd fd of data socket - sendian endian-ness of server ("little" or "big") - cendian endian-ness of client ("little" or "big" - version XPA version used to build this code -</PRE> - -<p> -Under Windows, the Tcl event handler cannot automatically sense when an -XPA socket is ready for IO (i.e. Tcl_CreateFileHandler() is not available -under Windows). The Windows Tcl event handler therefore must be awakened -occasionally for check for XPA events. This is done using the standard -Tcl_SetMaxBlockTime() call. The time parameter is defined in tclloop.c -and is currently set to 1000 microseconds (1/1000 of a second). - -<P> -The version option can be used to differentiate between source code versions. -It was created to support legacy Tcl code that needs to maintain the 2.0.5 -calling sequence for xpaaccess. You can use a version test such as: -<PRE> - if [catch { xparec "" version } version] { - puts "pre-2.1.0e" - } else { - puts [split $version .] - } -<PRE> - -<!-- =section xpatcl 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> diff --git a/xpa/doc/template.html b/xpa/doc/template.html deleted file mode 100644 index 6a9a0d0..0000000 --- a/xpa/doc/template.html +++ /dev/null @@ -1,112 +0,0 @@ -<!-- =defdoc xpatemplate xpatemplate n --> -<HTML> -<HEAD> -<TITLE>Access Point Names and Templates</TITLE> -</HEAD> -<BODY> - -<!-- =section xpatemplate NAME --> -<H2><A NAME="xpatemplate">XPATemplate: Access Point Names and Templates</A></H2> -<!-- =section xpatemplate SYNOPSIS --> -<H2>Summary</H2> -<P> -XPA access points are composed of two parts: a general class and a -specific name. Both parts accept template characters so that you -can send/retrieve data to/from multiple servers at one time. - -<!-- =section xpatemplate DESCRIPTION --> -<H2>Description</H2> -<P> -When XPA servers call -<A HREF="./server.html#xpanew">XPANew(),</A> -or -<A HREF="./server.html#xpacmdnew">XPACmdNew()</A> -to define XPA access points, they specify a string identifier composed of a -class and a name. When clients communicate with XPA access points, -they specify which access points to communicate with using -an identifier of the form: -<PRE> - class:name -</PRE> -All registered XPA access points that match the specified identifier -will be available for communication (subject to access control rules, -etc.) - -<P> -As of XPA 2.1.5, the length of both the class and name designations are -limited to 1024 characters. - -<P> -The XPA class:name identifier actually is a template: it accepts wild -cards in its syntax, so a single specifier can match more than one XPA -access point. (Note that the class is optional and defaults to "*".) -The allowed syntax for clients to specify the class:name template is -of the form shown below. (Note that "*" is used to denote a generic -wild card, but other wild cards characters are supported, as described -below). -<PRE> - template explanation - -------- ----------- - class:name exact match of class and name - name match any class with this name - *:name match any class with this name - class:* match any name of this class - *:* match any access point -</PRE> -<P> -In general, the following wild-cards can be applied to class and name: -<PRE> - wildcard explanation - -------- ----------- - ? match any character, but there must be one - * match anything, or nothing - [...] match an inclusive set -</PRE> -<P> -Although the class:name template normally is used to refer to XPA -access points, these also can be specified using their individual -socket identifiers. For inet sockets, the socket identifier is -<B>ip:port</B>, where ip can be the DNS-registered name, -the ASCII IP number (e.g. 123.45.67.890) or the hex IP number -(e.g. 838f3a60). For unix sockets, the identifier is the <B>socket file -name</B>. These socket identifiers are displayed as the fourth argument -in the xpans display of registered access points. For example, -consider the ds9 program started using inet sockets. The xpans name -server will register something like this: -<PRE> - csh> xpaget xpans - DS9 ds9 gs saord.harvard.edu:3236 eric -</PRE> -You can access ds9 using ip:3236 in any of the three forms: -<PRE> - csh> xpaget saord:3236 file - /home/eric/data/snr.ev - - csh> xpaget 123.45.67.890:3236 file - /home/eric/data/snr.ev - - csh> xpaget 838f3a60:3236 file - /home/eric/data/snr.ev -</PRE> -In the case of unix sockets, the socket identifier is a file: -<PRE> - csh> xpaget xpans - DS9 ds9 gs /tmp/.xpa/DS9_ds9.2631 eric - - csh> xpaget /tmp/.xpa/DS9_ds9.2631 file - /home/eric/data/snr.ev -</PRE> -This feature can be useful in distinguishing between multiple -instances of a program that all have the same class:name designation. - -<!-- =section xpatemplate 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> - diff --git a/xpa/doc/users.html b/xpa/doc/users.html deleted file mode 100644 index a849442..0000000 --- a/xpa/doc/users.html +++ /dev/null @@ -1,67 +0,0 @@ -<!-- =defdoc xpausers xpausers n --> -<HTML> -<HEAD> -<TITLE>Distinguishing Users</TITLE> -</HEAD> -<BODY> - -<!-- =section xpausers NAME --> -<H2><A NAME="xpausers">XPAUsers: Distinguishing Users</A></H2> - -<!-- =section xpausers SYNOPSIS --> -<H2>Summary</H2> -<P> -XPA normally distinguishes between users on a given host, but it is possible -to send data to access points belonging to other users. - -<!-- =section xpausers DESCRIPTION --> -<H2>Description</H2> -<P> -A single XPA name service typically serves all users on a given -machine. Two users can register the same XPA access points on the -same machine without conflict, because the user's username is -registered with each access point and, by default, programs such as -xpaget and xpaset only process access points of the appropriate user. -For example: -<PRE> - XPA xpa1 gs 838e2f67:1262 eric - XPA xpa2 gs 838e2f67:1266 eric - XPA xpa1 gs 838e2f67:2523 john - XPA xpa2 gs 838e2f67:2527 john -</PRE> -Here the users "eric" and "john" both have registered the access -points xpa1 and xpa2. When either "john" or "eric" retrieves -information from xpa1, they will process only the access point -registered in their user name. - -<P> -If you want to access another user's XPA access points on a single -machine, use the -u [user] option on xpaset, xpaget, etc. For example, -if eric executes: -<PRE> - xpaget -u john xpa1 -</PRE> -he will access John's xpa1 access point.Use "*" to access all users -on a given machine: -<PRE> - xpaget -u "*" xpa1 -</PRE> -Note that the <A HREF="./env.html">XPA Environment Variable</A> -XPA_NSUSERS can be used to specify the default list of users to -process: -<PRE> - setenv XPA_NSUSERS "eric,john" -</PRE> -will cause access points from both "eric" and "john" to be processed -by default. - -<!-- =section xpausers 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> diff --git a/xpa/doc/xpa.pdf b/xpa/doc/xpa.pdf Binary files differdeleted file mode 100644 index e2c4855..0000000 --- a/xpa/doc/xpa.pdf +++ /dev/null diff --git a/xpa/doc/xpa.ps b/xpa/doc/xpa.ps deleted file mode 100644 index 21d4910..0000000 --- a/xpa/doc/xpa.ps +++ /dev/null @@ -1,5294 +0,0 @@ -%!PS -%%Title: The XPA Help Facility -%%Creator: html2ps version 1.0 beta5 -%%EndComments -save -2000 dict begin -/d {bind def} bind def -/D {def} d -/t true D -/f false D -/FL [/Times-Roman -/Times-Italic -/Times-Bold -/Times-BoldItalic -/Courier -/Courier-Oblique -/Courier-Bold -/Courier-BoldOblique -/Helvetica -/Helvetica-Oblique -/Helvetica-Bold -/Helvetica-BoldOblique] D -/WF t D -/WI 0 D -/F 1 D -/IW 471 F div D -/IL 621 F div D -/PS 791 D -/EF [0 1 0 0 0 0 0 0 0 0 1 1 0 0 0 0 0 0 0 0 0 0 2 2] D -/EZ [11 9 19 17 15 13 12 11 11 11 11 11 11 11 11 11 11 11 11 11 11 11 8 8] D -/Ey [0 0 2 2 2 2 2 2 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0] D -/EG [-1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1] D -/Tm [1 1 0.8 0.8 0.8 0.8 0.8 0.8 0 0 0 0 0 0 0.5 1 1 1 1 0 0 1.3 0 0] D -/Bm [1 1 0.5 0.5 0.5 0.5 0.5 0.5 0 0 0 0 0 0 0.5 1 1 1 1 0 0 1 0 0] D -/Lm [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 2 2 0 0 2 0 0 0] D -/Rm [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0] D -/EU [-1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 0 0] D -/NO t D -/YY [[{()}1][{()}0][{()}2]] D -/ZZ [[{()}1][{()}0][{()}2]] D -/Ts EZ 0 get D -/TU f D -/Xp t D -/AU t D -/SN 0 D -/Cf f D -/Tp f D -/Fe f D -/TI 1 Ts mul D -/Fm 14 D -/xL 71 D -/xR 71 D -/yL 706 D -/yR 706 D -/Wl 471 F div D -/Wr 471 F div D -/hL 621 F div D -/hR 621 F div D -/FE {newpath Fm neg Fm M CP BB IW Fm add Fm L IW Fm add IL Fm add neg L CP BB - Fm neg IL Fm add neg L closepath} D -/LA {PM 0 eq{/IW Wl D /IL hL D}{/IW Wr D /IL hR D}ie /W IW D /LL W D /LS W D - TU PM 0 eq and{IW 56 F div add SA{Sf div}if 0 translate} - {PM 0 eq{xL yL}{xR yR}ie translate F SA{Sf mul}if dup scale - CS CF FS Cf{CA CL get VC}if /Bb f D}ie 0 0 M - TF not Tc or {Cf{gsave SA{1 Sf div dup scale}if Cb VC FE fill grestore}if}if}D -/Pi 0 Ts mul D -/SG [0.8 1 1] D -/Ab 15 D -/J 0 D -/Tc t D -/NH 6 D -/Nf f D -/Pa f D -/LH 1.2 D -/XR f D -/Xr {/pN E D ( [p ) WB pN WB (] )WB} D -/Db [16#FF 16#FF 16#FF] D -/Dt [16#00 16#00 16#00] D -/eA f D -/Fi f D -/bT f D -/Lc t D -/Dl [16#00 16#00 16#00] D -/LX f D -/Br 0.25 D -/IA ([IMAGE]) D -/DS {/PF f D()WB NL NP()pop RC ZF} D -/Gb f D -/Mb t D -/Hc [16#00 16#00 16#00] D -/Bl 3 D -/MI -15.2 D -/DX (DRAFT) D -/Di 0 D -/Tt 113.385826771654 D -/Th {()2 Al()BR ( - ) 0 1 -1 H()4 FZ Ti ES()EH ( - ) 0 2 -1 H() ME 0 get join EH()Ea()BR()} D -/tH {()0 1 -1 H (Table of Contents) EH()} D -/FD 2 D -/Dy 2 D -/cD [16#F0 16#F0 16#F0] D -/FW 0.6 D -/FU [16#00 16#00 16#00] D -/ET {/RM f D /A0 0 D /PN SN D /OU t D /Ou t D /W IW D /LL W D D1 - Ms not TP and{Ip}if /TF f D} D -[{true statusdict/setduplexmode get exec} stopped cleartomark -%-- End of variable part -- -/MySymbol 10 dict dup begin - /FontType 3 D /FontMatrix [.001 0 0 .001 0 0 ] D /FontBBox [25 -10 600 600] D - /Encoding 256 array D 0 1 255{Encoding exch /.notdef put}for - Encoding (e) 0 get /euro put - /Metrics 2 dict D Metrics begin - /.notdef 0 D - /euro 651 D - end - /BBox 2 dict D BBox begin - /.notdef [0 0 0 0] D - /euro [25 -10 600 600] D - end - /CharacterDefs 2 dict D CharacterDefs begin - /.notdef {} D - /euro{newpath 114 600 moveto 631 600 lineto 464 200 lineto 573 200 lineto - 573 0 lineto -94 0 lineto 31 300 lineto -10 300 lineto closepath clip - 50 setlinewidth newpath 656 300 moveto 381 300 275 0 360 arc stroke - -19 350 moveto 600 0 rlineto -19 250 moveto 600 0 rlineto stroke}d - end - /BuildChar{0 begin - /char E D /fontdict E D /charname fontdict /Encoding get char get D - fontdict begin - Metrics charname get 0 BBox charname get aload pop setcachedevice - CharacterDefs charname get exec - end - end}D - /BuildChar load 0 3 dict put /UniqueID 1 D -end -definefont pop - -/Cd {aload length 2 idiv dup dict begin {D} repeat currentdict end} D -/EX {EC cvx exec} D -/DU {} d -/BB {pop pop}d -/ie {ifelse} d -/E {exch} d -/M {moveto} d -/R {rmoveto} d -/L {lineto} d -/RL {rlineto} d -/CP {currentpoint} d -/SW {stringwidth} d -/GI {getinterval} d -/PI {putinterval} d -/Sg {setgray} d -/LW {setlinewidth} d -/S {dup () ne OU and{0 Co R AT 3 eq LB and HF not and A1 0 ne A2 0 ne or and - {A2 0 32 A1 0 6 -1 roll awidthshow}{show}ie 0 Co neg R}{pop}ie - OU PH 3 eq or{/Ms t D}if} D -/U {OU{gsave CP currentfont /FontInfo get /UnderlinePosition get - 0 E currentfont /FontMatrix get dtransform E pop add newpath M dup SW pop - CJ 0 RL stroke grestore}if} D -/B {OU Br 0 gt and{CP Ts neg Ts .33 mul R gsave 0 Sg - CP newpath Ts Br mul 0 360 arc closepath UI 2 mod 0 eq{stroke}{fill}ie - grestore M CP E Ts Br 1 add mul sub E BB /Ms t D}if}D -/NP {Ms TP not or PA and OU and{TP{OR}if f1{mF k2 /mF E D /YC 0 D}if - TP TU not PM 0 eq or and{showpage}if DU Ip TE not{LA}if 0.6 LW - /CI 0 D /TP t D /Hs f D /hl 6 D /Hv 6 D /HI hi D /Ms f D}if Bs XO BO M} D -/Np {LE sub CP E pop gt PL 0 eq and{NP}if}D -/Ip {/PN PN 1 add D /Pn RM{1}{4}ie PN Ns D /PM PN SN sub 2 mod D} D -/GP {E dup 3 -1 roll get PN 1 add 2 mod get dup type /integertype eq - {get 0 get}{E pop}ie}d -/Fc {dup 2 GP exec SW pop /S1 E D dup 1 GP exec SW pop /S2 E D 0 GP exec SW - pop /S3 E D S1 0 gt{S2 2 mul S1 add S3 2 mul S1 add 2 copy lt{E}if pop}{0}ie - S2 S3 add 2 copy lt{E}if pop IW .9 mul div dup 1 gt{1 E div}{pop 1}ie}D -/OR {Df{Sd}if tp not{gsave SA{1 Sf div dup scale}if Fe{Cf{FU VC}if FW LW - 1 setlinejoin FE stroke}if /YO {60 F div dup 40 gt{pop 40}if}D /cs CS D - /cf CF D /CF 0 D /pf PF D /PF f D /Fn FN D /At AT D /AT 0 D /FN EF Hf 1 add - get D Fz Fs FS ZZ Fc Fz mul Fs FS EU Hf 1 add get dup type /arraytype eq - Cf and{VC}{pop 0 Sg}ie IW IL neg YO sub M ZZ 1 GP exec dup SW pop neg 0 R Sh - 0 IL neg YO sub M ZZ 0 GP exec Sh ZZ 2 GP exec dup SW pop IW E sub 2 div - IL neg YO sub M Sh Fz Fs FS NO{/AW IW Pn SW pop sub D AW 2 div IL neg YO sub - S1 0 gt S2 AW .45 mul gt or S3 AW .45 mul gt or{Fz 2 mul sub}if M Pn Sh}if - EU Hf get dup type /arraytype eq Cf and{VC}{pop 0 Sg}ie YY Fc /FN EF Hf get D - Hz mul HS FS IW YO M YY 1 GP exec dup SW pop neg 0 R Sh 0 YO M YY 0 GP exec Sh - YY 2 GP exec dup SW pop IW E sub 2 div YO M Sh /FN Fn D /AT At D t Pb XO SZ - SL get neg R /PF pf D grestore /CF 0 D cs cf FS}if}D -/Sh {dup () ne{CP Hz 4 div sub BB show CP CS add BB}{pop}ie}D -/Pb {/OU E D /Ou OU D /PB t D 0 0 M Ba{/Sa save D /BP t D /Fl t D RC /PL 0 D - /PH 0 D /W IW D /LE IL .7 mul D /EO 0 D SI ZF /YA 0 D /BO 0 D /C1 () D - BA 0 Ts neg R Bb{Xl Yl Xh Yh}if Bb CP Sa restore M - {/Yh E D /Xh E D /Yl E D /Xl E D}if /Fl t D}if - BL /OU t D /HM f D /Ou t D /PB f D} D -/Bs {/BP Ba not D}D -/reencodeISO { - dup dup findfont dup length dict begin{1 index /FID ne{D}{pop pop}ie}forall - /Encoding ISOLatin1Encoding D currentdict end definefont} D -/ISOLatin1Encoding [ -/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef -/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef -/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef -/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef -/space/exclam/quotedbl/numbersign/dollar/percent/ampersand/quoteright -/parenleft/parenright/asterisk/plus/comma/hyphen/period/slash -/zero/one/two/three/four/five/six/seven/eight/nine/colon/semicolon -/less/equal/greater/question/at/A/B/C/D/E/F/G/H/I/J/K/L/M/N -/O/P/Q/R/S/T/U/V/W/X/Y/Z/bracketleft/backslash/bracketright -/asciicircum/underscore/quoteleft/a/b/c/d/e/f/g/h/i/j/k/l/m -/n/o/p/q/r/s/t/u/v/w/x/y/z/braceleft/bar/braceright/asciitilde -/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef -/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef -/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef -/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef -/.notdef/space/exclamdown/cent/sterling/currency/yen/brokenbar -/section/dieresis/copyright/ordfeminine/guillemotleft/logicalnot -/hyphen/registered/macron/degree/plusminus/twosuperior/threesuperior -/acute/mu/paragraph/periodcentered/cedilla/onesuperior/ordmasculine -/guillemotright/onequarter/onehalf/threequarters/questiondown -/Agrave/Aacute/Acircumflex/Atilde/Adieresis/Aring/AE/Ccedilla -/Egrave/Eacute/Ecircumflex/Edieresis/Igrave/Iacute/Icircumflex -/Idieresis/Eth/Ntilde/Ograve/Oacute/Ocircumflex/Otilde/Odieresis -/multiply/Oslash/Ugrave/Uacute/Ucircumflex/Udieresis/Yacute -/Thorn/germandbls/agrave/aacute/acircumflex/atilde/adieresis -/aring/ae/ccedilla/egrave/eacute/ecircumflex/edieresis/igrave -/iacute/icircumflex/idieresis/eth/ntilde/ograve/oacute/ocircumflex -/otilde/odieresis/divide/oslash/ugrave/uacute/ucircumflex/udieresis -/yacute/thorn/ydieresis -] D -[128/backslash 129/parenleft 130/parenright 141/circumflex 142/tilde -143/perthousand 144/dagger 145/daggerdbl 146/Ydieresis 147/scaron 148/Scaron -149/oe 150/OE 151/guilsinglleft 152/guilsinglright 153/quotesinglbase -154/quotedblbase 155/quotedblleft 156/quotedblright 157/endash 158/emdash -159/trademark] -aload length 2 idiv 1 1 3 -1 roll{pop ISOLatin1Encoding 3 1 roll put}for -/colorimage where{pop}{ - /colorimage { - pop pop /Pr E D {/Cv Pr D /Gr Cv length 3 idiv string D 0 1 Gr length 1 sub - {Gr E dup /i E 3 mul D Cv i get 0.299 mul Cv i 1 add get 0.587 mul add - Cv i 2 add get 0.114 mul add cvi put}for Gr} image} D -}ie -/pdfmark where{pop}{userdict /pdfmark /cleartomark load put}ie -WF{FL{reencodeISO D}forall}{4 1 FL length 1 sub{FL E get reencodeISO D}for}ie -/Symbol dup dup findfont dup length dict begin - {1 index /FID ne{D}{pop pop}ie}forall /Encoding [Encoding aload pop] - dup 128 /therefore put D currentdict end definefont D - -/SF {/CS E D SZ SL CS put FO SL FN put /YI CS LH neg mul D dup ST cvs ( ) join - CS ST cvs join C1 E join ( NF ) join /C1 E D CS NF /Wf WF FN 0 gt or D - /BW Wf{( ) SW pop}{0}ie D}D -/NF {/cS E D /cF E D cF 0 ge{FL cF get}{cF -1 eq{/Symbol}{/MySymbol}ie}ie - findfont cS scalefont setfont} D -/FS {CF or /CF E D FR SL CF put CF CF 0 ge{FN 4 mul add}if E SF} D -/PC {SH /BP f D fin not GL not and{NL}if /HM t D /LL LS D} D -/BS {/TX E D Wf{/fin f D /CW 0 D /LK 0 D /SC 0 D - /RT TX D {RT ( ) search{/NW E D pop /RT E D /WH NW SW pop D CW WH add LL gt - {TX SC LK SC sub 1 sub NN GI GL{SH cF cS OC - 2 copy cS ne E cF ne or{NF}{pop pop}ie}{PC /CW WH BW add D}ie - /SC LK D} - {GL{JC}if - /CW CW WH add BW add D /HM t D}ie /GL f D /Ph f D - /LK LK NW length 1 add add D}{pop exit}ie}loop - /fin t D TX SC LK SC sub GI SH RT () ne{GL not{CC}if}if - /LC TX length D /WH RT SW pop D CW WH add Hy{HC SW pop add}if LL gt - {RT GL{SH cF cS OC 2 copy cS ne E cF ne or{NF}{pop pop}ie - Hy{/Ph t D}if /LL LS D}{NL /LL LS D SH}ie} - {RT PC Hy{CC}if /Ph Ph Hy or D}ie RT () ne{/GL t D /HM t D}if} - {TX SW pop LL le{TX SH}{/NW () D 0 2 TX length 1 sub - {/CW E D TX 0 CW GI dup SW pop LL gt{pop NW SH /HM t D NL/LL W XO sub MR sub D - /CW CW 2 sub NN D /TX TX CW TX length CW sub GI D TX BS exit} - {/NW E D}ie}for}ie}ie /HM t D}D -/CC {C0 length 0 gt{JC}if /C0 [C1 L1 YA YB Mf NS NB TB AF Bw] D - /C1 () D /L0 L1 D /YA 0 D /YB 0 D /Mf 0 D /NS 0 D /NB 0 D}D -/JC {C0 aload length 0 gt{pop pop pop NB add /NB E D NS add /NS E D - dup Mf gt{/Mf E D}{pop}ie dup YB gt{/YB E D}{pop}ie - dup YA gt{/YA E D}{pop}ie pop C1 join /C1 E D /C0 [] D}if}D -/OC {C0 length 0 gt{C1 L1 L0 sub YA YB Mf NS NB TB AF Bw GL C0 aload pop - /Bw E D /AF E D /TB E D /NB E D /NS E D /Mf E D /YB E D /YA E D /C0 [] D - /L1 E D /C1 E D Ph{HC SH}if NL /GL E D /Bw E D /AF E D /TB E D /NB E D /NS E D - /Mf E D /YB E D /YA E D /L1 E D /LL W L1 sub XO sub MR sub WH sub D /CW 0 D - C1 E join /C1 E D}if}D -/BT {/LB t D dup length string copy RS dup dup () ne E ( ) ne and - {/CI 0 D /LS LL D /LL W L1 sub XO sub MR sub D BS} - {dup ( ) eq{/GL f D}if dup () eq L1 0 eq or{pop}{SH /BP f D /Ph f D}ie}ie - /LB f D} D -/BL {CP E pop XO E M} D -/NL {JC /GL f D /SK W XO sub MR sub L1 sub TB{Bw add}if D - /YA LF{Mf HM Fl not and PF or{LH mul}if}{0 /LF t D}ie YA 2 copy lt{E}if pop D - C1 () ne{/FB YB Mf SA{Sf mul}if 4 div 2 copy lt{E}if pop D}if Fl{/Ya YA D}if - CP E pop YA sub YB sub LE neg lt Fl not and PB not and{NP}if NT TL BL - OU PF not and PB or{/RE L1 TB{Bw sub}if - W XO sub MR sub div YA YB add LE BO add div 2 copy lt{E}if pop D - RE 1 gt{BL 1 RE div dup scale}if}if - AT 2 le{SK AT mul 2 div YA neg R}if - AT 3 eq{0 YA neg R TB{/NB NB 1 sub D /NS NS 1 sub D}if /NB NB 1 sub NN D - /A3 NS 6 mul NB add D NS NB add 0 eq - {/A1 0 D /A2 0 D} - {NS 0 eq{/A1 SK NB div dup J gt{pop 0}if D /A2 0 D}{J A3 mul SK lt - {/A1 J D /A2 SK J NB mul sub NS div dup Ab gt{/A1 0 D pop 0}if D} - {/A1 SK A3 div D /A2 A1 6 mul D}ie}ie}ie /A1 A1 NN D /A2 A2 NN D}if - AT 4 eq{0 YA neg R PH 2 le{PD 0 lt{/PD L1 D}if PD M1 gt{/M1 PD D}if - L1 PD sub M2 gt{/M2 L1 PD sub D}if}{DV ID 1 sub get 0 ge{Lo 0 R}if}ie}if - F0 cF ne Cs cS ne or{F0 Cs NF}if - /ms Ms D /Ms f D CP FB sub - C1 cvx exec XO EO sub L1 add TB{BW sub}if dup LM gt{/LM E D}{pop}ie - PH 0 eq PH 4 eq or Ms and{HF not{/PO t D /AH t D}if - BB CP YA add E AT 3 eq LB and{A1 sub}if TB{BW sub}if E BB} - {pop pop}ie Ms HM PH 3 eq and or{/BP f D /Fl f D}if - /Lo 0 D /L1 0 D /F0 cF D /Cs cS D BP not{0 YB NN neg R}if - OU f1 and mF not and{k2 /f1 f D}if - OU PF not and PB or{RE 1 gt{RE dup scale}if}if /Ms ms Ms or D - /C1 AF{(Cp )}{()}ie D /YA 0 D /YB 0 D BL - AT 4 eq LB not and PH 3 ge and - {ID DV length lt{DV ID get dup 0 ge{DO E sub /Lo E D /L1 Lo D}{pop}ie - /ID ID 1 add D}if}if /T t D CD{/LN LN 1 add D PD}if - /PD -1 D /NS 0 D /NB 0 D /TB f D /Ph f D /Mf 0 D /HM f D} D -/RS {/TM E D /CN 0 D TM{10 eq{TM CN ( ) PI}if /CN CN 1 add D}forall - /CN 0 D /BK HM EN and{0}{1}ie D TM - {dup 32 ne{TM CN 3 2 roll put /CN CN 1 add D /BK 0 D} - {pop BK 0 eq{TM CN 32 put /CN CN 1 add D}if /BK 1 D}ie}forall - TM 0 CN GI dup dup () ne E ( ) ne and - {dup CN 1 sub get 32 eq{/EN f D}{/EN t D}ie}if} D -/join {2 copy length E length add string dup 4 2 roll 2 index 0 3 index - PI E length E PI}d -/WR {(\n) search{dup () ne BP not or - {Li 4 le CP E pop YI Li mul add LE add 0 lt and PL 0 eq and{NP}if - SH NL pop /Li Li 1 sub D WR}{pop pop WR}ie}{SH}ie /CI 0 D /BP f D} D -/SH {dup dup () ne E ( ) ne and PF or CS Mf gt and{/Mf CS D}if - T not Wf and{( ) E join /T t D}if dup BP{/MF CS D}if - AT 3 eq{2 copy length dup 0 gt{/NB E NB add D - {( ) search{/NS NS 1 add D pop pop}{pop exit}ie}loop}{pop pop}ie}if - CD PD 0 lt and{dup DC search{SW pop /PD E L1 add D pop pop}{pop}ie}if - 0 Np dup SW pop L1 add /L1 E D dup () ne - {C1 (\() join E join (\)) join AU AF and UF or Wf and{( U ) join}if - sF{( s ) join}if ( S ) join - /C1 E D dup length 1 sub get 32 eq /TB E D /Bw BW D}{pop pop}ie} D -/BG {AI LG BC add add 0 eq} D -/ON {OU{Ty AR AI NN get dup 1 add Ln Ns Ty 2 mod 0 eq{(. )}{(\) )}ie join - dup SW pop neg 0 R CP E 0 lt{0 E M}{pop}ie CP BB show /Ms t D}if} D -/Ln {AR AI 3 -1 roll put}D -/SP {dup CI lt BP not and{dup CI sub 0 E R /CI E D}{pop}ie} D -/BN {PF{WR /HM f D}{BT NL}ie} D -/NN {dup 0 lt{pop 0}if} D -/h {(h) HI ST cvs join cvx exec dup 1 get E Nf{0 get E join}{pop}ie} D -/H {/fn FN D /Hi E 1 add D 1 sub /HL E D /H2 HL 2 add D /GS EZ H2 get D - E Tm H2 get GS mul BE dup 0 gt{1 sub}{pop EG H2 get dup 0 lt{pop AT}if}ie NA - WW Np /SL SL 1 add D /FN EF H2 get D GS Ey H2 get FS - EU H2 get Sc Hs not HL Hl lt and Hs HL hl lt and or Hi 0 eq or - {/HI Hi D /Hs t D /hl HL D /Hv HL D}if HL Hl lt{/hi Hi D}if - Nf HI 0 gt and{(h) Hi ST cvs join cvx exec 0 get WB}if - /HF t D /AH f D /PO f D} D -/EH {Bm H2 get GS mul BE OA /SL SL 1 sub NN D /CF 0 D /FN fn D - SZ SL get FR SL get FS /HF f D /GS Ts D ()Ec} D -/P {E PF{WR}{PO{EP}{BN}ie Ts 4 mul Np AE not{Tm 0 get Ts mul neg SP}if - dup 0 ge AH and{Pi Pd}if}ie 1 sub dup 0 lt{pop AV AL get}if /AT E D /PO t D} D -/EP {PF{WR}{BN Ts 4 mul Np}ie AE not{Bm 0 get Ts mul neg SP}if - /AT AV AL get D /PO f D} D -/BE {E PO{EP}{BN}ie Ts 4 mul Np neg SP} D -/HR {/Aw W EO sub D /RW E dup 0 gt{Aw mul}{neg}ie dup Aw gt{pop Aw}if D /RZ E D - E BN Ts neg SP 1 sub 2 div Aw RW sub mul EO add CP E pop M PF{0 Ps neg R}if - 0 Np OU{gsave RZ LW Cf{Hc VC}{0 Sg}ie CP BB RW 0 RL CP BB stroke grestore}if - /CI 0 D /BP f D PF not{Ts neg SP}if /Ms t D} D -/AD {I NL EG 14 get dup 0 lt{pop AT}if NA /AE t D Tm 14 get Ts mul neg SP - Cf{EU 14 get dup -1 eq{pop CA CL get}if Sc}if} D -/DA {BN ()ES OA /AE f D ()Ec Bm 14 get Ts mul neg SP} D -/PR {/MW E D /Li E D Tm 1 get Ps mul BE 0 NA /FN Fp D /PF t D SI /SL SL 1 add D - /CF 0 D Ps CS mul Ts div MW WC mul CS mul Ts div dup LL gt PL 0 eq and - {LL div div}{pop}ie Ey 1 get FS CP E pop LE add YI neg div cvi dup Li lt - AH and{4 lt YI Li mul 5 mul LE add 0 gt or PL 0 eq and{NP}if}{pop}ie - EU 1 get Sc /GS Ps D}D -/RP {WR NL () /PF f D SI /FN 0 D ES Bm 1 get Ps mul neg SP OA /GS Ts D} D -/SI {/XO Lm 15 get BC NN mul Lm 16 get AI UI sub NN mul add - Lm 17 get UI NN mul add Lm 20 get LG NN mul add Ts mul - PF{Lm 1 get Ps mul add}if EO add D - /MR Rm 15 get BC NN mul Rm 16 get AI UI sub NN mul add - Rm 17 get UI NN mul add Rm 20 get LG NN mul add Ts mul - PF{Rm 1 get Ps mul add}if D /LL W XO sub MR sub D} D -/DT {/cC E D BN /LG LG 1 sub D SI /LG LG 1 add D WW 2 div Np BL} D -/DD {WB Cc 0 eq cC 0 eq and L1 0 eq or Lm 20 get Ts mul L1 sub TB{BW add}if - Ts 2 div lt or NL /LF E D SI BL /cC 0 D} D -/DL {Dc LG Cc put /Cc E D BG{Tm 18 get Ts mul BE}{BN}ie /LG LG 1 add D BL} D -/LD {BN LG 0 gt{/LG LG 1 sub D}if /Cc Dc LG get D SI - BG{()Bm 18 get Ts mul BE}if BL} D -/UL {BG{Tm 17 get Ts mul BE}{BN}ie NR AI NN 0 put /UI UI 1 add D - /AI AI 1 add D SI BL} D -/LU {BN /UI UI 1 sub D /AI AI 1 sub D SI BG{()Bm 17 get Ts mul BE}if BL} D -/OL {E BG{Tm 16 get Ts mul BE}{BN}ie TR AI NN Ty put /Ty E D NR AI NN 1 put - /AI AI 1 add D SI BL 1 Ln} D -/LO {BN /AI AI 1 sub D /Ty TR AI get D SI BG{()Bm 16 get Ts mul BE}if BL} D -/LI {E BN -1 SP /BP f D /CI 0 D 0 Np NR AI 1 sub NN get 1 eq - {dup dup 0 gt E 4 le and{/Ty E D}{pop}ie - /L1 L1 Ty AR AI NN get Ns SW pop XO sub dup 0 lt{pop 0}if add D ( ON )} - {pop ( B )}ie C1 E join /C1 E D CS Mf gt{/Mf CS D}if BL} D -/BQ {Tm 15 get Ts mul BE /BC BC 1 add D SI BL} D -/QB {Bm 15 get Ts mul BE /BC BC 1 sub D SI BL} D -/Al {E EP 1 sub dup 0 lt{pop AV AL get}if NA} D -/Ea {EP OA} D -/WB {PF{WR}{BT}ie} D -/F1 {WB /FN 0 D CS 0 FS} D -/F2 {WB /FN WI D CS 0 FS} D -/HY {/Hy t D WB /Hy f D} D -/YH {WB} D -/A {/LT E D LT 1 eq{/RN E D}if /Lh E D WB /C1 C1 ( Cp ) join D - Lc AF not and{Cl Sc}if /AF t D} D -/EA {Lc AF and{Ec}{WB}ie TL Pa AF and Lh 0 ne and - {( \() Lh join (\)) join /AF f D WB}if /AF f D} D -/TL {C1 ( Tl ) apa /C1 E D} d -/apa {AF OU and Lh 0 ne LT 1 eq or and{LT 1 eq{RN ( /) E ST cvs join} - {(\() Lh join (\)) join}ie E join join}{pop}ie} d -/Cp {/Xc CP /Yc E D D} D -/SS {Cf{dup 0 ge{EU E get dup -1 eq{pop CA CL get}if}{pop CA CL get}ie Sc} - {pop}ie SZ SL get /SL SL 1 add D} D -/I {WB 8 SS 1 FS} D -/EM {WB 8 SS /CF CF 1 xor D 0 FS} D -/BD {WB 9 SS 2 FS} D -/TT {WB 10 SS /FN Fp D 0 FS} D -/KB {WB 11 SS /FN Fp D 2 FS} D -/CT {WB 12 SS 1 FS} D -/SM {WB 13 SS /FN Fp D 0 FS} D -/Q {/QL QL 1 add D QO QL 2 mod get La get join WB} D -/EQ {QC QL 2 mod get La get join WB /QL QL 1 sub D} D -/RO {WB -1 SS /CF 0 D 0 FS} D -/SY {WB -1 SS -1 FS} D -/MY {WB -1 SS -2 FS} D -/ES {WB /SL SL 1 sub NN D /CF 0 D /FN FO SL get D SZ SL get FR SL get FS ()Ec}D -/FZ {3 sub 1.2 E exp GS mul E WB TL /C1 C1 ( Cp ) join D /SL SL 1 add D 0 FS} D -/Ef {WB TL ()ES /C1 C1 ( Cp ) join D} D -/BZ {dup /Bf E D FZ}D -/Sc {dup -1 ne Cf and{/CL CL 1 add D dup 0 eq{pop [0 0 0]}if - dup CA E CL E put VS ( VC ) join C1 E join /C1 E D}{pop}ie} D -/Ec {WB Cf{/CL CL 1 sub NN D CA CL get VS ( VC ) join C1 E join /C1 E D}if} D -/VS {dup type /arraytype eq{([) E {ST cvs join ( ) join}forall (]) join}if} D -/VC {{255 div}forall setrgbcolor} D -/Sl {dup type /integertype ne{Ds}if /La E D WB}d -/UN {WB /UF t D} D -/NU {WB /UF f D} D -/SE {WB /sF t D} D -/XE {WB /sF f D} D -/sM {/C1 C1 ( k1 ) join D}d -/eM {/C1 C1 ( k2 ) join D}d -/k1 {/YC CP E pop Ts add D /mF t D /f1 t D}d -/k2 {gsave 3 LW -9 CP E pop Ts 0.2 mul sub M -9 YC L stroke grestore /mF f D}d -/Ac {/AC E D WB}d -/Ca {eA{( \()join AC join(\) )join}if WB}d -/s {OU{gsave 0 CS .25 mul R dup SW pop CJ 0 RL stroke grestore}if}D -/CJ {AT 3 eq LB and{E dup dup length 1 sub A1 mul E - {( ) search{pop pop E A2 add E}{pop exit}ie}loop 3 -1 roll add - W CP pop sub 2 copy gt{E}if pop}if}D -/So {/Co E D} D -/SO {C1 Yo ST cvs join ( So ) join /C1 E D (j) SW pop 2 div Pd} D -/Se {E WB CS E div Pd}D -/Pd {dup type /stringtype eq{SW pop}if dup /L1 E L1 add D - ST cvs ( 0 R ) join C1 E join /C1 E D} D -/Sp {0.35 CO} D -/Sb {-0.2 CO} D -/CO {OV Io Yo put /Yo E CS mul Yo add D /Io Io 1 add D -1.5 Io mul 3 add FZ SO - CS Yo add dup YA gt{/YA E D}{pop}ie - Yo neg dup YB gt{/YB E D}{pop}ie} D -/Es {ES /Io Io 1 sub NN D /Yo OV Io get D SO} D -/SB {/N2 0 D 0 1 NI{/N E D{IX N2 get 0 lt{/N2 N2 1 add D}{exit}ie}loop - /K WS N get FC N get mul D /NY AY N2 get D /BV NY array D - 0 1 NY 1 sub{/TM K string D currentfile TM readhexstring pop pop BV E TM put} - for BM N BV put /N2 N2 1 add D}for} D -/IC [{/MA E D /MB 0 D}{2 div /MA E D /MB MA D}{/MB E CS sub D /MA CS D} - {pop /MA YS AB mul D /MB 1 AB sub YS mul D}{pop /MA 0 D /MB 0 D}] D -/IP {BV N get /N N 1 add D} D -/II {/K E D IX K get 0 lt{/EC E D}if /TY E D - TY 4 eq{/Y E D /X E D}if TY 3 eq{/AB E D}if - /XW AX K get D /YW AY K get D /IS SG IT K get get D /XS XW IS mul D - /YS YW IS mul D YS IC TY get exec /MA MA Fl not{3 add}if D} D -/IM {II /ty TY D /xs XS D /ys YS D /ya YA D /yb YB D /ma MA D /mb MB D /k K D - /ec EC D /BP f D /CI 0 D WB TL L1 xs add dup XO add MR add W gt - {pop /ma ma Fl{3 add}if D NL /YA ma D /YB mb D /YS ys D /L1 xs D} - {/L1 E D ma YA gt{/YA ma D}if mb YB gt{/YB mb D}if}ie /TB f D - OU{CP E pop YS sub LE neg lt Fl not and PB not and{NP /YA ma D /YB mb D}if - /BP f D ty ST cvs ( ) join IX k get 0 lt{(\() join ec join (\) ) join}if - k ST cvs join ty 3 eq{AB ST cvs ( ) join E join}if - ty 4 eq{X ST cvs ( ) join Y ST cvs join ( ) join E join}if C1 E join - ( DI ) join FP 2 eq FP 1 eq AF and or{( FM ) join}if - ( Il Cp ) apa /C1 E D /EN f D}if /HM t D /T f D} D -/DI {II /Xc CP /Yc E D D /YN YW neg D /HM t D /CI 0 D /K2 IX K get D gsave - TY 4 eq{OX X IS mul add OY FY add YS sub Y IS mul sub} - {/FY YS D CP MB sub 2 copy /OY E D /OX E D}ie - translate K2 0 ge{/DP AZ K2 get D /BV BM K2 get D XS YS scale /N 0 D XW YW DP - [XW 0 0 YN 0 YW] {IP} FC K2 get 1 eq{image}{f 3 colorimage}ie} - {EX}ie grestore XS 0 R /Ms t D} D -/FM {gsave 0 Sg CP MB sub translate XS neg 0 M 0 YS RL XS 0 RL 0 YS neg RL - XS neg 0 RL stroke grestore} D -/NA {/AT E D /AL AL 1 add D AV AL AT put} D -/OA {AL 0 gt{/AL AL 1 sub D /AT AV AL get D}if} D -/D1 {/BR {CP E pop E BN Mb{CP E pop eq{0 YI R}if}{pop}ie} D - /Sn {OU{C1 E ST cvs join ( Ld ) join /C1 E D}{pop}ie} D} D -/D1 {/BR {BN} D /Sn {OU {C1 E ST cvs join ( Ld ) join /C1 E D} {pop} ie} D} D -/TC {/TF t D /ML 0 D HN{SW pop dup ML gt{/ML E D}{pop}ie}forall NP /RM RM not D - RC /OU Tc D Ep /PN 0 D Ms not TP and{Ip}if /W IW ML sub Ts sub D - /A0 0 D TH{/BR {( ) join BT} D /Sn {pop} D /Au () D}if} D -/TN {0 eq{E EA PF HF or not XR and{HN E get Xr}{pop}ie} - {OU{Tn 0 ge{() BN}if /Tn E D}{pop}ie WB}ie} D -/NT {OU LB not and Tn 0 ge and{PL 0 eq{Ms not{CS CF FS}if CP dup - /y E YA sub D W 9 sub CS -1.8 mul XO L1 add 2 add{y M (.) show}for - HN Tn get dup SW pop IW E sub y M show CP BB M}if /Tn -1 D}if} D -/Ld {/DN E D HN DN Pn put [/View [/XYZ -4 Fl{PS}{CP YA add US E pop}ie null] - /Dest DN ST cvs cvn /DEST pdfmark} D -/C {ND 1 eq{1 sub}if TI mul /XO E D NL Nf not{pop()}if 0 3 -1 roll 1 A} D -/OP {BP not{NP}if PN 2 mod 0 eq{/Ms t D NP}if}D -/Ep {Xp PN 2 mod 0 eq and OU and{/Pn (-) D showpage /PM 1 D LA}if}D -/Dg [73 86 88 76 67 68 77] D -/Rd [0 [1 1 0][2 1 0][3 1 0][2 1 1][1 1 1][2 2 1][3 3 1][4 4 1][2 1 2]] D -/Ns {/m E D /c E 32 mul D /j m 1000 idiv D /p j 12 add string D - c 96 le m 0 gt and{c 32 le {/i 0 D /d 77 D /l 100 D /m m j 1000 mul sub D - j -1 1 {pop p i d c add put /i i 1 add D}for - 4 -2 0 {/j E D /n m l idiv D /m m n l mul sub D /d Dg j get D - n 0 gt {/x Rd n get D x 0 get -1 1 {pop p i d c add put /i i 1 add D}for - p i x 1 get sub Dg x 2 get j add get c add put}if /l l 10 idiv D - }for p 0 i GI} - {/i ST length 1 sub D m {1 sub dup 0 ge{dup 26 mod c add 1 add - ST i 3 -1 roll put 26 idiv dup 0 eq{pop exit}if}if /i i 1 sub D}loop - ST i ST length i sub GI}ie} - {m p cvs}ie} D -/US {matrix currentmatrix matrix defaultmatrix matrix invertmatrix - matrix concatmatrix transform} D -/GB {Gb{US}if}D -/Tl {/Rn E D Xc CP pop ne{ - [/Rect [Xc 1 sub Yc cS 0.25 mul sub GB CP E 1 add E cS 0.85 mul add GB] - /Subtype /Link /Border [0 0 Cf Lc and LX and AU or{0}{1}ie] Rn type - /nametype eq {/Dest Rn}{/Action [/Subtype /URI /URI Rn] Cd}ie - /ANN pdfmark}if} D -/Il {/Rn E D [/Rect [Xc Yc GB Xc XS add Yc YS add GB] /Subtype /Link - /Border [0 0 0] Rn type /nametype eq{/Dest Rn} - {/Action [/Subtype /URI /URI Rn] Cd}ie /ANN pdfmark} D -/XP {[{/Z Bz 2 div D Z 0 R Z Z RL Z neg Z RL Z neg Z neg RL Z Z neg RL - Fi cH 1 eq and{fill}if} {Bz 0 RL 0 Bz RL Bz neg 0 RL 0 Bz neg RL - Fi cH 1 eq and{fill}if} {0 -5 R Bz 0 RL 0 21 RL Bz neg 0 RL 0 -21 RL}]} D -/MS {/Sm E D WB}D -/O {BN()Sm BX} D -/O {BN()0 Sm BX} D -/BX {/Bt E D Bt 2 lt{/Ch E D CS 0.8 mul}{11 mul}ie W XO sub MR sub - 2 copy gt{E}if pop /HZ E D Bt 2 eq{Fi not{pop()}if ( )E join /Ft E D TT - /PF t D /MW 1 D /Li 1 D /Fw Ft SW pop D Fw HZ gt{/HZ Fw 8 add D}if - HZ ST cvs( )join}{WB Ch ST cvs( )join}ie L1 HZ add XO add MR add W gt{NL}if - Bt 2 eq{Ft ES Fw neg HM{CS sub}if Pd}if Bt ST cvs join( Bx )join - Bt 2 eq HM and{CS Pd}if C1 E join /C1 E D /L1 L1 HZ add D /T f D - ( ) Pd /PF f D Bt 2 lt{YA CS .8 mul lt{/YA CS .8 mul D}if} - {YB 5 lt{/YB 5 D}if YA 21 lt{/YA 21 D}if}ie /CI 0 D} D -/Bx {dup 2 eq{E /Bz E D}{E /cH E D /Bz CS .8 mul D}ie - OU {gsave 0 Sg XP E get exec stroke grestore}{pop}ie Bz 0 R /Ms t D}D -/SD {FD 4 mul Dy add DZ NF newpath 0 0 M DX t charpath pathbbox - 3 -1 roll sub /DY E D E dup /X1 E D sub WM mul WX DY mul add WM DG mul E div - /DF E D /DR WX DF mul DY mul WM div 2 div D} d -/Sd {gsave 0 IL Di mul neg translate IL IW atan Di 0 eq{neg}if rotate - FD 4 mul Dy add DZ NF DR X1 sub DY 2 div neg M cD VC DX show grestore} d -/Pt {/tp t D Tp{NP /Pn (TP) D 0 Tt neg R Th BN NP Ep ET RC ZF}if /tp f D} D -/RC {/AI 0 D /LG 0 D /BC 0 D /UI 0 D /PF f D /Cc 0 D /cC 0 D /Dc 10 array D - /NR [0 1 9{pop 0}for] D /La Ds D /AR 10 array D /TR 10 array D /AV 30 array D - SI /AL -1 D /AT A0 D AT NA /OV 9 array D /Yo 0 D /Co 0 D /Io 0 D /Hy f D - /Ph f D /CL -1 D Ct Sc}D -/ZF {/FR [0 1 30{pop 0}for] D /SZ [0 1 30{pop 0}for] D /FO [0 1 30{pop 0}for] D - /SL 0 D /CF 0 D /FN 0 D 0 Ts SF}D -/QO [[(\234)(\233)(\253\240)(\232)(\273)(\253)][(')(`)(\253\240)(\231)(\273)(\253)]] D -/QC [[(\234)(\234)(\240\273)(\233)(\253)(\273)][(')(')(\240\273)(`)(\253)(\273)]] D -/Hf EF length 2 sub D -/Hz EZ Hf get D -/HS Ey Hf get D -/Fz EZ Hf 1 add get D -/Fs Ey Hf 1 add get D -/LE IL D -/Ps EZ 1 get D -/Fp EF 1 get D -/XO 0 D -/YI 0 D -/CI 0 D -/FP 0 D -/WW Ts 7 mul D -/Mf 0 D -/YA 0 D -/YB 0 D -/Cs Ts D -/GS Ts D -/F0 0 D -/NS 0 D -/NB 0 D -/N 0 D -/C0 [] D -/C1 () D -/Lo 0 D -/L1 0 D -/LM 0 D -/PH 0 D -/EC 0 D -/Lh 0 D -/LT 0 D -/CH 1 string D -/ST 16 string D -/CA 9 array D -/HC (\255) D -/HM f D -/PF f D -/EN f D -/TB f D -/UF f D -/sF f D -/AE f D -/AF f D -/BP t D -/CD f D -/PA t D -/GL f D -/T t D -/HF f D -/AH f D -/SA f D -/PB f D -/f1 f D -/mF f D -/OX 0 D -/OY 0 D -/FY 0 D -/EO 0 D -/FB 0 D -/PL 0 D -/Bw 0 D -/PD -1 D -/TP f D -/tp f D -/TH f D -/Ty 4 D -/Tn -1 D -/Fl t D -/LB t D -/PM 1 D -/Ms f D -/Ba f D -/Bb f D -/Hl 3 D -/hl 6 D -/Hv 6 D -/Hs f D -/HI 0 D -/hi 0 D -/PO t D -/TE f D -/LF t D -/BO 0 D -/Sm 1 D -/Bf 3 D -/A1 0 D -/A2 0 D -/Ds 1 D -/QL -1 D -/Cb Db D -/Ct Dt D -/Cl Dl D -[/Creator (html2ps version 1.0 beta5) /Author () /Keywords () /Subject () - /Title (The XPA Help Facility) /DOCINFO pdfmark -/ND 22 D -/HN [(1) (1) (1) (3) (5) (8) (10) (14) (15) (16) (15) (16) (17) (19) (22) (25) -(26) (29) (30) (30) (31) (32) (32) (33) (34) (34) (35) (37) (38) (46) (46) -(39) (40) (42) (43) (44) (47) (48) (50) (51) (55) (61) (63) (75) (76) (77) -(80) (1) (1) (1) (2) (1) (??) (??) (1) (1) (1) (2) (3) (3) (3) (3) (4) (5) -(5) (5) (5) (7) (8) (8) (8) (8) (9) (10) (10) (10) (10) (10) (11) (12) (13) -(14) (14) (14) (14) (14) (15) (15) (15) (16) (16) (17) (18) (19) (19) (19) -(19) (20) (21) (22) (22) (22) (24) (25) (25) (33) (25) (25) (25) (25) (26) -(29) (30) (30) (31) (32) (32) (33) (33) (34) (34) (35) (36) (37) (37) (37) -(37) (37) (38) (38) (38) (38) (38) (38) (39) (40) (42) (43) (44) (46) (46) -(47) (48) (49) (50) (50) (50) (50) (50) (51) (53) (51) (51) (51) (51) (51) -(52) (53) (54) (55) (55) (55) (55) (60) (61) (61) (61) (61) (62) (63) (63) -(63) (63) (63) (63) (64) (64) (64) (65) (65) (66) (67) (67) (67) (68) (68) -(68) (68) (69) (69) (69) (70) (70) (70) (70) (70) (71) (71) (71) (71) (72) -(72) (73) (73) (73) (74) (74) (74) (74) (75) (75) (75) (75) (75) (76) (76) -(76) (76) (76) (77) (77) (77) (77) (79) (80) (80) (80) (80) (80)] D -/h0 [()(Table of Contents)] D -/h1 [(0.1\240\240)(XPA: Public Access to Data and Algorithms)] D -/h2 [(0.2\240\240)(Summary)] D -/h3 [(0.3\240\240)(Description)] D -/h4 [(0.3.0.0.1\240\240)(Last updated: September 10, 2003)] D -/h5 [(0.4\240\240)(XPAIntro: Introduction to the XPA Messaging System)] D -/h6 [(0.5\240\240)(Summary)] D -/h7 [(0.6\240\240)(Description)] D -/h8 [(0.6.0.0.1\240\240)(Last updated: March 10, 2007)] D -/h9 [(0.7\240\240)(XPATemplate: Access Point Names and Templates)] D -/h10 [(0.8\240\240)(Summary)] D -/h11 [(0.9\240\240)(Description)] D -/h12 [(0.9.0.0.1\240\240)(Last updated: September 10, 2003)] D -/h13 [(0.10\240\240)(XPACommon: Getting Common Information About Access Points)] D -/h14 [(0.11\240\240)(Summary)] D -/h15 [(0.12\240\240)(Description)] D -/h16 [(0.12.0.0.1\240\240)(Last updated: September 10, 2003)] D -/h17 [(0.13\240\240)(XPAMethod: XPA Communication Methods)] D -/h18 [(0.14\240\240)(Summary)] D -/h19 [(0.15\240\240)(Description)] D -/h20 [(0.15.0.0.1\240\240)(Last updated: September 10, 2003)] D -/h21 [(0.16\240\240)(XPAInet: XPA Communication Between Hosts)] D -/h22 [(0.17\240\240)(Summary)] D -/h23 [(0.18\240\240)(Description)] D -/h24 [(0.19\240\240)(Manual Registration)] D -/h25 [(0.20\240\240)(Remote Registration)] D -/h26 [(0.21\240\240)(XPANS Proxy Registration)] D -/h27 [(0.21.0.0.1\240\240)(Last updated: September 10, 2003)] D -/h28 [(0.22\240\240)(XPAUsers: Distinguishing Users)] D -/h29 [(0.23\240\240)(Summary)] D -/h30 [(0.24\240\240)(Description)] D -/h31 [(0.24.0.0.1\240\240)(Last updated: September 10, 2003)] D -/h32 [(0.25\240\240)(XPA Programs)] D -/h33 [(0.26\240\240)(Summary)] D -/h34 [(0.27\240\240)(xpaset: send data to one or more XPA servers)] D -/h35 [(0.28\240\240)(xpaget: retrieve data from one or more XPA servers)] D -/h36 [(0.29\240\240)(xpainfo: send short message to one or more XPA servers)] D -/h37 [(0.30\240\240)(xpaaccess: see if template matches registered XPA access points)] D -/h38 [(0.30.0.0.1\240\240)(Last updated: September 10, 2003)] D -/h39 [(0.31\240\240)(xpamb: the XPA Message Bus)] D -/h40 [(0.32\240\240)(Summary)] D -/h41 [(0.33\240\240)(Description)] D -/h42 [(0.34\240\240)(Options)] D -/h43 [(0.34.0.0.1\240\240)(Last updated: September 10, 2003)] D -/h44 [(0.35\240\240)(xpans: the XPA Name Server)] D -/h45 [(0.36\240\240)(Summary)] D -/h46 [(0.36.0.0.1\240\240)(Last updated: January 24, 2005)] D -/h47 [(0.37\240\240)(XPAServer: The XPA Server-side Programming Interface)] D -/h48 [(0.38\240\240)(Summary)] D -/h49 [(0.39\240\240)(Introduction to XPA Server Programming)] D -/h50 [(0.40\240\240)(Introduction)] D -/h51 [(0.41\240\240)(XPANew: create a new XPA access point)] D -/h52 [(0.42\240\240)(XPACmdNew: create a new XPA public access point for commands)] D -/h53 [(0.43\240\240)(XPACmdAdd: add a command to an XPA command public access point)] D -/h54 [(0.44\240\240)(XPACmdDel: remove a command from an XPA command public access point)] D -/h55 [(0.45\240\240)(XPAInfoNew: define an XPA info public access point)] D -/h56 [(0.46\240\240)(XPAFree: remove an XPA public access point)] D -/h57 [(0.47\240\240)(XPAMainLoop: optional main loop for XPA)] D -/h58 [(0.48\240\240)(XPAPoll: execute existing XPA requests)] D -/h59 [(0.49\240\240)(XPAAtExit: install exit handler)] D -/h60 [(0.50\240\240)(XPACleanup: release reserved XPA memory)] D -/h61 [(0.51\240\240)(XPA Server Callback Macros)] D -/h62 [(0.52\240\240)(XPA Race Conditions)] D -/h63 [(0.52.0.0.1\240\240)(Last updated: September 10, 2003)] D -/h64 [(0.53\240\240)(Xpaoom: What happens when XPA runs out of memory?)] D -/h65 [(0.54\240\240)(Summary)] D -/h66 [(0.55\240\240)(Description)] D -/h67 [(0.55.0.0.1\240\240)(Last updated: April 7, 2009)] D -/h68 [(0.56\240\240)(XPAClient: The XPA Client-side Programming Interface)] D -/h69 [(0.57\240\240)(Summary)] D -/h70 [(0.58\240\240)(Introduction to XPA Client Programming)] D -/h71 [(0.59\240\240)(Introduction)] D -/h72 [(0.60\240\240)(XPAGet: retrieve data from one or more XPA servers)] D -/h73 [(0.61\240\240)(XPASet: send data to one or more XPA servers)] D -/h74 [(0.62\240\240)(XPAInfo: send short message to one or more XPA servers)] D -/h75 [(0.63\240\240)(XPAGetFd: retrieve data from one or more XPA servers and write to files)] D -/h76 [(0.64\240\240)(XPASetFd: send data from stdin to one or more XPA servers)] D -/h77 [(0.65\240\240)(XPAOpen: allocate a persistent client handle)] D -/h78 [(0.66\240\240)(XPAClose: close a persistent XPA client handle)] D -/h79 [(0.67\240\240)(XPANSLookup: lookup registered XPA access points)] D -/h80 [(0.68\240\240)(XPAAccess: return XPA access points matching template \(XPA 2.1 and above\))] D -/h81 [(0.68.0.0.1\240\240)(Last updated: March 10, 2007)] D -/h82 [(0.69\240\240)(XPAXt: the XPA Interface to Xt \(X Windows\))] D -/h83 [(0.70\240\240)(Summary)] D -/h84 [(0.71\240\240)(Description)] D -/h85 [(0.71.0.0.1\240\240)(Last updated: September 10, 2003)] D -/h86 [(0.72\240\240)(XPATcl: the XPA Interface to the Tcl/Tk Environment)] D -/h87 [(0.73\240\240)(Summary)] D -/h88 [(0.74\240\240)(Server Routines)] D -/h89 [(0.75\240\240)(Client Routines)] D -/h90 [(0.76\240\240)(Description)] D -/h91 [(0.77\240\240)(XPANew)] D -/h92 [(0.78\240\240)(XPARec)] D -/h93 [(0.78.0.0.1\240\240)(Last updated: September 10, 2003)] D -/h94 [(0.79\240\240)(XPAEnv: Environment Variables for XPA Messaging)] D -/h95 [(0.80\240\240)(Summary)] D -/h96 [(0.81\240\240)(Description)] D -/h97 [(0.81.0.0.1\240\240)(Last updated: December 23, 2009)] D -/h98 [(0.82\240\240)(XPAAcl: Access Control for XPA Messaging)] D -/h99 [(0.83\240\240)(Summary)] D -/h100 [(0.84\240\240)(Description)] D -/h101 [(0.84.0.0.1\240\240)(Last updated: September 10, 2003)] D -/h102 [(0.85\240\240)(XPA ChangeLog)] D -/h103 [(0.86\240\240)(Public Release 2.1.15 \(July 23, 2013\))] D -/h104 [(0.87\240\240)(Public Release 2.1.14 \(June 7, 2012\))] D -/h105 [(0.88\240\240)(Public Release 2.1.13 \(April 14, 2011\))] D -/h106 [(0.89\240\240)(Public Release 2.1.12 \(January 26, 2010\))] D -/h107 [(0.90\240\240)(Public Release 2.1.11 \(December 7, 2009\))] D -/h108 [(0.91\240\240)(Public Release 2.1.10 \(September 1, 2009\))] D -/h109 [(0.92\240\240)(Internal Release 2.1.9)] D -/h110 [(0.93\240\240)(Public Release 2.1.8 \(1 November 2007\))] D -/h111 [(0.94\240\240)(Patch Release 2.1.7b[1,2] \(Feb 22, 2006; March 8, 2007\))] D -/h112 [(0.95\240\240)(Patch Release 2.1.6 \(4 May 2005\))] D -/h113 [(0.96\240\240)(Patch Release 2.1.5 \(12 January 2004\))] D -/h114 [(0.97\240\240)(Patch Release 2.1.4 \(24 March 2003\))] D -/h115 [(0.98\240\240)(Patch Release 2.1.3 \(26 September 2002\))] D -/h116 [(0.99\240\240)(Patch Release 2.1.2 \(18 July 2002\))] D -/h117 [(0.100\240\240)(Patch Release 2.1.1 \(20 June 2002\))] D -/h118 [(0.101\240\240)(Public Release 2.1.0 \(22 April 2002\))] D -/h119 [(0.102\240\240)(Pre-Release 2.1.0e \(2 April 2002\))] D -/h120 [(0.103\240\240)(Pre-Release 2.1.0e \(1 April 2002\))] D -/h121 [(0.104\240\240)(Pre-Release 2.1.0e \(25 March 2002\))] D -/h122 [(0.105\240\240)(Pre-Release 2.1.0e \(19 March 2002\))] D -/h123 [(0.106\240\240)(Pre-Release 2.1.0e \(14 February 2002\))] D -/h124 [(0.107\240\240)(Pre-Release 2.1.0e \(11 February 2002\))] D -/h125 [(0.108\240\240)(Beta Release 2.1.0b10 \(31 January 2002\))] D -/h126 [(0.109\240\240)(Beta Release 2.1.0b9 \(26 January 2002\))] D -/h127 [(0.110\240\240)(Beta Release 2.1.0b8 \(4 January 2002\))] D -/h128 [(0.111\240\240)(Beta Release 2.1.0b7 \(21 December 2001\))] D -/h129 [(0.112\240\240)(Beta Release 2.1.0b6 \(29 October 2001\))] D -/h130 [(0.113\240\240)(Beta Release 2.1.0b5 \(22 October 2001\))] D -/h131 [(0.114\240\240)(Beta Release 2.1.0b4 \(24 September 2001\))] D -/h132 [(0.115\240\240)(Beta Release 2.1.0b3 \(6 September 2001\))] D -/h133 [(0.116\240\240)(Beta Release 2.1.0b2 \(17 August 2001\))] D -/h134 [(0.117\240\240)(Beta Release 2.1.0b1 \(6 August 2001\))] D -/h135 [(0.118\240\240)(Patch Release 2.0.5 \(10 November 2000\))] D -/h136 [(0.119\240\240)(Patch Release 2.0.4 \(20 September 2000\))] D -/h137 [(0.120\240\240)(Patch Release 2.0.3 \(15 June 2000\))] D -/h138 [(0.121\240\240)(Patch Release 2.0.2 \(9 September 1999\))] D -/h139 [(0.122\240\240)(Patch Release 2.0.1 \(6 August 1999\))] D -/h140 [(0.123\240\240)(Public Release 2.0 \(27 May 1999\))] D -/h141 [(0.123.0.0.1\240\240)(Last updated: 22 April 2002)] D -/h142 [(0.124\240\240)(XPACode: Where to Find Example/Test Code)] D -/h143 [(0.125\240\240)(Summary)] D -/h144 [(0.126\240\240)(Description)] D -/h145 [(0.126.0.0.1\240\240)(Last updated: September 10, 2003)] D -/h146 [(0.127\240\240)(XPA Changes: Changes For Users from XPA 1.0 and 2.0)] D -/h147 [(0.128\240\240)(Summary)] D -/h148 [(0.129\240\240)(Description)] D -/h149 [(0.129.0.0.1\240\240)(Last updated: September 10, 2003)] D -/h150 [(0.130\240\240)(XPAConvert: Converting the XPA API to 2.0)] D -/h151 [(0.131\240\240)(Summary)] D -/h152 [(0.132\240\240)(Description)] D -/h153 [(0.132.0.0.1\240\240)(Last updated: September 10, 2003)] D -/h154 [(0.133\240\240)(XPAName: What does XPA stand for?)] D -/h155 [(0.134\240\240)(Summary)] D -/h156 [(0.135\240\240)(Description)] D -/h157 [(0.135.0.0.1\240\240)(Last updated: September 10, 2003)] D -/Hr [-47 47 48 49 -50 -50 50 -54 54 55 56 -57 -57 57 -59 59 60 61 -62 -62 -62 -64 64 65 66 -67 -67 67 -69 69 70 71 -72 -72 72 -74 74 75 76 77 78 79 --80 -80 80 -82 82 83 84 -85 -85 85 -86 86 87 88 89 90 91 -92 -92 92 -94 -94 95 96 97 -98 -98 98 -100 100 101 -102 -102 102 -106 106 107 108 109 110 -111 112 113 114 115 116 117 118 119 120 121 -122 -122 122 -124 124 125 126 --127 -127 127 -130 130 131 132 133 134 135 136 137 138 139 140 141 142 -143 --143 143 -145 145 146 147 -148 -148 148 -151 151 152 153 154 155 156 157 --158 -158 158 -160 160 161 162 -163 -163 163 -165 165 166 167 -168 -168 -168 -169 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 -185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 -203 204 205 206 207 -208 -208 208 -210 210 211 212 -213 -213 213 -215 215 -216 217 -218 -218 218 -220 220 221 222 -223 -223 223 -225 225 226 227 -228 --228 228]D -/HV [1 2 2 2 3 4 5 1 2 2 2 3 4 5 1 2 2 2 3 4 5 1 2 2 2 3 4 5 1 2 2 2 3 -4 5 1 2 2 2 2 2 2 3 4 5 1 2 2 2 3 4 5 1 2 2 2 2 2 2 3 4 5 1 2 2 2 2 3 4 -5 1 2 2 3 4 5 1 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 3 4 5 1 2 2 2 3 4 5 1 2 -2 2 2 2 2 2 2 2 2 2 2 2 3 4 5 1 2 2 2 3 4 5 1 2 2 2 2 2 2 2 3 4 5 1 2 2 -2 3 4 5 1 2 2 2 3 4 5 1 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 -2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 3 4 5 1 2 2 2 3 4 5 1 2 2 2 3 4 5 1 2 2 2 -3 4 5 1 2 2 2 3 4 5]D -/Cn [3 0 0 1 1 1 0 3 0 0 1 1 1 0 3 0 0 1 1 1 0 3 0 0 1 1 1 0 3 0 0 1 1 -1 0 6 0 0 0 0 0 1 1 1 0 3 0 0 1 1 1 0 6 0 0 0 0 0 1 1 1 0 4 0 0 0 1 1 1 -0 2 0 1 1 1 0 16 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 0 3 0 0 1 1 1 0 13 -0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 0 3 0 0 1 1 1 0 7 0 0 0 0 0 0 1 1 1 0 3 0 -0 1 1 1 0 3 0 0 1 1 1 0 39 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 -0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 0 3 0 0 1 1 1 0 3 0 0 1 1 1 0 3 0 0 -1 1 1 0 3 0 0 1 1 1 0]D -Hr length 0 gt{[/PageMode /UseOutlines /DOCVIEW pdfmark}if -/Hn 1 D -0 1 Hr length 1 sub{ - /Bn E D [Cn Bn get dup 0 gt{/Count E HV Bn get Bl ge{neg}if}{pop}ie - /Dest Hr Bn get dup abs ST cvs cvn E 0 ge{(h)Hn ST cvs join cvx exec - dup 1 get E Nf{0 get E join}{pop}ie /Hn Hn 1 add D}{()}ie - /Title E dup length 255 gt{0 255 getinterval}if /OUT pdfmark}for -ZF /FN Fp D Ps 0 FS /WC Wf{( )}{<A1A1>}ie SW pop D -ET RC ZF -/Df f D -/R1 (http://hea-www.harvard.edu/RD/xpa/changelog.html) D -/Ba f D /BO 0 D Bs -/UR (help.html) D -/Ti (The XPA Help Facility) D -/Au () D -/Df f D -/ME [()] D - TC - -/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc - -/Ba f D /BO 0 D Bs -/UR (help.html) D -/Ti (The XPA Help Facility) D -/Au () D -/Df f D -/ME [()] D - TC - -NP RC ZF -()1 Sl()WB 0 Sn( - - -)0 2 0 H(XPA:)WB 47 Sn()WB 1 Sn( Public Access to Data and Algorithms)EA()EH( - - -)0 2 1 H(Summary)WB 48 Sn()EH( -This document is the Table of Contents for XPA. - - -)0 2 2 H(Description)WB 49 Sn()EH( -)0 P(The XPA messaging system provides seamless communication between many -kinds of Unix programs, including X programs and Tcl/Tk programs. It -also provides an easy way for users to communicate with XPA-enabled -programs by executing XPA client commands in the shell or by utilizing -such commands in scripts. Because XPA works both at the programming -level and the shell level, it is a powerful tool for unifying any -analysis environment: users and programmers have great flexibility in -choosing the best level or levels at which to access XPA services, and -client access can be extended or modified easily at any time. - -)0 P(A program becomes an XPA-enabled server by defining named points of -public access through which data and commands can be exchanged with -other client programs \201and users\202. Using standard TCP sockets as a -transport mechanism, XPA supports both single-point and broadcast -messaging to and from these servers. It supports direct communication -between clients and servers, or indirect communication via an -intermediate message bus emulation program. Host-based access control -is implemented, as is as the ability to communicate with XPA servers -across a network. - -)0 P(XPA implements a layered interface that is designed to be useful both -to software developers and to users. The interface consists of a -library of XPA client and server routines for use in C/C++ programs and -a suite of high-level user programs built on top of these libraries. -Using the XPA library, access points can be added to Tcl/Tk programs, -Xt programs, or to Unix programs that use the XPA event loop or any -event loop based on select\201\202. Client access subroutines can be added -to any Tcl/Tk, Xt, or Unix program. Client access also is supported at -the command line via a suite of high-level programs. - -)0 P(Choose from the following topics: - -)UL( -)-1 LI()0 2 1 A(Introduction to XPA)2 1 TN TL()Ec /AF f D( - -)-1 LI()0 3 1 A(Access Point Names and Templates)3 1 TN TL()Ec /AF f D( - -)-1 LI()0 4 1 A(Getting Common Information About Access Points)4 1 TN TL()Ec /AF f D( - -)-1 LI()0 5 1 A(Communication Methods)5 1 TN TL()Ec /AF f D( - -)-1 LI()0 6 1 A(Communication Between Hosts)6 1 TN TL()Ec /AF f D( - -)-1 LI()0 7 1 A(Distinguishing Users)7 1 TN TL()Ec /AF f D( - - -)-1 LI()0 8 1 A(XPA User Programs)8 1 TN TL()Ec /AF f D( -)UL()-1 LI()0 9 1 A(xpaget: get data and info)9 1 TN TL()Ec /AF f D( - -)-1 LI()0 10 1 A(xpaset: send data and info)10 1 TN TL()Ec /AF f D( - -)-1 LI()0 11 1 A(xpainfo: send info alert)11 1 TN TL()Ec /AF f D( - -)-1 LI()0 12 1 A(xpaaccess: get access point info)12 1 TN TL()Ec /AF f D( - -)-1 LI()0 13 1 A(xpamb: message bus emulation)13 1 TN TL()Ec /AF f D( - -)-1 LI()0 14 1 A(xpans: the XPA name server)14 1 TN TL()Ec /AF f D( -)LU( - -)-1 LI()0 15 1 A(XPA Server Routines)15 1 TN TL()Ec /AF f D( -)UL()-1 LI()0 16 1 A(XPANew: define a new access point)16 1 TN TL()Ec /AF f D( - -)-1 LI()0 17 1 A(XPACmdNew: define a new command access point)17 1 TN TL()Ec /AF f D( - -)-1 LI()0 18 1 A(XPACmdAdd: add a command)18 1 TN TL()Ec /AF f D( - -)-1 LI()0 19 1 A(XPACmdDel: delete a command)19 1 TN TL()Ec /AF f D( - -)-1 LI()0 20 1 A(XPAInfoNew: define an info access point)20 1 TN TL()Ec /AF f D( - -)-1 LI()0 21 1 A(XPAFree: free an access point)21 1 TN TL()Ec /AF f D( - -)-1 LI()0 22 1 A(XPAMainLoop: event loop for select server)22 1 TN TL()Ec /AF f D( - -)-1 LI()0 23 1 A(XPAPoll: poll for XPA events)23 1 TN TL()Ec /AF f D( - -)-1 LI()0 24 1 A(XPACleanup: release reserved XPA memory)24 1 TN TL()Ec /AF f D( - -)-1 LI()0 25 1 A(XPA Server Macros: accessing structure internals)25 1 TN TL()Ec /AF f D( - -)-1 LI()0 26 1 A(XPA Race Conditions: how to avoid them)26 1 TN TL()Ec /AF f D( - -)-1 LI()0 27 1 A(XPA Out of Memory \201OOM\202 errors)27 1 TN TL()Ec /AF f D( -)LU( - -)-1 LI()0 28 1 A(XPA Client Routines)28 1 TN TL()Ec /AF f D( -)UL()-1 LI()0 29 1 A(XPAOpen: open a persistent client connection)29 1 TN TL()Ec /AF f D( - -)-1 LI()0 30 1 A(XPAClose: close persistent client connection)30 1 TN TL()Ec /AF f D( - -)-1 LI()0 31 1 A(XPAGet: get data)31 1 TN TL()Ec /AF f D( - -)-1 LI()0 32 1 A(XPASet: send data or commands)32 1 TN TL()Ec /AF f D( - -)-1 LI()0 33 1 A(XPAInfo: send an info alert)33 1 TN TL()Ec /AF f D( - -)-1 LI()0 34 1 A(XPAGetFd: get data and write to an fd)34 1 TN TL()Ec /AF f D( - -)-1 LI()0 35 1 A(XPASetFd: read data from and fd and send)35 1 TN TL()Ec /AF f D( - -)-1 LI()0 36 1 A(XPANSLookup: look up an access point)36 1 TN TL()Ec /AF f D( - -)-1 LI()0 37 1 A(XPAAccess: get access info)37 1 TN TL()Ec /AF f D( - -)-1 LI()0 38 1 A(The XPA/Xt Interface: Xt interface to XPA)38 1 TN TL()Ec /AF f D( - -)-1 LI()0 39 1 A(The XPA/Tcl Interface: Tcl interface to XPA)39 1 TN TL()Ec /AF f D( -)LU( - -)-1 LI( Tailoring the XPA Environment -)UL()-1 LI()0 40 1 A(Environment Variables)40 1 TN TL()Ec /AF f D( - -)-1 LI()0 41 1 A(Access Control)41 1 TN TL()Ec /AF f D( -)LU( - -)-1 LI( Miscellaneous -)UL( -)-1 LI()0 42 1 A(XPA ChangeLog)42 1 TN TL()Ec /AF f D( - -)-1 LI()0 43 1 A(Where to Find Example/Test Code)43 1 TN TL()Ec /AF f D( -)-1 LI()0 44 1 A(User Changes Between XPA 1.0 and 2.0)44 1 TN TL()Ec /AF f D( -)-1 LI()0 45 1 A(API Changes Between XPA 1.0 and 2.0)45 1 TN TL()Ec /AF f D( -)-1 LI()0 46 1 A(What Does XPA Stand For, Anyway?)46 1 TN TL()Ec /AF f D()LU( -)LU( - - - -)0 5 3 H(Last)WB 50 Sn( updated: September 10, 2003)EH( -)WB NL NP Ep ET /Tc f D -/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc -DS -/Ba f D /BO 0 D Bs -/UR (intro.html) D -/Ti (Introduction to XPA) D -/Au () D -/Df f D -/ME [()] D - -0 BO R -()1 Sl()WB 2 Sn( - - -)0 2 4 H(XPAIntro:)WB 54 Sn()WB 51 Sn( Introduction to the XPA Messaging System)EA()EH( - - -)0 2 5 H(Summary)WB 55 Sn()EH( -)0 P(A brief introduction to the XPA messaging system, which provides -seamless communication between all kinds of Unix event-driven -programs, including X programs, Tcl/Tk programs, and Perl programs. - - -)0 2 6 H(Description)WB 56 Sn()EH( -)0 P(The XPA messaging system provides seamless communication between all -kinds of Unix programs, including X programs, Tcl/Tk programs, and -Perl programs. It also provides an easy way for users to communicate -with these XPA-enabled programs by executing XPA client commands in -the shell or by utilizing such commands in scripts. Because XPA works -both at the programming level and the shell level, it is a powerful -tool for unifying any analysis environment: users and programmers have -great flexibility in choosing the best level or levels at which to -access XPA services, and client access can be extended or modified -easily at any time. - -)0 P(A program becomes an XPA-enabled server by defining named points of -public access through which data and commands can be exchanged with -other client programs \201and users\202. Using standard TCP sockets as -a transport mechanism, XPA supports both single-point and broadcast -messaging to and from these servers. It supports direct communication -between clients and servers, or indirect communication via an -intermediate message bus emulation program. Host-based access control -is implemented, as is as the ability to communicate with XPA servers -across a network. - -)0 P(XPA implements a layered interface that is designed to be useful both -to software developers and to users. The interface consists of a -library of XPA client and server routines for use in programs and a -suite of high-level user programs built on top of these libraries. -Using the XPA library, access points can be added to -)0 52 1 A(Tcl/Tk)52 0 TN TL()Ec /AF f D( -programs, -)0 53 1 A(Xt)53 0 TN TL()Ec /AF f D( -programs, or to Unix programs that use the XPA event loop or any -event loop based on select\201\202. Client access subroutines can be added -to any Tcl/Tk or Unix program. Client access also is supported at the -command line via a suite of high-level programs. - -)0 P(The major components of the XPA layered interface are: -)UL()-1 LI(A set of XPA server routines, centered on -)0 16 1 A(XPANew\201\202,)16 0 TN TL()Ec /AF f D( -which are used by XPA server programs to tag public access points with -string identifiers and to register send and receive callbacks for -these access points. - -)-1 LI(A set of XPA client routines, centered on the -)0 32 1 A(XPASet\201\202)32 0 TN TL()Ec /AF f D( -and -)0 31 1 A(XPAGet\201\202,)31 0 TN TL()Ec /AF f D( -which are used by external client applications to exchange data and -commands with an XPA server. - -)-1 LI(High-level programs, centered on -)0 10 1 A(xpaset)10 0 TN TL()Ec /AF f D( -and -)0 9 1 A(xpaget,)9 0 TN TL()Ec /AF f D( -which allow data -and information to be exchanged with XPA server programs from the -command line and from scripts. These programs have the command syntax: -) 2 35 PR( [data] | xpaset [qualifiers ...] - xpaget [qualifiers ...])RP( -)-1 LI(An XPA name server program, -)0 14 1 A(xpans,)14 0 TN TL()Ec /AF f D( -through which XPA access point names are -registered by servers and distributed to clients.)LU( - -)0 P(Defining an XPA access point is easy: a server application calls -)0 16 1 A(XPANew\201\202,)16 0 TN TL()Ec /AF f D( -)0 17 1 A(XPACmdNew\201\202,)17 0 TN TL()Ec /AF f D( -or the experimental -)0 20 1 A(XPAInfoNew\201\202)20 0 TN TL()Ec /AF f D( -routine to -create a named public access point. An XPA service can specify "send" -and "receive" callback procedures \201or an "info" procedure in the case -of XPAInfoNew\201\202\202 to be executed by the program when an external -process either sends data or commands to this access point or requests -data or information from this access point. Either of the callbacks -can be omitted, so that a particular access point can be specified as -read-only, read-write, or write-only. Application-specific client -data can be associated with these callbacks. Having defined one or -more public access points in this way, an XPA server program enters -its usual event loop \201or uses the standard XPA event loop\202. - -)0 P(Clients communicate with these XPA public access points -using programs such as -)0 9 1 A(xpaget)9 0 TN TL()Ec /AF f D(, -)0 10 1 A(xpaset)10 0 TN TL()Ec /AF f D(, and -)0 11 1 A(xpainfo)11 0 TN TL()Ec /AF f D( -\201at the command line\202, -or routines such as -)0 31 1 A(XPAGet\201\202,)31 0 TN TL()Ec /AF f D( -)0 32 1 A(XPASet\201\202,)32 0 TN TL()Ec /AF f D( -and -)0 33 1 A(XPAInfo\201\202)33 0 TN TL()Ec /AF f D( -within a program. Both methods require specification of the name of -the access point. The xpaget program returns data or other -information from an XPA server to its standard output, while the -xpaset program sends data or commands from its standard input to an -XPA application. The corresponding API routines set/get data to/from -memory, returning error messages and other info as needed. If a -)0 3 1 A(template)3 0 TN TL()Ec /AF f D( -is used to specify the access point name \201e.g., "ds9*"\202, then -communication will take place with all servers matching that template. - -)0 P(Please note that XPA currently is not thread-safe. All XPA calls must be -in the same thread. - - - - - -)0 P()0 0 1 A(Go to XPA Help Index)0 0 TN TL()Ec /AF f D( - -)0 5 7 H(Last)WB 57 Sn( updated: March 10, 2007)EH( - -)WB NL -/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc -DS -/Ba f D /BO 0 D Bs -/UR (template.html) D -/Ti (Access Point Names and Templates) D -/Au () D -/Df f D -/ME [()] D - -0 BO R -()1 Sl()WB 3 Sn( - - -)0 2 8 H(XPATemplate:)WB 59 Sn()WB 58 Sn( Access Point Names and Templates)EA()EH( - -)0 2 9 H(Summary)WB 60 Sn()EH( -)0 P(XPA access points are composed of two parts: a general class and a -specific name. Both parts accept template characters so that you -can send/retrieve data to/from multiple servers at one time. - - -)0 2 10 H(Description)WB 61 Sn()EH( -)0 P(When XPA servers call -)0 16 1 A(XPANew\201\202,)16 0 TN TL()Ec /AF f D( -or -)0 17 1 A(XPACmdNew\201\202)17 0 TN TL()Ec /AF f D( -to define XPA access points, they specify a string identifier composed of a -class and a name. When clients communicate with XPA access points, -they specify which access points to communicate with using -an identifier of the form: -) 1 12 PR( class:name)RP( -All registered XPA access points that match the specified identifier -will be available for communication \201subject to access control rules, -etc.\202 - -)0 P(As of XPA 2.1.5, the length of both the class and name designations are -limited to 1024 characters. - -)0 P(The XPA class:name identifier actually is a template: it accepts wild -cards in its syntax, so a single specifier can match more than one XPA -access point. \201Note that the class is optional and defaults to "*".\202 -The allowed syntax for clients to specify the class:name template is -of the form shown below. \201Note that "*" is used to denote a generic -wild card, but other wild cards characters are supported, as described -below\202. -) 7 46 PR( template explanation - -------- ----------- - class:name exact match of class and name - name match any class with this name - *:name match any class with this name - class:* match any name of this class - *:* match any access point)RP( -)0 P(In general, the following wild-cards can be applied to class and name: -) 5 58 PR( wildcard explanation - -------- ----------- - ? match any character, but there must be one - * match anything, or nothing - [...] match an inclusive set)RP( -)0 P(Although the class:name template normally is used to refer to XPA -access points, these also can be specified using their individual -socket identifiers. For inet sockets, the socket identifier is -)BD(ip:port)ES(, where ip can be the DNS-registered name, -the ASCII IP number \201e.g. 123.45.67.890\202 or the hex IP number -\201e.g. 838f3a60\202. For unix sockets, the identifier is the )BD(socket file -name)ES(. These socket identifiers are displayed as the fourth argument -in the xpans display of registered access points. For example, -consider the ds9 program started using inet sockets. The xpans name -server will register something like this: -) 2 40 PR( csh> xpaget xpans - DS9 ds9 gs saord.harvard.edu:3236 eric)RP( -You can access ds9 using ip:3236 in any of the three forms: -) 8 37 PR( csh> xpaget saord:3236 file - /home/eric/data/snr.ev - - csh> xpaget 123.45.67.890:3236 file - /home/eric/data/snr.ev - - csh> xpaget 838f3a60:3236 file - /home/eric/data/snr.ev)RP( -In the case of unix sockets, the socket identifier is a file: -) 5 41 PR( csh> xpaget xpans - DS9 ds9 gs /tmp/.xpa/DS9_ds9.2631 eric - - csh> xpaget /tmp/.xpa/DS9_ds9.2631 file - /home/eric/data/snr.ev)RP( -This feature can be useful in distinguishing between multiple -instances of a program that all have the same class:name designation. - - - - - -)0 P()0 0 1 A(Go to XPA Help Index)0 0 TN TL()Ec /AF f D( - -)0 5 11 H(Last)WB 62 Sn( updated: September 10, 2003)EH( - -)WB NL -/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc -DS -/Ba f D /BO 0 D Bs -/UR (info.html) D -/Ti (Getting Common Information About Access Points) D -/Au () D -/Df f D -/ME [()] D - -0 BO R -()1 Sl()WB 4 Sn( - - -)0 2 12 H(XPACommon:)WB 64 Sn()WB 63 Sn( Getting Common Information About Access Points)EA()EH( - - -)0 2 13 H(Summary)WB 65 Sn()EH( -)0 P(There are various kinds of generic information you can retrieve about -an XPA access point by using the xpaget command. - - -)0 2 14 H(Description)WB 66 Sn()EH( -)0 P(You can find out which XPA access points have been registered with -the currently running -)0 14 1 A(XPA name server)14 0 TN TL()Ec /AF f D( -by executing the -)0 9 1 A(xpaget)9 0 TN TL()Ec /AF f D( -command to retrieve info from the XPA name server: -) 1 14 PR( xpaget xpans)RP( -If, for example, the -)0 43 1 A(stest)43 0 TN TL()Ec /AF f D( test server program -is running, the following XPA access points will be returned \201the specifics -of the returned info will vary for different machines and users\202: -) 4 33 PR( XPA xpa gs 838e2f67:1262 eric - XPA xpa1 gs 838e2f67:1266 eric - XPA c_xpa gs 838e2f67:1267 eric - XPA i_xpa i 838e2f67:1268 eric)RP( -Note that access to this information is subject to the usual -)0 41 1 A(XPA Access Control)41 0 TN TL()Ec /AF f D( restrictions. - -)0 P(Each XPA access point supports a number of reserved sub-commands that provide -access to different kinds of information, e.g. the access control for -that access point. These sub-commands can be executed by using -)0 10 1 A(xpaset)10 0 TN TL()Ec /AF f D( -or -)0 9 1 A(xpaget)9 0 TN TL()Ec /AF f D( -at the command line, or -)0 31 1 A(XPAGet\201\202)31 0 TN TL()Ec /AF f D( -or -)0 32 1 A(XPASet\201\202)32 0 TN TL()Ec /AF f D( -in programs, e.g: -) 5 30 PR( xpaget ds9 -acl - xpaget ds9 -help - xpaget ds9 env FOO - - xpaset -p ds9 env FOO foofoo)RP( -With the exception of )BD(-help)ES( and )BD(-version)ES(, reserved -sub-commands are available only on the machine on which the XPA server -itself is running. - -The following reserved sub-commands are defined for all access points: -)0 DL( -)0 P()0 DT()BD(-acl)ES( get \201set\202 the access control list [options: host type acl, for set] -)DD( -The 'xpaset' option allows you to add a new acl for a given host, or change -the acl for an existing host. See -)0 41 1 A(XPA Access Control)41 0 TN TL()Ec /AF f D( -for more information. -This access point is available only on the server machine. - -)0 P()0 DT()BD(-env)ES( get \201set\202 an environment variable [options: name \201value, for set\202] -)DD(The 'xpaget' option will return the value of the named environment -variable. The 'xpaset' option will set the value of the names -variable to the specified value. -This access point is available only on the server machine. -\201Please be advised that we have had problems setting environment -variables in static Tcl/Tk programs such as ds9 running under Linux.\202 - -)0 P()0 DT( )BD(-clipboard)ES( set\201get\202 information on a named clipboard -)DD( Clients can store ASCII state information on any number of named -clipboards. Clipboards of the same name created by clients on -different machines are kept separate. The syntax for creating a -clipboard is: -) 2 65 PR( [data] | xpaset [server] -clipboard add|append [clipboard_name] - xpaset -p [server] -clipboard delete [clipboard_name])RP( -Use "add" to create a new clipboard or replace the contents of an existing -one. Use "append" to append to an existing clipboard. -)0 P(Information on a named clipboard is retrieved using: -) 1 45 PR( xpaget [server] -clipboard [clipboard_name])RP( -)0 P()0 DT()BD(-exec)ES( set: execute commands from buffer [options: none] -)DD(If -exec is specified in the paramlist of an 'xpaset' call, then further -sub-commands will be retrieved from the data buffer. - -)0 P()0 DT()BD(-help)ES( get: return help string for this XPA or sub-command [options: name \201for sub-commands\202] -)DD(Each XPA access point and each XPA sub-command can have a help string -associated with it that is specified when the access point is defined. -The -help option will return this help string. For XPA access points -that contain user-defined sub-commands, you can get the help string -for a particular sub-command by specifying its name, or else get the -help strings for all sub-commands if not name is specified. - -)0 P()0 DT()BD(-ltimeout)ES( get \201set\202 the long timeout value [options: seconds|reset] -)DD(The 'xpaget' option will return the value of the long timeout \201in seconds\202. -The 'xpaset' option will set the value of the long timeout. If "reset" is -specified, then the timeout value will be reset to the default value. - -)0 P()0 DT()BD(-nsconnect)ES( set: re-establish name server connection to all XPA's [options: none] -)DD(If the -)0 14 1 A(XPA Name Server \201xpans\202)14 0 TN TL()Ec /AF f D( -process has terminated unexpectedly and then re-started, this -sub-command can be used to re-establish the connection. You use it by -sending the command to the [name:port] or [file] of the access point -instead of to the XPA name \201since the latter requires the xpans -connection!\202: -) 1 36 PR( xpaset -p 838e2f67:1268 -nsconnect)RP( -See )0 14 1 A(xpans)14 0 TN TL()Ec /AF f D( for more information. - -)0 P()0 DT()BD(-nsdisconnect)ES( set: break name server connection to all XPA's [options: none] -)DD(This sub-command will terminate the connection to the -)0 14 1 A(XPA Name Server \201xpans\202)14 0 TN TL()Ec /AF f D(, thereby making -all access points inaccessible except through their underlying [name:port] -or [file] identifiers. I forget why we added it, it seems pretty useless. - -)0 P()0 DT()BD(-stimeout)ES( get \201set\202 the short timeout value [options: seconds|reset] -)DD(The 'xpaget' option will return the value of the short timeout \201in seconds\202. -The 'xpaset' option will set the value of the short timeout. If "reset" is -specified, then the timeout value will be reset to the default value. - -)0 P()0 DT()BD(-remote)ES( set: register xpa with remote server [options: host[:port] [acl]] [-proxy] -)DD(This sub-command will register the XPA access point with the XPA name -server \201xpans\202 on the specified host \201which must already be running\202. -The specified host also is given access control to the access point, -using the specified acl or the default acl of "+" \201meaning the remote -host can xpaset, xpaget, xpainfo or xpaaccess\202. If the acl is -specified as "-", then the access point is unregistered. -See )0 6 1 A(Communication Between Machines)6 0 TN TL()Ec /AF f D( -for more information on how this sub-command is used. - -)0 P()0 DT()BD(-version)ES( get: return XPA version string [options: none] -)DD(The version refers to the version of XPA used to define this access point -\201currently something like 2.0\202. -)LD( - -)0 P(You can add your own reserved commands to all XPA access points by using the -)0 18 1 A(XPACmdAdd\201\202)18 0 TN TL()Ec /AF f D( -routine, passing the XPA handle returned by )EM(XPA XPAGetReserved\201void\202)ES( -as the first argument. Note again that these will only be available on the -machine where the XPA service is running. - - - - - -)0 P()0 0 1 A(Go to XPA Help Index)0 0 TN TL()Ec /AF f D( - -)0 5 15 H(Last)WB 67 Sn( updated: September 10, 2003)EH( -)WB NL -/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc -DS -/Ba f D /BO 0 D Bs -/UR (method.html) D -/Ti (XPA Communication Methods) D -/Au () D -/Df f D -/ME [()] D - -0 BO R -()1 Sl()WB 5 Sn( - - -)0 2 16 H(XPAMethod:)WB 69 Sn()WB 68 Sn( )EA(XPA Communication Methods)EH( - - -)0 2 17 H(Summary)WB 70 Sn()EH( -)0 P(XPA supports both inet and unix \201local\202 socket communication. - - -)0 2 18 H(Description)WB 71 Sn()EH( -)0 P(XPA uses sockets for communication between processes. It supports -three methods of socket communication: inet, localhost, and unix. In -general, the same method should be employed for all XPA processes in a -session and the global environment variable XPA_METHOD should be used -to set up the desired method. By default, the preferred method is -"inet", which is appropriate for most users. You can set up a -different method by typing something like: -) 3 70 PR( setenv XPA_METHOD local # unix csh - XPA_METHOD=local; export XPA_METHOD # unix sh, bash, windows/cygwin - set XPA_METHOD=localhost # dos/windows)RP( -The options for XPA_METHOD are: )BD(inet)ES(, )BD(unix)ES( \201or -)BD(local)ES(\202, and )BD(localhost)ES(. On Unix machines, this -environment setup command can be placed in your shell init file -\201.cshrc, .profile, .bashrc, etc.\202 On Windows platforms, it can be -placed in your AUTOEXEC.BAT file \201I think!\202. - -)0 P(By default, )BD(inet)ES( sockets are used by XPA. These are the standard -Internet sockets that are used by programs such as Netscape, -ftp. etc. Inet sockets utilize the IP address of the given machine and -a \201usually random\202 port number to communicate between processes on the -same machine or between different machines on the Internet. \201Note that -XPA has an )0 41 1 A(Access Control)41 0 TN TL()Ec /AF f D( mechanism to -prevent unauthorized access of XPA access points by other computers on -the Net\202. For users connected to the Internet, this usually is the -appropriate communication method. For more information about setting -up XPA communication between machines, see -)0 6 1 A(Communication Between Machines)6 0 TN TL()Ec /AF f D(. - -)0 P(In you are using XPA on a machine without an Internet connection, then -inet sockets are not appropriate. In fact, an XPA process often will -hang for many seconds while waiting for a response from the Domain -Name Service \201DNS\202 when using inet sockets. Instead of inet sockets, -users on Unix platforms can also use )BD(unix)ES( sockets \201also known -as local sockets\202. These sockets are based on the local file system -and do not make use of the DNS. They generally are considered to be -faster than inet sockets, but they are not implemented under -Windows. Use local sockets as a first resort if you are on a Unix -machine that is not connected to the Internet. - -)0 P(Users not connected to the Internet also can use )BD(localhost)ES( -sockets. These are also inet-type sockets but the IP address used for -the local machine is the )BD(localhost)ES( address, 0x7F000001, instead -of the real IP of the machine. Depending on how sockets are set up for -a given platform, communication with the DNS usually is not required in -this case \201though of course, XPA cannot interact with other machines\202. -The localhost method will generally work on both Unix and Windows -platforms, but whether the DNS is required or not is subject to -individual configurations. - -)0 P(A final warning/reminder: if your XPA-enabled server hangs at startup -time and your XPA_METHOD is )BD(inet)ES(, the problem probably is -related to an incorrect Internet configuration. This can be confirmed -by using the )BD(unix)ES( method or \201usually\202 the )BD(localhost)ES( -method. You can use these alternate methods if other hosts do not need -access to the XPA server. - - - - - -)0 P()0 0 1 A(Go to XPA Help Index)0 0 TN TL()Ec /AF f D( - -)0 5 19 H(Last)WB 72 Sn( updated: September 10, 2003)EH( -)WB NL -/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc -DS -/Ba f D /BO 0 D Bs -/UR (inet.html) D -/Ti (XPA Communication Between Hosts) D -/Au () D -/Df f D -/ME [()] D - -0 BO R -()1 Sl()WB 6 Sn( - - -)0 2 20 H(XPAInet:)WB 74 Sn()WB 73 Sn( XPA Communication Between Hosts)EA()EH( - - -)0 2 21 H(Summary)WB 75 Sn()EH( -XPA uses standard inet sockets to support communication between two or -more host computers. - - -)0 2 22 H(Description)WB 76 Sn()EH( -)0 P(When the )0 5 1 A(Communication Method)5 0 TN TL()Ec /AF f D( is set to -)BD(inet)ES( \201as it is by default\202, XPA can be used to communicate -between different computers on the Internet. INET sockets utilize the -IP address of the given machine and a \201usually random\202 port number to -communicate between processes on the same machine or between different -machines on the Internet. These standard Internet sockets are also -used by programs such as Netscape, ftp. etc. - -)0 P(XPA supports a host-based )0 41 1 A(Access Control)41 0 TN TL()Ec /AF f D( mechanism -to prevent unauthorized access of XPA access points by other computers -on the Net. By default, only the machine on which the XPA server is -running can access XPA services. Therefore, setting up communication -between a local XPA server machine and a remote client machine -requires a two-part registration process: - -)UL()-1 LI( the XPA service on the local machine must be made known to the -remote machine -)-1 LI( the remote machine must be given permission to access the local -XPA service)LU( - -Three methods by which this remote registration can be accomplished -are described below. - -)0 2 23 H(Manual)WB 77 Sn( Registration)EH( - -The first method is the most basic and does not require the remote -client to have xpans running. To use it, the local server simply -gives a remote client machine access to one or more XPA access points -using xpaset and the )BD(-acl)ES( sub-command. For example, -consider the XPA test program "stest" running on a local machine. By -default the access control for the access point named "xpa" is -restricted to that machine: -) 3 25 PR( [sh]$ xpaget xpa -acl - *:* 123.456.78.910 gisa - *:* localhost gisa)RP( -Using xpaset and the )BD(-acl)ES( sub-command, a remote client -machine can be given permission to perform xpaget, xpaset, xpaaccess, -or xpainfo operations. For example, to allow the xpaget operation, the -following command can be issued on the local machine: -) 1 45 PR( [sh]$ xpaset -p xpa -acl "remote_machine g")RP( -This results in the following access permissions on the local machine: -) 4 26 PR( [sh]$ xpaget xpa -acl - XPA:xpa 234.567.89.012 g - *:* 123.456.78.910 gisa - *:* localhost gisa)RP( - -The remote client can now use the local server's xpans name server to -establish communication with the local XPA service. This can be done -on a call-by-call basis using the )BD(-i)ES( switch on xpaset, xpaget, etc: -) 6 43 PR( [sh]$ xpaget -i "local_machine:12345" xpa - class: XPA - name: xpa - method: 88877766:2778 - sendian: little - cendian: big)RP( -Alternatively, the XPA_NSINET variable on the remote machine can be -set to point directly to xpans on the local machine, removing -the need to override this value each time an XPA program is run: -) 7 42 PR( [csh]$ setenv XPA_NSINET 'karapet:$port' - [csh]$ xpaget xpa - class: XPA - name: xpa - method: 88877766:2778 - sendian: little - cendian: big)RP( -Here, '$port' means to use the default XPA name service port \20114285\202. -not a port environment variable. - -)0 P(Access permission for remote client machines can be stored in a file -on the local machine pointed to by the )BD(XPA_ACLFILE)ES( environment -variable or using the )BD(XPA_DEFACL)ES( environment variable. See )0 41 1 A(XPA Access Control)41 0 TN TL()Ec /AF f D( for more information. - -)0 2 24 H(Remote)WB 78 Sn( Registration)EH( - -If xpans is running on the remote client machine, then a local xpaset -command can be used with the )BD(-remote)ES( sub-command to -register the local XPA service in the remote name service, while at -the same time giving the remote machine permission to access the local -service. For example, assume again that "stest" is running on the -local machine and that xpans is also running on the remote machine. -To register access of this local xpa on the remote machine, use -the xpaset and the )BD(-remote)ES( sub-command: -) 1 56 PR( [sh]$ ./xpaset -p xpa -remote 'remote_machine:$port' +)RP( -To register the local xpa access point on the remote machine with xpaget -access only, execute: -) 1 56 PR( [sh]$ ./xpaset -p xpa -remote 'remote_machine:$port' g)RP( -Once the remote registration command is executed, the remote client -machine will have an entry such as the following in its own xpans name -service: -) 2 31 PR( [csh]$ xpaget xpans - XPA xpa gs 88877766:2839 eric)RP( -The xpa access point can now be utilized on the remote machine without -further setup: -) 6 23 PR( [csh]$ xpaget xpa - class: XPA - name: xpa - method: 838e2f68:2839 - sendian: little - cendian: big)RP( -To unregister remote access from the local machine, use the same -command but with a '-' argument: -) 1 54 PR( [sh]$ xpaset -p xpa -remote 'remote_machine:$port' -)RP( -The benefit of using remote registration is that communication with -remote access points can be mixed with that of other access points -on the remote machine. Using )0 3 1 A(Access Point -Names and Templates)3 0 TN TL()Ec /AF f D(, one XPA command can be used to send or -receive messages to the remote and local services. - -)0 2 25 H(XPANS)WB 79 Sn( Proxy Registration)EH( - -The two methods described above are useful when the local and remote -machines are able to communicate freely to one another. This would be -the case on most Local Area Networks \201LANs\202 where all machines are -behind the same firewall and there is no port blocking between -machines on the same LAN. The situation is more complicated when the -XPA server is behind a firewall, where outgoing connections are -allowed, but incoming port blocking is implemented to prevent machines -outside the firewall from connecting to machines inside the -firewall. Such incoming port blocking will prevent xpaset and xpaget -from connecting to an XPA server inside a firewall. - -)0 P(To allow locally fire-walled XPA services to register with remote -machines, we have implemented a proxy service within the xpans name -server. To register remote proxy service, xpaset and the -)BD(-remote)ES( sub-command is again used, but with an additional -)BD(-proxy)ES( argument added to the end of the command: -) 1 63 PR( [sh]$ ./xpaset -p xpa -remote 'remote_machine:$port' g -proxy)RP( -Once a remote proxy registration command is executed, the remote -machine will have an entry such as the following in its own xpans name -service: -) 2 32 PR( [csh]$ xpaget xpans - XPA xpa gs @88877766:2839 eric)RP( -The '@' sign in the name service entry indicates that xpans proxy -processing is being used for this access point. Other than that, from -the user's point of view, there is no difference in how this XPA -access point is contacted using XPA programs \201xpaset, xpaget, etc.\202 or -libraries: -) 6 23 PR( [csh]$ xpaget xpa - class: XPA - name: xpa - method: 88877766:3053 - sendian: little - cendian: big)RP( -)0 P(Of course, the underlying processing of the XPA requests is very much -different when xpans proxy is involved. Instead of an XPA program such -contacting the XPA service directly, it contacts the local xpans. -Acting as a proxy server, xpans communicates with the XPA service -using the command channel established at registration time. Commands -\201including establishing a new data channel\202 are sent between xpans and -the XPA service to set up a new message transfer, and then data is fed -to/from the xpa request, through xpans, from/to the XPA service. In -this way, it can be arranged so that connections between the -fire-walled XPA service and the remote client are always initiated by -the XPA service itself. Thus, incoming connections that would be -blocked by the firewall are avoided. Note that there is a performance -penalty for using the xpans/proxy service. Aside from extra overhead -to set up proxy communication, all data must be sent through the -intermediate proxy process. - -)0 P(The xpans proxy scheme requires that the remote client allow the local -XPA server machine to connect to the remote xpans/proxy server. If the -remote client machine also is behind a port-blocking firewall, such -connections will be disallowed. In this case, the only solution is to -open up some ports on the remote client machine to allow incoming -connections to xpans/proxy. Two ports must be opened \201for command and -data channel connections\202. By default, these two ports are 14285 and -14287. The port numbers can be changed using the )BD(XPA_NSINET)ES( -environment variable. This variable takes the form: -) 1 49 PR( setenv XPA_NSINET machine:port1[,port2[,port3]])RP( -where port1 is the main connecting port, port2 is the XPA access port, -and port3 is the secondary data connecting port. The second and third -ports are optional and default to port1+1 and port1+2, respectively. -It is port1 and port3 that must be left open for incoming connections. - -)0 P(For example, to change the port assignments so that xpans listens -for registration commands on port 12345 and data commands on port 28573: -) 1 32 PR( setenv XPA_NSINET myhost:12345)RP( -Alternatively, all three ports can be assigned explicitly: -) 1 43 PR( setenv XPA_NSINET remote:12345,3000,12346)RP( -In this case 12345 and 12346 should be open for incoming connections. -The XPA access port \201which need not be open to the outside -world\202 is set to 3000. - -)0 P(Finally, note that we currently have no mechanism to cope with -Internet proxy servers \201such as SOCKS servers\202. If an XPA service is -running on a machine that cannot connect directly to outside machines, -but goes through a proxy server instead, there currently is no way to -register that XPA service with a remote machine. We hope to implement -support for SOCKS proxy in a future release. - - - - - -)0 P()0 0 1 A(Go to XPA Help Index)0 0 TN TL()Ec /AF f D( - -)0 5 26 H(Last)WB 80 Sn( updated: September 10, 2003)EH( -)WB NL -/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc -DS -/Ba f D /BO 0 D Bs -/UR (users.html) D -/Ti (Distinguishing Users) D -/Au () D -/Df f D -/ME [()] D - -0 BO R -()1 Sl()WB 7 Sn( - - -)0 2 27 H(XPAUsers:)WB 82 Sn()WB 81 Sn( Distinguishing Users)EA()EH( - - -)0 2 28 H(Summary)WB 83 Sn()EH( -)0 P(XPA normally distinguishes between users on a given host, but it is possible -to send data to access points belonging to other users. - - -)0 2 29 H(Description)WB 84 Sn()EH( -)0 P(A single XPA name service typically serves all users on a given -machine. Two users can register the same XPA access points on the -same machine without conflict, because the user's username is -registered with each access point and, by default, programs such as -xpaget and xpaset only process access points of the appropriate user. -For example: -) 4 32 PR( XPA xpa1 gs 838e2f67:1262 eric - XPA xpa2 gs 838e2f67:1266 eric - XPA xpa1 gs 838e2f67:2523 john - XPA xpa2 gs 838e2f67:2527 john)RP( -Here the users "eric" and "john" both have registered the access -points xpa1 and xpa2. When either "john" or "eric" retrieves -information from xpa1, they will process only the access point -registered in their user name. - -)0 P(If you want to access another user's XPA access points on a single -machine, use the -u [user] option on xpaset, xpaget, etc. For example, -if eric executes: -) 1 21 PR( xpaget -u john xpa1)RP( -he will access John's xpa1 access point.Use "*" to access all users -on a given machine: -) 1 20 PR( xpaget -u "*" xpa1)RP( -Note that the )0 40 1 A(XPA Environment Variable)40 0 TN TL()Ec /AF f D( -XPA_NSUSERS can be used to specify the default list of users to -process: -) 1 32 PR( setenv XPA_NSUSERS "eric,john")RP( -will cause access points from both "eric" and "john" to be processed -by default. - - - - - -)0 P()0 0 1 A(Go to XPA Help Index)0 0 TN TL()Ec /AF f D( - -)0 5 30 H(Last)WB 85 Sn( updated: September 10, 2003)EH( -)WB NL -/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc -DS -/Ba f D /BO 0 D Bs -/UR (programs.html) D -/Ti (XPA Programs) D -/Au () D -/Df f D -/ME [()] D - -0 BO R -()1 Sl()WB 8 Sn( -)0 2 31 H(XPA)WB 86 Sn( Programs)EH( - -)0 2 32 H(Summary)WB 87 Sn()EH( - -)0 P(Use the XPA programs to send/receive data to/from XPA servers from the -command line or from scripts. - -)0 P() 7 116 PR( <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])RP( - - - - -)0 2 33 H(xpaset:)WB 88 Sn()WB 10 Sn( send data to one or more XPA servers)EA()EH( - - -)BD() 1 124 PR(<data> | xpaset [-h] [-i nsinet] [-m method] [-n] [-p] [-s] [-t sval,lval] [-u users] [-v] <template|host:port> [paramlist])RP()ES( - - -)0 P() 10 79 PR( -h print help message - -i access XPA point on different machine \201override XPA_NSINET\202 - -m override XPA_METHOD environment variable - -n don't wait for the status message after server completes - -p don't read \201or send\202 buf data from stdin - -s enter server mode - -t [s,l] set short and long timeouts \201override XPA_[SHORT,LONG]_TIMEOUT\202 - -u [users] XPA points can be from specified users \201override XPA_NSUSERS\202 - -v verify message to stdout - --version display version and exit)RP( - - -)0 P(Data read from stdin will be sent to access points matching the -)0 3 1 A(template)3 0 TN TL()Ec /AF f D( -or host:port. -A set of qualifying parameters can be appended. -)0 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: -) 1 32 PR( cat foo.fits | xpaset ds9 fits)RP( -)0 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: -) 1 30 PR( csh> xpaset -p ds9 cmap Heat)RP( -Of course, this also can be accomplished by sending EOF to stdin in -any of the usual ways: -) 4 43 PR( csh> echo "" | xpaset ds9 cmap Heat - csh> xpaget ds9 cmap Heat < /dev/null - csh> xpaset ds9 cmap Heat - ^D # Ctl-D signals EOF)RP( -)0 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. -\201Its not clear if this buys you much!\202 The syntax for sending commands -in server mode is: -)0 P() 8 24 PR( csh> xpaset -s - xpaset ds9 colormap I8 - ^D - xpaset ds9 regions - circle 200 300 40 - circle 300 400 50 - ^D -etc.)RP( -After the required "xpaset" command is specified, optional ASCII data -can be appended \201as in the region example\202. A single data/command set is -delimited by ^D. Note that typing ^D when a command is expected terminates -the program. -)0 P(NB: server mode only works from the terminal and only ASCII data can be -sent in this way. -)0 P()BD(Examples:)ES( -) 2 40 PR( csh> xpaset ds9 file < foo.fits - csh> echo "stop" | xpaset myhost:12345)RP( - - - - -)0 2 34 H(xpaget:)WB 89 Sn()WB 9 Sn( retrieve data from one or more XPA servers)EA()EH( - - -)BD() 1 99 PR(xpaget [-h] [-i nsinet] [-m method] [-s] [-t sval,lval] [-u users] <template|host:port> [paramlist])RP()ES( - - -)0 P() 8 79 PR( -h print help message - -i access XPA point on different machine \201override XPA_NSINET\202 - -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 \201override XPA_[SHORT,LONG]_TIMEOUT\202 - -u [users] XPA points can be from specified users \201override XPA_NSUSERS\202 - --version display version and exit)RP( - - -)0 P(Data will be retrieved from access points matching the -)0 3 1 A(template)3 0 TN TL()Ec /AF f D( -or host:port. -A set of qualifying parameters can be appended. -)0 P()BD(Examples:)ES( -) 2 38 PR( csh> xpaget ds9 images - csh> xpaget myhost.harvard.edu:12345)RP( - - - - -)0 2 35 H(xpainfo:)WB 90 Sn()WB 11 Sn( send short message to one or more XPA servers)EA()EH( - - -)BD() 1 105 PR(xpainfo [-h] [-i nsinet] [-m method] [-n] [-s] [-t sval,lval] [-u users] <template|host:port> [paramlist])RP()ES( - - -)0 P() 8 79 PR( -h print help message - -i access XPA point on different machine \201override XPA_NSINET\202 - -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 \201override XPA_[SHORT,LONG]_TIMEOUT\202 - -u [users] XPA points can be from specified users \201override XPA_NSUSERS\202 - --version display version and exit)RP( - - -)0 P(Info will be sent to access points matching the -)0 3 1 A(template)3 0 TN TL()Ec /AF f D( -or host:port. -A set of qualifying parameters can be appended. -)0 P()BD(Examples:)ES( -) 1 30 PR( csh> xpainfo IMAGE ds9 image)RP( - - - - -)0 2 36 H(xpaaccess:)WB 91 Sn()WB 12 Sn( see if template matches registered XPA access points)EA()EH( - - -)BD() 1 95 PR(xpaaccess [-c] [-h] [-i nsinet] [-m method] [-n] [-t sval,lval] [-u users] -v <template> [type])RP()ES( - - -)0 P() 10 79 PR( -c contact each access point individually - -h print help message - -i access XPA point on different machine \201override XPA_NSINET\202 - -m override XPA_METHOD environment variable - -n return number of matches instead of "yes" or "no" - -t [s,l] set short and long timeouts \201override XPA_[SHORT,LONG]_TIMEOUT\202 - -u [users] XPA points can be from specified users \201override XPA_NSUSERS\202 - -v print info about each successful access point - -V print info or error about each access point - --version display version and exit)RP( - - -)0 P(xpaaccess returns "yes" to stdout \201with a return error code if 1\202 if there are -existing XPA access points that match the -)0 3 1 A(template)3 0 TN TL()Ec /AF f D( -\201and optional access type: g,i,s\202. Otherwise, it returns "no" \201with a -return error code of 0\202. If -n is specified, the number of matches is -returned instead \201both to stdout and in the returned error code\202. If --v is specified, each access point is displayed to stdout instead of -the number of matches. - -)0 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 \201contact\202 -switch. With this switch, xpaaccess contacts each matching XPA server -\201rather than the name server\202 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: -) 1 27 PR( xpaaccess -c -t "2,2" ds9)RP( -The first argument is the short delay value, and is ignored in this -operation. The second is the long delay timeout. - -)0 P(Note also that the default xpaaccess method \201no -c switch\202 does not -check access control \201acls\202 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 \201contact\202 switch, which -contacts the access point directly, can and does check the access -control \201only for servers using version 2.1 and above\202 and also -returns the real status of xpans. - - - - - - - - - - - -)0 P()0 0 1 A(Go to XPA Help Index)0 0 TN TL()Ec /AF f D( - -)0 5 37 H(Last)WB 92 Sn( updated: September 10, 2003)EH( -)WB NL -/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc -DS -/Ba f D /BO 0 D Bs -/UR (xpamb.html) D -/Ti (The XPA Message Bus \201xpamb\202) D -/Au () D -/Df f D -/ME [()] D - -0 BO R -()1 Sl()WB 13 Sn( - - -)0 2 38 H(xpamb:)WB 94 Sn()WB 93 Sn( the XPA Message Bus)EA()EH( - - -)0 2 39 H(Summary)WB 95 Sn()EH( -)0 P(The xpamb program can act as a "classical" message bus interface -between clients and servers. A client can send a data request to -the message bus, which then interfaces with multiple servers and -returns the data back to the client. - - -)0 2 40 H(Description)WB 96 Sn()EH( -)0 P(A "classical" message bus \201such as ToolTalk\202 consists of servers and -clients, along with a mediating program that transfers data between -different processes. XPA takes a slightly different approach in that -communication between clients and servers is direct. This generally -is the correct technique when there is only one connection \201or even a -small number of connections\202, but can become inefficient for the -serving program if a large amount of data is being transferred to many -clients. For example, if a real-time data acquisition program is -broadcasting a FITS image to several clients, it would need to -transmit that image to each client individually. This might interfere -with its own processing cycles. The preferable mechanism would be to -pass the image off to an intermediate program that can then broadcast -the data to the several clients. -)0 P(The )BD(xpamb)ES( program can alleviate such problems by functioning -as a message bus in cases where such an intermediary process is -wanted. It pre-defines a single access point named -)BD(XPAMB:xpamb)ES( to which data can be sent for re-broadcast. You -also can tell )BD(xpamb)ES( to save the data, and associate with that -data a new access point, so that it can be retrieved later on. - -)0 P(All interaction with )BD(xpamb)ES( is performed through -)BD(xpaset)ES( and )BD(xpaget)ES( \201or the corresponding API -routines, )BD(XPASet\201\202)ES( and )BD(XPAGet\201\202)ES(\202 to the -)BD(XPAMB:xpamb)ES( access point. That is, )BD(xpamb)ES( is just -another XPA-enabled program that responds to requests from -clients. The paramlist is used to specify the targets to which -the data will be for re-broadcast, as well as the re-broadcast paramlist: -) 1 69 PR( data | xpaset xpamb [switches] broadcast-target broadcast-paramlist)RP( -Optional switches are used to store data, and manipulate stored data, -and are described below. - -)0 P(In its simplest form, you can, for example, send a FITS image to xpamb for -broadcasting to all ds9 image simply by executing: -) 1 51 PR( cat foo.fits | xpaset xpamb "DS9:*" fits foo.fits)RP( -Since )BD(DS9)ES( is the class name for the ds9 image display -program, this will result in the FITS image being re-sent to all fits -access points for all active image display programs. - -)0 P(You can send stored data and new data to the same set of access points at -the same time. The stored data always is send first, followed by the new -data: -) 1 62 PR( cat foo2.fits | xpaset xpamb -send foo "DS9:*" fits foo.fits)RP( -will first send the foo.fits file, and then the foo2.fits file to all -access points of class )BD(DS9)ES(. Notice that in this example, -the foo2.fits file is not stored, but it could be stored by using the -)BD(-store [name])ES( switch on the command line. - -)0 P(The )BD(xpaget)ES( command can be used to retrieve a data from XPA -access points or from a stored data buffer, or retrieve information -about a stored data buffer. If no arguments are given: -) 1 14 PR( xpaget xpamb)RP( -then information about all currently stored data buffers is returned. This -information includes the data and time at which the data was stored, the -size in bytes of the data, and the supplied info string. - -)0 P(If arguments are specified, they will be in the form: -) 1 49 PR( xpaget xpamb [-info] [-data] [name [paramlist]])RP( -If the optional )BD(-info)ES( and/or )BD(-data)ES( switches are specified, then -information and/or data will be returned for the named data buffer -following the switches. You can use either or both of these switches -in a single command. For example, if the -info switch is used: -) 1 24 PR( xpaget xpamb -info foo)RP( -then the info about that stored data buffer will be returned. -If the -data is used with a specific name: -) 1 24 PR( xpaget xpamb -data foo)RP( -then the stored data itself will be returned. If both are used: -) 1 30 PR( xpaget xpamb -info -data foo)RP( -then the info will be returned, followed by the data. Note that it is an -error to specify one of these switches without a data buffer name and that -the paramlist will be ignored. - -)0 P(If neither the )BD(-info)ES( or )BD(-data)ES( switch is specified, then -the name refers to an XPA access point \201with an optional paramlist -following\202. -For example: -) 1 23 PR( xpaget xpamb ds9 file)RP( -is equivalent to: -) 1 17 PR( xpaget ds9 file)RP( - - -)0 2 41 H(Options)WB 97 Sn()EH( -)0 P(For xpaset, several optional switches are used to save data and -manipulate the stored data: -)0 DL( -)0 P()0 DT()BD(-data [name])ES( -)DD( Add the supplied data buffer to a pool of stored data buffers, -using the specified name as a unique identifier for later retrieval. -An error occurs if the name already exists \201use either )BD(replace)ES( -or )BD(del)ES( to rectify this\202. The )BD(-add)ES( switch is supported -for backwards compatibility with xpa 2.0. - -)0 P()0 DT()BD(-replace [name])ES( -)DD( Replace previously existing stored data having the same unique name -with new data. This essentially is a combination of the )BD(del)ES( -and )BD(data)ES( commands. - -)0 P()0 DT()BD(-info ["'info string'"])ES( -)DD( When adding a data buffer, you can specify an informational -string to be stored with that data. This string will be returned -by xpaget: -) 1 24 PR( xpaget xpamb foo -info)RP( -\201along with other information such as the date/time of storage and the size of -the data buffer\202 if the -info switch is specified. If the info string contains -spaces, you must enclose it in )BD(two)ES( sets of quotes: -) 1 65 PR( cat foo | xpaset xpamb -store foo -info "'this is info on foo'")RP( -The first set of quotes is removed by the shell while the second is used to -delineate the info string. - -)0 P()0 DT()BD(-send [name])ES( -)DD( Broadcast the stored data buffer to the named template. - -)0 P()0 DT()BD(-del [name])ES( -)DD( Delete the named data buffer and free all allocated space.)LD( - -)0 P(Switches can be used in any combination that makes sense. For example: -) 1 75 PR( cat foo.fits | xpaset xpamb -store foo -info "FITS" "DS9:*" fits foo.fits)RP( -will broadcast the foo.fits image to all access points of class -)BD(DS9)ES(. In addition, the foo.fits file will be stored under the -name of )BD(foo)ES( for later manipulation such as: -) 1 49 PR( xpaset -p xpamb -send foo "DS9:*" fits foo.fits)RP( -will re-broadcast the foo.fits image to all access points of class "DS9". - - - - - -)0 P()0 0 1 A(Go to XPA Help Index)0 0 TN TL()Ec /AF f D( - -)0 5 42 H(Last)WB 98 Sn( updated: September 10, 2003)EH( -)WB NL -/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc -DS -/Ba f D /BO 0 D Bs -/UR (xpans.html) D -/Ti (The XPA Name Server \201xpans\202) D -/Au () D -/Df f D -/ME [()] D - -0 BO R -()1 Sl()WB 14 Sn( - - -)0 2 43 H(xpans:)WB 100 Sn()WB 99 Sn( the XPA Name Server)EA()EH( - - -)0 2 44 H(Summary)WB 101 Sn()EH( -) 1 70 PR( xpans [-h] [-e] [-k sec] [-p port] [-l log] [-s security log] [-P n])RP( - - -)0 P() 8 71 PR( -h print help message - -e exit when there are no more XPA connections - -k send keepalive messages every n sec - -l log data base entries to specified file - -p listen for connections on specified port - -s log security info for each connection to specified file - -P accept proxy requests \201P=1\202 using separate thread \201P=2\202 - --version display version and exit)RP( - - -)0 P(The xpans name server is an XPA-enabled program that is used to -manage the names and ports of XPA access points. It is started -automatically when an XPA access point is registered. You can access -the name server using xpaget to get a list of registered access points. -)0 P(The )EM(xpans)ES( name server provides a crucial link between XPA -clients and servers. When an XPA server defines an access point using -XPANew\201\202, XPACmdNew\201\202, or XPAInfoNew\201\202, the name of the access point -is registered in the name service, along with connection information. -The name server then matches class:name templates passed to it by XPA -clients with these registered entries, so that the clients can -communicate with the appropriate servers. - -)0 P(The socket connection between an XPA-enabled program and -)EM(xpans)ES( is kept open until the former exits \201or explicitly -closes the connection\202. Apparently, some Internet equipment \201e.g. DSL -modems\202 can cause such a connection to time-out after a period of -inactivity. To prevent this from happening, you can use the )EM(-k -[sec])ES( switch to send a short keep-alive message to each open -connection after the specified time delay. \201Note that this -application level use of keep-alive is necessary only if you are -serving XPA-enabled clients over the Internet and have to deal with -long-term connections involving DSL or similar equipment. XPA uses -the ordinary socket-level keep-alive, which works for all other cases.\202 -)BD(NB \20112/2/2009\202: Out-of-band \201URG\202 TCP data, used by xpans -keep-alive, is changed by some Cisco routers into in-band data. -Encountering such a router will break the keep-alive function and may -break your XPA server as well. Proceed with caution!)ES( - -)0 P(The )EM(xpans)ES( program will be started automatically \201assuming it -can be found in the user's path\202 when the first XPA access point is -registered. It therefore need not be started explicitly. However, -when started automatically, the )EM(-e)ES( switch is used, so that -the name server will exit when there are no more XPA access points -registered. If you wish to keep the name server running continually, -simply start it manually without the )EM(-e)ES( switch. - -)0 P(The name server will keep a log of registered access points if the -)EM(-l [log])ES( switch is used on the command line \201this is the -case for automatic start-up\202. The log contains enough name and connection -information to allow you to re-register all XPA access points in case -the name server process is terminated prematurely. For example, after -the ds9 access point is registered,the log will contain the entry: -) 1 35 PR( add 838e2f67:1863 ds9 ds9 gs eric)RP( -If )EM(xpans)ES( is terminated but ds9 still is running, you -can re-register both access points for the ds9 process by running: -) 1 36 PR( xpaset -p 838e2f67:1863 -nsconnect)RP( -Notice that the ip:port specifier is used with )EM(xpaset)ES( to bypass -the need for contacting the name server \201which does not have the name -registered yet!\202 - -)0 P(The name server will keep a log of security information if the )EM(-s -[security log])ES( switch is used on the command line. For each -accepted connection, \201including connections via the )EM(xpaget)ES( -command\202, information will be logged about the host issuing the -command and the parameters passed into the program. This is most -useful when )EM(xpans)ES( is accepting connections from untrusted -machines. - -)0 P(When an XPA access point is removed by a server using )EM(XPAFree\201\202)ES(, -the access information is removed from the name server. If an -XPA-enabled process is terminated, all names registered by that process -will be removed automatically. The log file is always updated to -reflect the currently registered access points. - -)0 P(The name server itself has an XPA access point names )EM(xpans)ES( -registered through which you can find out information about currently -registered access points \201assuming you have access to the name server; -see )0 41 1 A(XPA Access Control)41 0 TN TL()Ec /AF f D( for more information\202. -For each registered access point, the following information is returned: -) 5 80 PR( class # class of the access point - name # name of the access point - access # allowed access \201g=xpaget,s=xpaset,i=xpainfo\202 - id # socket access method \201host:port for inet, file for local/unix\202 - user # user name of access point owner)RP( - -)0 P(For example, to display all currently registered access points, simply execute: -) 1 14 PR( xpaget xpans)RP( -Continuing the example of ds9 above, this will return: -) 1 31 PR( DS9 ds9 gs 838e2f67:1863 eric)RP( -If the same program has been started with different XPA access names, -you can look up only names matching a specified template. For example, -assume that ds9 has been started up using: -) 3 25 PR( ds9 & - ds9 -title ds9-1-eric & - ds9 -title ds9-2-eric &)RP( -To lookup all ds9 access points which end in ".eric" and which can -be accessed using )EM(xpaset)ES(, use: -) 1 35 PR( xpaget xpans "DS9:*.eric" "s" "*")RP( -This will return: -) 2 39 PR( DS9 ds9-2-eric gs 838e29d3:42102 eric - DS9 ds9-1-eric gs 838e29d3:42105 eric)RP( -The third argument "*" requests all access points from all users. -You also can specify a specific user name and only access points -registered by that user will be returned. - -)0 P(The name server uses the )EM(XPA_METHOD)ES( environment variable -to determine whether it should listen for requests on INET or LOCAL -sockets. Since XPA access points also use this environment variable, -the choice of socket method will be consistent. Note that, when INET -sockets are used, a local server can be accessed from remote machines -if the )EM(XPA_NSINET)ES( environment variable is set to point to -the local machine. See -)0 40 1 A(XPA Environment Variables)40 0 TN TL()Ec /AF f D( -for more information. - -)0 P(An experimental feature of xpans is its ability to act as a proxy to -XPA servers behind firewalls that want to communicate with external -processes. The basic idea is the following: an XPA server \201call it -"foo"\202 on host1, possibly behind a firewall, makes a remote connection -to a proxy-enabled xpans program on host2 \201specifying host2's XPA method\202. -For example: -) 1 59 PR( xpaset -p foo -remote 'host2:28571' + -proxy # on host1)RP( -When this is done, host2 can use xpaset, xpaget, and xpainfo calls to -communicate with the XPA server foo. All command communication is -performed via the xpans socket connection between foo on host1 and -xpans on host2 \201which was initiated by foo from inside the firewall\202. -Data communication is similarly performed using a socket connection -initiated on host1 \201usually with a port value two greater than the -port value of the main xpans socket connection\202. An xpaset or xpaget -call on host2 contacts xpans, which performs an XPASet\201\202 or XPAGet\201\202 -call to foo, passing commands and data back and forth between the two -programs. - -)0 P(By default, proxy connections are not allowed by xpans. If the -P switch is -specified with a value of 1, proxy connection are allowed, but all proxy -communication is performed in the same thread as xpans processing. If -a value of 2 is specified, the proxy processing is performed in a -separate thread \201assuming pthreads are supported on your system\202. -Because xpa callback processing of any type can take a long time and -therefore can interfere with normal xpans processing, threaded proxy -connections \201-P 2\202 are recommended. When using proxy connections, it -might also be useful to set the XPA_IOCALLSXPA environment variable, so -that multiple proxy requests can be handled at the same time, instead of -serially. - -)0 P(Note that this proxy interface to xpans is experimental. It is used -to provide remote data analysis capabilities on the Chandra-Ed system -using ds9. \201See http://chandra-ed.cfa.harvard.edu and -http://hea-www.harvard.edu/saord/ds9 for more details\202. As always, please -contact us if you have problems or questions. - - - - - -)0 P()0 0 1 A(Go to XPA Help Index)0 0 TN TL()Ec /AF f D( - -)0 5 45 H(Last)WB 102 Sn( updated: January 24, 2005)EH( -)WB NL -/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc -DS -/Ba f D /BO 0 D Bs -/UR (server.html) D -/Ti (XPA Server API) D -/Au () D -/Df f D -/ME [()] D - -0 BO R -()1 Sl()WB 15 Sn( - - -)0 2 46 H(XPAServer:)WB 106 Sn()WB 103 Sn( The XPA Server-side Programming Interface)EA()EH( - - -)0 2 47 H(Summary)WB 107 Sn()EH( -A description of the XPA server-side programming interface. - - -)0 2 48 H(Introduction)WB 108 Sn()WB 104 Sn( to XPA Server Programming)EH()EA( -)0 P(Creating an XPA server is easy: you generally only need to call the -XPANew\201\202 subroutine to define a named XPA access point and set up the -send and receive callback routines. You then enter an event loop such -as XPAMainLoop\201\202 to field XPA requests. -) 27 66 PR( #include <xpa.h> - - XPA )0 16 1 A(XPANew)16 0 TN TL()Ec /AF f D(\201char *class, char *name, char *help, - int \201*send_callback\202\201\202, void *send_data, char *send_mode, - int \201*rec_callback\202\201\202, void *rec_data, char *rec_mode\202; - - XPA )0 17 1 A(XPACmdNew)17 0 TN TL()Ec /AF f D(\201char *class, char *name\202; - - XPACmd )0 18 1 A(XPACmdAdd)18 0 TN TL()Ec /AF f D(\201XPA xpa, - char *name, char *help, - int \201*send_callback\202\201\202, void *send_data, char *send_mode, - int \201*rec_callback\202\201\202, void *rec_data, char *rec_mode\202; - - void )0 19 1 A(XPACmdDel)19 0 TN TL()Ec /AF f D(\201XPA xpa, XPACmd cmd\202; - - XPA )0 20 1 A(XPAInfoNew)20 0 TN TL()Ec /AF f D(\201char *class, char *name, - int \201*info_callback\202\201\202, void *info_data, char *info_mode\202; - - int )0 21 1 A(XPAFree)21 0 TN TL()Ec /AF f D(\201XPA xpa\202; - - void )0 22 1 A(XPAMainLoop)22 0 TN TL()Ec /AF f D(\201void\202; - - int )0 23 1 A(XPAPoll)23 0 TN TL()Ec /AF f D(\201int msec, int maxreq\202; - - void )0 105 1 A(XPAAtExit)105 0 TN TL()Ec /AF f D(\201void\202; - - void )0 24 1 A(XPACleanup)24 0 TN TL()Ec /AF f D(\201void\202;)RP( - -)0 2 49 H(Introduction)WB 109 Sn()EH( - -To use the XPA application programming interface, a software developer -generally will include the xpa.h definitions file: -) 1 18 PR( #include <xpa.h>)RP( -in the software module that defines or accesses an XPA access point, and -then will link against the libxpa.a library: -) 1 27 PR( gcc -o foo foo.c libxpa.a)RP( -XPA has been compiled using both C and C++ compilers. - -)0 P(A server program generally defines an XPA access point by calling the -XPANew\201\202 routine and specifies "send" and/or "receive" callback -procedures to be executed by the program when an external process -either sends data or commands to this access point or requests data or -information from this access point. A program also can define several -sub-commands for a single access point by calling XPACmdNew\201\202 and -XPACmdAdd\201\202 instead. Having defined one or more public access points -in this way, an XPA server program enters its usual event loop \201or -uses the standard XPA event loop\202. - - - - -)0 2 50 H(XPANew:)WB 110 Sn()WB 16 Sn( create a new XPA access point)EA()EH( - - -)BD() 7 49 PR( #include <xpa.h> - - XPA XPANew\201char *class, char *name, char *help, - int \201*send_callback\202\201\202, - void *send_data, char *send_mode, - int \201*rec_callback\202\201\202, - void *rec_data, char *rec_mode\202;)RP()ES( - - -)0 P(Create a new XPA public access point with the class:name -identifier )0 3 1 A(template)3 0 TN TL()Ec /AF f D( -and enter this access point into the XPA name server, so that it -can be accessed by external processes. XPANew\201\202 returns an XPA struct. -Note that the length of the class and name designations must be less -than or equal to 1024 characters each. - -)0 P(The XPA name server daemon, xpans, will be started automatically if it -is not running already \201assuming it can be found in the path\202. The -program's ip address and listening port are specified by the -environment variable XPA_NSINET, which takes the form :. If -no such environment variable exists, then xpans is started on the -current machine listening on port 14285. It also uses 14286 as a -known port for its public access point \201so that routines do not have -to go to the name server to find the name server ip and port!\202 -As of XPA 2.1.1, version information is exchanged between the xpans -process and the new access point. If the access point uses an XPA -major/minor version newer than xpans, a warning is issued by both processes, -since mixing of new servers and old xpa programs \201xpaset, xpaget, -xpans, etc.\202 is not likely to work. You can turn off the warning -message by setting the XPA_VERSIONCHECK environment variable to "false". - -)0 P(The help string is meant to be returned by a request from xpaget: -) 1 25 PR( xpaget class:name -help)RP( -)0 P(A send_callback and/or a receive_callback can be specified; at -least one of them must be specified. - -)0 P(A send_callback can be specified that will be executed in response to -an external request from the xpaget program, the XPAGet\201\202 routine, or -XPAGetFd\201\202 routine. This callback is used to send data to the -requesting client. - -)0 P(The calling sequence for send_callback\201\202 is: -) 7 53 PR( int send_callback\201void *send_data, void *call_data, - char *paramlist, char **buf, size_t *len\202 - { - XPA xpa = \201XPA\202call_data; - ... - return\201stat\202; - })RP( -)0 P(The send_mode string is of the form: "key1=value1,key2=value2,..." -The following keywords are recognized: -) 4 81 PR( key value default explanation - ------ -------- -------- ----------- - acl true/false true enable access control - freebuf true/false true free buf after callback completes)RP( -)0 P(The call_data should be recast to the XPA struct as shown. In -addition, client-specific data can be passed to the callback in -send_data. - -)0 P(The paramlist will be supplied by the client as qualifying parameters -for the callback. There are two ways in which the send_callback\201\202 -routine can send data back to the client: - -)0 P(1. The send_callback\201\202 routine can fill in a buffer and pass back a -pointer to this buffer. An integer len also is returned to specify the -number of bytes of data in buf. XPA will send this buffer to the -client after the callback is complete. - -)0 P(2. The send_callback can send data directly to the client by writing -to the fd pointed by the macro: -) 1 17 PR( xpa_datafd\201xpa\202)RP( -)0 P(Note that this fd is of the kind returned by socket\201\202 or open\201\202. - -)0 P(If a buf has been allocated by a standard malloc routine, filled, and -returned to XPA, then freebuf generally is set so that the buffer will -be freed automatically when the callback is completed and data has -been sent to the client. If a static buf is returned, freebuf should -be set to false to avoid a system error when freeing static storage. -Note that default value for freebuf implies that the callback will -allocate a buffer rather than use static storage. - -)0 P(On the other hand, if buf is dynamically allocated using a method -other than a standard malloc/calloc/realloc routine \201e.g. using Perl's -memory allocation and garbage collection scheme\202, then it is necessary -to tell XPA how to free the allocated buffer. To do this, use the -XPASetFree\201\202 routine within your callback: -) 1 69 PR( void XPASetFree\201XPA xpa, void \201*myfree\202\201void *\202, void *myfree_ptr\202;)RP( -The first argument is the usual XPA handle. The second argument is the -special routine to call to free your allocated memory. The third -argument is an optional pointer. If not NULL, the specified free -routine is called with that pointer as its sole argument. If NULL, the -free routine is called with the standard buf pointer as its sole -argument. This is useful in cases where there is a mapping between the -buffer pointer and the actual allocated memory location, and the -special routine is expecting to be passed the former. - -)0 P(If, while the callback performs its processing, an error occurs that -should be communicated to the client, then the routine XPAError should be -called: -) 1 29 PR( XPAError\201XPA xpa, char *s\202;)RP( -)0 P(where s is an arbitrary error message. The returned error message -string will be of the form: -) 1 42 PR( XPA$ERROR [error] \201class:name ip:port\202)RP( -)0 P(If the callback wants to send a specific acknowledgment message back -to the client, the routine XPAMessage can be called: -) 1 31 PR( XPAMessage\201XPA xpa, char *s\202;)RP( -)0 P(where s is an arbitrary error message. The returned error message -string will be of the form: -) 1 44 PR( XPA$MESSAGE [message] \201class:name ip:port\202)RP( -)0 P(Otherwise, a standard acknowledgment is sent back to the client -after the callback is completed. - -)0 P(The callback routine should return 0 if no error occurs, or -1 to -signal an error. - -)0 P(A receive_callback can be specified that will be executed in response -to an external request from the xpaset program, or the XPASet \201or -XPASetFd\201\202\202 routine. This callback is used to process data received -from an external process. - -)0 P(The calling sequence for receive_callback is: -) 7 59 PR( int receive_callback\201void *receive_data, void *call_data, - char *paramlist, char *buf, size_t len\202 - { - XPA xpa = \201XPA\202call_data; - ... - return\201stat\202; - })RP( -)0 P(The mode string is of the form: "key1=value1,key2=value2,..." -The following keywords are recognized: -) 6 92 PR( key value default explanation - ------ -------- -------- ----------- - acl true/false true enable access control - buf true/false true server expects data bytes from client - fillbuf true/false true read data into buf before executing callback - freebuf true/false true free buf after callback completes)RP( -)0 P(The call_data should be recast to the XPA struct as shown. In -addition, client-specific data can be passed to the callback in -receive_data. - -)0 P(The paramlist will be supplied by the client. In addition, if the -receive_mode keywords buf and fillbuf are true, then on entry into the -receive_callback\201\202 routine, buf will contain the data sent by the -client. If buf is true but fillbuf is false, it becomes the callback's -responsibility to retrieve the data from the client, using the data fd -pointed to by the macro xpa_datafd\201xpa\202. If freebuf is true, then buf -will be freed when the callback is complete. - -)0 P(If, while the callback is performing its processing, an error occurs -that should be communicated to the client, then the routine XPAError -can be called: -) 1 29 PR( XPAError\201XPA xpa, char *s\202;)RP( -)0 P(where s is an arbitrary error message. - -)0 P(The callback routine should return 0 if no error occurs, or -1 to -signal an error. - - - - -)0 2 51 H(XPACmdNew:)WB 111 Sn()WB 17 Sn( create a new XPA public access point for commands)EA()EH( - - -)BD() 3 41 PR( #include <xpa.h> - - XPA XPACmdNew\201char *class, char *name\202;)RP()ES( - - -)0 P(Create a new XPA public access point for commands that will share a -common identifier class:name. Enter this access point into the XPA -name server, so that it can be accessed by external processes. -XPACmdNew\201\202 returns an XPA struct. - -)0 P(It often is more convenient to have one public access point that can -manage a number of commands, rather than having individual access -points for each command. For example, it is easier to command the -ds9 image display using: -) 3 35 PR( echo "colormap I8" | xpaset ds9 - echo "scale log" | xpaset ds9 - echo "file foo.fits" | xpaset ds9)RP( -)0 P(then to use: -) 3 39 PR( echo "I8" | xpaset ds9_colormap - echo "log" | xpaset ds9_scale - echo "foo.fits" | xpaset ds9_file)RP( -)0 P(In the first case, the commands remain the same regardless of the -target XPA name. In the second case, the command names must change -for each instance of ds9. That is, if a second instance of ds9 -called DS9 were running, it would be commanded either as: -) 3 35 PR( echo "colormap I8" | xpaset DS9 - echo "scale log" | xpaset DS9 - echo "file foo.fits" | xpaset DS9)RP( -)0 P(or as: -) 3 39 PR( echo "I8" | xpaset DS9_colormap - echo "log" | xpaset DS9_scale - echo "foo.fits" | xpaset DS9_file)RP( -)0 P(Thus, in cases where a program is going to manage many commands, it -generally is easier to define them as commands associated with the -XPACmdNew\201\202 routine, rather than as separate access points using -XPANew\201\202. - -)0 P(When XPACmdNew\201\202 is called, only the class:name identifier is -specified. Each sub-command is subsequently defined using the -XPACmdAdd\201\202 routine. - - - - -)0 2 52 H(XPACmdAdd:)WB 112 Sn()WB 18 Sn( add a command to an XPA command public access point)EA()EH( - - -)BD() 7 52 PR( #include <xpa.h> - - XPACmd XPACmdAdd\201XPA xpa, char *name, char *help, - int \201*send_callback\202\201\202, - void *send_data, char *send_mode, - int \201*rec_callback\202\201\202, - void *rec_data, char *rec_mode\202;)RP()ES( - - -)0 P(Add a command to an XPA command access point. The XPA argument specifies the -XPA struct returned by a call to XPANewCmd\201\202. The name argument is the -name of the command. The other arguments function identically to the -arguments in the XPANew\201\202 command, i.e., the send_callback and rec_callback -routines have identical calling sequences to their XPANew\201\202 counterparts, -with the exceptions noted below. - -)0 P(When help is requested for a command access point using: -) 1 22 PR( xpaget -h class:name)RP( -)0 P(all of the command help strings are listed. To get help for a given -command, use: -) 1 26 PR( xpaget -h class:name cmd)RP( -)0 P(Also, the acl keyword in the send_mode and receive_mode strings is -global to the access point, not local to the command. Thus, the value -for the acl mode should be the same in all send_mode \201or receive_mode\202 -strings for each command in a command access point. \201The acl for -send_mode need not be the same as the acl for receive_mode, though\202. - - - - -)0 2 53 H(XPACmdDel:)WB 113 Sn()WB 19 Sn( remove a command from an XPA command public access point)EA()EH( - - -)BD() 3 38 PR( #include <xpa.h> - - void XPACmdDel\201XPA xpa, XPACmd cmd\202;)RP()ES( - - -)0 P(This routine removes a command from the list of available commands in -a given XPA. That command will no longer be available for processing. - - - - -)0 2 54 H(XPAInfoNew:)WB 114 Sn()WB 20 Sn( define an XPA info public access point)EA()EH( - - -)BD() 5 51 PR( #include <xpa.h> - - XPA XPAInfoNew\201char *class, char *name, - int \201*info_callback\202\201\202, - void *info_data, char *info_mode\202;)RP()ES( - - -)0 P([NB: this is an experimental interface, new to XPA 2.0, whose value -and best use is evolving.] - -)0 P(A program can register interest in receiving a short message about a -particular topic from any other process that cares to send such a -message. Neither has to be an XPA server. For example, if a user -starts to work with a new image file called new.fits, she might -wish to alert interested programs about this new file by sending a -short message using xpainfo: -) 1 34 PR( xpainfo IMAGEFILE /data/new.fits)RP( - -)0 P(In this example, each process that has used the XPAInfoNew\201\202 call to -register interest in messages associated with the identifier IMAGEFILE -will have its info_callback\201\202 executed with the following calling -sequence: -) 4 64 PR( int info_cb\201void *info_data, void *call_data, char *paramlist\202 - { - XPA xpa = \201XPA\202call_data; - })RP( -)0 P(The arguments passed to this routine are equivalent to those sent in -the send_callback\201\202 routine. The main difference is that there is no -buf sent to the info callback: this mechanism is meant for short -announcement of messages of interest to many clients. - -)0 P(The mode string is of the form: "key1=value1,key2=value2,..." -The following keywords are recognized: -) 3 69 PR( key value default explanation - ------ -------- -------- ----------- - acl true/false true enable access control)RP( -)0 P(Because no buf is passed to this callback, the usual buf-related keywords -are not applicable here. - -)0 P(The information sent in the parameter list is arbitrary. However, we -envision sending information such as file names or XPA access points -from which to collect more data. Note that the xpainfo program and -the XPAInfo\201\202 routine that cause the info_callback to execute do not -wait for the callback to complete before returning. - - - - -)0 2 55 H(XPAFree:)WB 115 Sn()WB 21 Sn( remove an XPA public access point)EA()EH( - - -) 3 23 PR()BD( #include <xpa.h> - - int XPAFree\201XPA xpa\202;)ES()RP( - - -)0 P(Remove the specified XPA public access point from the name server and -free all associated storage. Note that removal from the name server -happens automatically when the process terminates, so this call is not -generally needed. It is used when public access points are being -defined temporarily and then destroyed when no longer needed. For -example, ds9 temporarily creates a public access point when it -loads a new image for display and destroys it when the image is -unloaded. - - - - -)0 2 56 H(XPAMainLoop:)WB 116 Sn()WB 22 Sn( optional main loop for XPA)EA()EH( - - -)BD() 3 21 PR( #include <xpa.h> - - void XPAMainLoop\201\202;)RP()ES( - - -)0 P(Once XPA access points have been defined, a program must enter an -event loop to watch for requests from external programs. This can be -done in a variety of ways, depending on whether the event loop is -processing events other than XPA events. In cases where there are no -non-XPA events to be processed, the program can simply call the -XPAMainLoop\201\202 event loop. This loop is implemented essentially as -follows \201error checking is simplified in this example\202: -) 8 62 PR( FD_ZERO\201&readfds\202; - while\201 XPAAddSelect\201NULL, &readfds\202 \202{ - if\201 sgot = select\201swidth, &readfds, NULL, NULL, NULL\202 >0 \202 - XPAProcessSelect\201&readfds, 0\202; - else - break; - FD_ZERO\201&readfds\202; - })RP( -)0 P(The XPAAddSelect\201\202 routine sets up the select\201\202 readfds variable so -that select\201\202 will wait for I/O on all the active XPA channels. It -returns the number of XPAs that are active; the loop will end when -there are no active XPAs. The standard select\201\202 routine is called to -wait for an external I/O request. Since no timeout struct is passed -in argument 5, the select\201\202 call hangs until there is an external -request. When an external I/O request is made, the XPAProcessSelect\201\202 -routine is executed to process the pending requests. In this routine, -the maxreq value determines how many requests will be processed: if -maxreq <=0, then all currently pending requests will be processed. -Otherwise, up to maxreq requests will be processed. \201The most usual -values for maxreq is 0 to process all requests.\202 - -)0 P(If a program has its own Unix select\201\202 loop, then XPA access points can -be added to it by using a variation of the standard XPAMainLoop: -) 7 39 PR( XPAAddSelect\201xpa, &readfds\202; - [app-specific ...] - if\201 select\201width, &readfds, ...\202 \202{ - XPAProcessSelect\201&readfds, maxreq\202; - [app-specific ...] - FD_ZERO\201&readfds\202; - })RP( -)0 P(XPAAddSelect\201\202 is called before select\201\202 to add the access points. -If the first argument is NULL, then all active XPA access points -are added. Otherwise only the specified access point is added. -After select\201\202 is called, the XPAProcessSelect\201\202 routine can be called -to process XPA requests. Once again, the maxreq value determines how -many requests will be processed: if maxreq <=0, then all currently -pending requests will be processed. Otherwise, up to maxreq requests -will be processed. - -)0 P(XPA access points can be added to -)0 38 1 A(Xt event loops)38 0 TN TL()Ec /AF f D( \201using XtAppMainLoop\201\202\202 -and -)0 39 1 A(Tcl/Tk event loops)39 0 TN TL()Ec /AF f D( \201using vwait and the Tk loop\202. -When using XPA with these event loops, you only need to call: -) 1 44 PR(int XPAXtAddInput\201XtAppContext app, XPA xpa\202)RP( -or -) 1 29 PR( int XPATclAddInput\201XPA xpa\202)RP( -respectively before entering the loop. - - - - -)0 2 57 H(XPAPoll:)WB 117 Sn()WB 23 Sn( execute existing XPA requests)EA()EH( - - -)BD() 3 36 PR( #include <xpa.h> - - int XPAPoll\201int msec, int maxreq\202;)RP()ES( - - -)0 P(It is sometimes desirable to implement a polling loop, i.e., where one -checks for and processes XPA requests without blocking. For this -situation, use the XPAPoll\201\202 routine: -) 1 32 PR( XPAPoll\201int msec, int maxreq\202;)RP( -)0 P(The XPAPoll\201\202 routine will perform XPAAddSelect\201\202 and select\201\202, but with a -timeout specified in millisecs by the msec argument. If one or more -XPA requests are made before the timeout expires, the XPAProcessSelect\201\202 -routine is called to process those requests. The maxreq value determines -how many requests will be processed: if maxreq < 0, then no events are -processed, but instead, the return value indicates the number of events -that are pending. If maxreq == 0, then all currently pending requests -will be processed. Otherwise, up to maxreq requests will be processed. -\201The most usual values for maxreq are 0 to process all requests and 1 -to process one request\202. - - - - -)0 2 58 H(XPAAtExit:)WB 118 Sn()WB 105 Sn( install exit handler)EA()EH( - - -) 3 23 PR()BD( #include <xpa.h> - - void XPAAtExit\201void\202;)ES()RP( - - -)0 P(XPAAtExit\201\202 will install an exit handler using atexit\201\202 to run XPAFree on all -XPA access points. This might be useful in cases where Unix sockets are being -used: if an explicit call to XPAFree\201\202 is not made by the program, the Unix -socket file will not be deleted immediately without an atexit handler. \201NB: this -call should not be made in a Tcl/Tk application. Accessing the Tcl native file -system after Tcl has shut down all file systems causes the Tcl/Tl program to -crash\202. - - - - -)0 2 59 H(XPACleanup:)WB 119 Sn()WB 24 Sn( release reserved XPA memory)EA()EH( - - -) 3 24 PR()BD( #include <xpa.h> - - void XPACleanup\201void\202;)ES()RP( - - -)0 P(When XPA is initialized, it allocates a small amount of memory for the -access control list, temp directory path, and reserved commands. This -memory is found by valgrind to be "still reachable", meaning that "your -program didn't free some memory it could have". Calling the -XPACleanup\201\202 routine before exiting the program will free this memory -and make valgrind happy. - - - - -)0 2 60 H(XPA)WB 120 Sn()WB 25 Sn( Server Callback Macros)EA()EH( - - -)BD() 4 57 PR( #include <xpa.h> - - xpa_class, xpa_name, xpa_method, xpa_cmdfd, xpa_datafd, - xpa_sendian, xpa_cendian)RP()ES( - - -)0 P(Server routines have access to information about the XPA being called via -the following macros \201each of which takes the xpa handle as an argument\202: -) 9 66 PR( macro explanation - ------ ----------- - xpa_class class of this xpa - xpa_name name of this xpa - xpa_method method string \201inet or local connect info\202 - xpa_cmdfd fd of command socket - xpa_datafd fd of data socket - xpa_sendian endian-ness of server \201"little" or "big"\202 - xpa_cendian endian-ness of client \201"little" or "big")RP( -)0 P(The argument to these macros is the call_data pointer that is passed -to the server procedure. This pointer should be type case to XPA -in the server routine: -) 1 27 PR( XPA xpa = \201XPA\202call_data;)RP( - -)0 P(The most important of these macros is xpa_datafd\201\202. A server routine -that sets "fillbuf=false" in receive_mode or send_mode can use this -macro to perform I/O directly to/from the client, rather than using -buf. - -)0 P(The xpa_cendian and xpa_sendian macros can be used together to determine -if the data transferred from the client is byte swapped with respect -to the server. Values for these macros are: "little", "big", or "?". -In order to do a proper conversion, you still need to know the format -of the data \201i.e., byte swapping is dependent on the size of the data -element being converted\202. - - - - -)0 2 61 H(XPA)WB 121 Sn()WB 26 Sn( Race Conditions)EA()EH( - - -Potential XPA race conditions and how to avoid them. - - -)0 P(Currently, there is only one known circumstance in which XPA can get -\201temporarily\202 deadlocked in a race condition: if two or more XPA -servers send messages to one another using an XPA client routine such -as XPASet\201\202, they can deadlock while each waits for the other server -to respond. \201This can happen if the servers call XPAPoll\201\202 with a -time limit, and send messages in between the polling call.\202 The -reason this happens is that both client routines send a string to the -other server to establish the handshake and then wait for the server -response. Since each client is waiting for a response, neither is able -to enter its event-handling loop and respond to the other's -request. This deadlock will continue until one of the timeout periods -expire, at which point an error condition will be triggered and the -timed-out server will return to its event loop. - -)0 P(Starting with version 2.1.6, this rare race condition can be -avoided by setting the XPA_IOCALLSXPA environment variable for servers -that will make client calls. Setting this variable causes all XPA -socket IO calls to process outstanding XPA requests whenever the -primary socket is not ready for IO. This means that a server making a -client call will \201recursively\202 process incoming server requests while -waiting for client completion. It also means that a server callback -routine can handle incoming XPA messages if it makes its own XPA call. -The semi-public routine oldvalue=XPAIOCallsXPA\201newvalue\202 can be used -to turn this behavior off and on temporarily. Passing a 0 will turn -off IO processing, 1 will turn it back on. The old value is returned -by the call. - -)0 P(By default, the XPA_IOCALLSXPA option is turned off, because we judge -that the added code complication and overhead involved will not be -justified by the amount of its use. Moreover, processing XPA requests -within socket IO can lead to non-intuitive results, since incoming -server requests will not necessarily be processed to completion in the -order in which they are received. - -)0 P(Aside from setting XPA_IOCALLSXPA, the simplest way to avoid this race -condition is to multi-process: when you want to send a client message, -simply start a separate process to call the client routine, so that -the server is not stopped. It probably is fastest and easiest to use -fork\201\202 and then have the child call the client routine and exit. But -you also can use either the system\201\202 or popen\201\202 routine to start one -of the command line programs and do the same thing. Alternatively, you -can use XPA's internal launch\201\202 routine instead of system\201\202. Based on -fork\201\202 and exec\201\202, this routine is more secure than system\201\202 because -it does not call /bin/sh. - -)0 P(Starting with version 2.1.5, you also can send an XPAInfo\201\202 message with -the mode string "ack=false". This will cause the client to send a message -to the server and then exit without waiting for any return message from -the server. This UDP-like behavior will avoid the server deadlock when -sending short XPAInfo messages. - - - - - - - - - - - - - - - - - - - - - - - - - - - -)0 P()0 0 1 A(Go to XPA Help Index)0 0 TN TL()Ec /AF f D( - -)0 5 62 H(Last)WB 122 Sn( updated: September 10, 2003)EH( -)WB NL -/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc -DS -/Ba f D /BO 0 D Bs -/UR (oom.html) D -/Ti (Out of Memory) D -/Au () D -/Df f D -/ME [()] D - -0 BO R -()1 Sl()WB 27 Sn( - - -)0 2 63 H(Xpaoom:)WB 124 Sn()WB 123 Sn( What happens when XPA runs out of memory?)EA()EH( - - -)0 2 64 H(Summary)WB 125 Sn()EH( -)0 P(When XPA can't allocate memory, it exits. You can arrange to have it call -longjmp\201\202 instead. - - -)0 2 65 H(Description)WB 126 Sn()EH( -)0 P(When an XPA server or client cannot allocate memory, it will attempt to -output an error message and then exit. If this is not satisfactory \201e.g., -perhaps your program is interactive and can recover from OOM errors\202, you -can tell XPA to call longjmp\201\202 to go to a recovery branch. To pass the -requisite jmp_buf variable to XPA, make the following call: -) 1 24 PR( XPASaveJmp\201void *env\202;)RP( -The value of env is the address of a jmp_buf variable that was previously -passed to setjmp\201\202. For example: -) 9 62 PR( jmp_buf env; - ... - if\201 setjmp\201jmp_buf\202 != 0 \202{ - /* out of memory -- take corrective action, if possible */ - } else { - /* save env for XPA */ - XPASaveJmp\201\201void *\202&jmp_buf\202; - } - // enter main loop ...)RP( - - - - - -)0 P()0 0 1 A(Go to XPA Help Index)0 0 TN TL()Ec /AF f D( - -)0 5 66 H(Last)WB 127 Sn( updated: April 7, 2009)EH( - -)WB NL -/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc -DS -/Ba f D /BO 0 D Bs -/UR (client.html) D -/Ti (XPA Client API) D -/Au () D -/Df f D -/ME [()] D - -0 BO R -()1 Sl()WB 28 Sn( - - -)0 2 67 H(XPAClient:)WB 130 Sn()WB 128 Sn( The XPA Client-side Programming Interface)EA()EH( - - -)0 2 68 H(Summary)WB 131 Sn()EH( -A description of the XPA client-side programming interface. - - -)0 2 69 H(Introduction)WB 132 Sn()WB 129 Sn( to XPA Client Programming)EH()EA( -)0 P(Sending/receiving data to/from an XPA access point is easy: you -generally only need to call the XPAGet\201\202 or XPASet\201\202 subroutines. -) 33 71 PR( #include <xpa.h> - - int )0 31 1 A(XPAGet)31 0 TN TL()Ec /AF f D(\201XPA xpa, - char *template, char *paramlist, char *mode, - char **bufs, size_t *lens, char **names, char **messages, int n\202; - - int )0 32 1 A(XPASet)32 0 TN TL()Ec /AF f D(\201XPA xpa, - char *template, char *paramlist, char *mode, - char *buf, size_t len, char **names, char **messages, int n\202; - - int )0 33 1 A(XPAInfo)33 0 TN TL()Ec /AF f D(\201XPA xpa, - char *template, char *paramlist, char *mode, - char **names, char **messages, int n\202; - - int )0 37 1 A(XPAAccess)37 0 TN TL()Ec /AF f D(\201XPA xpa, - char *template, char *paramlist, char *mode, - char **names, char **messages, int n\202; - - int )0 34 1 A(XPAGetFd)34 0 TN TL()Ec /AF f D(\201XPA xpa, - char *template, char *paramlist, char *mode, - int *fds, char **names, char **messages, int n\202; - - int )0 35 1 A(XPASetFd)35 0 TN TL()Ec /AF f D(\201XPA xpa, - char *template, char *paramlist, char *mode, - int fd, char **names, char **messages, int n\202; - - XPA )0 29 1 A(XPAOpen)29 0 TN TL()Ec /AF f D(\201char *mode\202; - - void )0 30 1 A(XPAClose)30 0 TN TL()Ec /AF f D(\201XPA xpa\202; - - int )0 36 1 A(XPANSLookup)36 0 TN TL()Ec /AF f D(\201XPA xpa,)WR( - char *template, char *type, - char ***classes, char ***names, char ***methods, char ***infos\202;)RP( - -)0 2 70 H(Introduction)WB 133 Sn()EH( - -To use the XPA application programming interface, a software developer -generally will include the xpa.h definitions file: -) 1 18 PR( #include <xpa.h>)RP( -in the software module that defines or accesses an XPA access point and -then will link against the libxpa.a library: -) 1 27 PR( gcc -o foo foo.c libxpa.a)RP( -XPA has been compiled using both C and C++ compilers. -)0 P(Client communication with XPA public access points generally is -accomplished using XPAGet\201\202 or XPASet\201\202 within a program \201or xpaget -and xpaset at the command line\202. Both routines require specification -of the name of the access point. If a )0 3 1 A(template)3 0 TN TL()Ec /AF f D( -is used to specify the access point name \201e.g., "ds9*"\202, then -communication will take place with all servers matching that template. - - - - -)0 2 71 H(XPAGet:)WB 134 Sn()WB 31 Sn( retrieve data from one or more XPA servers)EA()EH( - - -)BD() 6 70 PR( #include <xpa.h> - - int XPAGet\201XPA xpa, - char *template, char *paramlist, char *mode, - char **bufs, size_t *lens, char **names, char **messages, - int n\202;)RP()ES( - - -)0 P(Retrieve data from one or more XPA servers whose class:name identifier -matches the specified template. - -)0 P(A -)0 3 1 A(template)3 0 TN TL()Ec /AF f D( -of the form "class1:name1" is sent to the -XPA name server, which returns a list of at most n matching XPA -servers. A connection is established with each of these servers and -the paramlist string is passed to the server as the data transfer -request is initiated. If an XPA struct is passed to the call, then the -persistent connections are updated as described above. Otherwise, -temporary connections are made to the servers \201which will be closed -when the call completes\202. - -)0 P(The XPAGet\201\202 routine then retrieves data from at most n XPA servers, -places these data into n allocated buffers and places the buffer -pointers in the bufs array. The length of each buffer is stored in the -lens array. A string containing the class:name and ip:port is stored -in the name array. If a given server returned an error or the server -callback sends a message back to the client, then the message will be -stored in the associated element of the messages array. NB: if -specified, the name and messages arrays must be of size n or greater. - -)0 P(The returned message string will be of the form: -) 1 46 PR( XPA$ERROR error-message \201class:name ip:port\202)RP( -or -) 1 42 PR( XPA$MESSAGE message \201class:name ip:port\202)RP( -)0 P(Note that when there is an error stored in an messages entry, the -corresponding bufs and lens entry may or may not be NULL and 0 -\201respectively\202, depending on the particularities of the server. - -)0 P(The return value will contain the actual number of servers that were -processed. This value thus will hold the number of valid entries in -the bufs, lens, names, and messages arrays, and can be used to loop -through these arrays. In names and/or messages is NULL, no information is -passed back in that array. - -)0 P(The bufs, names, and messages arrays should be freed upon completion \201if -they are not NULL\202; - -)0 P(The mode string is of the form: "key1=value1,key2=value2,..." -The following keywords are recognized: -) 4 115 PR( key value default explanation - ------ -------- -------- ----------- - ack true/false true if false, don't wait for ack from server \201after callback completes\202 - doxpa true/false true client processes xpa requests)RP( -)0 P(The ack keyword is not very useful, since the server completes the callback -in order to return the data anyway. It is here for completion \201and perhaps -for future usefulness\202. - -)0 P(Normally, an XPA client will process incoming XPA server requests -while awaiting the completion of the client request. Setting this -variable to "false" will prevent XPA server requests from being -processed by the client. - -)0 P()BD(Example:)ES( -) 25 70 PR( #include <xpa.h> - - #define NXPA 10 - int i, got; - size_t lens[NXPA]; - char *bufs[NXPA]; - char *names[NXPA]; - char *messages[NXPA]; - got = XPAGet\201NULL, "ds9", "file", NULL, bufs, lens, names, messages, - NXPA\202; - for\201i=0; i<got; i++\202{ - if\201 messages[i] == NULL \202{ - /* process buf contents */ - ProcessImage\201bufs[i], ...\202; - free\201bufs[i]\202; - } - else{ - /* error processing */ - fprintf\201stderr, "ERROR: %s \201%s\202\200n", messages[i], names[i]\202; - } - if\201 names[i] \202 - free\201names[i]\202; - if\201 messages[i] \202 - free\201messages[i]\202; - })RP( - - - - -)0 2 72 H(XPASet:)WB 135 Sn()WB 32 Sn( send data to one or more XPA servers)EA()EH( - - -)BD() 6 66 PR( #include <xpa.h> - - int XPASet\201XPA xpa, - char *template, char *paramlist, char *mode, - char *buf, size_t len, char **names, char **messages, - int n\202;)RP()ES( - - -)0 P(Send data to one or more XPA servers whose class:name identifier -matches the specified template. - -)0 P(A -)0 3 1 A(template)3 0 TN TL()Ec /AF f D( -of the form "class1:name1" is sent to the -XPA name server, which returns a list of at most n matching XPA -servers. A connection is established with each of these servers and -the paramlist string is passed to the server as the data transfer -request is initiated. If an XPA struct is passed to the call, the -persistent connections are updated as described above. Otherwise, -temporary connections are made to the servers \201which will be closed -when the call completes\202. - -)0 P(The XPASet\201\202 routine transfers data from buf to the XPA servers. -The length of buf \201in bytes\202 should be placed in the len variable. - -)0 P(A string containing the class:name and ip:port of each of these server -is returned in the name array. If a given server returned an error or -the server callback sends a message back to the client, then the -message will be stored in the associated element of the messages -array. NB: if specified, the name and messages arrays must be of size -n or greater. - -)0 P(The returned message string will be of the form: - -) 1 42 PR( XPA$ERROR [error] \201class:name ip:port\202)RP( -or -) 1 44 PR( XPA$MESSAGE [message] \201class:name ip:port\202)RP( -)0 P(The return value will contain the actual number of servers that were -processed. This value thus will hold the number of valid entries in -the names and messages arrays, and can be used to loop through these -arrays. In names and/or messages is NULL, no information is passed back -in that particular array. - -)0 P(The mode string is of the form: "key1=value1,key2=value2,..." -The following keywords are recognized: -) 5 115 PR( key value default explanation - ------ -------- -------- ----------- - ack true/false true if false, don't wait for ack from server \201after callback completes\202 - verify true/false false send buf from XPASet[Fd] to stdout - doxpa true/false true client processes xpa requests)RP( -)0 P(The ack keyword is useful in cases where one does not want to wait for -the server to complete, e.g. if a lot of processing needs to be done -by the server on the passed data or when the success of the server -operation is not relevant to the client. - -)0 P(Normally, an XPA client will process incoming XPA server requests -while awaiting the completion of the client request. Setting this -variable to "false" will prevent XPA server requests from being -processed by the client. - -)0 P()BD(Example:)ES( -) 21 75 PR( #include <xpa.h> - - #define NXPA 10 - int i, got; - size_t len; - char *buf; - char *names[NXPA]; - char *messages[NXPA]; - ... - [fill buf with data and set len to the length, in bytes, of the data] - ... - /* send data to all access points */ - got = XPASet\201NULL, "ds9", "fits", NULL, buf, len, names, messages, NXPA\202; - /* error processing */ - for\201i=0; i<got; i++\202{ - if\201 messages[i] \202{ - fprintf\201stderr, "ERROR: %s \201%s\202\200n", messages[i], names[i]\202; - } - if\201 names[i] \202 free\201names[i]\202; - if\201 messages[i] \202 free\201messages[i]\202; - })RP( - - - - -)0 2 73 H(XPAInfo:)WB 136 Sn()WB 33 Sn( send short message to one or more XPA servers)EA()EH( - - -)BD() 5 58 PR( #include <xpa.h> - - int XPAInfo\201XPA xpa, - char *template, char *paramlist, char *mode, - char **names, char **messages, int n\202;)RP()ES( - - -)0 P(Send a short paramlist message to one or more XPA servers whose -class:name identifier matches the specified -)0 3 1 A(template)3 0 TN TL()Ec /AF f D(. - -)0 P(A -)0 3 1 A(template)3 0 TN TL()Ec /AF f D( -of the form "class1:name1" is sent to the -XPA name server, which returns a list of at most n matching XPA -servers. A connection is established with each of these servers and -the paramlist string is passed to the server as the data transfer -request is initiated. If an XPA struct is passed to the call, then the -persistent connections are updated as described above. Otherwise, -temporary connections are made to the servers \201which will be closed -when the call completes\202. - -)0 P(The XPAInfo\201\202 routine does not send data from a buf to the XPA -servers. Only the paramlist is sent. The semantics of the paramlist -is not formalized, but at a minimum is should tell the server how to -get more information. For example, it might contain the class:name -of the XPA access point from which the server \201acting as a client\202 -can obtain more info using XPAGet. - -)0 P(A string containing the class:name and ip:port of each server is -returned in the name array. If a given server returned an error or -the server callback sends a message back to the client, then the -message will be stored in the associated element of the messages -array. The returned message string will be of the form: -) 1 48 PR( XPA$ERROR error-message \201class:name ip:port\202)RP( -or -) 1 46 PR( XPA$MESSAGE message \201class:name ip:port\202)RP( -)0 P(The return value will contain the actual number of servers that were -processed. This value thus will hold the number of valid entries in -the names and messages arrays, and can be used to loop through these -arrays. In names and/or messages is NULL, no information is passed back -in that array. - -)0 P(The following keywords are recognized: -) 3 88 PR( key value default explanation - ------ -------- -------- ----------- - ack true/false true if false, don't wait for ack from server)RP( -)0 P(When ack is false, XPAInfo\201\202 will not wait for an error return from the XPA -server. This means, in effect, that XPAInfo will send its paramlist string -to the XPA server and then exit: no information will be sent from the server -to the client. This UDP-like behavior is essential to avoid race -conditions in cases where XPA servers are sending info messages to -other servers. If two servers try to send each other an info message -at the same time and then wait for an ack, a race condition will result and -one or both will time out. - -)0 P()BD(Example:)ES( -) 1 65 PR( \201void\202XPAInfo\201NULL, "IMAGE", "ds9 image", NULL, NULL, NULL, 0\202;)RP( - - - - -)0 2 74 H(XPAGetFd:)WB 137 Sn()WB 34 Sn( retrieve data from one or more XPA servers and write to files)EA()EH( - - -)BD() 5 63 PR( #include <xpa.h> - - int XPAGetFd\201XPA xpa, - char *template, char *paramlist, char *mode, - int *fds, char **names, char **messages, int n\202;)RP()ES( - - -)0 P(Retrieve data from one or more XPA servers whose class:name identifier -matches the specified -)0 3 1 A(template)3 0 TN TL()Ec /AF f D( -and write it to files associated with -one or more standard I/O fds \201i.e, handles returned by open\201\202\202. - -)0 P(A -)0 3 1 A(template)3 0 TN TL()Ec /AF f D( -of the form "class1:name1" is sent to the -XPA name server, which returns a list of at most ABS\201n\202 matching XPA -servers. A connection is established with each of these servers and -the paramlist string is passed to the server as the data transfer -request is initiated. If an XPA struct is passed to the call, then the -persistent connections are updated as described above. Otherwise, -temporary connections are made to the servers \201which will be closed -when the call completes\202. - -)0 P(The XPAGetFd\201\202 routine then retrieves data from the XPA servers, -and write these data to the fds associated with one or more fds -\201i.e., results from open\202. Is n is positive, then there will be n fds -and the data from each server will be sent to a separate fd. If n is -negative, then there is only 1 fd and all data is sent to this single -fd. \201The latter is how xpaget is implemented.\202 - -)0 P(A string containing the class:name and ip:port is stored in the name -array. If a given server returned an error or the server callback -sends a message back to the client, then the message will be stored in -the associated element of the messages array. NB: if specified, the -name and messages arrays must be of size n or greater. - -)0 P(The returned message string will be of the form: -) 1 48 PR( XPA$ERROR error-message \201class:name ip:port\202)RP( -or -) 1 46 PR( XPA$MESSAGE message \201class:name ip:port\202)RP( -)0 P(Note that when there is an error stored in an messages entry, the -corresponding bufs and lens entry may or may not be NULL and 0 -\201respectively\202, depending on the particularities of the server. - -)0 P(The return value will contain the actual number of servers that were -processed. This value thus will hold the number of valid entries in -the bufs, lens, names, and messages arrays, and can be used to loop -through these arrays. In names and/or messages is NULL, no information is -passed back in that array. - -)0 P(The mode string is of the form: "key1=value1,key2=value2,..." -The following keywords are recognized: -) 3 115 PR( key value default explanation - ------ -------- -------- ----------- - ack true/false true if false, don't wait for ack from server \201after callback completes\202)RP( -)0 P(The ack keyword is not very useful, since the server completes the callback -in order to return the data anyway. It is here for completion \201and perhaps -for future usefulness\202. - -)0 P()BD(Example:)ES( -) 19 72 PR( #include <xpa.h> - #define NXPA 10 - int i, got; - int fds[NXPA]; - char *names[NXPA]; - char *messages[NXPA]; - for\201i=0; i<NXPA; i++\202 - fds[i] = open\201...\202; - got = XPAGetFd\201NULL, "ds9", "file", NULL, fds, names, messages, NXPA\202; - for\201i=0; i<got; i++\202{ - if\201 messages[i] != NULL \202{ - /* error processing */ - fprintf\201stderr, "ERROR: %s \201%s\202\200n", messages[i], names[i]\202; - } - if\201 names[i] \202 - free\201names[i]\202; - if\201 messages[i] \202 - free\201messages[i]\202; - })RP( - - - - -)0 2 75 H(XPASetFd:)WB 138 Sn()WB 35 Sn( send data from stdin to one or more XPA servers)EA()EH( - -)ES( -) 5 60 PR( #include <xpa.h> - - int XPASetFd\201XPA xpa, - char *template, char *paramlist, char *mode, - int fd, char **names, char **messages, int n\202)RP()ES( - - -)0 P(Read data from a standard I/O fd and send it to one or more XPA -servers whose class:name identifier matches the specified -)0 3 1 A(template. - -)0 P(A -)0 3 1 A(template)3 0 TN TL()Ec /AF f D( -of the form "class1:name1" is sent to the -XPA name server, which returns a list of at most n matching XPA -servers. A connection is established with each of these servers and -the paramlist string is passed to the server as the data transfer -request is initiated. If an XPA struct is passed to the call, then the -persistent connections are updated as described above. Otherwise, -temporary connections are made to the servers \201which will be closed -when the call completes\202. - -)0 P(The XPASetFd\201\202 routine then reads bytes from the specified fd -until EOF and sends these bytes to the XPA servers. -The final parameter n specifies the maximum number of servers to contact. -A string containing the class:name and ip:port of each server is returned in -the name array. If a given server returned an error, then the error -message will be stored in the associated element of the messages array. -NB: if specified, the name and messages arrays must be of size n or greater. - -)0 P(The return value will contain the actual number of servers that were -processed. This value thus will hold the number of valid entries in -the names and messages arrays, and can be used to loop through these -arrays. In names and/or messages is NULL, no information is passed back -in that array. - -)0 P(The mode string is of the form: "key1=value1,key2=value2,..." -The following keywords are recognized: -) 4 115 PR( key value default explanation - ------ -------- -------- ----------- - ack true/false true if false, don't wait for ack from server \201after callback completes\202 - verify true/false false send buf from XPASet[Fd] to stdout)RP( -)0 P(The ack keyword is useful in cases where one does not want to wait for -the server to complete, e.g. is a lot of processing needs to be done -on the passed data or when the success of the server operation is not -relevant to the client. - -)0 P()BD(Example:)ES( -) 19 71 PR( #include <xpa.h> - - #define NXPA 10 - int i, got; - int fd; - char *names[NXPA]; - char *messages[NXPA]; - fd = open\201...\202; - got = XPASetFd\201NULL, "ds9", "fits", NULL, fd, names, messages, NXPA\202; - for\201i=0; i<got; i++\202{ - if\201 messages[i] != NULL \202{ - /* error processing */ - fprintf\201stderr, "ERROR: %s \201%s\202\200n", messages[i], names[i]\202; - } - if\201 names[i] \202 - free\201names[i]\202; - if\201 messages[i] \202 - free\201messages[i]\202; - })RP( - - - - -)0 2 76 H(XPAOpen:)WB 139 Sn()WB 29 Sn( allocate a persistent client handle)3 0 TN TL()Ec /AF f D()EH( - - -)BD() 3 26 PR( #include <xpa.h> - - XPA XPAOpen\201char *mode\202;)RP()ES( - - -)0 P(XPAOpen\201\202 allocates a persistent XPA struct that can be used with -calls to XPAGet\201\202, XPASet\201\202, XPAInfo\201\202, XPAGetFd\201\202, and -XPASetFd\201\202. Persistence means that a connection to an XPA server is -not closed when one of the above calls is completed but will be -re-used on successive calls. Using XPAOpen\201\202 therefore saves the time -it takes to connect to a server, which could be significant with slow -connections or if there will be a large number of exchanges with a -given access point. The mode argument currently is ignored \201"reserved -for future use"\202. - -)0 P(An XPA struct is returned if XPAOpen\201\202 was successful; otherwise NULL -is returned. This returned struct can be passed as the first argument -to XPAGet\201\202, etc. Those calls will update the list of active XPA -connections. Already connected servers \201from a previous call\202 are -left connected and new servers also will be connected. Old servers -\201from a previous call\202 that are no longer needed are disconnected. -The connected servers will remain connected when the next call to -XPAGet\201\202 is made and connections are once again updated. - -)0 P()BD(Example:)ES( -) 4 22 PR( #include <xpa.h> - - XPA xpa; - xpa = XPAOpen\201NULL\202;)RP( - - - - -)0 2 77 H(XPAClose:)WB 140 Sn()WB 30 Sn( close a persistent XPA client handle)EA()EH( - - -)BD() 3 25 PR( #include <xpa.h> - - void XPAClose\201XPA xpa\202;)RP()ES( - - -)0 P(XPAClose closes the persistent connections associated with this XPA struct -and frees all allocated space. It also closes the open sockets connections -to all XPA servers that were opened using this handle. - -)0 P()BD(Example:)ES( -) 4 18 PR( #include <xpa.h> - - XPA xpa; - XPAClose\201xpa\202;)RP( - - - - -)0 2 78 H(XPANSLookup:)WB 141 Sn()WB 36 Sn( lookup registered XPA access points)EA()EH( - - -)BD() 6 49 PR( #include <xpa.h> - - int XPANSLookup\201XPA xpa, - char *template, char type, - char ***classes, char ***names, - char ***methods, char ***infos\202)RP()ES( - - -)0 P(XPA routines act on a class:name identifier in such a way -that all access points that match the identifier are processed. It is -sometimes desirable to choose specific access points from the -candidates that match the -)0 3 1 A(template)3 0 TN TL()Ec /AF f D(. In order to do this, the -XPANSLookup routine can be called to return a list of matches, so that -specific class:name instances can then be fed to XPAGet\201\202, XPASet\201\202, etc. - -)0 P( The first argument is an optional XPA struct. If non-NULL, the -existing name server connection associated with the specified xpa is -used to query the xpans name server for matching templates. Otherwise, -a new \201temporary\202 connection is established with the name server. - -)0 P(The second argument to XPANSLookup is the class:name -)0 3 1 A(template)3 0 TN TL()Ec /AF f D( -to match. - -)0 P(The third argument for XPANSLookup\201\202 is the type of access and can be -any combination of: -) 5 62 PR( type explanation - ------ ----------- - g xpaget calls can be made on this access point - s xpaset calls can be made on this access point - i xpainfo calls can be made on this access point)RP( -)0 P(The call typically specifies only one of these at a time. - -)0 P(The final arguments are pointers to arrays that will be filled -in and returned by the name server. The name server will allocate and -return arrays filled with the classes, names, and methods of all XPA -access points that match the )0 3 1 A(template)3 0 TN TL()Ec /AF f D( -and have the specified type. Also returned are info strings, which -generally are used internally by the client routines. These can be -ignored \201but the strings must be freed\202. The function returns the -number of matches. The returned value can be used to loop through the -matches: - -)BD(Example:)ES( -) 24 73 PR( #include <xpa.h> - - char **classes; - char **names; - char **methods; - char **infos; - int i, n; - n = XPANSLookup\201NULL, "foo*", "g", &classes, &names, &methods, &infos\202; - for\201i=0; i<n; i++\202{ - [more specific checks on possibilities ...] - [perhaps a call to XPAGet for those that pass, etc. ...] - /* don't forget to free alloc'ed strings when done */ - free\201classes[i]\202; - free\201names[i]\202; - free\201methods[i]\202; - free\201infos[i]\202; - } - /* free up arrays alloc'ed by names server */ - if\201 n > 0 \202{ - free\201classes\202; - free\201names\202; - free\201methods\202; - free\201infos\202; - })RP( -)0 P(The specified -)0 3 1 A(template)3 0 TN TL()Ec /AF f D( -also can be a host:port specification, for example: -) 1 14 PR( myhost:12345)RP( -)0 P(In this case, no connection is made to the name server. Instead, the -call will return one entry such that the ip array contains the ip for -the specified host and the port array contains the port. The class -and name entries are set to the character "?", since the class and -name of the access point are not known. - - - - -)0 2 79 H(XPAAccess:)WB 142 Sn()WB 37 Sn( return XPA access points matching -template \201XPA 2.1 and above\202)EA()EH( - - -)BD() 5 60 PR( #include <xpa.h> - - int XPAAccess\201XPA xpa, - char *template, char *paramlist, char *mode, - char **names, char **messages, int n\202;)RP()ES( - - -)0 P(The XPAAccess routine returns the public access points that match the -specified second argument )0 3 1 A(template)3 0 TN TL()Ec /AF f D( and -have the specified access type. - -)0 P(A -)0 3 1 A(template)3 0 TN TL()Ec /AF f D( -of the form "class1:name1" is sent to the -XPA name server, which returns a list of at most n matching XPA -servers. A connection is established with each of these servers and -the paramlist string is passed to the server as the data transfer -request is initiated. If an XPA struct is passed to the call, then the -persistent connections are updated as described above. Otherwise, -temporary connections are made to the servers \201which will be closed -when the call completes\202. - -)0 P(The XPAAccess\201\202 routine retrieves names from at most n XPA servers -that match the specified template and that were checked for access -using the specified mode. The return string contains both the -class:name and ip:port. If a given server returned an error or the -server callback sends a message back to the client, then the message -will be stored in the associated element of the messages array. -NB: if specified, the name and messages arrays must be of size n or greater. - -)0 P(The returned message string will be of the form: -) 1 46 PR( XPA$ERROR error-message \201class:name ip:port\202)RP( -)0 P(Note that names of matching registered access points are always -returned but may not be valid; it is not sufficient to assume that the -returned number of access points is the number of valid access points. -Rather, it is essential to check the messages array for error -messages. Any string in the messages array is an error message and -indicated that the associated access point is not available. - -)0 P(For example, assume that a server registers a number of access points -but delays entering its event loop. If a call to XPAAccess\201\202 is made -before the event loop is entered, the call will timeout \201after waiting -for the long timeout period\202 and return an error of the form: -) 1 65 PR( XPA$ERROR: timeout waiting for server authentication \201XPA:xpa1\202)RP( -The error means that the XPA access point has been registered but is -not yet available \201because events are not being processed\202. When the -server finally enters its event loop, subsequent calls to XPAAccess\201\202 -will return successfully. - -)0 P(NB: This routine only works with XPA servers built with XPA 2.1.x and later. -Servers with older versions of XPA will return the error message: - - XPA$ERROR invalid xpa command in initialization string - -If you get this error message, then the old server actually is ready -for access, since it got to the point of fielding the query! The -xpaaccess program, for example, ignores this message in order to work -properly with older servers. - -)0 P(The third argument for XPAAccess\201\202 is the type of access and can be -any combination of: -) 5 62 PR( type explanation - ------ ----------- - g xpaget calls can be made on this access point - s xpaset calls can be made on this access point - i xpainfo calls can be made on this access point)RP( -)0 P(The mode string argument is of the form: "key1=value1,key2=value2,..." -The following keywords are recognized: -) 3 115 PR( key value default explanation - ------ -------- -------- ----------- - ack true/false true if false, don't wait for ack from server \201after callback completes\202)RP( -)0 P(The ack keyword is not very useful, since the server completes the callback -in order to return the data anyway. It is here for completion \201and perhaps -for future usefulness\202. - - - - - - - - - - - - - - - - - - - - - - - -)0 P()0 0 1 A(Go to XPA Help Index)0 0 TN TL()Ec /AF f D( - -)0 5 80 H(Last)WB 143 Sn( updated: March 10, 2007)EH( - -)WB NL -/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc -DS -/Ba f D /BO 0 D Bs -/UR (xt.html) D -/Ti (XPA/Xt Interface) D -/Au () D -/Df f D -/ME [()] D - -0 BO R -()1 Sl()WB 38 Sn( - - -)0 2 81 H(XPAXt:)WB 145 Sn()WB 144 Sn( the XPA Interface to Xt \201X Windows\202)EA()EH( - - -)0 2 82 H(Summary)WB 146 Sn()EH( -Describes how XPA access points can be added to X Toolkit \201Xt\202 programs. - - -)0 2 83 H(Description)WB 147 Sn()EH( -)0 P(XPA supports Xt programs: you can call XPANew\201\202, XPACmdNew\201\202, or -XPAInfoNew\201\202 within any C routine to add XPA server callbacks to an Xt -program. Since an Xt program has its own event loop call \201i.e., -XtAppMainLoop\201\202\202, it therefore does not need or want to use the XPA -even loop. Thus, in order to add XPA access points to the standard Xt -event loop, the following routine should be called before entering the -loop: -) 1 46 PR( int XPAXtAddInput\201XtAppContext app, XPA xpa\202)RP( -)0 P(The XPAAddAddInput\201\202 routine will add XPA access points to the Xt event -loop by making calls to the standard XtAppAddInput\201\202 routine. \201If the -XtAppContext argument is NULL, then the alternate XtAddInput\201\202 routine -is used instead.\202 If the xpa argument is NULL, then all active XPA -access points are added to the loop. If xpa is not NULL, then only -the specified access point is added. The latter type of call is used -to add new access points from within a callback, after the program has -entered the XtAppMainLoop\201\202 even loop. - - - - - -)0 P()0 0 1 A(Go to XPA Help Index)0 0 TN TL()Ec /AF f D( - -)0 5 84 H(Last)WB 148 Sn( updated: September 10, 2003)EH( -)WB NL -/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc -DS -/Ba f D /BO 0 D Bs -/UR (tcl.html) D -/Ti (XPA/Tcl Interface) D -/Au () D -/Df f D -/ME [()] D - -0 BO R -()1 Sl()WB 39 Sn( - - -)0 2 85 H(XPATcl:)WB 151 Sn()WB 149 Sn( the XPA Interface to the Tcl/Tk Environment)EA()EH( - - -)0 2 86 H(Summary)WB 152 Sn()EH( - -)0 P(Tcl/Tk programs can act as XPA clients and/or servers using the Tcl -interface to XPA that is contained in the libtclxpa.so shared object. - -)0 2 87 H(Server)WB 153 Sn( Routines)EH( - -) 11 70 PR( set xpa [xpanew class name help sproc sdata smode rproc rdata rmode] - xpafree xpa - set xpa [xpanew class name help iproc idata imode] - set xpa [xpacmdnew class name] - xpacmdadd xpa name help sproc sdata smode rproc rdata rmode - xpacmddel xpa cmd - set val [xparec xpa option] - options: name, class, method, cmdfd, datafd, cmdchan, datachan - xpasetbuf xpa buf len - xpaerror xpa message - xpamessage xpa message)RP( - -)0 2 88 H(Client)WB 154 Sn( Routines)EH( - -) 11 69 PR( set xpa [xpaopen mode] - xpaclose xpa - set got [xpaget xpa template paramlist mode bufs lens names errs n] - set got [xpaget xpa template paramlist mode chans names errs n] - set got [xpaset xpa template paramlist mode buf len names errs n] - set got [xpasetfd xpa template paramlist mode chan names errs n] - set got [xpainfo xpa template paramlist mode names errs n] - # NB: 2.1 calling sequence change - # set got [xpaaccess template type] \2012.0.5\202 - set got [xpaaccess xpa template paramlist mode names errs n] - set got [xpanslookup template type classes names methods])RP( - - -)0 2 89 H(Description)WB 155 Sn()EH( -)0 P(You can call XPANew\201\202, XPACmdNew\201\202, or XPAInfoNew\201\202 within a C -routine to add C-based XPA server callbacks to a TCL/Tk program that -uses a Tcl/Tk event loop \201either vwait\201\202 or the Tk event loop\202; -Such a program does not need or want to use the XPA event loop. -Therefore, in order to add XPA access points to the Tcl/Tk loop, the -following routine should be called beforehand: -) 1 30 PR( int XPATclAddInput\201XPA xpa\202;)RP( -)0 P(Normally, the xpa argument is NULL, meaning that all current XPA -access points are registered with the event loop. However, if a -single XPA access point is to be added \201i.e., after the event loop is -started\202 then the handle of that XPA access point can be passed to -this routine. - -)0 P(The significance of the XPA/TCL interface goes beyond the support for -using XPA inside C code. The interface allows you to write XPA -servers and to make calls to the XPA client interface within the Tcl -environment using the Tcl language directly. The XPA/Tcl -interface can be loaded using the following package command: -) 1 28 PR( package require tclxpa 2.0)RP( -Alternatively, you can load the shared object \201called libtclxpa.so \202 directly: -) 1 30 PR( load .../libtclxpa.so tclxpa)RP( -)0 P(Once the tclxpa package is loaded, you can use Tcl versions of XPA -routines to define XPA servers or make client XPA calls. The -interface for these routines is designed to match the Unix XPA -interface as nearly as possible. Please refer to -)0 15 1 A(XPA Servers)15 0 TN TL()Ec /AF f D( -and -)0 28 1 A(XPA Clients)28 0 TN TL()Ec /AF f D( -for general information about these routines. - -)0 P(The file test.tcl in the XPA source directory gives examples for using the -XPA/Tcl interface. - -)0 P(The following notes describe the minor differences between the interfaces. - -)0 2 90 H(XPANew)WB 156 Sn()WB 150 Sn()EA()EH( -) 1 70 PR()BD( set xpa [xpanew class name help sproc sdata smode rproc rdata rmode])ES()RP( -)0 P(rproc and sproc routines are routines. The calling sequence of the -rproc routine is identical to its C counterpart: -) 1 59 PR( proc rec_cb { xpa client_data paramlist buf len } { ... })RP( -)0 P(The sproc routine, however is slightly different from its C counterpart -because of the difficulty of passing data back from the callback to C: -) 1 51 PR( proc sendcb { xpa client_data paramlist } { ... })RP( -)0 P(Note that the C-based server's char **buf and int *len arguments are -missing from the Tcl callback. This is because we did not know how to -fill buf with data and pass it back to the C routines for communication -with the client. Instead, the Tcl server callback uses the following -routine to set buf and len: -) 1 23 PR( xpasetbuf xpa buf len)RP( -where: -) 5 79 PR( arg explanation - ------ ----------- - xpa the first argument of the server callback - buf the data to be returned to the client - len data length in bytes, \201if absent, use length of the buf object\202)RP( -)0 P(When this routine is called, a copy of buf is saved for transmission to -the client. - -)0 P(The fact that buf is duplicated means that TCL server writers might wish to -perform the I/O directly within the callback, rather than have XPA do it -automatically at the end of the routine. To do this, set: -) 1 15 PR( fillbuf=false)RP( -)0 P(in the xpanew smode and then perform I/O through the Tcl channel -obtained from: -) 1 34 PR( set dchan [xparec $xpa datachan])RP( -)0 P(where: -) 5 79 PR( arg explanation - ------ ----------- - xpa the first argument of the server callback - datachan literal string "datachan" that returns the data channel - len data length in bytes, \201if absent, use length of the buf object\202)RP( -)0 P()BD(NB: datachan and cmdchan are not available under Windows. It is -necessary to use the "raw" equivalents: datafd and cmdfd.)ES( - -)0 P(The same considerations apply to the rproc for receive servers: a copy -of the incoming data is generated to pass to the receive callback. This -copy again can be avoided by using "fillbuf=false" in the rmode and then -reading the incoming data from datachan. - -)0 P(The send and receive callback routines can use the xpaerror and xpamessage -routines to send errors and messages back to the client. If you also -want tcl itself to field an error condition, use the standard return call: -) 1 56 PR( return ?-code c? ?-errorinfo i? ?-errorcode ec? string)RP( -)0 P(See the Tcl man page for more info. - -)0 2 91 H(XPARec)WB 157 Sn()WB 150 Sn()EA()EH( -)0 P(The Tcl xparec procedure supplies server routines with access to information -that is available via macros in the C interface: -) 1 31 PR( set val [xparec xpa <option>])RP( -)0 P(where option is: name, class, method, cmdfd, datafd, cmdchan, -datachan. Note that two additional identifiers, cmdchan and datachan, -have been added to to provide Tcl channels corresponding to datafd and -cmdfd. \201These latter might still be retrieved in Tcl and passed back -to a C routines.\202 An additional option called "version" can be used to -determine the XPA version used to build the Tcl interface. Note that -the standard options require a valid XPA handle, but "version" does -not \201since it simply reports the value of the XPA_VERSION definition -in the XPA source include file\202. - -)0 P()BD(NB: datachan and cmdchan are not available under Windows. It is -necessary to use the "raw" equivalents: datafd and cmdfd.)ES( -) 12 58 PR( macro explanation - ------ ----------- - class class of this xpa - name name of this xpa - method method string \201inet or local connect info\202 - cmdchan Tcl channel of command socket - datachan Tcl channel of data socket - cmdfd fd of command socket - datafd fd of data socket - sendian endian-ness of server \201"little" or "big"\202 - cendian endian-ness of client \201"little" or "big" - version XPA version used to build this code)RP( - -)0 P(Under Windows, the Tcl event handler cannot automatically sense when an -XPA socket is ready for IO \201i.e. Tcl_CreateFileHandler\201\202 is not available -under Windows\202. The Windows Tcl event handler therefore must be awakened -occasionally for check for XPA events. This is done using the standard -Tcl_SetMaxBlockTime\201\202 call. The time parameter is defined in tclloop.c -and is currently set to 1000 microseconds \2011/1000 of a second\202. - -)0 P(The version option can be used to differentiate between source code versions. -It was created to support legacy Tcl code that needs to maintain the 2.0.5 -calling sequence for xpaaccess. You can use a version test such as: -) 12 44 PR( if [catch { xparec "" version } version] { - puts "pre-2.1.0e" - } else { - puts [split $version .] - } -) 7 32 PR( - - - -)0 P()0 0 1 A(Go to XPA Help Index)0 0 TN TL()Ec /AF f D( - -)0 5 92 H(Last)WB 158 Sn( updated: September 10, 2003)EH( -)WB NL -/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc -DS -/Ba f D /BO 0 D Bs -/UR (env.html) D -/Ti (The XPA Environment) D -/Au () D -/Df f D -/ME [()] D - -0 BO R -()1 Sl()WB 40 Sn( - - -)0 2 93 H(XPAEnv:)WB 160 Sn()WB 159 Sn( Environment Variables for XPA Messaging)EA()EH( - - -)0 2 94 H(Summary)WB 161 Sn()EH( -Describes the environment variables which can be used to tailor the overall -XPA environment. - - -)0 2 95 H(Description)WB 162 Sn()EH( -)0 P(The following environment variables are supported by XPA: -)0 DL()0 P()0 DT()BD(XPA_ACL)ES( -)DD( If )EM(XPA_ACL)ES( is )EM(true)ES(, then -host-based )0 41 1 A(XPA Access Control)41 0 TN TL()Ec /AF f D( -is turned on and only specified machines can access specified access -points. If )EM(false)ES(, then access control is turned off and any -machine can access point. The default is turn turn access control on. - -)0 P()0 DT()BD(XPA_ACLFILE)ES( -)DD( If -)0 41 1 A(XPA Access Control)41 0 TN TL()Ec /AF f D( -is turned on, this variable specifies the name of the file containing -access control information for all access points started by this user. -The default file name is: )EM($HOME/acls.xpa)ES(. - -)0 P()0 DT()BD(XPA_CONNECT_TIMEOUT)ES( -)DD( When an XPA server first starts up, it immediately tries to -connect to the XPA name server program \201xpans\202 on the host specified by -the )EM(XPA_NSINET)ES( variable. \201If this connection fails on the -local host, and if xpans can be found in the path, then the name -server is started automatically.\202 Unfortunately, a mis-configured -network can cause this connect attempt to hang for many seconds while -the connect\201\202 system call times out. Therefore, an alarm is started -to interrupt the connect\201\202 call and prevent a long hang. The initial -value of the alarm timeout is 10 seconds, but can be changed by setting -this environment variable. If you want to disable the alarm and allow -the initial connect\201\202 to time out, set the value of this variable to -0. Normally, users would not change this variable at all. - -)0 P()0 DT()BD(XPA_CLIENT_DOXPA)ES( -)DD( Normally, an XPA client \201xpaget, xpaset, etc.\202 will process incoming -XPA server requests while awaiting the completion of the client request. -Setting this variable to "false" will prevent XPA server requests from -being processed by the client. - -)0 P()0 DT()BD(XPA_DEFACL)ES( -)DD( If -)0 41 1 A(XPA Access Control)41 0 TN TL()Ec /AF f D( -is turned on, this variable specifies the default access control -condition for all access points, if the )EM(XPA_ACLFILE)ES( file does -not exist. The default acl is: )EM($host:* $host +)ES(, meaning that -all processes on the host machine have full access to all access points. - -)0 P()0 DT()BD(XPA_HOST)ES( -)DD(For the INET socket method, XPA utilizes the canonical hostname \201as -returned by the gethostname\201\202 routine\202 to construct the IP part of the -method id. Under some circumstances, this might not be a correct choice -of name and IP. For example, if an XPA server is started on a machine -running VPN, you might want to use the VPN name and IP instead of the -canonical host name, so that other machines in the VPN network can -access the server. In this case, you can set the XPA_HOST to be -the VPN name \201if resolvable\202 or, more easily, the VPN IP. - -)0 P()0 DT()BD(XPA_IOCALLSXPA)ES( -)DD( -Setting this variable causes all XPA socket IO calls to process -outstanding XPA requests whenever the primary socket is not ready for -IO. This means that a server making a client call will \201recursively\202 -process incoming server requests while waiting for client completion. -This inter-IO XPA processing avoids a rare -)0 26 1 A(XPA Race Condition)26 0 TN TL()Ec /AF f D(: two or more -XPA servers sending messages to one another using an XPA client -routine such as XPASet\201\202 can deadlock while each waits for the other -server to respond. This can happen, for example, if the servers call -XPAPoll\201\202 with a time limit, and send messages in between the polling call. - -)0 P(By default, this option is turned off, because we judge that the added -code complication and overhead involved will not be justified by the -amount of its use. Moreover, processing XPA requests within socket IO -can lead to non-intuitive results, since incoming server requests will -not necessarily be processed to completion in the order in which they -are received. - -)0 P()0 DT()BD(XPA_LOGNAME)ES( -)DD(XPA preferentially uses the de facto standard environment variable -LOGNAME to determine the username when registering an access point in -the name server. If this environment variable has been used for -something other than the actual user name \201such as a log file name\202, -unexpected results can ensue. In such cases, use the XPA_LOGNAME -variable to set the user name. \201If neither exists, then getpwuid\201geteuid\201\202\202 -is used as a last resort\202. - -)0 P()0 DT()BD(XPA_LONG_TIMEOUT)ES( -)DD( XPA is designed to allow data to be sent from one process to -another over a long period of time \201i.e., a program that generates -image data sends that data to an image display, but slowly\202 but it -also seeks to prevent hangs. This is done by supporting 2 timeout -periods: a )EM(short)ES( timeout for protocol communication -and a )EM(long)ES( for data communication. -)0 P(The )EM(XPA_LONG_TIMEOUT)ES( variable controls the )EM(long)ES( -timeout and is used to prevent hangs in cases where communication -between the client and server that is )EM(not)ES( controlled by the -XPA interface itself. Transfer of data between client and server, or a -client's wait for a status message after completion of the server -callback, are two examples of this sort of communication. By default, -the )EM(long)ES( timeout is set to 180 seconds. -Setting the value to -1 will disable )EM(long)ES( timeouts and allow -an infinite amount of time. - -)0 P()0 DT()BD(XPA_MAXHOSTS)ES( -)DD( The maximum number of access points that the programs -)EM(xpaset)ES(, )EM(xpaget)ES(, and )EM(xpainfo)ES( will -communicate with at one time. The default is 64, meaning, for -example, that the )EM(xpaset)ES( program will not send a message -to more than 100 access points at one time and )EM(xpaget)ES( will -not retrieve from more than 100 access points at one time. - -)0 P()0 DT()BD(XPA_METHOD)ES( -)DD(Determines the socket connection method used by this session of XPA. -The choices are: )EM(inet)ES( \201to use INET or Internet-based -sockets\202, )EM(localhost)ES( \201to use the machines localhost inet -socket\202, or )EM(local \201unix\202)ES( \201to use UNIX sockets\202. The default -is )EM(INET)ES(. Using the )EM(inet)ES( method will allow access -from other machines \201subject to access controls\202 but using -)EM(localhost)ES( or )EM(local)ES( will not. Localhost is most useful -for private access and when the machine in question is not connected -to the Internet. The unix method also can be used for private access -and non-Internet connections \201Unix platforms only\202. -)0 P(Once defined, the first registration of an XPA access point will -ensure that an instance of the -)0 14 1 A(XPA Name Server \201xpans\202)14 0 TN TL()Ec /AF f D( -is running that handles that connection method. All new access points -will use the new connection method but existing access points will use -the original method. - -)0 P()0 DT()BD(XPA_NSINET)ES( -)DD( For the )EM(inet)ES( method of socket connection, this variable -specifies the host and port on which the -)0 14 1 A(XPA Name Server \201xpans\202)14 0 TN TL()Ec /AF f D( -is listens for new access points. The default is )EM($host:$port)ES(, -meaning that the default XPA port \20114285\202 on the current machine -\201as returned by gethostname\201\202\202 is used. If several machines were all -accessing the same XPA access points, you would use this variable to -specify that they all use the same name server to find out about these -access points. For example, a value of )EM(myhost:$port)ES( would -mean that the xpans name server is running on myhost and uses the -default port 12345. All machines would then get the XPA access points -registered with that name server, subject to access controls. -)0 P(The port used by xpans to register its XPA access point normally is -taken to be one greater than the port on which it receives new access -points from XPA servers. You can specify a specific access point port -using the syntax machine:port1,port2, i.e., the access point port is -specified after the comma. For example, $host:12345,23456 will listen -for new access ports on 12345 and will accept XPA commands on 23456. - -)0 P()0 DT()BD(XPA_NSREGISTER)ES( -)DD(This boolean variable specifies whether a server registers its XPA -access point with the specified xpans name server. The default is -)EM(true)ES(. If set to )EM(false)ES(, the access point still is -set up but it is not registered with xpans and therefore cannot be -accessed by name. \201It can be accessed by method, if the latter is -known.\202 Note that an access point can be registered later on \201using --remote or -proxy, for example\202. This variable mainly is useful in -cases where the Internet configuration is broken \201so that registration -causes a DNS hang\202 but you still wish to and can use the server with a -remote xpans \201e.g., ds9's Virtual Observatory capability\202. - -)0 P()0 DT()BD(XPA_NSUNIX)ES( -)DD( For the )EM(local)ES( method of socket connection, this variable -specifies the name of the Unix file that will be used to access the -)0 14 1 A(XPA Name Server \201xpans\202)14 0 TN TL()Ec /AF f D(. The default is -)EM(xpans_unix)ES(. This variable is not usually needed. Note that -is the )EM(local)ES( socket method is used, then remote machines will -not be able to access the xpans name server or the registered XPA access -points. - -)0 P()0 DT()BD(XPA_NSUSERS)ES( -)DD(This variable specifies whether other users' access points will be -returned by the -)0 14 1 A(XPA Name Server \201xpans\202)14 0 TN TL()Ec /AF f D( for use by -)EM(xpaget)ES(, )EM(xpaset)ES(, etc. -Generally speaking, it is sufficient to run one xpans name server per -machine and register the access points for all users with that xpans. -This means, for example, that if you request information from -ds9 by running: -) 1 21 PR( xpaget ds9 colormap)RP( -you might get information from your own ds9 as well as -from another user running ds9 on the same machine. The -)EM(XPA_NSUSERS)ES( variable controls whether you want such access -to the access points of other users. -By default, only your own access points are returned, so -that, in the example above, you would only get the colormap information -from the ds9 you registered. If, however, you had set the value of the -)EM(XPA_NSUSERS)ES( variable to )EM(eric,fred)ES(, then you would be -able to communicate with both eric and fred's access points. Note that -this variable can be overridden using the )EM(-u)ES( switch on the -)EM(xpaget)ES(, )EM(xpaset)ES(, and )EM(xpainfo)ES( programs. - -)0 P()0 DT()BD(XPA_PORT)ES( -)DD( -A semi-colon delimited list of user specified ports to use for specific -XPA access points. The format is each specification is: -) 1 28 PR(class:template port1[ port2])RP( -where )BD(port1)ES( is the main \201command\202 port for the access point and -)BD(port2)ES( is the \201secondary\202 data port. If port2 is not specified, -it defaults to a value of 0 \201meaning the system assigns the port\202. - -)0 P(Specification of specific ports is useful, for example, when a machine -outside a firewall needs to communicate with a machine inside a -firewall. In such a case, the firewall should be configured to allow -socket connections to both the command and data port from the outside -machine, and the inside XPA program should be started up with the -outside machine in its ACL list. Then, when the inside program is -started with specified ports, outside XPA programs can use -"machine:port" to contact the inside access points, instead of the -access point names. That is, the machine outside the firewall does not -need access to the XPA name server: -) 2 62 PR(export XPA_PORT="DS9:ds9 12345 12346" # on machine "inside" -cat foo.fits | xpaset inside:12345 fits # on machine "outside")RP( -Note that 2 ports are required for full XPA communication and -therefore 2 ports should be specified to go through a firewall. The -second port assignment is not important if you simply are assigning -the command port in order to communicate commands with a known -port \201e.g., to bypass the xpans name server\202. If only one \201command\202 -port is specified, the system will negotiate a random data port and -everything will work properly. - -)0 P(This support is somewhat experimental. If you run into problems, please -let us know. - -)0 P()0 DT()BD(XPA_PORTFILE)ES( -)DD( -A list of user-specified port to use for specific xpa access points. -The format of the file is: -) 1 28 PR(class:template port1 [port2])RP( -where )BD(port1)ES( is the main port for the access point and -)BD(port2)ES( is the data port. If port2 is not specified, it defaults -to a value of 0 \201meaning the system assigns the port\202. See -)BD(XPA_PORT)ES( above for an explanation of user-specified ports. - -)0 P()0 DT()BD(XPA_SHORT_TIMEOUT)ES( -)DD( XPA is designed to allow data to be sent from one process to -another over a long period of time \201i.e., a program that generates -image data sends that data to an image display, but slowly\202 but it -also seeks to prevent hangs. This is done by supporting 2 timeout -periods: a )EM(short)ES( timeout for protocol communication -and a )EM(long)ES( for data communication. -)0 P(The )EM(XPA_SHORT_TIMEOUT)ES( variable -controls the )EM(short)ES( timeout and is used to prevent hangs -in cases where the XPA protocol requires internal communication between -the client and server that is controlled by the XPA interface -itself. Authentication is an example of this sort of communication, -as is the establishment of a data channel between the two processes. -The default value for the )EM(short)ES( is 30 seconds \201which is -a pretty long time, actually\202. Setting the value to -1 will disable -)EM(short)ES( timeouts and allow an infinite amount of time. - -)0 P()0 DT()BD(XPA_SIGUSR1)ES( -)DD( If the value of this variable is )EM(true)ES(, then XPA will -catch SIGUSR1 signals when performing an I/O operation in order to -curtail that operation. This facility allows users to send a SIGUSR1 -signal to an XPA server if a client is hanging up the server by -sending or receiving data too slowly \201timeouts also can be used -- see -above\202. When enabled in this way, the SIGUSR1 signal is ignored at all other -times, so that its safe to send the signal at any time. If the -variable is set to )EM(false)ES(, then SIGUSR1 is not used at -all. Turning off SIGUSR1 would be desired in cases there the program -uses SIGUSR1 for some other reason and does not want XPA interfering. -The default is to use the signal. - -)0 P()0 DT()BD(XPA_TIMESTAMP_ERRORS)ES( -)DD( If )EM(XPA_TIMESTAMP_ERRORS)ES( is )EM(true)ES(, then error -messages will include a date/time string. This can be useful when -XPA errors are being saved in an error log \201e.g. Web/CGI use\202. The -default is false.)LD( - -)0 P()0 DT()BD(XPA_TMPDIR)ES( -)DD( This variable specifies the directory into which XPA logs, Unix -socket files \201when )EM(XPA_METHOD)ES( is )EM(local)ES(\202, etc. are -stored. The default is )EM(/tmp/.xpa)ES(. - -)0 P()0 DT()BD(XPA_VERBOSITY)ES( -)DD( Specify the verbosity level of error messages. If the value is -set to )EM(0)ES(, )EM(false)ES(, or )EM(off)ES(, then no error -messages are printed to stderr. If the value is )EM(1)ES(, then -important XPA error messages will be output. If the value is -set to )EM(2)ES(, XPA warnings about out-of-sync messages will also -be output. These latter almost always can be ignored. - -)0 P()0 DT()BD(XPA_VERSIONCHECK)ES( -)DD( Specify whether a new access point should check its major and minor XPA -version number against the version used by the xpans name server at -registration time. The default is )EM(true)ES(. When checking is -performed, a warning is issued if the server major version is found to -be greater than the xpans version. Note that the check is performed -both by the XPA server and by the xpans process and warnings will be -issued by each. Also, instead of the values of )EM(true)ES( or -)EM(false)ES(, you can give this variable an integer value n. In this -case, each version checking process \201i.e., the XPA-enabled server or -xpans\202 will print out a maximum of n warning messages \201after which -version warnings are silently swallowed\202. -)0 P(In general, it is a bad idea to run an XPA-enabled server program -using a version of XPA newer than the basic xpaset, xpaget, xpaaccess, -xpans programs. This sort of mismatch usually will not work due to -protocol changes. - - - - - -)0 P()0 0 1 A(Go to XPA Help Index)0 0 TN TL()Ec /AF f D( - -)0 5 96 H(Last)WB 163 Sn( updated: December 23, 2009)EH( - -)WB NL -/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc -DS -/Ba f D /BO 0 D Bs -/UR (acl.html) D -/Ti (XPA Access Control) D -/Au () D -/Df f D -/ME [()] D - -0 BO R -()1 Sl()WB 41 Sn( - - -)0 2 97 H(XPAAcl:)WB 165 Sn()WB 164 Sn( Access Control for XPA Messaging)EA()EH( - - -)0 2 98 H(Summary)WB 166 Sn()EH( -)0 P(XPA supports host-based access control for each XPA access point. You -can enable/disable access control using the XPA_ACL environment -variable. You can specify access to specific XPA access points for -specific machines using the XPA_DEFACL and XPA_ACLFILE environment -variables. By default, an XPA access point is accessible only to -processes running on the same machine \201same as X Windows\202. - - -)0 2 99 H(Description)WB 167 Sn()EH( -)0 P(When INET sockets are in use \201the default, as specified by the -)EM(XPA_METHOD)ES( environment variable\202, XPA supports a host-based -access control mechanism for individual access points. This mean that -access can be specified for get, set, or info operations for each -access point on a machine by machine basis. For LOCAL sockets, access -is restricted \201by definition\202 to the host machine. - -)0 P(XPA access control is enabled by default, but can be turned off by -setting the )EM(XPA_ACL)ES( environment variable to )EM(false)ES(. -In this case, any process can access any XPA server. - -)0 P(Assuming that access control is turned on, the ACL for an individual -XPA access point is set up when that access point is registered -\201although it can be changed later on; see below\202. This can be done in -one of two ways: - -Firstly, the )EM(XPA_ACLFILE)ES( environment variable can defined to -point to a file of access controls for individual access points. The format -of this file is: -) 1 18 PR( class:name ip acl)RP( -The first argument is a template that specifies the class:name of the -access point covered by this ACL. See -)0 3 1 A(XPA Access Points and Templates)3 0 TN TL()Ec /AF f D( -for more information about xpa templates. - -)0 P(The second argument is the IP address \201in human-readable format\202 of -the machine which is being given access. This argument can be -)EM(*)ES( to match all IP addresses. It also can be )EM($host)ES( -to match the IP address of the current host. - -)0 P(The third argument is a string combination of )EM(s)ES(, )EM(g)ES(, -or )EM(i)ES( to allow )EM(xpaset)ES(, )EM(xpaget)ES(, or -)EM(xpainfo)ES( access respectively. The ACL argument can be -)EM(+)ES( to give )EM(sgi)ES( access or it can be )EM(-)ES( to turn -off all access. - -)0 P(For example, -) 3 21 PR( *:xpa1 somehost sg - *:xpa1 myhost + - * * g)RP( -will allow processes on the machine somehost to make xpaget and xpaset calls, -allow processes on myhost to make any call, and allow all other hosts to -make xpaget \201but not xpaset\202 calls. - -Secondly, if the )EM(XPA_ACLFILE)ES( does not exist, then a single -default value for all access points can be specified using the -)EM(XPA_DEFACL)ES( environment variable. The default value for this -variable is: -) 1 34 PR( #define XPA_DEFACL "*:* $host +")RP( -meaning that all access points are fully accessible to all processes -on the current host. Thus, in the absence of any ACL environment variables, -processes on the current host have full access to all access points -created on that host. This parallels the X11 xhost mechanism. - -)0 P(Access to an individual XPA access point can be changed using the -acl -parameter for that access point. For example: -) 1 34 PR( xpaset -p xpa1 -acl "somehost -")RP( -will turn off all access control for somehost to the xpa1 access point, while: -) 1 38 PR( xpaset -p XPA:xpa1 -acl "beberly gs")RP( -will give beberly xpaget and xpaset access to the access point whose -class is XPA and whose name is xpa1. -)0 P(Similarly, the current ACL for a given access point can be retrieved using: -) 1 18 PR( xpaget xpa1 -acl)RP( -Of course, you must have xpaget access to this XPA access point to -retrieve its ACL. - -)0 P(Note that the XPA access points registered in the )EM(xpans)ES( -program also behave according to the ACL rules. That is, you cannot -use xpaget to view the access points registered with xpans unless -you have the proper ACL. - -)0 P(Note also when a client request is made to an XPA server, the access -control is checked when the initial connection is established. This -access in effect at this time remains in effect so long as the client -connection is maintained, regardless of whether the access fro that -XPA is changed later on. - -)0 P(We recognize that host-based access control is only relatively secure -and will consider more stringent security \201e.g., private key\202 in the -future if the community requires such support. - - - - - -)0 P()0 0 1 A(Go to XPA Help Index)0 0 TN TL()Ec /AF f D( - -)0 5 100 H(Last)WB 168 Sn( updated: September 10, 2003)EH( - -)WB NL -/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc -DS -/Ba f D /BO 0 D Bs -/UR (changelog.html) D -/Ti (XPA ChangeLog) D -/Au () D -/Df f D -/ME [()] D - -0 BO R -()1 Sl()WB 42 Sn( -)0 2 101 H(XPA)WB 169 Sn( ChangeLog)EH( - -)0 P(This ChangeLog covers the XPA 2 implementation. It will be updated -as we continue to develop and improve XPA. The up-to-date version can be -found )R1 2 A(here)EA(. - -)0 2 102 H()WB 170 Sn( Public Release 2.1.15 \201July 23, 2013\202)EH( -)UL()0 P()-1 LI( Added support for large data transfers -)0 P()-1 LI( XPAGet and XPASet now pass size_t instead of int for lengths -)0 P()-1 LI( Send and receive callbacks now pass size_t instead of int for lengths -)0 P()-1 LI( Port to mingw \201Windows\202)LU( - - -)0 2 103 H()WB 171 Sn( Public Release 2.1.14 \201June 7, 2012\202)EH( -)UL()0 P()-1 LI( Fixed several memory leaks in the Tcl wrappers \201tcl.c\202. -)0 P()-1 LI( Use Tcl stubs library for linking shared Tcl, if available.)LU( - -)0 2 104 H()WB 172 Sn( Public Release 2.1.13 \201April 14, 2011\202)EH( -)UL()0 P()-1 LI( An atexit handler is no longer installed automatically \201it crashes -Tcl 8.5.8 applications\202. Call XPAAtExit\201void\202 to install the handler. -)0 P()-1 LI( Removed permission checking from Find\201\202 on cygwin systems. This was broken -by Windows 7. -)0 P()-1 LI( Removed addition of -no-cpp-precomp flag from gcc 4.2 and beyond \201Mac\202.)LU( - -)0 2 105 H()WB 173 Sn( Public Release 2.1.12 \201January 26, 2010\202)EH( -)UL()0 P()-1 LI( Added XPA_HOST environment variable to allow users to specify -the hostname \201and hence, ip\202 component of the INET method id. This is -useful, for example, if you want to register an access point using a -VPN-generated IP instead of the canonical IP. -)0 P()-1 LI( Fix typo in Tcl binding to xpainfo causing a crash after 2 invocations.)LU( - -)0 2 106 H()WB 174 Sn( Public Release 2.1.11 \201December 7, 2009\202)EH( -)UL()0 P()-1 LI( Generalized XPANSKeepAlive\201\202 to send messages to xpans, proxy xpans, or -both. The default is to send just to proxies \201e.g. chandra-ed\202. -)0 P()-1 LI( Changed XPANSKeepAlive\201\202 to send an in-band new-line char to -xpans, changed xpans to handle an in-band new-line as a keep-alive -message. Necessitated by Cisco routers that clear the URG flag in -a TCP packet, breaking OOB data transfer for the whole Internet, as -well as the OOB-based keep-alive implemented in xpans. -)0 P()-1 LI( In xpans, print warning when the keep-alive option switch is used. -)0 P()-1 LI( Port to mingw \201thanks to B.Schoenhammer\202 -)0 P()-1 LI( Change OOB character sent by xpans keepalive to a space, trying to working around cisco routers that force OOB data into the inbound stream. -)0 P()-1 LI( fix gcc fprintf warning in xpans.c)LU( - -)0 2 107 H()WB 175 Sn( Public Release 2.1.10 \201September 1, 2009\202)EH( -)UL()0 P()-1 LI( Update mklib and configure.ac to support 64-bit builds on Macs. -)0 P()-1 LI( Fixed bug in XPAAccess\201\202 in which the returned names could have an extra -\201bogus\202 character when the target is an explicit ip:port or local socket file. -)0 P()-1 LI( Add setjmp/longjmp support to xalloc. -)0 P()-1 LI( Add XPASaveJmp\201void *env\202 as a high-level interface to xalloc_savejmp\201\202;)LU( - -)0 2 108 H()WB 176 Sn( Internal Release 2.1.9)EH( -)UL()0 P()-1 LI( Fixed a bug that prevented an access point starting with a number -from being recognized peoperly. NB: a pure number still signifies a -port on the current machine. Also num:num signifies ip:port, where ip -can be a pure hex value or the canonical form vvv.xxx.yyy.zzz. -)0 P()-1 LI( Modified internal Launch\201\202 routine to use posix_spawn\201\202, if necessary. -This is required for OS X 10.5 \201leopard\202, which frowns upon use of fork\201\202 -and exec\201\202. Also modified zprocess routines to use Launch\201\202. -)0 P()-1 LI( Added XPASetFree\201xpa, void \201*myfree\202\201void *\202\202 routine to allow callbacks -to specify a free routine other than malloc free \201e.g. Perl garbage collection\202. -)0 P()-1 LI( XPACmdAdd\201\202 now checks to ensure that it was passed an XPA struct created -by XPACmdNew\201\202. -)0 P()-1 LI( Change launch.h to xlaunch.h to avoid conflict with OS X.)LU( - -)0 2 109 H()WB 177 Sn( Public Release 2.1.8 \2011 November 2007\202)EH( -)UL()0 P()-1 LI( A public release to complete current XPA development work.)LU( - -)0 2 110 H()WB 178 Sn( Patch Release 2.1.7b[1,2] \201Feb 22, 2006; March 8, 2007\202)EH( -)UL( -)0 P()-1 LI( Added a convenience null to the end of the buffers returned by XPAGet. - -)0 P()-1 LI( Added code to avoid calling atexit routine if a fork'ed child -calls exit\201\202 instead of _exit\201\202. - -)0 P()-1 LI( Added XPA_CLIENT_DOXPA environment variable to turn off client -processing of xpa server requests. - -)0 P()-1 LI( Added --version to xpaset, xpaget, xpainfo, xpaaccess, xpans to -display XPA version and exit. - -)0 P()-1 LI( Added support for integrating XPA into a Gtk loop. - -)0 P()-1 LI( xpaaccess now returns its answer in the error code as well as to stdout -\201without the -n switch, it returns 1 for a match, with the -n switch, -the number of matches is returned\202. - -)0 P()-1 LI( Fixed bug which prevented xpans from being started up automatically -by an xpa server if its pathname contained a space character. - -)0 P()-1 LI( Fixed bug in MINGW port of xpans in which an XPA server that -terminated via an interrupt was not being properly removed from the -list of registered access points. - -)0 P()-1 LI( Added XPA_LOGNAME to override LOGNAME when registering username - -)0 P()-1 LI( Upgraded swish-e indexing code to 2.4.5. -)LU( - -)0 2 111 H()WB 179 Sn( Patch Release 2.1.6 \2014 May 2005\202)EH( -)UL( -)0 P()-1 LI( Added -P switch to xpans to enable experimental proxy support -\201default is disabled\202. An argument of 1 processes proxy requests in -the same thread as xpans requests, while an argument of 2 processes -proxy requests in a separate thread. \201The latter is recommended to -avoid xpans timeouts, since xpa callback processing can take a long -time.\202 - -)0 P( -)-1 LI( Added ability to build shared libraries \201done automatically with -configure --enable-shared\202 with compilers other than gcc. - -)0 P()-1 LI( Made yet another attempt to build shared libraries under OS X. - -)0 P()-1 LI( Fixed a server bug in Tcl support under Windows \201introduced early -in 2.1.6\202 which caused an occasional SEGV. - -)0 P()-1 LI( Fixed race condition in cases where 2 or more servers makes client calls -to one another. - -)0 P()-1 LI( Fixed bug in the XPA handler routine in which an access point was -turned off if an error occurred in that routine \201as opposed to the -user-defined callback routine\202. - -)0 P()-1 LI( Fixed race condition when "ack=false" flag \201or -n\202 is used with XPASet\201\202 -\201or xpaset\202. - -)0 P()-1 LI( Added defensive code to XPA handler to ensure that the passed XPA record -is valid. - -)0 P()-1 LI( Tcl/XPA servers such as ds9 were not turning off select\201\202 on the -xpa channels inside an xpa callback, as required. This is now fixed. - -)0 P()-1 LI( Added timestamps to most server and client error messages if the -XPA_TIMESTAMP_ERRORS variable is set. This is useful when XPA errors are -being logged in an error log \201e.g. Web/CGI use\202. - -)0 P()-1 LI( Generated PostScript and PDF versions of the help pages. - -)0 P()-1 LI( Moved OPTIONS section before \201often-lengthy\202 DESCRIPTION section in -man pages. - -)0 P()-1 LI( All memory allocation now performs error checking on the result. - -)0 P()-1 LI( Removed some compiler warnings that surfaced when using gcc -O2. - -)0 P()-1 LI( Updated configure.ac to better support Tcl in Panther with Apple -Frameworks. -)LU( - -)0 2 112 H()WB 180 Sn( Patch Release 2.1.5 \20112 January 2004\202)EH( -)UL( -)0 P()-1 LI( Fixed bug in XPAPoll\201\202. Erroneously, no requests were being -processed when maxreq==0. Now, all pending events are processed, as -per the documentation. - -)0 P()-1 LI( Added ack=false to XPAInfo\201\202 \201and corresponding -n to xpainfo\202 -so that client does not wait for a response from the server. This is -essential in cases where XPA servers wish to send info messages to -one another without causing a race condition. - -)0 P()-1 LI( Generated man pages from the html pages. These are installed -automatically at build time. - -)0 P()-1 LI( The xpans program with Unix sockets now uses a lock file to signal -that it is running, in order to avoid a potential \201but rare\202 race -condition at startup. - -)0 P()-1 LI( Code that calls Unix-type bind\201\202 now manipulate umask\201\202 to ensure that -all users have write permissions to the socket file \201OS X apparently uses -these permissions while previous platforms ignore them\202. - -)0 P()-1 LI( Configure now checks for socklen_t type \201OS X does not define it\202. - -)0 P( -)-1 LI( Added an atexit function to run XPAFree. The aim here is to delete Unix -socket files on exiting. - -)0 P()-1 LI( Under Windows, the Tcl event-handling code now blocks for 1/1000 of a -second instead of not blocking at all \201which inadvertently used 100% of cpu\202. - -)0 P()-1 LI( Upgraded Tcl/Tk support to 8.4. - -)0 P()-1 LI( Made another round of checks was made through all instances of -strcat, strcpy, etc. to look for potential buffer overflows. Changed -all instances of sprintf\201\202 to snprintf\201\202. - -)0 P()-1 LI( Class and name designators are now limited to 1024 characters, for -no particular reason. - -)0 P()-1 LI( The obsolete $SAORD_BIN variable was being added to the path when -searching for xpans. This is no longer the case. - -)0 P()-1 LI( Fixed non-ANSI compiler errors in both xpa.c and xpans.c. - -)0 P()-1 LI( Fixed minor problems to support compilation with g++. - -)0 P()-1 LI( Ported to Intel icc and gcc 3.3 compilers. - -)0 P()-1 LI( Upgraded autoconf to 2.57. Included in this upgrade is a change that -makes gcc the default compiler \201use "configure CC=cc" to change this\202. -Also, by default, the Tcl shared object is no longer automatically built -if the Tcl libraries are used. Use the --enable-tclshlib switch in -configure to enable this feature. - -)0 P()-1 LI( Changed license from public domain to GNU GPL. -)LU( - -)0 2 113 H()WB 181 Sn( Patch Release 2.1.4 \20124 March 2003\202)EH( -)UL( -)0 P()-1 LI( Made inet method unique, even when hosts are behind a firewall using -the same ports \201on different local machines\202. - -)0 P()-1 LI( The initial connection from an xpa server to a local xpans now is -controlled by a timeout \201default 5 sec, controlled by XPA_CONNECT_TIMEOUT -variable\202. This should prevent a hang on connect\201\202 if the network -is not set up correctly. - -)0 P()-1 LI( Fixed rare race condition when an XPA server callback performed its own -XPAGet or XPASet call to another XPA server. - -)0 P()-1 LI( Use POSIX O_NONBLOCK for non-blocking I/O in fcntl call if it -exists, instead of O_NDELAY. -)LU( - -)0 2 114 H()WB 182 Sn( Patch Release 2.1.3 \20126 September 2002\202)EH( -)UL( -)0 P()-1 LI( Added -k [sec] switch to xpans to support sending one-byte keepalive -messages from xpans to registered xpa servers. - -)0 P()-1 LI( Added XPANSKeepAlive routine \201and Tcl equivalent\202 to allow -xpa servers to send a one-byte keepalive message to xpans. -)LU( - -)0 2 115 H()WB 183 Sn( Patch Release 2.1.2 \20118 July 2002\202)EH( -)UL( -)0 P()-1 LI( The "-help" reserved command now also displays the XPA version, if -no explicit sub-commands are specified. - -)0 P()-1 LI( Change internal state of xpans proxy to save ip:port value of a -server behind a NAT firewall. This is required to give some hope of -distinguishing multiple instances of ds9 running behind NAT. -)LU( - -)0 2 116 H()WB 184 Sn( Patch Release 2.1.1 \20120 June 2002\202)EH( -)UL( -)0 P()-1 LI( Added a version check between xpans and an access point, -performed when it gets registered by an XPA server. If the server -has a version greater than the xpans version, a warning is issued by -both programs. - -)0 P()-1 LI( Added a boolean XPA_NSREGISTER environment variable to allow an -XPA server to skip xpans registration. The default is to register with -the name server. If set to "false", the access point still is set up -but it is not registered with an xpans. It can be registered later on -\201using -remote or -proxy, for example\202. - -)0 P()-1 LI( Fixed bug in which xpans was still listening on any interface when -XPA_METHOD was localhost \201instead of just listening on localhost\202. -)LU( - -)0 2 117 H()WB 185 Sn( Public Release 2.1.0 \20122 April 2002\202)EH( - -)0 P(New features include: - -)UL()0 P()-1 LI( Support for proxy access to XPA servers \201e.g. ds9\202 situated -behind a firewall \201useful for NVO-type applications\202. - -)0 P()-1 LI( Improved support for allowing remote machines access rights to the -XPA access points \201useful for NVO-type applications\202. - -)0 P()-1 LI( Ability for XPAAccess\201\202 routine and xpaaccess program to contact XPA - directly. - -)0 P()-1 LI( Support for a clipboard access point that allows clients to store ASCII -state information in an XPA-enabled server. - -)0 P()-1 LI( Improved support for Windows platform, as well as new support for Mac OSX.)LU( - -)0 2 118 H()WB 186 Sn( Pre-Release 2.1.0e \2012 April 2002\202)EH( -)UL( -)0 P()-1 LI( Removed the environment variable generated by each XPA access -point \201of the form XPA_name=method\202. The putenv\201\202 call was causing ds9 -to crash under both Linux and LinuxPPC during a socket operation. We -suspect a bug in putenv but cannot prove it and this feature is not -essential, so ... -)LU( - -)0 2 119 H()WB 187 Sn( Pre-Release 2.1.0e \2011 April 2002\202)EH( -)UL( -)0 P()-1 LI( Fixed an uninitialized variable in xpamb which prevented it from -working at all on some systems. - -)0 P()-1 LI( Changed xpamb switch from "-add" to "-data" \201to store named data\202. - -)0 P()-1 LI( Changed how xpamb works with xpaget so that xpamb can return data -from XPA access points as well as from stored data. \201Previous versions -only returned stored data.\202 Now, you can retrieve stored data -explicitly using the -info and/or -data switches. For example: -) 1 24 PR( xpaget xpamb -info foo)RP( -will return info about the previously stored data named foo. If -neither switch is present, then the name is assumed to be an XPA access -point.)LU( - -)0 2 120 H()WB 188 Sn( Pre-Release 2.1.0e \20125 March 2002\202)EH( -)UL( -)0 P()-1 LI( Changed symbol for default port from "*" to "$port" to avoid -a syntactical conflict between class:* and machine:* when processing an -XPA access point class:name specification. Thus, the default inet -method now is '$host:$port' instead of '$host:*'. -)LU( - -)0 2 121 H()WB 189 Sn( Pre-Release 2.1.0e \20119 March 2002\202)EH( -)UL( -)0 P()-1 LI( Removed timeout check when reading data \201in clients using xpaget -and servers filling the data buffer\202. We have more and more cases -where we need to wait a long time to retrieve data \201e.g., slow -networks or receiving data being compressed on the fly\202. - -)0 P()-1 LI( Moved call to sigaction\201SIGCHLD,...\202 out of XPAOpen\201\202, so that it -is only executed when needed by XPAGet\201\202/XPASet\201\202 routines called from -within xpans/proxy. But then changed logic to use a double fork\201\202 instead -of sigaction\201\202 to prevent zombies \201Stevens Adv. Programming p 202\202. - -)0 P()-1 LI( Each XPA access point now generates an environment variable of the -form XPA_name=method so that children can communicate with the parent access -point more easily. - -)0 P()-1 LI( Added version option to Tcl xparec: -) 5 44 PR( if [catch { xparec "" version } version] { - puts "pre-2.1.0e" - } else { - puts [split $version .] - })RP( -to help differentiate between XPA versions within Tcl code. -)LU( - -)0 2 122 H()WB 190 Sn( Pre-Release 2.1.0e \20114 February 2002\202)EH( -)UL()0 P()-1 LI( Fixed client handling of out-of-sync messages.)LU( - -)0 2 123 H()WB 191 Sn( Pre-Release 2.1.0e \20111 February 2002\202)EH( -)UL( -)0 P()-1 LI( Fixed client.c/xopen\201\202 so that it does not open an extra socket. - -)0 P()-1 LI( Fixed xpainfo/xopen\201\202 to prevent client from hanging waiting for ack. - -)0 P( -)-1 LI( Modified stest to generate xpaaccess points xpa, xpa1, c_xpa, and -i_xpa \201or more generally, , 1, c_, i\202 to allow -more flexible testing of templates. Also added -a for testing XPAAccess\201\202. -)LU( - -)0 2 124 H()WB 192 Sn( Beta Release 2.1.0b10 \20131 January 2002\202)EH( -)UL( -)0 P()-1 LI( Added support for Mac OSX/Darwin to configure file. -)LU( - -)0 2 125 H()WB 193 Sn( Beta Release 2.1.0b9 \20126 January 2002\202)EH( -)UL( -)0 P()-1 LI( Fixed bug in client library that caused XPAAccess\201\202 call to hang. -)LU( - -)0 2 126 H()WB 194 Sn( Beta Release 2.1.0b8 \2014 January 2002\202)EH( -)UL( -)0 P()-1 LI( Made modifications to Makefile.in to make releases easier. - -)0 P()-1 LI( Added instructions to Makefile.in so that xpa.h will always have -correct #defines for XPA_VERSION, XPA_MAJOR_VERSION, XPA_MINOR_VERSION, -and XPA_PATCH_LEVEL. -)LU( - -)0 2 127 H()WB 195 Sn( Beta Release 2.1.0b7 \20121 December 2001\202)EH( -)UL( -)0 P()-1 LI( Added -proxy switch to -remote sub-command to allow remote access -through a firewall, using xpans as a proxy server. The support for proxy -processing required a change to the client/server protocol. This means -that new xpa servers will not work with old xpa clients \201although new -xpa clients will work with old xpa servers\202. For details about proxy -firewall support, see http://hea-www.harvard.edu/RD/xpa/inet.html. - -)0 P()-1 LI( Fixed Tcl support for XPA under Windows/Cygwin by re-writing -the code used to add XPA to the Tcl event loop. This fix makes ds9 -support for XPA much more stable under Windows. - -)0 P()-1 LI( Added the shutdown\201\202 call to XPA under Cygwin/Windows before -closing send\201\202 sockets. It appears that a Cygwin recv\201\202 socket call -does not always sense when the other end closes the socket using -close\201\202. This measure must be considered a hack, since the actual -problem was never resolved. - -)0 P()-1 LI( Added code to protect accept\201\202 and select\201\202 calls from interrupts. - -)0 P()-1 LI( Extended syntax of the environment variable XPA_NSINET to: -) 1 43 PR( setenv XPA_NSINET host:port[,port[,port]])RP( -to allow specification of the XPA access point port for xpans, -as well as the proxy data port. - -)0 P()-1 LI( Modified xpans log file so that it contains the xpaset commands -required to reconnect with xpa servers. - -)0 P()-1 LI( xpans now deletes its Unix socket files. -)LU( - -)0 2 128 H()WB 196 Sn( Beta Release 2.1.0b6 \20129 October 2001\202)EH( -)UL( -)0 P()-1 LI( Implemented a reserve public access point named -clipboard so -that clients can store ASCII state information on any number of named -clipboards. Clipboards of the same name created by clients on -different machines are kept separate. The syntax for creating a -clipboard is: -) 3 65 PR( [data] | xpaset [server] -clipboard add|append [clipboard_name] - xpaset -p [server] -clipboard delete [clipboard_name] - xpaget [server] -clipboard [clipboard_name])RP( -Use "add" to create a new clipboard or replace the contents of an existing -one. Use "append" to append to an existing clipboard. -)LU( - -)0 2 129 H()WB 197 Sn( Beta Release 2.1.0b5 \20122 October 2001\202)EH( -)UL( -)0 P()-1 LI( Use FD_SETSIZE instead of getdtablesize\201\202 to determine how many files -to check during select\201\202; - -)0 P()-1 LI( Under Cygwin, the launch\201\202 routine now uses the Cygwin spawnvp\201\202 -instead of fork\201\202/exec\201\202 where possible \201i.e., if no stdfiles are -being redirected\202. This is recommended by Cygwin's \201skimpy\202 on-line -documentation and seems to fix the problems ds9 had when starting xpans -automatically. - -)0 P()-1 LI( Added error check to select\201\202 call in xpans. -)LU( - -)0 2 130 H()WB 198 Sn( Beta Release 2.1.0b4 \20124 September 2001\202)EH( -)UL( -)0 P()-1 LI( The launch\201\202 now can return an error code if the execv\201\202 system -call fails \201something system\201\202 does not do\202. - -)0 P()-1 LI( INET socket calls between xpa clients and servers now will use -localhost if they are on the same machine. This protects against -Linux systems where the hostname is hardwired \201wrongly\202 in a DHCP -environment. -)LU( - -)0 2 131 H()WB 199 Sn( Beta Release 2.1.0b3 \2016 September 2001\202)EH( -)UL( -)0 P()-1 LI( Modified xpans so that, in the case of a firewall, it tries to -correct the specified ip:port by matching against the ip found in -the socket packet at accept\201\202 time. - -)0 P()-1 LI( Replaced system\201\202 call used to start xpans automatically with -a special launch\201\202 call, which performs execvp\201\202 directly without going -through sh. \201launch\201\202 works under DOS and has fewer security problems.\202 - -)0 P()-1 LI( Fixed bug in xpans in which its xpa port was always being set to 14286. -)LU( - -)0 2 132 H()WB 200 Sn( Beta Release 2.1.0b2 \20117 August 2001\202)EH( -)UL( -)0 P()-1 LI(Added support for -remote command, which registers the access -point in the XPA name server of the specified remote server, and gives -the remote server access rights to the access point. This is used, for -example, to give data servers xpa access to ds9 so that data can be -sent to ds9 as a result of a CGI-based Web query. - -)0 P()-1 LI(Reserved commands \201except "-help" and "-version"\202 now can only be -executed on the machine on which the xpa service is running \201not -through -remote servers\202. - -)0 P()-1 LI(Fixed bug in xpans in which a bad telnet command could hang the program. - -)0 P()-1 LI(Added -s [security file] to xpans to allow logging of all external -connections. -)LU( - -)0 2 133 H()WB 201 Sn( Beta Release 2.1.0b1 \2016 August 2001\202)EH( -)UL()0 P()-1 LI( The xpaaccess client program and XPAAccess\201\202 client subroutine -were modified so that an access-type query can directly contact the -xpa servers matching the requested xpa template, instead of just -querying the name server for registered access points. This avoid the -race condition in which an access point is registered but is not yet -available, perhaps because the server has not yet entered its event -loop. Note that the calling sequence of the XPAAccess\201\202 routine was -changed to return all matching access points and their availability -status \201instead of just returning the number of registered access -points\202. Because of this, we are calling this a minor release instead -of a patch. - -)0 P()-1 LI( Added support for XPA_PORT and XPA_PORTFILE environment variables -to allow specification of the port to be used by the command channel -\201and data channel, if an optional second port is specified\202 for a given -access point. - -)0 P()-1 LI( Added -m switch to xpaget, xpaset, xpainfo, xpaaccess to allow -override of the XPA_METHOD environment variable. - -)0 P()-1 LI( Changed the default name of the ACL file from xpa.acl to acls.xpa. - -)0 P()-1 LI( Fixed bug in which it was not possible to send a "set ACL" -command to an XPA server which did not have a receive callback \201i.e., -did not allow xpaset\202. The xpans program is one such server. It now is -possible to set the ACL on xpans. - -)0 P()-1 LI( We have discovered that Tcl support for datachan and cmdchan is -broken under Windows due to an unexplained incompatibility between -Cygwin sockets and Win32 sockets. We therefore have removed datachan -and cmdchan from the Windows/Tcl support until further notice. - -)0 P()-1 LI( Extended the behavior of the XPA_DEFACL environment variable so that -it can support more than one acl, using a list of semi-colon delimited -controls such as: setenv XPA_DEFACL '*:* $host +; *:foo1 otherhost +'. - -)0 P()-1 LI( Fixed bug in which the class:name specifier "*:*" was erroneously -trying to access the xpans name server, instead of accessing all -access points. - -)0 P()-1 LI( Support TMPDIR and TMP environment variables as well as XPA_TMPDIR. -)LU( - -)0 2 134 H()WB 202 Sn( Patch Release 2.0.5 \20110 November 2000\202)EH( -)UL()0 P()-1 LI( Added support for Tcl on Windows where there is no select\201\202-based -event loop \201i.e., where there is no Tcl_CreateFileHandler call in Tcl\202 -)0 P()-1 LI( Minor fixes in Makefile for installing on Windows -)0 P()-1 LI( Minor compiler fixes from gcc -Wall.)LU( - -)0 2 135 H()WB 203 Sn( Patch Release 2.0.4 \20120 September 2000\202 )EH( -)UL()0 P()-1 LI( Removed extraneous include of varargs.h from find.c. -)0 P()-1 LI( Ported to SGI C compiler, which caught lots of unused variables, etc. -)0 P()-1 LI( Ported to Cygwin/Windows, which required that we change socket read\201\202 -and write\201\202 calls to recv\201\202 and send\201\202 respectively. Also had to ensure that -we only did socket I/O on sockets \201no fileio\202.)LU( - -)0 2 136 H()WB 204 Sn( Patch Release 2.0.3 \20115 June 2000\202 )EH( -)UL( -)0 P()-1 LI( Fixed the client XPASet\201\202 and XPASetFd\201\202 calls to handle the specified -max number of connections \201they were ignoring this argument, leading to -memory overwrites\202. -)0 P()-1 LI( Fixed Makefile.in so that CFLAGS and LDFLAGS are not hard-wired values. -)0 P()-1 LI( Fixed word.h to load malloc.h and stdlib.h only if they exist. -)0 P()-1 LI( Documentation fixes to programs.html \201in xpaaccess\202 and client.html -\201XPANSLookup\202. -)0 P()-1 LI( Added explicit typecast to strlen\201\202 argument to MAX #define in -XPAClientStart \201strlen\201\202 is unsigned in Linux, which can break MAX\202. -)0 P()-1 LI( Removed bogus Imakefile from directory. -)0 P()-1 LI( Changed directory name to include patch level \201i.e., xpa-2.0.3\202.)LU( - -)0 2 137 H()WB 205 Sn( Patch Release 2.0.2 \2019 September 1999\202)EH( -)UL( -)0 P()-1 LI( Fixed server mode \201-s\202 in the xpaset program by properly cleaning up -the input buffers \201sending commands and data in server mode was broken\202.)LU( - -)0 2 138 H()WB 206 Sn( Patch Release 2.0.1 \2016 August 1999\202)EH( -)UL( -)0 P()-1 LI( Fixed the Tcl binding code \201tcl.c\202 for 64-bit machines \201Dec Alpha\202 -\201erroneously used %x instead of %p when converting pointers to ASCII\202. -)0 P()-1 LI( Got rid of a few compiler warnings on 64-bit machines \201a few are -unavoidable since we must cast int to void * and back when passing around -client data\202.)LU( - -)0 2 139 H()WB 207 Sn( Public Release 2.0 \20127 May 1999\202)EH( -)UL( -)0 P()-1 LI( "a new day with no mistakes ... yet")LU( - -)2 1 1 HR()0 P()0 0 1 A(Index to the XPA Help Pages)0 0 TN TL()Ec /AF f D( - -)2 1 1 HR()0 5 140 H(Last)WB 208 Sn( updated: 22 April 2002)EH( -)WB NL -/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc -DS -/Ba f D /BO 0 D Bs -/UR (examples.html) D -/Ti (Where to Find Example/Test Code) D -/Au () D -/Df f D -/ME [()] D - -0 BO R -()1 Sl()WB 43 Sn( - - -)0 2 141 H(XPACode:)WB 210 Sn()WB 209 Sn( Where to Find Example/Test Code)EA()EH( - - -)0 2 142 H(Summary)WB 211 Sn()EH( -)0 P(The XPA source code directory contains two test programs, -)EM(stest.c)ES(, and )EM(ctest.c)ES( that can serve as -examples for writing XPA servers and clients, respectively. -They also can be used to test various features of XPA. - - -)0 2 143 H(Description)WB 212 Sn()EH( -)0 P(To build the XPA test programs, execute: -) 1 11 PR( make All)RP( -in the XPA source directory to generate the )EM(stest)ES( and -)EM(ctest)ES( programs. \201NB: this should work on all platforms, -although we have had problems with unresolved externals on one -Sun/Solaris machine, for reasons still unknown.\202 -)0 P(The stest program can be executed with no arguments to start -an XPA server that contains the access points: xpa, xpa1, -c_xpa \201containing sub-commands cmd1 and cmd2\202, and i_xpa. -You then can use xpaset and xpaget to interact with these access points: -) 4 57 PR( cat xpa.c | xpaset xpa # send to xpa - cat xpa.c | xpaset "xpa*" # send to xpa and xpa1 - xpaget xpa # receive from xpa - xpaget xpa* # receive from xpa and xpa1)RP( -etc. You also can use ctest to do the same thing, or to iterate: -) 4 66 PR( ctest -s -l 100 xpa # send to xpa 100 times - ctest -s -l 100 "xpa*" # send to xpa and xpa1 100 times - ctest -g -l 100 xpa # receive from xpa 100 times - ctest -g -l 100 "xpa*" # receive from xpa and xpa1 100 times)RP( -More options are available: see the stest.c and ctest.c code itself, which -were used extensively to debug XPA. - -)0 P(The file test.tcl in the XPA source directory gives examples for using the -)0 39 1 A(XPATcl)39 0 TN TL()Ec /AF f D(Interface. - - - - - -)0 P()0 0 1 A(Go to XPA Help Index)0 0 TN TL()Ec /AF f D( - -)0 5 144 H(Last)WB 213 Sn( updated: September 10, 2003)EH( -)WB NL -/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc -DS -/Ba f D /BO 0 D Bs -/UR (changes.html) D -/Ti (Changes For Users from XPA 1.0 and 2.0) D -/Au () D -/Df f D -/ME [()] D - -0 BO R -()1 Sl()WB 44 Sn( - - -)0 2 145 H(XPA)WB 215 Sn()WB 214 Sn( Changes: Changes For Users from XPA 1.0 and 2.0)EA()EH( - - -)0 2 146 H(Summary)WB 216 Sn()EH( -)0 P(This document describes changes that will affect users who migrate -from XPA 1.0 to XPA 2.0. - - -)0 2 147 H(Description)WB 217 Sn()EH( -)0 P(There have been a few changes that affect users who upgrade XPA -from version 1.0 to version 2.0. These changes are detailed below. -)UL()0 P()-1 LI(XPA commands no longer have a resolver routine \201this is open to -negotiations, but we decided the idea was dumb\202. For the SAOtng -program, this means that you must explicitly specify the access -point, i.e.,: -) 1 35 PR( cat foo.fits | xpaset SAOtng fits)RP( - -)0 P(instead of: -) 1 30 PR( cat foo.fits | xpaset SAOtng)RP( -)0 P()-1 LI(By default, xpaset, xpaget, etc. now wait for the server callback to -complete; i.e., the old -W is implied \201and the switch is ignored\202. -This allows support for better error handling. If you want xpaset, etc. -to return before the callback is complete, use -n switch: -) 1 41 PR( echo "file foo.fits" | xpaset -n SAOtng)RP( -)0 P()-1 LI(The old -w switch in xpaset and xpaget is no longer necessary \201and is -ignored\202, since you can have more than one process communicating with -an xpa access point at one time. - -)0 P()-1 LI(The new -p switch on xpaset means you need not read from stdout: -) 2 30 PR( - xpaset -p SAOtng colormap I8)RP( -)0 P(will send the paramlist to the SAOtng callback without reading from stdin. -)LU( - - - - - -)0 P()0 0 1 A(Go to XPA Help Index)0 0 TN TL()Ec /AF f D( - -)0 5 148 H(Last)WB 218 Sn( updated: September 10, 2003)EH( -)WB NL -/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc -DS -/Ba f D /BO 0 D Bs -/UR (convert.html) D -/Ti (Converting the XPA API to 2.0) D -/Au () D -/Df f D -/ME [()] D - -0 BO R -()1 Sl()WB 45 Sn( - - -)0 2 149 H(XPAConvert:)WB 220 Sn()WB 219 Sn( Converting the XPA API to 2.0)EA()EH( - - -)0 2 150 H(Summary)WB 221 Sn()EH( -)0 P(This document describes tips for converting from xpa 1.0 \201Xt-based -xpa\202 to xpa 2.0 \201socket-based xpa\202. - - -)0 2 151 H(Description)WB 222 Sn()EH( -)0 P(The following are tips for converting from xpa 1.0 \201Xt-based xpa\202 to -xpa 2.0 \201socket-based xpa\202. The changes are straight-forward and -almost can be done automatically \201we used editor macros for most of -the conversion\202. -)UL()0 P()-1 LI(The existence of the cpp XPA_VERSION directive to distinguish between 1.0 -\201where it is not defined\202 and 2.0 \201where it is defined\202. - -)0 P()-1 LI(Remove the first widget argument from all send and receive server -callbacks. Also change first 2 arguments from XtPointer to void -*. For example: -) 16 74 PR(#ifdef XPA_VERSION -static void XPAReceiveFile\201client_data, call_data, paramlist, buf, len\202 - void *client_data; - void *call_data; - char *paramlist; - char *buf; - int len; -#else -static void XPAReceiveFile\201w, client_data, call_data, paramlist, buf, len\202 - Widget w; - XtPointer client_data; - XtPointer call_data; - char *paramlist; - char *buf; - int len; -#endif)RP( -)0 P()-1 LI(Server callbacks should be declared as returning int instead -of void. They now should return 0 for no errors, -1 for error. - -)0 P()-1 LI( The mode flags have changed when defining XPA server callbacks. -The old )EM(S)ES( flag \201save buffer\202 is replaced by )EM(freebuf=false)ES(. -The old )EM(E)ES( flag \201empty buffer is OK\202 is no longer used \201it -was an artifact of the X implementation\202. - -)0 P()-1 LI(Change NewXPACommand\201\202 to XPAcmdNew\201\202, with the new calling sequence: -) 1 52 PR( xpa = NewXPACommand\201toplevel, NULL, prefix, NULL\202;)RP( -is changed to: -) 1 32 PR( xpa = XPACmdNew\201xclass, name\202;)RP( -)0 P()-1 LI(Change the AddXPACommand\201\202 subroutine name to XPACmdAdd \201with the same -calling sequence\202: -) 3 53 PR( AddXPACommand\201xpa, "file", - "\200tdisplay a new file\200n\200t\200t requires: filename", - NULL, NULL, NULL, XPAReceiveFile, text, NULL\202;)RP( -is changed to: -) 3 53 PR( XPACmdAdd\201xpa, "file", - "\200tdisplay a new file\200n\200t\200t requires: filename", - NULL, NULL, NULL, XPAReceiveFile, text, NULL\202;)RP( -)0 P()-1 LI(The XPAXtAppInput\201\202 routine should be called just before XtAppMainLoop\201\202 -to add xpa fds to the Xt event loop: -) 5 35 PR( /* add the xpas to the Xt loop */ - XPAXtAddInput\201app, NULL\202; - - /* process events */ - XtAppMainLoop\201app\202;)RP( -)0 P()-1 LI(Change NewXPA\201\202 to XPANew\201\202 and call XPAXtAddInput\201\202 if the XtAppMainLoop -routine already has been entered: -) 4 71 PR( xpa = NewXPA\201saotng->xim->toplevel, prefix, xparoot, - "FITS data or image filename\200n\200t\200t options: file type", - XPASendData, new, NULL, - XPAReceiveData, new, "SE"\202;)RP( -is changed to: -) 6 74 PR( sprintf\201tbuf, "%s.%s", prefix, xparoot\202; - xpa = XPANew\201"SAOTNG", tbuf, - "FITS data or image filename\200n\200t\200t options: file type", - XPASendData, new, NULL, - XPAReceiveData, new, "SE"\202; - XPAXtAddInput\201XtWidgetToApplicationContext\201saotng->xim->toplevel\202, xpa\202;)RP( -)0 P()-1 LI(Change XPAInternalReceiveCommand\201\202 to XPACmdInternalReceive\201\202 -remove first argument in the calling sequence\202: -) 3 61 PR( XPAInternalReceiveCommand\201im->saotng->xim->toplevel, - im->saotng, im->saotng->commands, - "zoom reset", NULL, 0\202;)RP( -is changed to: -) 2 57 PR( XPACmdInternalReceive\201im->saotng, im->saotng->commands, - "zoom reset", NULL, 0\202;)RP( -)0 P()-1 LI(Change DestroyXPA to XPAFree: -) 1 26 PR( DestroyXPA\201im->dataxpa\202;)RP( -is changed to: -) 1 23 PR( XPAFree\201im->dataxpa\202;)RP()LU( - - - - - -)0 P()0 0 1 A(Go to XPA Help Index)0 0 TN TL()Ec /AF f D( - -)0 5 152 H(Last)WB 223 Sn( updated: September 10, 2003)EH( - -)WB NL -/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc -DS -/Ba f D /BO 0 D Bs -/UR (name.html) D -/Ti (What does XPA stand for?) D -/Au () D -/Df f D -/ME [()] D - -0 BO R -()1 Sl()WB 46 Sn( - - -)0 2 153 H(XPAName:)WB 225 Sn()WB 224 Sn( What does XPA stand for?)EA()EH( - - -)0 2 154 H(Summary)WB 226 Sn()EH( -)0 P(What does XPA stand for? Who knows anymore! - - -)0 2 155 H(Description)WB 227 Sn()EH( -)0 P(What does XPA stand for? Dunno! The XPA messaging system originally -was built on top of the X Window System and XPA was the mnemonic for -)EM(X Public Access)ES(, to emphasize that we were providing public -access to previously private data and algorithms in Xt programs. Now -that XPA no longer is tied to X, it can be argued that we ought to -change the name \201how about )EM(SPAM: simple public access mechanism)ES(\202, but XPA is in wide-spread use in the astronomical community of -its birth, and the name has taken on a life of its own. If anyone can -think of what XPA now means, please let us know. - -)0 P(If you think this is bad, consider the MMT Telescope on Mount Hopkins, -Arizona. When first installed twenty years ago, it featured an array -of six 72-inch diameter mirrors. from which came its name: the -)EM(Multiple Mirror Telescope)ES(. In spring of 1999, these mirrors -were replaced by a single 21 and 1/2 -foot diameter primary mirror, -the largest single-piece glass reflector on the North American -continent. And now MMT stands for ... MMT! - - - - - -)0 P()0 0 1 A(Go to XPA Help Index)0 0 TN TL()Ec /AF f D( - -)0 5 156 H(Last)WB 228 Sn( updated: September 10, 2003)EH( - -)WB NL -/TE t D NP TU PM 0 eq and{/Pn () D showpage}if end restore diff --git a/xpa/doc/xpamb.html b/xpa/doc/xpamb.html deleted file mode 100644 index c1e27c8..0000000 --- a/xpa/doc/xpamb.html +++ /dev/null @@ -1,197 +0,0 @@ -<!-- =defdoc xpamb xpamb 1 --> -<HTML> -<HEAD> -<TITLE>The XPA Message Bus (xpamb)</TITLE> -</HEAD> -<BODY> - -<!-- =section xpamb NAME --> -<H2><A NAME="xpamb">xpamb: the XPA Message Bus</A></H2> - -<!-- =section xpamb SYNOPSIS --> -<H2>Summary</H2> -<P> -The xpamb program can act as a "classical" message bus interface -between clients and servers. A client can send a data request to -the message bus, which then interfaces with multiple servers and -returns the data back to the client. - -<!-- =section xpamb DESCRIPTION --> -<H2>Description</H2> -<P> -A "classical" message bus (such as ToolTalk) consists of servers and -clients, along with a mediating program that transfers data between -different processes. XPA takes a slightly different approach in that -communication between clients and servers is direct. This generally -is the correct technique when there is only one connection (or even a -small number of connections), but can become inefficient for the -serving program if a large amount of data is being transferred to many -clients. For example, if a real-time data acquisition program is -broadcasting a FITS image to several clients, it would need to -transmit that image to each client individually. This might interfere -with its own processing cycles. The preferable mechanism would be to -pass the image off to an intermediate program that can then broadcast -the data to the several clients. -<P> -The <B>xpamb</B> program can alleviate such problems by functioning -as a message bus in cases where such an intermediary process is -wanted. It pre-defines a single access point named -<B>XPAMB:xpamb</B> to which data can be sent for re-broadcast. You -also can tell <B>xpamb</B> to save the data, and associate with that -data a new access point, so that it can be retrieved later on. - -<P> -All interaction with <B>xpamb</B> is performed through -<B>xpaset</B> and <B>xpaget</B> (or the corresponding API -routines, <B>XPASet()</B> and <B>XPAGet()</B>) to the -<B>XPAMB:xpamb</B> access point. That is, <B>xpamb</B> is just -another XPA-enabled program that responds to requests from -clients. The paramlist is used to specify the targets to which -the data will be for re-broadcast, as well as the re-broadcast paramlist: -<PRE> - data | xpaset xpamb [switches] broadcast-target broadcast-paramlist -</PRE> -Optional switches are used to store data, and manipulate stored data, -and are described below. - -<P> -In its simplest form, you can, for example, send a FITS image to xpamb for -broadcasting to all ds9 image simply by executing: -<PRE> - cat foo.fits | xpaset xpamb "DS9:*" fits foo.fits -</PRE> -Since <B>DS9</B> is the class name for the ds9 image display -program, this will result in the FITS image being re-sent to all fits -access points for all active image display programs. - -<P> -You can send stored data and new data to the same set of access points at -the same time. The stored data always is sent first, followed by the new -data: -<PRE> - cat foo2.fits | xpaset xpamb -send foo "DS9:*" fits foo.fits -</PRE> -will first send the foo.fits file, and then the foo2.fits file to all -access points of class <B>DS9</B>. Notice that in this example, -the foo2.fits file is not stored, but it could be stored by using the -<B>-store [name]</B> switch on the command line. - -<P> -The <B>xpaget</B> command can be used to retrieve a data from XPA -access points or from a stored data buffer, or retrieve information -about a stored data buffer. If no arguments are given: -<PRE> - xpaget xpamb -</PRE> -then information about all currently stored data buffers is returned. This -information includes the data and time at which the data was stored, the -size in bytes of the data, and the supplied info string. - -<P> -If arguments are specified, they will be in the form: -<PRE> - xpaget xpamb [-info] [-data] [name [paramlist]] -</PRE> -If the optional <B>-info</B> and/or <B>-data</B> switches are specified, then -information and/or data will be returned for the named data buffer -following the switches. You can use either or both of these switches -in a single command. For example, if the -info switch is used: -<PRE> - xpaget xpamb -info foo -</PRE> -then the info about that stored data buffer will be returned. -If the -data is used with a specific name: -<PRE> - xpaget xpamb -data foo -</PRE> -then the stored data itself will be returned. If both are used: -<PRE> - xpaget xpamb -info -data foo -</PRE> -then the info will be returned, followed by the data. Note that it is an -error to specify one of these switches without a data buffer name and that -the paramlist will be ignored. - -<P> -If neither the <B>-info</B> or <B>-data</B> switch is specified, then -the name refers to an XPA access point (with an optional paramlist -following). -For example: -<PRE> - xpaget xpamb ds9 file -</PRE> -is equivalent to: -<PRE> - xpaget ds9 file -</PRE> - -<!-- =section xpamb OPTIONS --> -<H2>Options</H2> -<P> -For xpaset, several optional switches are used to save data and -manipulate the stored data: -<DL> - -<P> -<DT><B>-data [name]</B> -<DD> Add the supplied data buffer to a pool of stored data buffers, -using the specified name as a unique identifier for later retrieval. -An error occurs if the name already exists (use either <B>replace</B> -or <B>del</B> to rectify this). The <B>-add</B> switch is supported -for backwards compatibility with xpa 2.0. - -<P> -<DT><B>-replace [name]</B> -<DD> Replace previously existing stored data having the same unique name -with new data. This essentially is a combination of the <B>del</B> -and <B>data</B> commands. - -<P> -<DT><B>-info ["'info string'"]</B> -<DD> When adding a data buffer, you can specify an informational -string to be stored with that data. This string will be returned -by xpaget: -<PRE> - xpaget xpamb foo -info -</PRE> -(along with other information such as the date/time of storage and the size of -the data buffer) if the -info switch is specified. If the info string contains -spaces, you must enclose it in <B>two</B> sets of quotes: -<PRE> - cat foo | xpaset xpamb -data foo -info "'this is info on foo'" -</PRE> -The first set of quotes is removed by the shell while the second is used to -delineate the info string. - -<P> -<DT><B>-send [name]</B> -<DD> Broadcast the stored data buffer to the named template. - -<P> -<DT><B>-del [name]</B> -<DD> Delete the named data buffer and free all allocated space. -</DL> - -<P> -Switches can be used in any combination that makes sense. For example: -<PRE> - cat foo.fits | xpaset xpamb -data foo -info "FITS" "DS9:*" fits foo.fits -</PRE> -will broadcast the foo.fits image to all access points of class -<B>DS9</B>. In addition, the foo.fits file will be stored under the -name of <B>foo</B> for later manipulation such as: -<PRE> - xpaset -p xpamb -send foo "DS9:*" fits foo.fits -</PRE> -will re-broadcast the foo.fits image to all access points of class "DS9". - -<!-- =section xpamb 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> diff --git a/xpa/doc/xpans.html b/xpa/doc/xpans.html deleted file mode 100644 index a0aebb2..0000000 --- a/xpa/doc/xpans.html +++ /dev/null @@ -1,212 +0,0 @@ -<!-- =defdoc xpans xpans 1 --> -<HTML> -<HEAD> -<TITLE>The XPA Name Server (xpans)</TITLE> -</HEAD> -<BODY> - -<!-- =section xpans NAME --> -<H2><A NAME="xpans">xpans: the XPA Name Server</A></H2> - -<!-- =section xpans SYNOPSIS --> -<H2>Summary</H2> -<PRE> - xpans [-h] [-e] [-k sec] [-p port] [-l log] [-s security log] [-P n] -</PRE> - -<!-- =section xpans OPTIONS --> -<P> -<PRE> - -h print help message - -e exit when there are no more XPA connections - -k send keepalive messages every n sec - -l log data base entries to specified file - -p listen for connections on specified port - -s log security info for each connection to specified file - -P accept proxy requests (P=1) using separate thread (P=2) - --version display version and exit -</PRE> - -<!-- =section xpans DESCRIPTION --> -<P> -The xpans name server is an XPA-enabled program that is used to -manage the names and ports of XPA access points. It is started -automatically when an XPA access point is registered. You can access -the name server using xpaget to get a list of registered access points. -<P> -The <EM>xpans</EM> name server provides a crucial link between XPA -clients and servers. When an XPA server defines an access point using -XPANew(), XPACmdNew(), or XPAInfoNew(), the name of the access point -is registered in the name service, along with connection information. -The name server then matches class:name templates passed to it by XPA -clients with these registered entries, so that the clients can -communicate with the appropriate servers. - -<P> -The socket connection between an XPA-enabled program and -<EM>xpans</EM> is kept open until the former exits (or explicitly -closes the connection). Apparently, some Internet equipment (e.g. DSL -modems) can cause such a connection to time-out after a period of -inactivity. To prevent this from happening, you can use the <EM>-k -[sec]</EM> switch to send a short keep-alive message to each open -connection after the specified time delay. (Note that this -application level use of keep-alive is necessary only if you are -serving XPA-enabled clients over the Internet and have to deal with -long-term connections involving DSL or similar equipment. XPA uses -the ordinary socket-level keep-alive, which works for all other cases.) -<B>NB (12/2/2009): Out-of-band (URG) TCP data, used by xpans -keep-alive, is changed by some Cisco routers into in-band data. -Encountering such a router will break the keep-alive function and may -break your XPA server as well. Proceed with caution!</B> - -<P> -The <EM>xpans</EM> program will be started automatically (assuming it -can be found in the user's path) when the first XPA access point is -registered. It therefore need not be started explicitly. However, -when started automatically, the <EM>-e</EM> switch is used, so that -the name server will exit when there are no more XPA access points -registered. If you wish to keep the name server running continually, -simply start it manually without the <EM>-e</EM> switch. - -<P> -The name server will keep a log of registered access points if the -<EM>-l [log]</EM> switch is used on the command line (this is the -case for automatic start-up). The log contains enough name and connection -information to allow you to re-register all XPA access points in case -the name server process is terminated prematurely. For example, after -the ds9 access point is registered,the log will contain the entry: -<PRE> - add 838e2f67:1863 ds9 ds9 gs eric -</PRE> -If <EM>xpans</EM> is terminated but ds9 still is running, you -can re-register both access points for the ds9 process by running: -<PRE> - xpaset -p 838e2f67:1863 -nsconnect -</PRE> -Notice that the ip:port specifier is used with <EM>xpaset</EM> to bypass -the need for contacting the name server (which does not have the name -registered yet!) - -<P> -The name server will keep a log of security information if the <EM>-s -[security log]</EM> switch is used on the command line. For each -accepted connection, (including connections via the <EM>xpaget</EM> -command), information will be logged about the host issuing the -command and the parameters passed into the program. This is most -useful when <EM>xpans</EM> is accepting connections from untrusted -machines. - -<P> -When an XPA access point is removed by a server using <EM>XPAFree()</EM>, -the access information is removed from the name server. If an -XPA-enabled process is terminated, all names registered by that process -will be removed automatically. The log file is always updated to -reflect the currently registered access points. - -<P> -The name server itself has an XPA access point names <EM>xpans</EM> -registered through which you can find out information about currently -registered access points (assuming you have access to the name server; -see <A HREF="./acl.html">XPA Access Control</A> for more information). -For each registered access point, the following information is returned: -<PRE> - class # class of the access point - name # name of the access point - access # allowed access (g=xpaget,s=xpaset,i=xpainfo) - id # socket access method (host:port for inet, file for local/unix) - user # user name of access point owner -</PRE> - -<P> -For example, to display all currently registered access points, simply execute: -<PRE> - xpaget xpans -</PRE> -Continuing the example of ds9 above, this will return: -<PRE> - DS9 ds9 gs 838e2f67:1863 eric -</PRE> -If the same program has been started with different XPA access names, -you can look up only names matching a specified template. For example, -assume that ds9 has been started up using: -<PRE> - ds9 & - ds9 -title ds9-1-eric & - ds9 -title ds9-2-eric & -</PRE> -To lookup all ds9 access points which end in ".eric" and which can -be accessed using <EM>xpaset</EM>, use: -<PRE> - xpaget xpans "DS9:*.eric" "s" "*" -</PRE> -This will return: -<PRE> - DS9 ds9-2-eric gs 838e29d3:42102 eric - DS9 ds9-1-eric gs 838e29d3:42105 eric -</PRE> -The third argument "*" requests all access points from all users. -You also can specify a specific user name and only access points -registered by that user will be returned. - -<P> -The name server uses the <EM>XPA_METHOD</EM> environment variable -to determine whether it should listen for requests on INET or LOCAL -sockets. Since XPA access points also use this environment variable, -the choice of socket method will be consistent. Note that, when INET -sockets are used, a local server can be accessed from remote machines -if the <EM>XPA_NSINET</EM> environment variable is set to point to -the local machine. See -<A HREF="./env.html">XPA Environment Variables</A> -for more information. - -<P> -An experimental feature of xpans is its ability to act as a proxy to -XPA servers behind firewalls that want to communicate with external -processes. The basic idea is the following: an XPA server (call it -"foo") on host1, possibly behind a firewall, makes a remote connection -to a proxy-enabled xpans program on host2 (specifying host2's XPA method). -For example: -<PRE> - xpaset -p foo -remote 'host2:28571' + -proxy # on host1 -</PRE> -When this is done, host2 can use xpaset, xpaget, and xpainfo calls to -communicate with the XPA server foo. All command communication is -performed via the xpans socket connection between foo on host1 and -xpans on host2 (which was initiated by foo from inside the firewall). -Data communication is similarly performed using a socket connection -initiated on host1 (usually with a port value two greater than the -port value of the main xpans socket connection). An xpaset or xpaget -call on host2 contacts xpans, which performs an XPASet() or XPAGet() -call to foo, passing commands and data back and forth between the two -programs. - -<P> -By default, proxy connections are not allowed by xpans. If the -P switch is -specified with a value of 1, proxy connection are allowed, but all proxy -communication is performed in the same thread as xpans processing. If -a value of 2 is specified, the proxy processing is performed in a -separate thread (assuming pthreads are supported on your system). -Because xpa callback processing of any type can take a long time and -therefore can interfere with normal xpans processing, threaded proxy -connections (-P 2) are recommended. When using proxy connections, it -might also be useful to set the XPA_IOCALLSXPA environment variable, so -that multiple proxy requests can be handled at the same time, instead of -serially. - -<P> -Note that this proxy interface to xpans is experimental. It is used -to provide remote data analysis capabilities on the Chandra-Ed system -using ds9. (See http://chandra-ed.cfa.harvard.edu and -http://hea-www.harvard.edu/saord/ds9 for more details). As always, please -contact us if you have problems or questions. - -<!-- =section xpans 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: January 24, 2005</H5> -</BODY> -</HTML> diff --git a/xpa/doc/xt.html b/xpa/doc/xt.html deleted file mode 100644 index 2b68604..0000000 --- a/xpa/doc/xt.html +++ /dev/null @@ -1,47 +0,0 @@ -<!-- =defdoc xpaxt xpaxt n --> -<HTML> -<HEAD> -<TITLE>XPA/Xt Interface</TITLE> -</HEAD> -<BODY> - -<!-- =section xpaxt NAME --> -<H2><A NAME="xpatcl">XPAXt: the XPA Interface to Xt (X Windows)</A></H2> - -<!-- =section xpaxt SYNOPSIS --> -<H2>Summary</H2> -Describes how XPA access points can be added to X Toolkit (Xt) programs. - -<!-- =section xpaxt DESCRIPTION --> -<H2>Description</H2> -<P> -XPA supports Xt programs: you can call XPANew(), XPACmdNew(), or -XPAInfoNew() within any C routine to add XPA server callbacks to an Xt -program. Since an Xt program has its own event loop call (i.e., -XtAppMainLoop()), it therefore does not need or want to use the XPA -even loop. Thus, in order to add XPA access points to the standard Xt -event loop, the following routine should be called before entering the -loop: -<PRE> - int XPAXtAddInput(XtAppContext app, XPA xpa) -</PRE> -<P> -The XPAAddAddInput() routine will add XPA access points to the Xt event -loop by making calls to the standard XtAppAddInput() routine. (If the -XtAppContext argument is NULL, then the alternate XtAddInput() routine -is used instead.) If the xpa argument is NULL, then all active XPA -access points are added to the loop. If xpa is not NULL, then only -the specified access point is added. The latter type of call is used -to add new access points from within a callback, after the program has -entered the XtAppMainLoop() even loop. - -<!-- =section xpaxt 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> |