Equi4 Software                                                  [www.equi4.com]

                            MetaKit for TCL
                              version 0.2 


This is a preview release of the Tcl interface to a flexible and efficient
C++ storage library. The main reason for making this code available at 
this stage is to offer proof of concept, and to sollicit feedback at an 
early stage to arrive at a "natural" interface for use in Tcl. 


About MetaKit 

   * Stores highly structured binary data, can scale to millions of entries 
   * Data files are very compact, their structure can be changed instantly 
   * Fail-safe storage, commit/rollback, on-demand loading, can be streamed 
   * Portable, both the code (Unix, Windows, Mac, VMS) and the data files 

Some more facts about this library: MetaKit has been field-tested in many
thousands of copies, the Win32 DLL is under 100 Kb, ports are freely available
(source license is required for royalty-free commercial use), this product 
is actively supported and extended. 


About this Tcl extension 

   * The extension is packaged as shared library, and uses the "mk::" namespace 
   * The Tcl interface is still young, ugly things like memory leaks can happen 
   * There is not yet an interface to use derived views, joins, selections, etc 
   * Streaming is to and from file only, there is not yet a channel interface 

Visit the MetaKit homepage at [http://www.equi4.com/metakit/] for latest news. 
Send problem reports/suggestions to jcw@equi4.com, this is a supported product. 


Installing MetaKit for Tcl on your system

  [Note: if this package contains "mk4tcl.so", then that's a build for Linux]

To build and install MetaKit for Tcl, you must have MetaKit 1.8 on your system,
since this extension requires header "m4kit.h" and links to the "-lmk" library.
You only need an appropriate binary distribution, not the MetaKit source code.
See the release list for the latest builds:  http://www.equi4.com/metakit/info/

Once you have that, you can go through the usual motions:
	% ./configure
	% make
	% make test
That last step runs a simple "demo.tcl" script.  MetaKit for Tcl is a standard
package, you can install it anywhere and use it with "package require mk 0.2".

I have only built this extension on Linux (2.0.32), if you intend to try this
stuff on any other platform, I'd love to hear about it!  (email: jcw@equi4.com>

                                                    -- Jean-Claude Wippler


===============================================================================


 TERMINOLOGY

     MetaKit uses the following model: a file contains a number of
     views (tables).  Each view hold zero or more rows (records),
     all consisting of a number of common properties (attributes).
     Views may be nested, by defining subview properties in rows.
     
     A cursor is a lightweight iterator for a view or subview.
     To refer to a specific subview you must specify its path.
     Datafiles are accessed via a tag, as specified when opened.


 VIEW STRUCTURES

     View structures are described using a list of property names,
     a ":X" suffix must be used to specify non-string datatypes:

         name        string, using only as many characters as needed
         name:I      integer, automatically adjusts to use 1..32-bit
         name:F      single precision floating point
         name:D      double precision floating point
         name:B      binary data (like string, may include 0-bytes)
         name:M      memo data (binary, better for large entries)

     Subview properties are specified as a list with a sublist:

         {subview {prop ...}}

     The datatype must be specified whenever the property is used.
     This is an artefact of the current setup, to be changed later.


 SYNTAX

     path ::= tag.view[!row.view]*
                     a path describes a specific (sub-) view
     cursor ::= tag[.view!row]+
                     a cursor refers to a row in a view

     Note: cursors may be used anywhere where paths are expected.


 LINKED TO TCL 8.0 DLL'S FOR USE ON WIN 95/NT

     package require mk
                     see the "demo.tcl" script for a few examples


 DATAFILE SETUP - RETURNS TAG

     mk::file open tag filename ?-readonly? ?-nocommit?
                     nocommit prevents automatic commit on close
     mk::file close tag
                     close datafile
     mk::file commit tag
                     commit now
     mk::file rollback tag
                     rollback now


 RESTRUCTURING, REMOVING VIEWS - RETURNS PATH

     mk::view layout tag.view {structure}
                     defines or restructures view as needed
     mk::view delete tag.view
                     removes entire view (permanent once committed)


 GET/SET THE SIZE OF A VIEW

     mk::view size path
                     returns size
     mk::view size path size
                     resizes view, returns path


 INSERTING, REMOVING, REPLACING ROWS - RETURNS CURSOR
     
     mk::row ?create? ?prop value ?...??
                     returns cursor to a fresh temporary row
     mk::row append path ?prop value ?...??
                     add a new row, optionally setting values
     mk::row insert cursor cursor2 ?count?
                     insert row at cursor2 before cursor
     mk::row delete cursor ?count?
                     delete row(s) at cursor
     mk::row replace cursor cursor2
                     copy row at cursor2 over row at cursor
     mk::row replace cursor
                     clear contents at cursor


 CURSOR POSITIONING - RETURNS CURSOR

     mk::cursor ?create? cursorName path ?index?
                     set up a cursor for a view, default index is 0
     mk::cursor position cursorName 0
                     reposition cursor to first row
     mk::cursor position cursorName end
                     reposition cursor to last row
     mk::cursor position cursorName index
                     reposition cursor to specified row
     mk::cursor position cursorName
                     returns current cursor position
     mk::cursor incr cursorName ?step?
                     advance the cursor by given step, or by 1


 CURSOR ITERATION

     mk::loop cursorName {cmds...}
                     perform cmds for each row (cursor must exist)
     mk::loop cursorName path {cmds...}
                     perform cmds for each row in specified path
     mk::loop cursorName path first ?limit ?step?? {cmds...}
                     default limit is past end, default step is 1


 GET/SET PROPERTY VALUES

     mk::get cursor
                     gets all property value(s) as keyed list
     mk::get cursor prop ?...?
                     gets specified property value(s)
     mk::set cursor prop value ?prop value ?...??
                     sets property value(s), returns cursor


 LOADING/SAVING AS STREAMING BINARY DATA - RETURNS TAG
     
     mk::file load tag filename
                     ### only from file right now
     mk::file save tag filename
                     save all data in "serialized" format




Copyright (C) 1998 Equi4 Software. All rights reserved. 

