=begin
= DBD Specification Version 0.2.2 (Draft)
by Michael Neumann (neumann@s-direknet.de)

 $Id: DBD_SPEC,v 1.1 2002/10/02 18:10:37 mneumann Exp $

== DBD Directory Layout
The directory layout is the following:

  DBD/
  DBD/Driver1
  DBD/Driver1/Driver1.rb
  DBD/Driver1/helper.rb
  .
  .

  DBD/Driver2
  .
  .
  .

Where "Driver1" and "Driver2" are the names of DBD driver.
For example if you have two drivers installed, "Oracle" and 
"Sybase" it would look like:

  DBD/
  DBD/Oracle
  DBD/Oracle/Oracle.rb         # <== this is the main driver
  DBD/Oracle/oracle.so         # <== is used by Oracle.rb

  DBD/Sybase/Sybase.so         # <== this is the main driver
                               # has no helper files

When DBI loads a DBD driver it search all "DBD" directories in Ruby's
LOAD_PATH ($:).

Database dependent functions, that should be callable with DBI::func, must
use the prefix "__" before their method names, to prevent nameclashes with 
further versions of Ruby/DBI!

== Driver Name
The DBD driver is simply named after the Database, e.g. Oracle, DB2 etc.
The suffix will normally be ".rb" but can be any other valid suffix, 
which Ruby is possible to load, e.g. ".so", ".sl" or ".dll", and depends
for non-Ruby DBD driver on the underlying operating system.
When I refer to the driver name, then I speak of the filename without
the suffix, e.g. Oracle or DB2.

The name specified in the DSN ((-Data Source Name, e.g. "dbi:Oracle:oracle.neumann"-)) 
must be the same as the driver name. 

== Classes provided by a DBD
A DBD driver has to provide three classes in the namespace
(({DBI::DBD::}))((*DriverName*)) where ((*DriverName*)) is the name of the 
driver, e.g. Oracle or DB2.

The three classes must be named (({Driver})), (({Database})) and (({Statement})).

== Class Driver
This class must inherit from (({DBI::BaseDriver})).

=== Methods which must be provided by (({Driver}))

--- connect( dbname, user, auth, attr )
    Connect to a database and return a newly created (({Database})) object.

=== Optional methods which can be specified by (({Driver}))

--- default_user
    Return an array of the form (({['username', 'password']})) which represent
    the default user when no user and password was specified.

    Defaults to (({['', '']})) if not implemented.

--- default_attributes
    Return a (({Hash})) containing the default attributes which are used
    in (({connect})) additional to the ones the user specify.
  
    Defaults to (({{}})) (empty hash) if not implemented.   
 
--- data_sources
    Return an array of all valid DSN this driver can access.
    
    Defaults to (({[]})) (empty array) if not implemented.     


--- disconnect_all
    Disconnect all connections made with this driver.

    Defaults to raise a NotImplementedError.


== Class Database
This class must inherit from (({DBI::BaseDatabase})).

=== Methods which must be provided by (({Database}))

--- disconnect
    Disconnect from database.
    But before you have to rollback all outstanding transactions, so 
    all changes not yet commited get lost.

--- prepare( statement )
    Prepare the SQL ((*statement*)) and return an object of class (({Statement})).

--- ping
    Ping the database, and check if the connection is alive.
    This can be implemented by executing a SQL statement like
    "SELECT 1 FROM DUAL" for Oracle database, or for other databases
    this should be query on a table which normally always exists.

    Return (({true})) if the connection is alive, otherwise (({false})).

=== Optional methods which can be specified by (({Database}))

--- commit
--- rollback
    Commit or roll back the current transaction.
 
    Defauls to raise a NotSupportedError, so if the database do not implement 
    transactions (mSQL, mySQL, CSV) do not overwrite this method.

--- tables
    Return an Array of all tables and views. 
    
    Defaults to return the empty Array [].

--- columns( table )
    Return more information about the columns of table ((*table*)). 
    Return an Array of Hashes, like Statement#column_info do.
    
    Defaults to return an empty Array [].
 
--- execute( statement, *bindvars )
    Immediate execution (without preparation) of SQL ((*statement*))
    with binding of placeholders to values given in ((*bindvars*)) before.

    Return a (({Statement})) object.
 
    Defaults to the call sequence of Database#prepare(), Statement#bind_params() and 
    Statement#execute().

--- do( statement, *bindvars )
    Execution of SQL ((*statement*)) with binding of placeholders to values given
    in ((*bindvars*)) before, but without returning a (({Statement})) object.
    So this is used for 'INSERT', 'UPDATE', 'DELETE' as well as for DCL, which
    do not return a result-set.

    Return the RPC (Row Processed Count) or (({nil})) if no RPC is available.

    Defaults to Database#execute() and Statement#rows() followed by Statement#finish(). 

--- quote( value )
    Quote the given value ((*value*)) database specific and return the result.

    NOTE: This method is not really useful, because of Statement#bind_param. 

--- []( attr )
    Return value of attribute ((*attr*)).

    Defauls to return the value of (({@attr[attr]})).

--- []=( attr, value ) 
    Set value of attribute ((*attr*)) to ((*value*)).
    An attribute is e.g. "AutoCommit".
    Raise a NotSupportedError, if the database do not support an attribute.

    The default implementation is to raise a NotSupportedError.

   

== Class Statement
This class must inherit from (({DBI::BaseStatement})).

=== Methods which must be provided by (({Statement}))

--- bind_param( param, value, attribs )
    Bind ((|param|)) which is either a (({String})) which is then the name of the 
    placeholder used in the SQL statement (e.g. Oracle: "SELECT * FROM EMP WHERE ENAME = :ename") 
    or it is a (({Fixnum})) which is then the number of the placeholder where counting starts at 1.

    ((|value|)) is the value which is bound to the placeholder.
    If ((|value|)) is a (({String})), then the default SQL type is (({VARCHAR})) or (({CHAR})).
    If ((|value|)) is a (({Fixnum})) or (({Bignum})), the default SQL type is (({INT})).
    If ((|value|)) is a (({Float})), the default SQL type is (({FLOAT})).

    ((*attribs*)) is not yet used in this version but could be a hash containing more information
    like parameter type etc.

--- execute
    Execute the statement.

--- finish
    Free all the resources for the statement.
    After calling (({finish})) no other operation on this
    statement is valid.

--- fetch
    Fetch the current row.
    Return a (({Array})) containing all column-data or (({nil})) if
    the last column has been read.

    Note: This method should return not a newly created object on each call, 
    instead you should return one and the same Array object but with 
    changed data. 


--- column_info
    Return an (({Array})) of (({Hash}))'s, one for each column.
    Each (({Hash})) object must have at least one key 'name' which 
    value is the name of that column.
    Further possible values are 'sql_type' (integer, e.g. DBI::SQL_INT), 
    'type_name' (string), 'precision' (= column size), 'scale' (= decimal digits),
    'default', 'nullable', 'indexed', 'primary' and 'unique'.

--- rows
    Return the RPC (Row Processed Count) of the last executed statement, or
    (({nil})) if no such exist.


=== Optional methods which can be specified by (({Statement}))

--- bind_params( *bindvars )
    Binds the placeholders in the statement to the values of ((|bindvars|)).

    Defaults to calling ((<bind_param>)) for each value, with ((*param*)) starting
    from 1 increasingly.

--- cancel 
    Free any result set resources which were made after a call to (({execute})).
    After calling this method, a call to one of the ((*fetch*)) methods is no more valid.

    Defaults to do nothing.

--- fetch_scroll( direction, offset )
    ((*direction*)) is one of the following constants:
    * SQL_FETCH_NEXT
    * SQL_FETCH_PRIOR
    * SQL_FETCH_FIRST
    * SQL_FETCH_LAST
    * SQL_FETCH_ABSOLUTE
    * SQL_FETCH_RELATIVE
    
    ((*offset*)) is a positive or negativ number (only when SQL_FETCH_RELATIVE is used).

    By default only SQL_FETCH_NEXT, SQL_FETCH_LAST, SQL_FETCH_RELATIVE (if positive) are
    implemented, otherwise it raises NotSupportedError.

    Note: This method should return not a newly created object on each call, 
    instead you should return one and the same Array object but with 
    changed data. 


--- fetch_many( cnt )
    Return an (({Array})) of the next ((*cnt*)) rows, where a row is itself an (({Array})).

    Note: Unlike (({fetch})), this method should return a new Array object.
 
    If there are no more ((*cnt*)) rows available return the rest.
    Return (({nil})) if no rows are available.

    Defaults to multiple calls to (({fetch})).

--- fetch_all
    Return an (({Array})) of all rows which have not yet been fetched, where a row is 
    itself an (({Array})) (see Statement#fetch_many).

    Note: Unlike (({fetch})), this method should return a new Array object.

    Return (({nil})) if no rows are available.

    Defaults to multiple calls to (({fetch})).

--- []( attr )
    Return value of attribute ((*attr*)).

    Defauls to return the value of (({@attr[attr]})).

--- []=( attr, value ) 
    Set value of attribute ((*attr*)) to ((*value*)).
    Raise a NotSupportedError, if the database do not support an attribute.

    The default implementation is to raise a NotSupportedError.


=end