Mckoi SQL Database Beta ReadMe
------------------------------

This is a Beta release of the Mckoi SQL Database engine.  The homepage for
this project is at 'http://www.mckoi.com/database'.


IMPORTANT INFORMATION FOR UPGRADING OF DATA BEFORE VERSION 0.88
===============================================================

Version 0.88 sees the introduction of transactions.  Transaction support
required a rewrite of the format of the database files.  Any database
files that you have made with versions of the software before version
0.88 will need to be converted to the latest format.  Before converting
the data files it is recommended you back up the data first.

To convert the data files, use the following command from the
distribution directory;

java -cp mckoidb.jar com.mckoi.tools.DataFileConvertTool \
     -dbpathsrc [source directory] -dbpathdst [destination directory]

Substitute [source directory] with the location of your pre version
0.88 data files, and [destination directory] with the directory to
write the latest format data files.  If is best not to convert the
files into the same directory as the old version.

If you have any problems converting old data then contact
toby@mckoi.com.



Installing the software
-----------------------

To use this software, you need a Java runtime environment version 1.2 or
greater.  See the FAQ for details on where to get a Java runtime.

Unpack the zip file to a directory in your file system.  Most Java
developer kits come with a utility called 'jar' which can be used to
unpack the distribution file.  Type 'jar xvf [zip file]' at a prompt
to unpack the distribution into the current directory or you can
use another unzip package.  A popular zip package on the  Microsoft
Windows platform is WinZIP.  Most modern Unix systems ship with an
'unzip' utility.


What's in this distribution?
----------------------------

This distribution includes the source code as well as the compiled binary
class files.  It also includes tools/documentation and demonstrations of
a simple application using the database.  The binaries were compiled
using the Sun javac compiler.

Below is a description of the files/directories in this release;

demo/        - Demonstrations of a simple database application.
docs/        - HTML documentation.
test/        - Test script demonstration.
db.conf      - A typical database configuration file.
gnu-regexp-1.0.8.jar
             - The GNU regular expression library.
gnu-regexp-1.0.8-src.zip
             - The source and LGPL license for the GNU regular
               expression library.
mckoidb.jar  - The complete compiled database class files.
mkjdbc.jar   - Only the JDBC Driver class files.
src.zip      - The database source code.
LICENSE.txt  - The GPL license the software is distributed under.
README.txt   - This file.


Building the binaries
---------------------

First you will need to unpack the source files that are archived in the
src.zip file.  You can use the command 'jar xvf src.zip' to unpack the
source.  To build the binaries into a 'lib' sub-directory, use the
following commands (from the distribution directory);

  mkdir lib
  javac -classpath src;lib;gnu-regexp-1.0.8.jar -O -d lib/ \
      src/com/mckoi/runtime/McKoiDBMain.java \
      src/com/mckoi/JDBCDriver.java \
      src/com/mckoi/database/jdbcserver/LocalDatabaseInterface.java \
      src/com/mckoi/tools/*.java \
      src/com/mckoi/database/regexbridge/GNURegex.java

You will get some deprecation warnings but they can be safely ignored.

Note that Unix and Windows use different path separators.  Windows uses
the semi-colon (;) character and Unix uses colon (:).  The build command
under Unix will need ';' replaced with ':'.

JavaCC, the Java compiler compiler, was used to build the SQL parser.
You may still compile the source without JavaCC however you will not be
able to change the grammar.

JavaCC is available at 'http://www.metamata.com/JavaCC/'.

To compile the grammar with JavaCC, use the following commands;

  cd src/com/mckoi/database/sql
  javacc SQL.jj


Contacting the Author
---------------------

My email is 'toby@mckoi.com'.  If you have any general comments or
questions about the software a mailing list has been set up at
'http://www.mckoi.com/database/index.html#support' for this purpose.