
qddb/README
Last Updated: Fri Mar  7 17:25:57 EST 1997
Version 1.43 GNU
 
 Copyright (C) 1993-1997 Herrin Software Development, Inc.
 All rights reserved.

 This file is part of Qddb.

 Qddb is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License Version 2
 as published by the Free Software Foundation.

 Qddb is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.

 You should have received a copy of the GNU General Public License
 along with Qddb; see the file LICENSE.  If not, write to:

	Herrin Software Development, Inc. 
	R&D Division
	41 South Highland Ave. 
	Prestonsburg, KY 41653 
	http://www.hsdi.com

------------------------------------------------------------------------------

This is the successor to the QDDB package originally developed by Eric H. 
Herrin, II and Raphael A. Finkel at the University of Kentucky.   The 
original authors may be reached at the above address (or via e-mail to 
eric@hsdi.com and/or raphael@cs.engr.uky.edu).

QDDB stands for 'Quick and Dirty DataBase' (due to the nature of its origin) 
and is rapidly evolving.  Most of the code has changed drastically (or has 
been totally rewritten) from the original version and is now much more 
stable.   Suggestions and bug reports are also quite welcome.

This version of Qddb is a release that updates Qddb 1.9.5 with various
bug fixes and enhancements (like a generic TCL/TK interface).  The new Qddb has 
an incompatible API with Qddb 1.9.5, so any code you wrote for V1.9.5 cannot 
be used with this version.   Qddb 2.0 will be the first complete release 
containing Qsql (based on SQL9X) and other major enhancements.

There is a mailing list 'qddb-users@ms.uky.edu' that you can subscribe to 
for general discussion/information about qddb.  Send mail to:

	'qddb-users-request@ms.uky.edu'

with the subject of 'subscribe' and a body containing your name/e-mail address.
To UNSUBSCRIBE from the mailing list, send an e-mail message to
'qddb-users-request@ms.uky.edu' with the subject of 'unsubscribe' and
a body containing your name/e-mail address.   (Please do *not* send subscribe
and unsubscribe requests to the mailing list qddb-users@ms.uky.edu!)  We
monitor (not moderate) this list and I will usually answer posted 
questions.   For bug reports, you may wish to submit them to both 
'qddb-users@ms.uky.edu' and 'qddb-bugs@ms.uky.edu' so that other qddb 
users may benefit from your experiences.


-------------------------*****Instructions!!!!*****--------------------

Qddb currently runs on most versions of UNIX.

*** IMPORTANT NOTES ****
------------------------------------------------------------

If you have never installed a Qddb distribution, you should start by
reading the "INSTALL" file in the top-level directory.   There are
several very useful notes in INSTALL that should get you started
quickly.

You will need both bison 1.25 and flex 2.5.4.  Earlier versions may work,
but I have no way of knowing for sure.   Also, later versions may break
things (for example, flex tends to break qddb from release to release), but
the compile usually fails so you'll know if this happens.   We generally
keep up with the latest releases of these tools.

We are currently using bison version 1.25 and flex 2.5.4 for
testing on BSD/OS, Linux, FreeBSD, HP/UX, SunOS and Solaris.  We 
no longer have machines running under any other operating systems, 
so we can't really test them.  We have reports that it runs under 
IRIX, UnixWare, OSF/1, Ultrix, and NetBSD.   If your company wants
a particular platform well-supported, just send us a machine, OS,
and compiler tools.

We use several unique features of flex and bison, so lex and yacc
are probably a lost cause.

See the file "INSTALL" in the current directory for more information
on installing Qddb.

GENERAL USAGE (getting started quick)
-------------------------------------------------------------------------------
To build a new database:

	$ qnewdb MyRelationName   # makes a relation 'MyRelationName' in the 
                                  # current dir.
        $ #<edit MyRelationName/Schema to add the Schema>
	$ qadd MyRelationName     # add one entry
	$ nxqddb MyRelationName   # startup the nifty generic Tk interface.

To stabilize a database:
	$ qstab MyRelationName
	$ qkeys MyRelationName
	$ qindex MyRelationName
or simply:
	$ qstall MyRelationName [AdditionalRelation ...]

Remember that the order of the {qstab,qkeys,qindex} commands is critical.  
qkeys and qindex (in that order) must be run AFTER qstab.  qkeys and qindex 
may be run anytime by themselves, but they will produce identical structure
files unless the relation has been stabilized with qstab or the indices
have been corrupted.  (qkeys; qindex) is useful for regenerating the indices 
if they become corrupted.  If just doing a general re-stabilization, use qstall.
(qkeys; qstab; qkeys; qindex) is needed if you manually edit the database.
qstall(1) will notice that the Database has been edited and perform the correct
operations.

Read the nxqddb.1 manual page (ManPages/man1/nxqddb.1).   It explains
most of what you need to know to get started.    For lots of up-to-date
information, see our home page at http://www.hsdi.com/qddb.

Documentation:
--------------
Some methods used in Qddb are documented in the following papers:

    An ASCII Database for Fast Queries of Relatively Stable Data
    Eric H. Herrin, II and Raphael A. Finkel
    Computing Systems, Vol. 4 No. 2, Spring 1991, PP 127-155
    (ftp.ms.uky.edu:/pub/unix/qddb/papers/qddb.ps.gz)
    (http://www.hsdi.com/qddb/article1)

    Tuple and Schema Trees: An Intuitive Structure for Representing
        Relational Data
    Eric H. Herrin, II and Raphael A. Finkel
    Computing Systems, Vol. 9 No. 2, Spring 1996
    (tech-report version -- 
        ftp.ms.uky.edu:/pub/unix/qddb/papers/255-95.ps.gz)
    (http://www.hsdi.com/qddb/article2)

Manual pages are provided for all Tcl procedures and all of the provided 
utilities.   You should be able to do most simple things with the given 
utilities, and you can write your own special interface with qddb_wish 
using the Tcl procedures.

More papers are in the works, stay tuned!


