The XPA Interface to the Tcl/Tk Environment

Summary

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 

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]

set got [xpaaccess template type]

set got [xpanslookup template type classes names methods]

Introduction

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:

    argument

    explanation

    xpa

    the first argument of the server callback

    buf

    the data to be returned to the client

    len

    length of data in bytes, or, 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 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:

    argument

    explanation

    xpa

    the first argument of the server callback

    datachan

    is the literal string "datachan" that returns the data channel

    len

    length of data in bytes, or, if absent, use length of the buf object.

    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.)

    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")


    Index to the XPA Help Pages

    Last updated: May 18, 1999