1xpatcl(n) SAORD Documentation xpatcl(n)
2
6 XPATcl: the XPA Interface to the Tcl/Tk Environment
7
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 Server Routines
13 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 Client Routines
27 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
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 int XPATclAddInput(XPA xpa);
49 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 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
58 environment using the Tcl language directly. The XPA/Tcl interface can
59 be loaded using the following package command:
60 package require tclxpa 2.0
62 Alternatively, you can load the shared object (called libtclxpa.so )
64 directly:
65 load .../libtclxpa.so tclxpa
67 Once the tclxpa package is loaded, you can use Tcl versions of XPA
69 routines 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 The file test.tcl in the XPA source directory gives examples for using
75 the XPA/Tcl interface.
76 The following notes describe the minor differences between the
78 interfaces.
79 XPANew
81 set xpa [xpanew class name help sproc sdata smode rproc rdata rmode]
83 rproc and sproc routines are routines. The calling sequence of the
85 rproc routine is identical to its C counterpart:
86 proc rec_cb { xpa client_data paramlist buf len } { ... }
88 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 proc sendcb { xpa client_data paramlist } { ... }
93 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 xpasetbuf xpa buf len
101 where:
103 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 When this routine is called, a copy of buf is saved for transmission to
111 the client.
112 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 fillbuf=false
118 in the xpanew smode and then perform I/O through the Tcl channel
120 obtained from:
121 set dchan [xparec $xpa datachan]
123 where:
125 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 NB: datachan and cmdchan are not available under Windows. It is
133 necessary to use the "raw" equivalents: datafd and cmdfd.
134 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 The send and receive callback routines can use the xpaerror and
141 xpamessage routines to send errors and messages back to the client. If
142 you also want tcl itself to field an error condition, use the standard
143 return call:
144 return ?-code c? ?-errorinfo i? ?-errorcode ec? string
146 See the Tcl man page for more info.
148 XPARec
150 The Tcl xparec procedure supplies server routines with access to
152 information that is available via macros in the C interface:
153 set val [xparec xpa <option>]
155 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
161 determine the XPA version used to build the Tcl interface. Note that
162 the 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 NB: datachan and cmdchan are not available under Windows. It is
167 necessary to use the "raw" equivalents: datafd and cmdfd.
168 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 Under Windows, the Tcl event handler cannot automatically sense when an
183 XPA socket is ready for IO (i.e. Tcl_CreateFileHandler() is not
184 available under Windows). The Windows Tcl event handler therefore must
185 be awakened occasionally for check for XPA events. This is done using
186 the standard Tcl_SetMaxBlockTime() call. The time parameter is defined
187 in tclloop.c and is currently set to 1000 microseconds (1/1000 of a
188 second).
189 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
193 version test such as:
194 if [catch { xparec "" version } version] {
196 puts "pre-2.1.0e"
197 } else {
198 puts [split $version .]
199 }
200
202 See xpa(n) for a list of XPA help pages
203version 2.1.15 July 23, 2013 xpatcl(n)