qddb/README Last Updated: Thu Feb 27 15:22:28 EST 1997 Version 1.43 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. $ # $ 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!