APQ

$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 -