file: ptcl/README
TRott, Sun Oct 19 19:22:51 CEST 1997

	ptcl: persistent Tcl variables
	------------------------------

As you may know the value of Tcl variables will be lost if you
terminate the process containing it (mostly tclsh or wish).
You will have to write some code to save and reload the variables
that should be available at the next invocation of your program.

The basic idea of "persistent" variables is to do this transparent
and automatically for variables that are "declared" to be persistent.
For example:
>tclsh
% persistent myvar
% set myvar somevalue
% exit

... more processes to be run ...

>tclsh
% persistent myvar
% puts $myvar
somevalue
% ...

I hope this gives an idea of persistent variables and how they can be used
to store things like setup information or user preferences.

Making Tcl a persistent language can be achieved very easily because:
	(1) every Tcl value can be written and parsed as a string
	(2) Tcl's sophistcated variable traces
	(3) Tcl's exithandlers

All you need to do is using something like gdbm to store the variables
in a portable and fast way. Since these standard dbm packages use
key hashed access methods (just like Tcl itself), it is easy to intercept
the first read access to a variable and load the dbm-file stored value
for it. A write access to a persistent variable marks it "dirty" and
consequently an unset on it marks it's name for later deletion from
the dbm-file. Finally, at exit time, the exithandler updates the
"persistent storage".

Performance should be nearly optimal on scalar variables since
all traces are only once triggered. After the first read (or write)
access they perform exactly like other scalar variables.
If you declare an array to be persistent, the traces are called
at any access, because new array components may be added. This makes
whole persistent arrays sligthly slower.
Please note, that it is not known it advance if a nonexistent variable
name will later be an array or scalar. The best you can do, is to
set some component of your array and declare it afterwards persistent.
This way the array is known as such and further accesses to other components
will behave as expected.

The "persistent storage"-file will show up in your home directory, having
the name of your application (from argv0). It can be shared by several
instances of your application for reading, but only the last one of it
will be able to copy back its values-- the persistent storage is
not a multiuser database (maybe I will use tdbm to overcome this limitation).

And, of course, only global variables can be declared persistent.

This is a Tcl-8.x extension package that uses the Tcl-Object interface.
You will need the gdbm package both a compile- and at runtime.
This extension has been built and tested under:
	Linux (2.0.17), Tcl-8.0 (final) and gdbm (1.7.3)

How to build & use it:
	(1) Untar the package: tar xvzf ptcl.tar.gz
	(2) change to ptcl and make it: cd ptcl;make
	(3) copy the extension to a place of your choice
	(4) use it by loading: load ./ptcl[info sharedlibextension]
	    or by a "package require"
	(5) declare something with the "persistent varName ?varName?" command
	(6) hack away...


  /-----------------------------------------\
  | Copyright (c) 1997 by Torsten Rottmann  |
  | 31162 Bad Salzdetfurth, Griesbergstr.11 |
  | Germany, Phone: (+49)05063/5710	    |
  | eMail: trott@rottmann.hi.shuttle.de     |
  \_________________________________________/
 
  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, version 2.
  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABLITY or FITNESS FOR A PARTICULAR PURPOSE.