
qddb/README
Last Updated: Wed Apr  5 08:32:22 EDT 1995
Version 1.42
 
 Copyright (C) 1993, 1994, 1995 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 

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

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 authors
may be reached at the above address (or via e-mail to eric@ms.uky.edu 
and/or raphael@ms.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.  The program(s) are currently in BETA condition, so there are 
undoubtedly numerous bugs that we would appreciate hearing about.  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 SQL92) and other 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.
I 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
ill experiences.

Upcoming features
-----------------
1. Improved methods for manipulating schemas on existing databases.
2. Spreadsheet-style access to tuples.
3. Approximate matching (search technique)

There is a guide to Qddb in Doc/Manual.   It is incomplete, but there is quite 
a bit there.   Please let me know of suggestions you have or typos in the 
manual.

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

Qddb currently runs on many versions of UNIX.  

*** IMPORTANT NOTES ****
------------------------------------------------------------
You will need both bison 1.22 and flex 2.4.7.  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.22 and flex 2.4.7 for
testing on BSD/386, Linux, Dynix, OSF/1, 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 UnixWare, 
FreeBSD, and NetBSD.

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

*** Configuration ***
-------------------------------------------------------------------------------
Qddb now uses the GNU autoconf utility to automatically configure itself.
To configure Qddb, type (for example):

    $ export CC=gcc2 CFLAGS="-O3 -m486" MAKE=gmake
    $ ./configure

If you have TCL/TK, [incr Tcl] and/or BLT libraries in a place that Qddb 
can find, you can include them with:

    $ ./configure --with-tk --with-itcl --with-blt

Otherwise, you can specify the directories for Xpm and BLT with:

    $ XPM_LIBRARY_DIR=/usr/myXdir/lib BLT_LIBRARY_DIR=/usr/mylocaldir/blt/lib \
	  ./configure --with-tk --with-xpm --with-blt

Note that --with-xpm and --with-blt require --with-tk (xpm and/or blt will be 
ignored otherwise.)  

Also, the following configure options are available (in addition to the 
standard stuff):

	1) --with-diagnostics: turn on various sanity-checking mechanisms.
			       (Highly recommended)
	2) --with-gnumalloc:   use GNU malloc (under Lib/GNUmalloc).
	3) --with-mallocstats: print malloc statistics at stabilization. 
                               (NOTE: automatically includes --with-gnumalloc.)
	4) --enable-maxmem=X:  set maximum Qddb stabilization growth to 'X' 
                               kilobytes.  (NOTE: 5MB is the default, 
                               reasonable for a 16MB machine.)  This number 
                               is just a soft limit; qindex may grow somewhat
                               larger if necessary.
	5) --disable-maxmem:   disable maximum stabilization growth.
                               (NOTE: this option is not recommended)
	6) --with-default-editor=/X/Y/editor
                               Change the default editor to /X/Y/editor
                               for qedit/qadd.
	7) --with-tcl:         Compile & install qddb_tclsh
		TCL_LIBRARY_DIR
	8) --with-tk:          Compile & install BOTH qddb_wish & qddb_tclsh
		TK_LIBRARY_DIR
	9) --with-xpm:         Required if TK libraries are compiled with XPM 
			       extensions (TkPixmap).
		XPM_LIBRARY_DIR
       10) --with-blt:         Include BLT TK extensions in qddb_wish
		BLT_LIBRARY_DIR
       11) --with-tcltcp:      Include TclTCP-2.X in qddb_{tclsh,wish}
		TCLTCP_LIBRARY_DIR
       12) --with-tclx:        Include TclX in qddb_{tclsh, wish}
		TCLX_LIBRARY_DIR
       13) --with-expect:      Include expect in qddb_{tclsh, wish}
		EXPECT_LIBRARY_DIR
       14) --with-tktable:     Include TkTable-0.2 in qddb_wish
		This package is included in Qddb for convenience
       15) --with-itcl:        Include [incr Tcl] in qddb_{tclsh,wish}
                ITCL_LIBRARY_DIR
       16) --disable-record-locking: Disable fcntl-style record locking.
                               (NOTE: enabled by default)
       17) --with-default-date-format=%d/%m/%y:
                               Change default format of dates to dd/mm/yy.

See MACHINE SPECIFIC NOTES below for info on these options for particular 
architectures.

Once the distribution has been configured, you may issue a 'make' in the 
top-level directory to make the binaries and libraries.   'make install' will 
install the distribution and install in the place specified by --prefix 
(default: /usr/local/qddb).  'make clean' cleans object files, while 
'make distclean' cleans the distribution so that you can re-configure for 
another OS type.

NOTE: Some versions of make won't work well with Qddb.  You might want to use 
GNU make instead.

The documentation in ManPages explains each command and library call.  The
postscript version of a tech-report is included in Doc, so that you can
get a better idea of the goals we had while building the code.   In Doc/Manual
you will find a fairly nice manual: "A Guide to Qddb."

MACHINE SPECIFIC NOTES:
-------------------------------------------------------------------------------

* DEC Alpha OSF/1:

    When configuring, you should use the standard C compiler:
	CC="cc -std1" ./configure [options]

    Qddb apparently brings out a bug in GCC on the Alpha, so don't use GCC
    on DEC Alphas.

    --with-mallocstats and --with-gnumalloc cannot be used with DEC Alpha OSF/1
    --enable-maxmem=22528 seems to be about right for an active 64MB DEC Alpha.

* BSD/386 V1.1, BSD/OS V2.0:
    Configure with:
        $ export CC=gcc2 CFLAGS="-O3 -m486" MAKE=gmake
        $ ./configure <options> 

* Solaris 2.3:  Tcl seems to include compat/dirent.h, compat/getcwd.c and 
    compat/opendir.c when it shouldn't.   It also seems to use 
    compat/dirent.h.   Force the configure script not to use the compat stuff.

* SunOS 4.1.3:
    Only tested with GCC.

* Linux: Linux record locking is very broken, (as of 1.1.69 or so) so if 
    you have problem, try configuring with --disable-record-locking.   Qddb 
    attempts to work around Linux' record locking problems.  We currently 
    know of no problems with our workaround.

You should refer to the manual in Doc/Manual for more information.

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 new nxqddb.1 manual page (ManPages/man1/nxqddb.1).   It explains
most of what you need to know to get started.   The Doc directory includes 
some pretty good info too.   Doc/Manual is especially useful for beginners.

ADDING A NEW MACHINE/OS TYPE
-------------------------------------------------------------------------------

If you add a new machine type, please send me the diffs to configure.in and 
any sources you modify so that I can incorporate the changes in the next 
release.   If no changes were necessary, please send me a note to let me
know that it works on another OS/architecture.

Please send any modifications you make (fixing bugs, etc.) to 
eric@ms.uky.edu.   If you build a neat specialty application that is 
generally useful, send us a copy and we'll include it in the upcoming 
Qddb application archive.

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

    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

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.

