Re: DBperl. Database Independent API for Perl.

This section was last modified on $Date: 1993/08/13 19:04:50 $ ============================================================ 2. CONVENTIONS, STRUCTURE and OPEN ISSUES ============================================================ 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 a) "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. @ary - returns an array of values. Typically an error condition will result in an empty array being returned. 2.4 General Interface Rules & Caveats a) 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. b) 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. c) 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. d) 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. e) 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 a) 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