The eSQL Library
================

eSQL is a library for easily executing SQL queries using any supported
database engine.  Currently, only the mSQL engine from Hughes Technologies
(http://www.hughes.com.au) is supported, and only for SmallEiffel, but
hopefully as the library matures it wi ll come to support more engines and
compilers. 

If you are interested in using or enhancing the library, please read on... 
(Some acronyms are listed below.) 

The library is based on a set of ADTs which describe the functionality of
the library in an abstract manner.  These ADTs are then implemented for
the particular database engines and compilers supported by the library.
The engine/compiler-specific portion of the library is itself structured
in such a way as to promote expandability and flexibility.  These portions
have four notable features: 

* An interface class (ADT) describing the API provided by the engine. 

* Implementations of the API interface for a particular compiler-currently
just the one for SmallEiffel. 

* Classes implementing the eSQL ADTs in terms of the API interface. 

* Extra classes which provide functionality specific to the particular
database engine. 


Supported Functionality
=======================

Not all database engines support the same functionality.  The only
functionality assumed for all database engines, as embodied in the
SQL_DATA_SOURCE class, is this: 

* Data sources can be identified by a single string name.

* Data sources have the capability to provide some sort of textual error
descriptions. 

* Data sources can be "connected" to, at which time they are prepared to
execute SQL queries until they are "disconnected". 

* Data sources can be disconnected with certainty; that is, the
"disconnect" command has a postcondition of "not connected". 

* Queries which produce no results can be distinguished from those that
produce an empty result set. 

* Result sets can be retrieved a row at a time. 

* The returned data can be expressed as text (i.e. STRING objects). 

* Columns in a result set have a name.  

* Columns have a "display width" which places a limit on the length of a
string that can be contained in that column. 

Note that this leaves a few open questions:

* What happens if the connection is broken without "disconnect" having
been called? 

* What happens if "disconnect" cannot disconnect for some reason? 

* What if the database supports a datatype that has no preset size limit? 

* What if the engine does not distinguish between queries without results
and queries with an empty result set? 

* How should data types other than char be handled?  Surely of the engine
provides the data in some other format, it would be silly to convert to
STRING and then back to the original format? 

* Exactly how much of the SQL language should be supported? 

eSQL deals with other functionality beyond this by splitting the most
common functionality into separate ADTs (along the lines of Robert
Martin's Interface Segregation Principle (http://www.oma.com
/Publications/publications.html)).  For any particular engine, a single
class will be defined which will implement all the ADTs that the engine is
capable of supporting.  An instance of this class can then be downcast
(using assignment attempt) to probe its capabilities.  Despite the general
dislike for downcasting in the OO community, I believe this to be a sound
application of the technique, and I believe it will minimize maintenance
problems down the road.

Other functionality is very specific to a particular API, and is thus not
provided by the main ADTs at all.  Such functionality can be accessed
again by downcasting to the appropriate engine-specific classes. 

I look forward to hearing criticisms and suggestions for the library. 
Don't hesitate to mail me at doylep@ecf.toronto.edu with any comments. 

Thanks to Geoff Eldridge for his support and assistance with publicizing
the eSQL library. 


Acronyms and abbreviations
==========================

ADT = Abstract Data Type; a description of a type of entity in terms of
its externally-observable properties only

API = Application Programming Interface; the raw set of functions provided
to access some functionality

eSQL = The Eiffel SQL library

mSQL = The Mini-SQL database engine

SQL = Structured Query Language; standard language for accessing
relational databases