$Id: README,v 1.19 2004/10/07 03:35:27 wwg Exp $

                The APQ Ada95 Binding to PostgreSQL & MySQL
                         Warren W. Gay VE3WWG
			mailto:ve3wwg@cogeco.ca
                     http://home.cogeco.ca/~ve3wwg
                           APQ Version 2.2

The software you have in this directory, when compiled and installed, is
the APQ Ada95 binding to the PostgreSQL, MySQL and Sybase database servers.
For C/C++ types, this "binding" represents an interface between the
Ada95 language, and the C language libraries provided by those database
products.

Why use APQ over other products?


APQ Features:
-------------

  - It is a thick binding, making it natural for Ada programmers.
  - It is very simple to use, making programming easy.
  - Can be used with strong Ada types.
  - Generic procedure and function support for strong types.
  - Supports multiple database engines generically
  - MySQL supported as of APQ-2.0
  - Sybase supported as of APQ-2.2
  - Database neutral code is possible (portable)

  - Full BLOB support (for PostgreSQL)
  - Blob I/O is performed through Ada95 stream I/O.
  - High performance blob I/O through buffered stream I/O
  - Optionally blob I/O can be unbuffered.

  - Native binding (no ODBC muss or fuss!)
  - Full support for NULL values.
  - Additional support for DATE, TIME and TIMESTAMP data types.
  - Some support for TIMEZONE types (PostgreSQL)
  - Supports bit string types (PostgreSQL)
  - Leaves the SQL in human readable form

  - 4 levels of tracing for application debugging
    - Trace_None  (no tracing)
    - Trace_DB    (C library trace information only)
    - Trace_APQ   (SQL query trace information only)
    - Trace_Full  (both Trace_DB and Trace_APQ)
  - Trace_APQ output can be fed as SQL text for testing

  - Dual-license :
    - ACL (Ada Community License)
    - GPL2 (GNU Public License)

  - Extensive manual, with examples for nearly every function.
  - Manual includes a chapter on generic database programming.

  - Experimental support of the Decimal_Type package (using
    decimal routines used internally by the PostgreSQL database
    engine).
  - Under active development

Design Goals:
-------------

The main design goals for the APQ binding development were:

  - simple to use
  - easy to read
  - reliable
  - database vendor neutral (generic database programming)
  - at the user's option, strongly typed
  - strong blob support
  - No C language interfaces or types
  - good documentation

It is the author's belief that these goals have been suitably met,
although the package is still undergoing active research. Excluding blob
support, there are only 2 tagged object types that the programmer must
become familiar with. These objects include Finalization and  nicely
clean up after themselves. Blob support adds one more tagged object that
the programmer can interact with.

  1. The Connection_Type object for database connections
  2. The Query_Type object for SQL interactions with server
  3. The Blob_Type type for Blob I/O and operations

Having few objects reduces the learning curve substantially. A large
number of functions and procedures are overloaded -- reusing the same
name. This also reduces the learning curve, since the remaining
differences are only in the involved data types. Much complexity
is hidden within the state driven objects.

The APQ binding allows the Ada95 programmer to interface with blobs
using stream I/O. This preserves the Ada advantage for strong type
checking while making it simple for the programmer to perform I/O. As of
APQ 1.2, the blob I/O is buffered, giving the stream I/O for blobs a
major performance boost. No longer will the programmer need to search
for performance work-arounds for blob operations.

Version 2.2 of APQ brings Sybase into the fold of supported
databases. This is particularly useful now that Sybase has
generously made their ASE-12.5x Express edition of their
server available to developers for free.


Trial Programs:
---------------

Before you commit to a package like this, you want to see it
work. No problem for UNIX users. Just try the example program in
the ./eg2 directory. This example program is a simple
illustration of how to load your /etc/passwd and /etc/group
files into database tables. The example program does just this,
and then performs some rudimentary checks on them.

Just cd to the directory and type make. Follow the
instructions from there.

The ./eg directory is PostgreSQL only. The ./eg2 directory is
the same example, but will operate for PostgreSQL or MySQL
(depending upon your database support installed).

The ./sybase directory has more extensive test programs
available for those that are using APQ with Sybase (or have
Sybase available).

Platforms:
----------

This binding has been tested under Linux and Win2k.
using the installed debian GNAT 3.14p compiler. The two
databases used in testing were:

	PostgreSQL 7.3.5
	MySQL 4.0.14
	Sybase ASE 12.52

While not yet tested on all platforms, this package will likely
port well for must UNIX platforms, including:

 - FreeBSD		(2.0 untested)
 - NetBSD 		(untested)
 - OpenBSD		(untested)
 - Linux		(tested)
 - HP-UX 10.2 or higher (to be tested)
 - Sun Solaris 		(possibly)


Win32 Builds:
-------------

Win32 builds are now possible. See the pdf document
named win32.pdf for instructions on how to build APQ
from sources.


Feedback:
---------

Please feedback suggestions and bugs to ve3wwg@cogeco.ca .

	When reporting bugs, please indicate :

	  - PostgreSQL server version (if used)
	  - MySQL server version (if used)
	  - Sybase server version (if used)
	  - O/S and kernel release
	  - Ada compiler vendor and version
            (do gnatls -v)

Thank-you for downloading and using APQ.

Warren W. Gay.


See file HISTORY for revision history, or see the
History chapter of the manual.

- End -
