Provided by: tcl-xpa_2.1.15-3_amd64 bug

NAME

       XPATcl -  the XPA Interface to the Tcl/Tk Environment

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.

       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

       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]

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.

       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.

       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 .]
         }

SEE ALSO

       See xpa(7) for a list of XPA help pages