Re: DBperl. Database Independent API for Perl.

This section was last modified on $Date: 1993/08/13 19:04:50 $

2.1 Architecture of a DBperl Application

             |<-- Scope of DBperl --->|
                  .-.   .-------------.   .-------------.
   .------.       | |---| XYZ Module  |---| XYZ Engine  |


   |Perl  |       |S|   `-------------'   `-------------'

   |script|  |A|  |w|   .-------------.   .-------------.

   |using |--|P|--|i|---|Oracle Module|---|Oracle Engine|

   |DBperl|  |I|  |t|   `-------------'   `-------------'

   | API  |       |c|...


   |funcs |       |h|... Other modules


   `------'       | |...
                  `-'

2.2 Terms

 API -- Application Perl-script Interface

    The call interface and variables provided by DBperl to perl     scripts. The API is implemented via the perl usub mechanism.

 Switch

    The code that provides the DBperl API and re-directs the DBperl     function calls to the appropriate Module for actual execution.     The Switch is also responsible for the dynamic loading of Modules,     error checking/handling and other general duties.

 Module

    A Module implements support for a given type of Engine (database).     Modules contain implementations of the DBperl functions written     using the private interface functions of the corresponding Engine.     Only authors of sophisticated/multi-database applications or     generic library functions need be concerned with Modules.     The Switch itself has a Module interface and can be conveniently     treated as a Module by applications.

 Engine

    The actual "engine" that is being communicated with by a Module,     e.g., Oracle, Ingres, Sybase etc. Note that Engines need not be     databases, consider DNS, X.500, SNMP for example.

 MPI -- Module Programmer's Interface

    This is the interface provided by the Switch which is used to     communicate with Modules. Only module implementors need be     concerned with this interface. The Switch and MPI will take most of     the work out of writing Modules for DBperl. Hopefully this will     encourage people to implement Modules for their favourite database.     Work on the MPI specification is unlikely to start until the DBperl     specification is stable and implementation of the Switch has begun.     The MPI is likely to provide both perl usub and C style interfaces     so Modules can be implemented with whichever is the most appropriate.     It should be possible to implement DBperl Modules in perl code!

 Handle

    Handles are opaque values returned by some functions which can be     passed back to DBperl functions to refer to objects such as a     Module, a database connection or a prepared SQL query.

 Library

    A perl package of utility functions to aid the DBperl user in     performing common activities. Within the DBperl spec these     functions are not separated out but are located in their     appropriate sections and identified by the label 'Library     Function'.

 Bundle

    The actual collection of DBperl Switch and DBperl Modules which are     built and installed on the system where the perl script is being     executed.

 TBD
    To Be Decided. Parts of the specification that have not yet been     completed. These are generally section cross references.

2.3 Notation

1. "Handles", if defined, are assumed to be active:

    $modh - designates a handle for a database module and is

            interchangeable (except in exotic cases) with the name of
            the module to which it connects. Typically users need not
            be concerned with module handles.

    $dbh  - designates a handle for an open database connection and
            presumes a module designation.

    $qh   - designates a query handle for a single prepared SQL statement
            and presumes a $dbh to which it is connected. There is no
            separate cursor handle in DBperl. The $qh serves as a
            handle for both the prepared statement and it's cursor.
            Multi-statements tied to a single handle are not supported.

    $hh   - designates either a $qh, $dbh or $modh. Note that $hh
            is sometimes specified where a $modh would not be acceptable.

    Handle overloading is allowed, e.g., any function specified to     accept a $modh parameter can also accept a $dbh or an $qh to     indirectly specify the module. Similarly, any function that calls     for a $dbh parameter can accept a $qh to specify the $dbh     indirectly. This applies everywhere.

 b) Return values are noted as:

    $rc - return condition (or a handle), evaluates (in Perl) to boolean

            false on an error condition to facilitate short-cut chaining.
            E.g., &db_something() || die "db_something failed"

    $rv   - return value, does not necessarily evaluate as false on an error
            condition.

    _at_ary  - returns an array of values. Typically an error condition will
            result in an empty array being returned.

2.4 General Interface Rules & Caveats

1. All data is returned to the perl script as perl strings. This allows arbitrary precision representations within the scope of the engine/module to be handled without loss of accuracy. Beware that perl conversions and other engines/modules may not preserve the same accuracy.
2. Dates and times are returned as character strings in the native format of the corresponding Engine. Functions are provided to convert the native format values into integers representing the number of seconds since 1 January 1970, e.g., 'unix time'. Other conversion functions may be defined later. Timezone effects are engine/module dependent and can be deduced from (and in some cases affected by) parameters available from &db_getvalue(), q.v.
3. Binary data types are not yet explicitly supported by DBperl. Perl itself supports binary data in perl strings and the Switch will pass binary data to the Modules without change. It is up to the Module implementors to decide how they wish to handle such binary data.
4. Multiple SQL statements may not be combined in a single execution handle, e.g., a single $qh. This restriction has most impact upon Sybase users. An alternative approach may be possible.
5. Positioned updates and deletes are not currently supported by DBperl. E.g., it is not possible to execute a select query, fetch a number of rows and then update or delete the 'current row' before fetching more rows. All cursors are assumed to be read-only and unnamed. This may change in the future. Individual Modules may provide private mechanisms but it's not currently part of this specification.

2.5 Naming Conventions

1. The name space 'db_*' is reserved for DBperl functions, variables, packages etc. E.g., scripts using identifiers which begin with db_ may experience compatibility problems with future versions of the DBperl API. The package name 'db' is also reserved for future use.
2. All environment variables used by the DBperl Switch or Modules begin with 'DBPERL_'.
3. Attribute name-value pairs are used in many places throughout the DBperl specification. They provide a very simple and flexible way to determine or alter the behaviour of a Module or a particular database query.

    Attribute names and their values are described in detail in section     TBD. For now it is only important to note that the case of the     attribute name is used to signify who defined the meaning of that     name and it's values.

      Case of name  Meaning defined by
      ------------  ------------------
       UPPER_CASE   Standards, e.g.,  X/Open, SQL92 etc (portable)
       MixedCase    DBperl API (portable)
       lower_case   Module or engine specific (non-portable)

2.6 Each function is documented with the following general structure:

    5.4.3 db_something    

      $rv = &db_something($dbh, $arg [,%attr]);
          $dbh -- database handle
          $arg -- description of argument
          %attr -- associative array of additional attributes that can
                   be passed to this function to affect it's behaviour
      $rv -- description of returned value
   
      Several sentences describing the purpose and behaviour of the function.
   
      Events:          description of events/errors that may occur (if any)
        NO_MORE_ROWS -- ...
   
      Attributes:      description of optional attributes (where appropriate)
        name, value -- description of attribute and it's possible values

    Events and errors are described in section TBD. Standard events and     errors such as ERROR and WARN are also described in that section.     Only events that are specific to a function are listed in that     functions description.

2.7 Open Issues

1. The contents of the DBperl Library are subject to expansion. Please let me know what other common patterns of SQL execution you think would be useful to DBperl application developers.
2. Suggestions for additional attribute names and values to be accessible via functions &db_getvalue() and &db_setvalue() are requested. See section TBD.
3. How to handle date and time intervals in a distinct manner from absolute dates and times is yet to be defined.
4. Data typing issues in general have been put to one side for now (other than the absolute vs interval date/time issue noted above). It seems best to ignore them until implementations of the spec actually exist.
5. Should we use a 'db' package or the db_* namespace? either &db'connect() or &db_connect() This may have an impact once we can implement modules in perl, e.g., Module 'xbase' could be implemented in "package db_xbase" and would have a function &db_xbase'connect() which would be called by the Switch as required.

    This would still work for db_xbase'db_connect but db_xbase'connect     seems cleaner to me. Packages may have a greater role to play in     Perl 5 than they have done in Perl 4. I have added the 'db'     package name to the reserved name space so we can leave the issue     open for now.

End of DBperl API Section 2. Received on Fri Aug 13 1993 - 21:45:40 CEST