SQLite 2.8.16 for OS/2
---------------------

This is a port of the SQLite embedded SQL database library, v2.8.16, to
OS/2.

Please see http://www.sqlite.org/ for more information about SQLite.


Dependancies

sqlite.exe requires the EMX runtime environment - v0.9d at least.


Installation

1.  Copy sqlite.exe (in the bin subdirectory) to a directory on the PATH
    (sqlite_va.exe and sqlite_ow.exe don't include the readline library
     support, but also don't depend on the EMX runtime; you may copy
     either instead of, or in addition to, sqlite.exe if you wish).
2.  Copy sqlite28.dll to a directory on the LIBPATH, or make sure that
    you use BEGINLIBPATH or ENDLIBPATH appropriately.  This version of
    the DLL should be a dropin replacement for previous 2.8.x releases.
3.  If you intend compiling your own SQLite code, copy the contents
    of the include and lib subdirectories to locations appropriate for
    your development tools.


Documentation

The doc subdirectory contains the SQLite README, manpage (sqlite.1), and
HTML documentation.


Source

The src subdirectory contains the Makefile, module definition file, and
a patch file with the changes to the original source, and a patch to the
generated sqlite.h header that adds support for non-EMX compilers.


YOU HAVE BEEN WARNED

1.  While the build infrastructure requires the EMX 0.9d toolchain, the
DLL (sqlite28.dll) has been built as a standalone DLL (-Zso -Zsys EMX
gcc options) so is not dependant on the EMX runtime.  In consequence,
the library should be able to be used from any development environment
that can call OS/2 DLL APIs. The library has been compiled with 
multithread support (-Zmt), and the sqlite API is fully multithreaded, 
with certain restrictions (see the SQLite documentation for more 
information).  See item 4 below for more information about using the 
DLL with other compilers.

2.  [for developers] As a consequence of the DLL being built as a 
standalone DLL, care must be taken about releasing memory allocated 
by SQLite calls.  There are some SQLite API functions that allocate 
memory for which responsibility of deallocation is assigned to the 
caller.  The sqlite_freemem() function is used for this purpose - free()
should not be used for such memory, as your application's runtime 
memory allocator won't have any record of the memory and using free() 
will have undefined (and probably unwanted) results.

A bug of this nature was found in the SQLite interface for Python
(PySQLite), which resulted in Python dumping core when deallocation
of error message strings was attempted with free().

3.  [for developers] This port contains support for multiuser/multiprocess 
access to databases using the OS/2 file locking primitives.  Because of
architectural issues in the SQLite code, I am not completely happy
with the database locking implementation as the locking policy doesn't
allow use of OS/2's capability to wait for release of file locks, but
rather implements its own timeout strategy.  As a result, much more
attention needs to be paid to handling locking issues in 
multiuser/multiprocess applications than I believe should be necessary
- at least on OS/2 (and also Linux/*BSD).

4.  [for developers] include/sqlite.h has been modified to include support 
for compilers that don't use the _System calling convention by default, 
such as VisualAge C++ and OpenWatcom - see the sqlite.h._System.patch file 
in the src subdirectory for the changes made from the standard sqlite.h.

The files sqlite_va.exe and sqlite_ow.exe in the bin subdirectory were 
compiled with VisualAge C++ 3.65 and OpenWatcom 1.3 respectively, with 
only minor modifications required for compilation to succeed (though 
both the binaries lack readline support); the shell.c.VACPP.patch file 
in the src subdirectory contains the necessary changes.

An important consideration highlighted in the shell.c patch is the 
necessity for declaring callback functions as using the _System calling 
convention, when using compilers other than EMX's gcc.

I haven't yet attempted to use Innotek's gcc toolchain with this code.


Support

OS/2 specific issues, such as applications abnormally aborting or
issues with building applications on OS/2 with this port, can be
addressed to me at the email address below.

Issues with SQL or other general behaviour should be directed, at least
in the first instance, towards SQLite's author(s) - see the included
documentation or the SQLite home page noted above for contact details.
Note that SQLite's authors will not be able to help with OS/2 specific
issues.


Legal matters

This software is provided 'as-is', without any express or implied warranty.
In no event will the packager be held liable for any damages arising from
the use of the software.

The SQLite code has copyright disclaimed.  I quote from the source file
src/main.c:

/*
** 2001 September 15
**
** The author disclaims copyright to this source code.  In place of
** a legal notice, here is a blessing:
**
**    May you do good and not evil.
**    May you find forgiveness for yourself and forgive others.
**    May you share freely, never taking more than you give.
**
*************************************************************************
...


Andrew MacIntyre
email: andymac@bullseye.apana.org.au, or andymac@pcug.org.au
web:   http://www.andymac.org/

25 March, 2005.
