1 files changed, 258 insertions, 0 deletions
diff --git a/xpa/doc/pod/xpatcl.pod b/xpa/doc/pod/xpatcl.pod
new file mode 100644
index 0000000..008a4f3
--- /dev/null
+++ b/xpa/doc/pod/xpatcl.pod
@@ -0,0 +1,258 @@
+=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