README
1Tequila - Sharing and storing global Tcl arrays over the network
2
3 This is now part of the Metakit open source distribution.
4 See the Metakit homepage at http://www.equi4.com/metakit/
5
6
7
8This is the second release of a simple server which lets a number of
9clients share and store data held in global Tcl arrays. The whole
10mechanism is based on a central server managing all TCP/IP sessions.
11
12All a client needs to do to make an array "myData" available to other
13clients and persistent, is to include the following three lines:
14
15 source tequila.tcl # load the Tequila client code
16 tequila::open localhost 20458 # connect to server on given port
17 tequila::attach myData # sets up sharing for "myData"
18
19The array's contents will be permanently stored by the server, with
20all entries transmitted to the client when attached. From then on,
21Tcl's traces and background network communication take care of all
22changes. Whenever a client changes or unsets a value, this effect
23will be propagated to all other clients currently running.
24
25Because all clients continue to use global arrays as if they were
26running standalone, Tequila can be used to build a single application
27first and *then* split it up into several parts. With care, one can
28also create long-running applications of which parts get extended and
29replaced over time without having to shut down the entire system.
30
31The Tequila server was developed as part of a long-running / multi-
32platform / multi-user project. It has been in use since April 1999.
33
34
35What you need to use Tequila
36============================
37
38Tequila consists of a server script and a client package, both written
39in Tcl. The server stores all data using Metakit, a powerful database
40library which is available for Tcl (through the "Mk4tcl" extension).
41
42There are two ways to run the server:
43
44 - Grab a version of "TclKit", which combines Tcl, Tk, and Metakit
45 in a single installation-less runtime. There are ready-to-run
46 builds of TclKit for Windows, Solaris, Linux, and more.
47
48 - Get the Mk4tcl extension and use it with your own configuration
49 of Tcl/Tk. This may be needed if there is no suitable version of
50 TclKit, or if you wish to use this with your own build of Tcl/Tk.
51
52The client side of Tequila does not require Metakit, and should work
53with every installation of Tcl/Tk (version 8.0 or newer).
54
55
56The TequiCal demo
57=================
58
59TequiCal is a small Tk utility which lets you maintain a calendar of
60yearly events, such as birthdays. It uses Tequila to store all data,
61and can be used from any workstation which has access to the server.
62Changes will be seen by other clients as soon as they are entered.
63
64This very simple demo only uses the Tequila server to share one global
65"calendar" array, even though a single server can serve many different
66clients with a wide variety of shared datasets (changes are only sent
67to those clients which have "attached" themselves to specific arrays).
68
69Running the TequiCal demo is extremely simple with TclKit:
70
71 1) Get the TclKit executable which matches your platform, then
72 uncompress it (not needed for Windows), and put it somewhere
73 on your execution search path.
74 2) Get the Tequila distribution and unpack all files if you have
75 not already done so.
76 3) Start the Tequila server using the command:
77 tclkit tequilas.tcl &
78 (use "tclkit tequilas.tcl" on Windows, then start a new prompt)
79 You should see the text:
80 Tequila server started on port 20458
81 4) Start the TequiCal demo client using the commnd:
82 tclkit tequical.tcl
83 5) Go to another terminal, xterm, or MS-DOS shell and start again:
84 tclkit tequical.tcl
85 6) Now make some changes in the calendar and watch how changes get
86 propagated between the clients, even if on different machines.
87 7) That's it. You are looking at a distributed Tcl application.
88
89You can also use Tequila with an existing installation of Tcl (ver 8),
90by downloading / installing Mk4tcl, which is a compiled Tcl extension.
91Or compile and build all the necessary pieces yourself, of course.
92
93
94The Proxy demo
95==============
96
97The latest version of Tequila supports proxy support for Mk4tcl, which
98means that the client can be set up to pass all its Metakit requests
99down to the server. By calling "tequila::proxy", clients will be set
100up so all "mk::*" calls are passed on to the server, and results are
101passed back - a basic client/server system (without locking facilities
102between clients, though). The "proxy.tcl" demo code shows how this is
103used. To run it, start the tequila server first, then run proxy.tcl.
104
105Note: the "mk::loop" command is not implemented in this release, since
106it needs to be processed in the client. Use mk::select instead.
107
108
109-- Jean-Claude Wippler <jcw@equi4.com>
110