1xpatcl(n)                     SAORD Documentation                    xpatcl(n)
2
3
4

NAME

6       XPATcl: the XPA Interface to the Tcl/Tk Environment
7

SYNOPSIS

9       Tcl/Tk programs can act as XPA clients and/or servers using the Tcl
10       interface to XPA that is contained in the libtclxpa.so shared object.
11
12       Server Routines
13
14         set xpa [xpanew class name help sproc sdata smode rproc rdata rmode]
15         xpafree xpa
16         set xpa [xpanew class name help iproc idata imode]
17         set xpa [xpacmdnew class name]
18         xpacmdadd xpa name help sproc sdata smode rproc rdata rmode
19         xpacmddel xpa cmd
20         set val [xparec xpa option]
21           options: name, class, method, cmdfd, datafd, cmdchan, datachan
22         xpasetbuf xpa buf len
23         xpaerror xpa message
24         xpamessage xpa message
25
26       Client Routines
27
28         set xpa [xpaopen mode]
29         xpaclose xpa
30         set got [xpaget xpa template paramlist mode bufs lens names errs n]
31         set got [xpaget xpa template paramlist mode chans names errs n]
32         set got [xpaset xpa template paramlist mode buf len names errs n]
33         set got [xpasetfd xpa template paramlist mode chan names errs n]
34         set got [xpainfo xpa template paramlist mode names errs n]
35         # NB: 2.1 calling sequence change
36         # set got [xpaaccess template type] (2.0.5)
37         set got [xpaaccess xpa template paramlist mode names errs n]
38         set got [xpanslookup template type classes names methods]
39

DESCRIPTION

41       You can call XPANew(), XPACmdNew(), or XPAInfoNew() within a C routine
42       to add C-based XPA server callbacks to a TCL/Tk program that uses a
43       Tcl/Tk event loop (either vwait() or the Tk event loop); Such a program
44       does not need or want to use the XPA event loop.  Therefore, in order
45       to add XPA access points to the Tcl/Tk loop, the following routine
46       should be called beforehand:
47
48         int XPATclAddInput(XPA xpa);
49
50       Normally, the xpa argument is NULL, meaning that all current XPA access
51       points are registered with the event loop.  However, if a single XPA
52       access point is to be added (i.e., after the event loop is started)
53       then the handle of that XPA access point can be passed to this routine.
54
55       The significance of the XPA/TCL interface goes beyond the support for
56       using XPA inside C code. The interface allows you to write XPA servers
57       and to make calls to the XPA client interface within the Tcl environ‐
58       ment using the Tcl language directly. The XPA/Tcl interface can be
59       loaded using the following package command:
60
61         package require tclxpa 2.0
62
63       Alternatively, you can load the shared object (called libtclxpa.so )
64       directly:
65
66         load .../libtclxpa.so tclxpa
67
68       Once the tclxpa package is loaded, you can use Tcl versions of XPA rou‐
69       tines to define XPA servers or make client XPA calls.  The interface
70       for these routines is designed to match the Unix XPA interface as
71       nearly as possible.  Please refer to XPA Servers and XPA Clients for
72       general information about these routines.
73
74       The file test.tcl in the XPA source directory gives examples for using
75       the XPA/Tcl interface.
76
77       The following notes describe the minor differences between the inter‐
78       faces.
79
80       XPANew
81
82         set xpa [xpanew class name help sproc sdata smode rproc rdata rmode]
83
84       rproc and sproc routines are routines.  The calling sequence of the
85       rproc routine is identical to its C counterpart:
86
87         proc rec_cb { xpa client_data paramlist buf len } { ... }
88
89       The sproc routine, however is slightly different from its C counterpart
90       because of the difficulty of passing data back from the callback to C:
91
92         proc sendcb { xpa client_data paramlist } { ... }
93
94       Note that the C-based server's char **buf and int *len arguments are
95       missing from the Tcl callback. This is because we did not know how to
96       fill buf with data and pass it back to the C routines for communication
97       with the client.  Instead, the Tcl server callback uses the following
98       routine to set buf and len:
99
100         xpasetbuf xpa buf len
101
102       where:
103
104         arg           explanation
105         ------        -----------
106         xpa           the first argument of the server callback
107         buf           the data to be returned to the client
108         len           data length in bytes, (if absent, use length of the buf object)
109
110       When this routine is called, a copy of buf is saved for transmission to
111       the client.
112
113       The fact that buf is duplicated means that TCL server writers might
114       wish to perform the I/O directly within the callback, rather than have
115       XPA do it automatically at the end of the routine.  To do this, set:
116
117         fillbuf=false
118
119       in the xpanew smode and then perform I/O through the Tcl channel
120       obtained from:
121
122         set dchan [xparec $xpa datachan]
123
124       where:
125
126         arg           explanation
127         ------        -----------
128         xpa           the first argument of the server callback
129         datachan      literal string "datachan" that returns the data channel
130         len           data length in bytes, (if absent, use length of the buf object)
131
132       NB: datachan and cmdchan are not available under Windows. It is neces‐
133       sary to use the "raw" equivalents: datafd and cmdfd.
134
135       The same considerations apply to the rproc for receive servers: a copy
136       of the incoming data is generated to pass to the receive callback. This
137       copy again can be avoided by using "fillbuf=false" in the rmode and
138       then reading the incoming data from datachan.
139
140       The send and receive callback routines can use the xpaerror and xpames‐
141       sage routines to send errors and messages back to the client.  If you
142       also want tcl itself to field an error condition, use the standard
143       return call:
144
145         return ?-code c? ?-errorinfo i? ?-errorcode ec? string
146
147       See the Tcl man page for more info.
148
149       XPARec
150
151       The Tcl xparec procedure supplies server routines with access to infor‐
152       mation that is available via macros in the C interface:
153
154         set val [xparec xpa <option>]
155
156       where option is: name, class, method, cmdfd, datafd, cmdchan, datachan.
157       Note that two additional identifiers, cmdchan and datachan, have been
158       added to to provide Tcl channels corresponding to datafd and cmdfd.
159       (These latter might still be retrieved in Tcl and passed back to a C
160       routines.)  An additional option called "version" can be used to deter‐
161       mine the XPA version used to build the Tcl interface. Note that the
162       standard options require a valid XPA handle, but "version" does not
163       (since it simply reports the value of the XPA_VERSION definition in the
164       XPA source include file).
165
166       NB: datachan and cmdchan are not available under Windows. It is neces‐
167       sary to use the "raw" equivalents: datafd and cmdfd.
168
169         macro         explanation
170         ------        -----------
171         class         class of this xpa
172         name          name of this xpa
173         method        method string (inet or local connect info)
174         cmdchan       Tcl channel of command socket
175         datachan      Tcl channel of data socket
176         cmdfd         fd of command socket
177         datafd        fd of data socket
178         sendian       endian-ness of server ("little" or "big")
179         cendian       endian-ness of client ("little" or "big"
180         version       XPA version used to build this code
181
182       Under Windows, the Tcl event handler cannot automatically sense when an
183       XPA socket is ready for IO (i.e. Tcl_CreateFileHandler() is not avail‐
184       able under Windows). The Windows Tcl event handler therefore must be
185       awakened occasionally for check for XPA events. This is done using the
186       standard Tcl_SetMaxBlockTime() call. The time parameter is defined in
187       tclloop.c and is currently set to 1000 microseconds (1/1000 of a sec‐
188       ond).
189
190       The version option can be used to differentiate between source code
191       versions.  It was created to support legacy Tcl code that needs to
192       maintain the 2.0.5 calling sequence for xpaaccess. You can use a ver‐
193       sion test such as:
194
195         if [catch { xparec "" version } version] {
196           puts "pre-2.1.0e"
197         } else {
198           puts [split $version .]
199         }
200

SEE ALSO

202       See xpa(n) for a list of XPA help pages
203
204
205
206version 2.1.12                 January 26, 2010                      xpatcl(n)
Impressum