lib(dbi)


 This library provides an interface to database management systems (DBMS)
 that supports SQL (Structure Query Language), allowing SQL commands,
 written in an ECLiPSe program, to be passed to the DBMS for processing,
 and their results (if any) to be passed back to ECLiPSe.

 The exact SQL supported by the library is determined by the underlying
 DBMS, as the SQL commands are passed directly to the DBMS via its C API. 
 If supported by the C API, the library also allows the use of prepared SQL
 statements, where a SQL statement, possibly parameterised to accept
 different input data, is parsed once by the DBMS, and efficiently executed
 multiple times. Support for transactions (with commit and rollback) is also
 provided.

 The library provides a relatively low-level interface to the DBMS, but
 higher level interfaces (e.g. where a SQL query is viewed as a predicate,
 yielding different results tuples on backtracking) can be constructed on
 top of this.

 Currently, MySQL (version 5.0 or later) is supported by the library.
 Note that the MySQL client dynamic library (libmysqlclient.so on Unix
 systems, libmysql.dll on Windows) is not included with the distribution, and
 if this file is not found by ECLiPSe on loading lib(dbi), there will be 
 an error. This file can be obtained by downloading MySQL, and placing the
 .so or .dll file into a place where ECLiPSe can find it, i.e. one of
 the following:
 
 <eclipsedir>/lib/<arch>
 ECLIPSEMYSQL/lib (ECLIPSEMYSQL can be either an environment variable, or
 as registry entry under HKEY_LOCAL_MACHINE/SOFTWARE/IC-Parc/Eclipse/<version>)
 PROGRAMFILES/MySQL/MySQL Server X.Y/lib
 your PATH or LD_LIBRARY_PATH
 
 Note that this client library must correspond in word size (32/64) to the
 word size of your ECLiPSe.  The word size of the MySQL server is irrelevant.
 

 Data is exchanged with the DBMS via:


SQL statements (input)
  Directly in the SQL statements passed to the DBMS;

SQL query results (output)
  The results returned by SQL queries are returned to ECLiPSe via
      result tuples. Each tuple represents a single row of result, and is
      returned to ECLiPSe as a Prolog structure, with each argument
      represents one column in the result tuple. The ordering of the
      arguments corresponds to the ordering defined by the SQL query.
Parameters for prepared SQL statements (input)
  If prepared statements are supported by the DBMS, data can also be
      passed to the DBMS via parameters (also known as placeholders). Each
      parameter functions like a variable, whose value is instantiated when
      the statement is executed. The library passes parameter values to the
      DBMS via Prolog structures, with each argument represent one parameter. 
      The ordering of the arguments is defined by the ordering of the
      parameters in the prepared SQL statement.
 

 Input and output data in the structures need to be converted from/to
 ECLiPSe datatypes. The ECLiPSe datatype is specified by a template, which
 specifies the datatype by example, i.e. an example result tuple structure
 (for output) or parameter structure (for input) where each argument
 specify the type for that argument, e.g.
    emp(123,"some name",100.0,'some job',extra(data)),
 specifies that the first argument should be an integer, the second a 
 string, the third a real, the fourth, an atom, and the last, a general
 Prolog term. Note that general Prolog terms are stored in the database in
 a binary representation, and the conversion is done by the library. 

 The data is exchanged with the DBMS via buffers. Some DBMS require the
 sizes of the buffers to be specified. This is done automatically by the
 library, but if the default sizes need to overridden (e.g. if the argument
 is large), the template can be used to specify the size of buffers for
 variable length data, e.g.
    emp(123,"1000",100.0,'2000',extra(5000)),
 where the second argument "1000" specifies a buffer size of 1000
 bytes, the third argument '2000' a buffer size of 2000 bytes,
 and the last argument, extra(5000), a buffer size of 5000 bytes.
 Note that any size specifications are simply ignored if not required.


