dbd.pm

视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.

package DBI::DBD;
# vim:ts=8:sw=4

use vars qw($VERSION);	# set $VERSION early so we don't confuse PAUSE/CPAN etc

# don't use Revision here because that's not in svn:keywords so that the
# examples that use it below won't be messed up
$VERSION = sprintf("12.%06d", q$Id: DBD.pm 10002 2007-09-26 21:03:25Z timbo $ =~ /(\d+)/o);


# $Id: DBD.pm 10002 2007-09-26 21:03:25Z timbo $
#
# Copyright (c) 1997-2006 Jonathan Leffler, Jochen Wiedmann, Steffen
# Goeldner and Tim Bunce
#
# You may distribute under the terms of either the GNU General Public
# License or the Artistic License, as specified in the Perl README file.

=head1 NAME

DBI::DBD - Perl DBI Database Driver Writer's Guide

=head1 SYNOPSIS

  perldoc DBI::DBD

=head2 Version and volatility

This document is I<still> a minimal draft which is in need of further work.

The changes will occur both because the B<DBI> specification is changing
and hence the requirements on B<DBD> drivers change, and because feedback
from people reading this document will suggest improvements to it.

Please read the B<DBI> documentation first and fully, including the B<DBI> FAQ.
Then reread the B<DBI> specification again as you're reading this. It'll help.

This document is a patchwork of contributions from various authors.
More contributions (preferably as patches) are very welcome.

=head1 DESCRIPTION

This document is primarily intended to help people writing new
database drivers for the Perl Database Interface (Perl DBI).
It may also help others interested in discovering why the internals of
a B<DBD> driver are written the way they are.

This is a guide.  Few (if any) of the statements in it are completely
authoritative under all possible circumstances.  This means you will
need to use judgement in applying the guidelines in this document.
If in I<any> doubt at all, please do contact the I<dbi-dev> mailing list
(details given below) where Tim Bunce and other driver authors can help.

=head1 CREATING A NEW DRIVER

The first rule for creating a new database driver for the Perl DBI is
very simple: B<DON'T!>

There is usually a driver already available for the database you want
to use, almost regardless of which database you choose. Very often, the
database will provide an ODBC driver interface, so you can often use
B<DBD::ODBC> to access the database. This is typically less convenient
on a Unix box than on a Microsoft Windows box, but there are numerous
options for ODBC driver managers on Unix too, and very often the ODBC
driver is provided by the database supplier.

Before deciding that you need to write a driver, do your homework to
ensure that you are not wasting your energies.

[As of December 2002, the consensus is that if you need an ODBC driver
manager on Unix, then the unixODBC driver (available from
L<http://www.unixodbc.org/>) is the way to go.]

The second rule for creating a new database driver for the Perl DBI is
also very simple: B<Don't -- get someone else to do it for you!>

Nevertheless, there are occasions when it is necessary to write a new
driver, often to use a proprietary language or API to access the
database more swiftly, or more comprehensively, than an ODBC driver can.
Then you should read this document very carefully, but with a suitably
sceptical eye.

If there is something in here that does not make any sense, question it.
You might be right that the information is bogus, but don't come to that
conclusion too quickly.

=head2 URLs and mailing lists

The primary web-site for locating B<DBI> software and information is

  http://dbi.perl.org/

There are two main and one auxilliary mailing lists for people working
with B<DBI>.  The primary lists are I<[e-mail]> for general users
of B<DBI> and B<DBD> drivers, and I<[e-mail]> mainly for B<DBD> driver
writers (don't join the I<dbi-dev> list unless you have a good reason).
The auxilliary list is I<[e-mail]> for announcing new
releases of B<DBI> or B<DBD> drivers.

You can join these lists by accessing the web-site L<http://dbi.perl.org/>.
The lists are closed so you cannot send email to any of the lists
unless you join the list first.

You should also consider monitoring the I<comp.lang.perl.*> newsgroups,
especially I<comp.lang.perl.modules>.

=head2 The Cheetah book

The definitive book on Perl DBI is the Cheetah book, so called because
of the picture on the cover. Its proper title is 'I<Programming the
Perl DBI: Database programming with Perl>' by Alligator Descartes
and Tim Bunce, published by O'Reilly Associates, February 2000, ISBN
1-56592-699-4. Buy it now if you have not already done so, and read it.

=head2 Locating drivers

Before writing a new driver, it is in your interests to find out
whether there already is a driver for your database.  If there is such
a driver, it would be much easier to make use of it than to write your
own!

The primary web-site for locating Perl software is
L<http://search.cpan.org/>.  You should look under the various
modules listings for the software you are after. For example:

  http://search.cpan.org/modlist/Database_Interfaces

Follow the B<DBD::> and B<DBIx::> links at the top to see those subsets.

See the B<DBI> docs for information on B<DBI> web sites and mailing lists.

=head2 Registering a new driver

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

When you get the go ahead, you will need to establish the name of the
driver and a prefix for the driver. Typically, the name is based on the
name of the database software it uses, and the prefix is a contraction
of that. Hence, B<DBD::Oracle> has the name I<Oracle> and the prefix
'I<ora_>'.

This information will be recorded in the B<DBI> module. Apart from
documentation purposes, registration is a prerequisite for
L<installing private methods|DBI/install_method>.

If you are writing a driver which will not be distributed on CPAN, then
you should choose a prefix beginning with 'I<x_>', to avoid potential
prefix collisions with drivers registered in the future. Thus, if you
wrote a non-CPAN distributed driver called B<DBD::CustomDB>, the prefix
might be 'I<x_cdb_>'.

This document assumes you are writing a driver called B<DBD::Driver>, and
that the prefix 'I<drv_>' is assigned to the driver.

=head2 Two styles of database driver

There are two distinct styles of database driver that can be written to
work with the Perl DBI.

Your driver can be written in pure Perl, requiring no C compiler.
When feasible, this is the best solution, but most databases are not
written in such a way that this can be done. Some examples of pure
Perl drivers are B<DBD::File> and B<DBD::CSV>.

Alternatively, and most commonly, your driver will need to use some C
code to gain access to the database. This will be classified as a C/XS
driver.

=head2 What code will you write?

There are a number of files that need to be written for either a pure
Perl driver or a C/XS driver. There are no extra files needed only by
a pure Perl driver, but there are several extra files needed only by a
C/XS driver.

=head3 Files common to pure Perl and C/XS drivers

Assuming that your driver is called B<DBD::Driver>, these files are:

=over 4

=item * F<Makefile.PL>

=item * F<README>

=item * F<MANIFEST>

=item * F<Driver.pm>

=item * F<lib/Bundle/DBD/Driver.pm>

=item * F<lib/DBD/Driver/Summary.pm>

=item * F<t/*.t>

=back

The first four files are mandatory. F<Makefile.PL> is used to control
how the driver is built and installed. The F<README> file tells people
who download the file about how to build the module and any prerequisite
software that must be installed. The F<MANIFEST> file is used by the
standard Perl module distribution mechanism. It lists all the source
files that need to be distributed with your module. F<Driver.pm> is what
is loaded by the B<DBI> code; it contains the methods peculiar to your
driver.

The F<lib/Bundle/DBD/Driver.pm> file allows you to specify other Perl
modules on which yours depends in a format that allows someone to type a
simple command and ensure that all the pre-requisites are in place as
well as building your driver.

The F<lib/DBD/Driver/Summary.pm> file contains (an updated version of) the
information that was included - or that would have been included - in
the appendices of the Cheetah book as a summary of the abilities of your
driver and the associated database.

The files in the F<t> subdirectory are unit tests for your driver.
You should write your tests as stringently as possible, while taking
into account the diversity of installations that you can encounter:

=over 4

=item *

Your tests should not casually modify operational databases.

=item *

You should never damage existing tables in a database.

=item *

You should code your tests to use a constrained name space within the
database. For example, the tables (and all other named objects) that are
created could all begin with 'I<dbd_drv_>'.

=item *

At the end of a test run, there should be no testing objects left behind
in the database.

=item *

If you create any databases, you should remove them.

=item *

If your database supports temporary tables that are automatically
removed at the end of a session, then exploit them as often as possible.

=item *

Try to make your tests independent of each other. If you have a
test F<t/t11dowhat.t> that depends upon the successful running
of F<t/t10thingamy.t>, people cannot run the single test case
F<t/t11dowhat.t>. Further, running F<t/t11dowhat.t> twice in a row is
likely to fail (at least, if F<t/t11dowhat.t> modifies the database at
all) because the database at the start of the second run is not what you
saw at the start of the first run.

=item *

Document in your F<README> file what you do, and what privileges people
need to do it.

=item *

You can, and probably should, sequence your tests by including a test
number before an abbreviated version of the test name; the tests are run
in the order in which the names are expanded by shell-style globbing.

=item *

It is in your interests to ensure that your tests work as widely
as possible.

=back

Many drivers also install sub-modules B<DBD::Driver::SubModule>
for any of a variety of different reasons, such as to support
the metadata methods (see the discussion of L</METADATA METHODS>
below). Such sub-modules are conventionally stored in the directory
F<lib/DBD/Driver>. The module itself would usually be in a file
F<SubModule.pm>. All such sub-modules should themselves be version
stamped (see the discussions far below).

=head3 Extra files needed by C/XS drivers

The software for a C/XS driver will typically contain at least four
extra files that are not relevant to a pure Perl driver.

=over 4

=item * F<Driver.xs>

=item * F<Driver.h>

=item * F<dbdimp.h>

=item * F<dbdimp.c>

=back

The F<Driver.xs> file is used to generate C code that Perl can call to gain
access to the C functions you write that will, in turn, call down onto
your database software.

The F<Driver.h> header is a stylized header that ensures you can access the
necessary Perl and B<DBI> macros, types, and function declarations.

The F<dbdimp.h> is used to specify which functions have been implemented by
your driver.

The F<dbdimp.c> file is where you write the C code that does the real work
of translating between Perl-ish data types and what the database expects
to use and return.

There are some (mainly small, but very important) differences between
the contents of F<Makefile.PL> and F<Driver.pm> for pure Perl and C/XS
drivers, so those files are described both in the section on creating a
pure Perl driver and in the section on creating a C/XS driver.

Obviously, you can add extra source code files to the list.

=head2 Requirements on a driver and driver writer

To be remotely useful, your driver must be implemented in a format that
allows it to be distributed via CPAN, the Comprehensive Perl Archive
Network (L<http://www.cpan.org/> and L<http://search.cpan.org>).
Of course, it is easier if you do not have to meet this criterion, but
you will not be able to ask for much help if you do not do so, and
no-one is likely to want to install your module if they have to learn a
new installation mechanism.

=head1 CREATING A PURE PERL DRIVER

Writing a pure Perl driver is surprisingly simple. However, there are
some problems you should be aware of. The best option is of course
picking up an existing driver and carefully modifying one method
after the other.

Also look carefully at B<DBD::AnyData> and B<DBD::Template>.

As an example we take a look at the B<DBD::File> driver, a driver for
accessing plain files as tables, which is part of the B<DBD::CSV> package.

The minimal set of files we have to implement are F<Makefile.PL>,
F<README>, F<MANIFEST> and F<Driver.pm>.

=head2 Pure Perl version of Makefile.PL

You typically start with writing F<Makefile.PL>, a Makefile
generator. The contents of this file are described in detail in
the L<ExtUtils::MakeMaker> man pages. It is definitely a good idea
if you start reading them. At least you should know about the
variables I<CONFIGURE>, I<DEFINED>, I<PM>, I<DIR>, I<EXE_FILES>,
I<INC>, I<LIBS>, I<LINKTYPE>, I<NAME>, I<OPTIMIZE>, I<PL_FILES>,
I<VERSION>, I<VERSION_FROM>, I<clean>, I<depend>, I<realclean> from
the L<ExtUtils::MakeMaker> man page: these are used in almost any
F<Makefile.PL>.

Additionally read the section on I<Overriding MakeMaker Methods> and the
descriptions of the I<distcheck>, I<disttest> and I<dist> targets: They
will definitely be useful for you.

Of special importance for B<DBI> drivers is the I<postamble> method from
the L<ExtUtils::MM_Unix> man page.