
                            Zild Database Library
                                       
 Introduction
 ------------

 The Zild Database Library implements a small, fast and easy to use 
 database API with the following features: C database library - 
 connect to multiple database systems - zero runtime configuration,
 connect using URL scheme - Thread safe Connection Pooling and exceptions
 handling.

 This database library is part of the Zild Application Server, see
 http://www.zild.org/ and is released as Open Source with the hope 
 that others may find it useful in their Open Source Work.


 System requirements
 -------------------

 * Memory and Disk space

   A minimum of 1 megabytes RAM are required and around 500KB of free
   disk space. You may need more RAM depending on how many Connections
   the library should create.

 * ANSI-C Compiler and Build System

   You will need an ANSI-C compiler installed to build the library.
   The GNU C compiler (GCC) from the Free Software Foundation (FSF) is
   recommended. In addition, your PATH must contain basic build tools
   such as make and flex.

 * Database systems
 
   This Software supports the following database systems, 
     - MySQL         - version 4.1 or above
     - PostgreSQL    - version 7.4 or above on the server side
                     - version 8.0 or above on the client side
     - SQLite        - version 3.0 or above
   Client libraries for at least one of these database systems must
   be installed on the host on which this Software will be built.

 
 Installation
 ------------
 
 This library utilize the GNU auto-tools and provided the requirements 
 above are satisfied, building the library is conducted via the
 standard;

  ./configure
  make
  make install 
 
 Use ./configure --help for build and install options. By default, the 
 library is built with support for MySQL, PostgreSQL and SQLite. You may
 change this with the --without-<database> options to ./configure. E.g.
 --without-mysql, --without-postgresql or --without-sqlite
 
 To verify the library and run unit tests, do 'make verify'. You may
 also want to take a look at the test, test/pool.c, for examples on 
 how to use the library. 
 
 Note that unit tests cannot be built if the following configure 
 switches where used; --enable-protected or --enable-zild. These
 switches are used respectively for package protect non-api objects
 in the library and for usage with the zild application server. It
 is strongly recommended to build the library with --enable-protected
 as it will be faster and reduce the risk for name symbol interposing
 
  
 API Documentation
 -----------------
 
 The directory doc/api-docs/ and index.html contains the full API
 documentation for the library, generated by Doxygen. Start by reading
 the documentation for ConnectionPool.h
 
 
 Exceptions handling
 -------------------
 
 The library implements an elegant solution for thread-safe exceptions
 handling. Use of exceptions frees programmers from the tedious return 
 code idiom for dealing with errors. The API documents every method that
 can throw an exception. Methods that can throw an exception should be 
 called from inside a try-catch block.
 

 Link and include
 ----------------
 
 Clients should include the following interfaces, in this order. 
 
 #include <URL.h>
 #include <ResultSet.h>
 #include <PreparedStatement.h>
 #include <Connection.h>
 #include <ConnectionPool.h>
 #include <SQLException.h>

 Compiling and linking with the library depends on, if database libraries 
 was linked in static or dynamic when libzdb was created. To check, use 
 'otool -L libzdb.dylib' on Mac OS X, or 'ldd libzdb.so' on Linux. If 
 database libraries was linked static you can compile and link a program 
 which use libzdb, like so (your paths may vary). Otherwise you may have 
 to explicit add a link to a database library e.g. -lsqlite3
 
 gcc -o sql sql.c -L/usr/local/lib -lzdb -lpthread -I/usr/local/include
 
  
 License Notes
 -------------

 This Software product is licensed under the GNU General Public License
 version 3, with additional exceptions to allow most BSD licensed Open
 Source Work to use and link with the Software. Contact us if you want 
 to distribute the Software under another Open Source license than those
 listed in EXCEPTIONS.

 You can use this Software product free of charge to develop, use and
 distribute Open Source application programs, including reusable
 components and other software that link with the Software. You may
 also use and modify any example source code included with the
 Software for any purpose.
 
 See the files COPYING and EXCEPTIONS accompanying the Software for
 details. 


 Reporting a bug
 ---------------

 If you believe you have found a bug, please send this information,
 plus information about the machine and OS platform used along with a
 description of the problem to bugs-libzdb@tildeslash.com


 Questions and support
 ---------------------

 If you have questions or comments about the software or documentation 
 please subscribe to the libzdb general mailing list and post your 
 questions there. 
 
         http://www.tildeslash.com/mailman/listinfo/libzdb-general


 Contact information
 -------------------

 The Zild Database Library is a product of Tildeslash Ltd. a company 
 registered in Norway and in United Kingdom.
 
 For further information about this Software, please use the following 
 contact information.

 E-mail:
   info@tildeslash.com

 Telefax:
   All inquiries: +47 22 71 29 99

 Internet:
   http://www.tildeslash.com/
   

 Acknowledgments
 ---------------

 The design of this library was inspired by principles put forth by 
 David R. Hanson <drh@drhanson.net> in his excellent book, 
 "C Interfaces and Implementations". You can learn more about this 
 book here, http://www.cs.princeton.edu/software/cii/

