MAN page from Other DBI-perl-bin-0.91-1.i386.rpm

lib::DBI::DBD

Section: User Contributed Perl Documentation (3)
Updated: perl 5.004, patch 03
Index 

NAME

DBI::DBD - DBD Driver Writer's Guide (draft) 

SYNOPSIS

    perldoc DBI::FAQ

 

VERSION and VOLATILITY

        $Revision: 1.7 $        $Date: 1997/12/10 16:50:14 $

This document is very much a minimal draft which will need to be revisedfrequently (and extensively).

The changes will occur both because the DBI specification is changingand hence the requirements on DBD drivers change, and because feedbackfrom people reading this document will suggest improvements to it.

Please read the DBI documentation first and fully, including the DBI FAQ. 

DESCRIPTION

This document is primarily intended to help people writing newdatabase drivers for the Perl Database Interface (Perl DBI).It may also help others interested in discovering why the internals ofa DBD driver are written the way they are.

This is a guide. Few (if any) of the statements in it are completelyauthoritative under all possible circumstances. This means you willneed to use judgement in applying the guidelines in this document. 

REGISTERING A NEW DRIVER

Before writing a new driver, it is in your interests to find outwhether there already is a driver for your database.If there is such a driver, it should be easier to make use of it thanto write your own.

        [...More info TBS...]

 

Locating drivers

The primary web-site for locating Perl software isthe section on /www.perl.com/CPAN in the http: manpage.You should look under the various modules listings for the softwareyou are after.Two of the main pages you should look at are:

  http://www.perl.org/CPAN/modules/by-category/07_Database_Interfaces/DBI

  http://www.perl.org/CPAN/modules/by-category/07_Database_Interfaces/DBD

The primary web-site for locating DBI software and information ishttp://www.hermetica.com/technologia/DBI. 

DBI Mailing Lists

There are 2 main and one auxilliary mailing lists for people workingwith DBI. The primary lists are dbi-usersAATTfugue.com for general usersof DBI and DBD drivers, and dbi-devAATTfugue.com mainly for DBD driverwriters (don't join the dbi-dev list unless you have a good reason).The auxilliary list is dbi-announceAATTfugue.com for announcing newreleases of DBI or DBD drivers.

You can join these lists by accessing the web-sitethe section on /www.fugue.com/dbi in the http: manpage.If you have not got web access, you may send a request todbi-requestAATTfugue.com, but this will be handled manually when thepeople in charge find the time to deal with it. Use the web-site.

You should also consider monitoring the comp.lang.perl newsgroups. 

Registering a new driver

Before going through any official registration process, you will needto establish that there is no driver already in the works.You'll do that by asking the DBI mailing lists whether there is such adriver available, or whether anybody is working on one.

        [...More info TBS...]

 

CREATING A NEW DRIVER

Creating a new driver from scratch will always be a daunting task.You can and should greatly simplify your task by taking a goodreference driver implementation and modifying that to match thedatabase product for which you are writing a driver.

The de facto reference driver is the one for DBD::Oracle, written byTim Bunce who is also the author of the DBI package. The DBD::Oraclemodule is a good example of a driver implemented around a C-level API.

The DBD::ODBC module is also a good reference for a driver implementedaround an SQL CLI or ODBC based C-level API.

The DBD::Informix driver is a good reference for a driver implementedusing `embedded SQL'.

        [...More info TBS...]

 

REQUIREMENTS ON A DRIVER

T.B.S. 

CODE TO BE WRITTEN

A minimal driver will contain 7 files plus some tests.Assuming that your driver is called DBD::Driver, these files are:

Driver.pm

Driver.xs

Driver.h

dbdimp.h

dbdimp.c

Makefile.PL

README

MANIFEST

 

Driver.pm

The Driver.pm file defines the Perl module DBD::Driver for your driver.It will define a package DBD::Driver along with some versioninformation, some variable definitions, and a function driver() whichwill have a more or less standard structure.

It will also define a package DBD::Driver::dr (which will define thedriver() and connect() methods), and a package DBD::Driver::db (whichwill define a function prepare() etc), and a package DBD::Driver::st.

Each of these classes may define a function errstr(), which willsimply relay its arguments to DBD::Driver::errstr() and implicitlyreturn the value from DBD::Driver::errstr(). The DBD::Driver::errstr()function is actually defined in Driver.xs.

The Driver.pm file will also contain the documentation specific toDBD::Driver in the format used by perldoc. 

Driver.xs

Driver.xs should look like this:

  #include "Driver.h"

  DBISTATE_DECLARE;

  MODULE = DBD::Driver    PACKAGE = DBD::Driver

  INCLUDE: Driver.xsi

  MODULE = DBD::Driver    PACKAGE = DBD::Driver::st

 

Driver.h

Driver.h should look like this:

  #define NEED_DBIXS_VERSION 9

  #include <DBIXS.h>      /* installed by the DBI module  */

  #include "dbdimp.h"

  #include <dbd_xsh.h>     /* installed by the DBI module  */

 

Implementation header dbdimp.h

T.B.S 

Implementation source dbdimp.c

T.B.S 

Makefile.PL

Driver.xs should look like this:

  use 5.004;  use ExtUtils::MakeMaker;  use Config;  use strict;  use DBI 0.86;  use DBI::DBD;

  my %opts = (    NAME => 'DBD::Driver',    VERSION_FROM => 'Driver.pm',    clean => { FILES=> 'Driver.xsi' },    dist  => { DIST_DEFAULT=> 'clean distcheck disttest ci tardist',                PREOP => '$(MAKE) -f Makefile.old distdir' },

Add other options here as needed. See ExtUtils::MakeMaker for more info.

  );

  WriteMakefile(%opts);

  exit(0);

  sub MY::postamble {    return dbd_postamble();  }

 

README file

The README file should describe the pre-requisites for the buildprocess, the actual build process, and how to report errors.Note that users will find ways of breaking the driver build and testprocess which you would never dream possible.Therefore, you need to write this document defensively and precisely.Also, it is in your interests to ensure that your tests work as widelyas possible.As always, use the README from one of the established drivers as abasis for your own.

        [...More info TBS...]

 

MANIFEST

The MANIFEST will be used by the Makefile'd dist target to build thedistribution tar file that is uploaded to CPAN. 

Tests

The test process should conform as closely as possibly to the Perlstandard test harness.

In particular, most of the tests should be run in the t sub-directory,and should simply produce an `ok' when run under `make test'.For details on how this is done, see the Camel book and the section inChapter 7, ``The Standard Perl Library'' on Test::Harness.

The tests may need to adapt to the type of database which is beingused for testing, and to the privileges of the user testing thedriver.The DBD::Informix test code has to adapt in a number of places to thetype of database to which it is connected as different Informixdatabases have different capabilities.

        [...More info TBS...]

 

METHODS WHICH DO NOT NEED TO BE WRITTEN

The DBI code implements the majority of the methods which areaccessed using the notation DBI->function(), the only exceptions beingDBI->connect() and DBI->data_sources() which require support from thedriver.

DBI->available_drivers()

DBI->neat_list()

DBI->neat()

DBI->dump_results()

DBI->func()

The DBI code implements the following documented driver, database andstatement functions which do not need to be written by the DBD driverwriter.

$dbh->do()

The default implementation of this function prepares, executes anddestroys the statement. This should be replaced if there is a betterway to implement this, such as EXECUTE IMMEDIATE.

$h->err()

See the comments on $h->errstr() below.

$h->state()

See the comments on $h->errstr() below.

$h->trace()

The DBD driver does not need to worry about this routine at all.

$h->{ChopBlanks}

This attribute needs to be honured during fetch operations, but doesnot need to be handled by the attribute handling code.

$h->{RaiseError}

The DBD driver does not need to worry about this attribute at all.

$h->{PrintError}

The DBD driver does not need to worry about this attribute at all.

$sth->bind_col()

Assuming the driver uses the DBIS->get_fbav() function (see below),the driver does not need to do anything about this routine.

$sth->bind_columns()

Regardless of whether the driver uses DBIS->get_fbav(), the driverdoes not need to do anything about this routine as it simplyiteratively calls $sth->bind_col().

The DBI code implements a default implementation of the followingfunctions which do not need to be written by the DBD driver writerunless the default implementation is incorrect for the Driver.

$dbh->quote()

This should only be written if the database does not accept the ANSISQL standard for quoting strings, with the string enclosed in singlequotes and any embedded single quotes replaced by two consecutivesingle quotes.

$h->errstr()

As documented previously, this routine should currently be written foreach sub-package (dr, db, st).It is not clear why the $h->state and $h->err routines are not treatedsymmetrically.

$dbh->ping()

This should only be written if there is a simple, efficient way to determinewhether the connection to the database is still alive.Many drivers will accept the default, do-nothing implementation.

 

WRITING AN EMULATION LAYER FOR AN OLD PERL INTERFACE

Study Oraperl.pm (supplied with DBD::Oracle) and Ingperl.pm (suppliedwith DBD::Ingres) and the corresponding dbdimp.c files for ideas. 

Setting emulation perl variables

For example, ingperl has a $sql_rowcount variable. Rather than tryto manually update this in Ingperl.pm it can be done faster in C code.In dbd_init():

  sql_rowcount = perl_get_sv("Ingperl::sql_rowcount", GV_ADDMULTI);

In the relevant places do:

  if (DBIc_COMPAT(imp_sth))     /* only do this for compatibility mode handles */      sv_setiv(sql_rowcount, the_row_count);

 

OTHER MISCELLANEOUS INFORMATION

Many details still T.B.S. 

The imp_xyz_t types

T.B.S. 

Using DBIc_IMPSET_on

The driver code which initializes a handle should use DBIc_IMPSET_on()as soon as its state is such that the cleanup code must be called.When this happens is determined by your driver code.

Failure to call this can lead to corruption of data structures.For example, DBD::Informix maintains a linked list of database handlesin the driver, and within each handle, a linked list of statements.Once a statement is added to the linked list, it is crucial that it iscleaned up (removed from the list).When DBIc_IMPSET_on() was being called too late, it was able to causeall sorts of problems. 

Using DBIc_is(), DBIc_on() and DBIc_off()

Once upon a long time ago, the only way of handling the attributessuch as DBIcf_IMPSET, DBIcf_WARN, DBIcf_COMPAT etc was through macrossuch as:

    DBIc_IMPSET     DBIc_IMPSET_on      DBIc_IMPSET_off    DBIc_WARN       DBIc_WARN_on        DBIc_WARN_off    DBIc_COMPAT     DBIc_COMPAT_on      DBIc_COMPAT_off

Each of these took an imp_xyz pointer as an argument.

Since then, new attributes have been added such as ChopBlanks,RaiseError and PrintError, and these do not have the full set ofmacros.The approved method for handling these is now the triplet of macros:

        DBIc_is(imp, flag)        DBIc_has(imp, flag)    an alias for DBIc_is        DBIc_on(imp, flag)        DBIc_off(imp, flag)

Consequently, the DBIc_IMPSET family of macros is now deprecated andnew drivers should avoid using them, even though the older driverswill probably continue to do so for quite a while yet. 

Using DBIS->get_fbav()

The $sth->bind_col() and $sth->bind_columns() documented in the DBIspecification do not have to be implemented by the driver writerbecuase DBI takes care of the details for you.However, the key to ensuring that bound columns work is to call thefunction DBIS->get_fbav() in the code which fetches a row of data.This returns an AV, and each element of the AV contains the SV whichshould be set to contain the returned data. 

ACKNOWLEDGEMENTS

Tim Bunce (tim.bunceAATTig.co.uk) - for writing DBI and managing the DBIspecification and the DBD::Oracle driver. 

AUTHOR

Jonathan Leffler (johnlAATTinformix.com)

---

 

Index

NAME

SYNOPSIS

VERSION and VOLATILITY

DESCRIPTION

REGISTERING A NEW DRIVER

Locating drivers

DBI Mailing Lists

Registering a new driver

CREATING A NEW DRIVER

REQUIREMENTS ON A DRIVER

CODE TO BE WRITTEN

Driver.pm

Driver.xs

Driver.h

Implementation header dbdimp.h

Implementation source dbdimp.c

Makefile.PL

README file

MANIFEST

Tests

METHODS WHICH DO NOT NEED TO BE WRITTEN

WRITING AN EMULATION LAYER FOR AN OLD PERL INTERFACE

Setting emulation perl variables

OTHER MISCELLANEOUS INFORMATION

The imp_xyz_t types

Using DBIc_IMPSET_on

Using DBIc_is(), DBIc_on() and DBIc_off()

Using DBIS->get_fbav()

ACKNOWLEDGEMENTS

AUTHOR

---

This document was created byman2html,using the manual pages.