qddb/README Last Updated: Wed Nov 6 09:16:54 EST 1991 Pre-release version 1.9.5 Copyright (c) 1991 Eric H. Herrin II All rights reserved. Redistribution and use in source and binary forms are permitted provided that the above copyright notice and this paragraph are duplicated in all such forms and that any documentation, advertising materials, and other materials related to such distribution and use acknowledge that the software was developed by Eric H. Herrin II and Raphael Finkel at the University of Kentucky, Department of Computer Science. The names of the University or the authors may not be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. ------------------------------------------------------------------------------ This is the QDDB package developed at the University of Kentucky. QDDB stands for 'Quick and Dirty DataBase' (due to the nature of its origin) and is merely a distraction at the moment. We are starting to find the project useful, so we are releasing a version so that others may benefit from our work. The program(s) are currently in beta condition, so there are undoubtedly numerous bugs that we would appreciate hearing about. We would also appreciate hearing about improvements that you may make or programs that use our libraries. Suggestions and bug reports are also quite welcome. The first real release will be available as soon as I can finish it, but don't hold your breath. The current documentation may have some mild inaccuracies or shortcomings, so if you discover one, let me know! This release fixes all known bugs (up to the time of release). There might be screen and report generators in the future if I have time. If you remember that the code is written by one person in his spare time (occasionally:-), then life, the universe and everything will be just peachy. Feel free to use this code as you like, make improvements and enjoy! Also, feel free to make suggestions about useful utilities you would like to see. Please send all qddb related correspondence to: Eric H. Herrin II eric@ms.uky.edu 915 Patterson Office Tower Dept. of Computer Science University of Kentucky Lexington, KY 40506 Upcoming features ----------------- 1. Qsql interpreter should be ready for distribution sometime in early 1992. 2. More helpful features to allow the programmer to manipulate attributes within a tuple. 3. More example utilities; new ones will use X Window. -----------------------------*****Instructions!!!!*****------------------------- Qddb currently runs on many versions of UNIX. The following is a list of known versions (or previously known versions marked with *): symmetry (Sequent Symmetry: Dynix 3.0.12) ultrix (Vaxen, DECstations: Ultrix 3.1) sunos (Sun3,SparcStation: SunOS 4.1) svr2 (UnixPC: AT&T System V V3.51) * svr3 (i386,3b2: AT&T System V Release 3.2.2) * bsd (for generic BSD variants. Adding a new machine type recommended) * svr4 (i386,i486: AT&T System V Release 4.0) posix (not yet) *** IMPORTANT NOTES **** ------------------------------------------------------------ You will need both bison 1.14 and flex 2.3.7. Earlier versions may work, but I have no way of knowing for sure. Bison 1.11 has a bug in it that must be fixed before QDDB can be built with it. Remove the yylloc argument in the definition of: #define YYLEX yylex(&yylval, &yylloc) in bison.simple. This produces: #define YYLEX yylex(&yylval) Bison 1.14 works fine. We are currently using bison version 1.14 and flex 2.3.7 for testing on System V release 4.0, Dynix, Ultrix, and SunOS. We no longer have machines running under the other operating systems, so we can't really test them. You may use lex and yacc iff you are willing to make it work. I won't deal with them. We will likely support HPUX and any other machines we happen to obtain. If you have a problem, let me know and we'll try to work something out. Configuration -------------------------------------------------------------------------------- To prepare the distribution for configuration, you will need to edit the file Conf.sh in the ./Config directory. There are several definitions there that may need to be changed for your local site. You may configure the distribution to use a particular version, say svr4, by issuing the following command from the top-level directory: $ ./Setup svr4 You may like to browse the Conf.sh file in the ./Config directory to choose compilation options, installation directories, etc. before issuing the Setup command. Once the distribution has been 'Setup', you may issue a 'make' in the top-level directory to make the binaries and libraries. 'make install' will install the distribution in the place specified in Config/Conf.sh. 'make clean' cleans .o files, while 'make clobber' cleans the distribution so that you can Setup for another OS type. 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. If your version of UNIX isn't listed above, try one that looks close to it and see if it works. If not, make an entry in Setup and send me the diffs! Use appropriate #ifdef WHATEVER preprocessor commands to isolate your changes for your new machine type. Let me know if you have compiled on a new machine (i.e. one not listed above) and I'll add it to the list. Send diffs if necessary. GENERAL USAGE: (i.e. getting started quick) -------------------------------------------------------------------------------- To build a new database: $ qnewdb MyRelationName $ #<edit MyRelationName/Schema to add the Schema> $ qadd MyRelationName # add one entry To stabilize a database: $ qstab MyRelationName $ qkeys MyRelationName $ qindex MyRelationName Remember that the order of these 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. ADDING A NEW MACHINE/OS TYPE -------------------------------------------------------------------------------- When you add a new machine type to the list of supported machines, you should modify the 'Config/OSspecSetup' file for your new machine (just add a new case in the case statement that defines necessary constants). If your machine is an SVR3 variant (or any other), with some modifications to that variant, make sure that you embed your #ifdef WHATEVER commands (in the C code) within the existing #ifdef SVR3 commands and define both SVR3 and WHATEVER for the new case in OSspecSetup. Likewise for BSD, SVR2, etc. You should be able to look at OSspecSetup and figure out what needs to be done. If you can't, you should probably have someone else do it, it should be pretty simple for an experienced programmer. Please send any modifications you make (i.e. adding machine types, fixing bugs, etc) to eric@ms.uky.edu for inclusion in the next update. All fixes will be attributed to the contributor. Documentation: -------------- The 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 Finkel Computing Systems, Vol. 4 No. 2, Spring 1991, PP 127-155 If you do not have access to this journal, we can probably make arrangements to provide you with a copy. Manual pages are provided for the most useful routines and all of the provided utilities.
