SQLite 3.6.12 for OS/2
----------------------

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

Please see http://www.sqlite.org/ for more information about SQLite, 
include the documentation.


Dependancies

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


Installation

1.  Copy sqlite3.exe (in the bin subdirectory) to a directory on the PATH 
    (sqlite3va.exe and sqlite3ow.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, sqlite3.exe if you wish).
2.  Copy sqlite36.dll to a directory on the LIBPATH, or make sure that 
    you use BEGINLIBPATH or ENDLIBPATH appropriately.
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

Please refer to http://www.sqlite.org/


Source

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

Note that this port is based on the amalgamated source (ie 1 source file 
- sqlite3.c) release distributed as sqlite-amalgamation-3_6_12.zip, with 
the shell source taken from the standard v3.6.12 source tarball.  Using 
the amalgamated source simplifies the makefile considerably, though in my 
experience the performance gain which the SQLite authors claim arises 
from better optimisation possibilities using this technique are negligible 
with the compilers I use.


YOU HAVE BEEN WARNED

1.  While the build infrastructure requires the EMX 0.9d toolchain, the 
DLL (sqlite36.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 with the System calling convention. 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 5 below for more 
information about using the DLL with other compilers.

2.  This port is still restricted to 2GB file sizes :-(

3.  I have enabled the fts3 and rtree SQLite extensions - please refer 
to the documentation at http://www.sqlite.org/ for more information about 
this functionality.  I would have liked to also enable the icu extension, 
but that will require a bit of work to sort out the Unicode interface.

4.  [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 sqlite3_free() 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.

5.  [for developers] include/sqlite3.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 
sqlite3.h.patch file in the src subdirectory for the changes made from 
the standard sqlite3.h.

The files sqlite3va.exe and sqlite3ow.exe in the bin subdirectory were 
compiled with VisualAge C++ 3.65 and OpenWatcom 1.7a respectively, with
only minor modifications required for compilation to succeed (though
both the binaries lack readline support); the shell.c.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.

Be warned however that OpenWatcom (1.7a at least) has some level of 
incompatibility with the EMX toolchain for the function sqlite3_vmprintf().
The va_list implementation differences between the toolchains are 
significant enough that the 2nd and subsequent variable parameters are 
received incorrectly by the DLL function (the 1st variable parameter 
is okay). VAC++ 3.6.5 doesn't appear to have the same problem.

I haven't yet attempted to use Innotek's gcc toolchain with this code, 
though others have (without the patches in this port).

6.  This release has had only cursory testing.  Caveat utilitor....
Note that there is a very rudimentary test harness in the src 
subdirectory - read src/test_notes.txt for more information.


Credits

Daniel Kruse and Peter Weilbacker have been doing the lion's share of 
keeping SQLite supported on OS/2.  Peter has merged as many of the 
changes to support the EMX, VAC++ and OpenWatcom toolchains as is 
practical.  Thanks to you both!


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 though as I didn't write 
most of the OS/2 code in this release I mightn't be that much help :-|

Issues with SQL or other general behaviour should be directed, at least
in the first instance, towards SQLite's author(s) - see the SQLite home 
page noted above for contact details.

Note that SQLite's authors may not be able to help with OS/2 specific
issues, though they should be able to forward any issues to the 
contributor of this support.


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/

13 April, 2009.
