dbi::dbd.3

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

driver and the associated database.
.PP
The files in the \fIt\fR 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:
.IP "\(bu" 4
Your tests should not casually modify operational databases.
.IP "\(bu" 4
You should never damage existing tables in a database.
.IP "\(bu" 4
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 '\fIdbd_drv_\fR'.
.IP "\(bu" 4
At the end of a test run, there should be no testing objects left behind
in the database.
.IP "\(bu" 4
If you create any databases, you should remove them.
.IP "\(bu" 4
If your database supports temporary tables that are automatically
removed at the end of a session, then exploit them as often as possible.
.IP "\(bu" 4
Try to make your tests independent of each other. If you have a
test \fIt/t11dowhat.t\fR that depends upon the successful running
of \fIt/t10thingamy.t\fR, people cannot run the single test case
\&\fIt/t11dowhat.t\fR. Further, running \fIt/t11dowhat.t\fR twice in a row is
likely to fail (at least, if \fIt/t11dowhat.t\fR 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.
.IP "\(bu" 4
Document in your \fI\s-1README\s0\fR file what you do, and what privileges people
need to do it.
.IP "\(bu" 4
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.
.IP "\(bu" 4
It is in your interests to ensure that your tests work as widely
as possible.
.PP
Many drivers also install sub-modules \fBDBD::Driver::SubModule\fR
for any of a variety of different reasons, such as to support
the metadata methods (see the discussion of \*(L"\s-1METADATA\s0 \s-1METHODS\s0\*(R"
below). Such sub-modules are conventionally stored in the directory
\&\fIlib/DBD/Driver\fR. The module itself would usually be in a file
\&\fISubModule.pm\fR. All such sub-modules should themselves be version
stamped (see the discussions far below).
.PP
\fIExtra files needed by C/XS drivers\fR
.IX Subsection "Extra files needed by C/XS drivers"
.PP
The software for a C/XS driver will typically contain at least four
extra files that are not relevant to a pure Perl driver.
.IP "\(bu" 4
\&\fIDriver.xs\fR
.IP "\(bu" 4
\&\fIDriver.h\fR
.IP "\(bu" 4
\&\fIdbdimp.h\fR
.IP "\(bu" 4
\&\fIdbdimp.c\fR
.PP
The \fIDriver.xs\fR 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.
.PP
The \fIDriver.h\fR header is a stylized header that ensures you can access the
necessary Perl and \fB\s-1DBI\s0\fR macros, types, and function declarations.
.PP
The \fIdbdimp.h\fR is used to specify which functions have been implemented by
your driver.
.PP
The \fIdbdimp.c\fR 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.
.PP
There are some (mainly small, but very important) differences between
the contents of \fIMakefile.PL\fR and \fIDriver.pm\fR 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.
.PP
Obviously, you can add extra source code files to the list.
.Sh "Requirements on a driver and driver writer"
.IX Subsection "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 \s-1CPAN\s0, the Comprehensive Perl Archive
Network (<http://www.cpan.org/> and <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.
.SH "CREATING A PURE PERL DRIVER"
.IX Header "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.
.PP
Also look carefully at \fBDBD::AnyData\fR and \fBDBD::Template\fR.
.PP
As an example we take a look at the \fBDBD::File\fR driver, a driver for
accessing plain files as tables, which is part of the \fB\s-1DBD::CSV\s0\fR package.
.PP
The minimal set of files we have to implement are \fIMakefile.PL\fR,
\&\fI\s-1README\s0\fR, \fI\s-1MANIFEST\s0\fR and \fIDriver.pm\fR.
.Sh "Pure Perl version of Makefile.PL"
.IX Subsection "Pure Perl version of Makefile.PL"
You typically start with writing \fIMakefile.PL\fR, a Makefile
generator. The contents of this file are described in detail in
the ExtUtils::MakeMaker man pages. It is definitely a good idea
if you start reading them. At least you should know about the
variables \fI\s-1CONFIGURE\s0\fR, \fI\s-1DEFINED\s0\fR, \fI\s-1PM\s0\fR, \fI\s-1DIR\s0\fR, \fI\s-1EXE_FILES\s0\fR,
\&\fI\s-1INC\s0\fR, \fI\s-1LIBS\s0\fR, \fI\s-1LINKTYPE\s0\fR, \fI\s-1NAME\s0\fR, \fI\s-1OPTIMIZE\s0\fR, \fI\s-1PL_FILES\s0\fR,
\&\fI\s-1VERSION\s0\fR, \fI\s-1VERSION_FROM\s0\fR, \fIclean\fR, \fIdepend\fR, \fIrealclean\fR from
the ExtUtils::MakeMaker man page: these are used in almost any
\&\fIMakefile.PL\fR.
.PP
Additionally read the section on \fIOverriding MakeMaker Methods\fR and the
descriptions of the \fIdistcheck\fR, \fIdisttest\fR and \fIdist\fR targets: They
will definitely be useful for you.
.PP
Of special importance for \fB\s-1DBI\s0\fR drivers is the \fIpostamble\fR method from
the ExtUtils::MM_Unix man page.
.PP
For Emacs users, I recommend the \fIlibscan\fR method, which removes
Emacs backup files (file names which end with a tilde '~') from lists of
files.
.PP
Now an example, I use the word \f(CW\*(C`Driver\*(C'\fR wherever you should insert
your driver's name:
.PP
.Vb 1
\&  # \-*\- perl \-*\-
\&
\&  use DBI 1.03;
\&  use DBI::DBD;
\&  use ExtUtils::MakeMaker;
\&
\&  WriteMakefile(
\&      dbd_edit_mm_attribs( {
\&          \*(AqNAME\*(Aq         => \*(AqDBD::Driver\*(Aq,
\&          \*(AqVERSION_FROM\*(Aq => \*(AqDriver.pm\*(Aq,
\&          \*(AqINC\*(Aq          => $DBI_INC_DIR,
\&          \*(Aqdist\*(Aq         => { \*(AqSUFFIX\*(Aq   => \*(Aq.gz\*(Aq,
\&                              \*(AqCOMPRESS\*(Aq => \*(Aqgzip \-9f\*(Aq },
\&          \*(Aqrealclean\*(Aq    => { FILES => \*(Aq*.xsi\*(Aq },
\&      },
\&      { create_pp_tests => 1})
\&  );
\&
\&  package MY;
\&  sub postamble { return main::dbd_postamble(@_); }
\&  sub libscan {
\&      my ($self, $path) = @_;
\&      ($path =~ m/\e~$/) ? undef : $path;
\&  }
.Ve
.PP
Note the calls to \f(CW\*(C`dbd_edit_mm_attribs()\*(C'\fR and \f(CW\*(C`dbd_postamble()\*(C'\fR.
.PP
The second hash reference in the call to \f(CW\*(C`dbd_edit_mm_attribs()\*(C'\fR
(containing \f(CW\*(C`create_pp_tests()\*(C'\fR) is optional; you should not use it
unless your driver is a pure Perl driver (that is, it does not use C and
\&\s-1XS\s0 code). Therefore, the call to \f(CW\*(C`dbd_edit_mm_attribs()\*(C'\fR is not
relevant for C/XS drivers and may be omitted; simply use the (single)
hash reference containing \s-1NAME\s0 etc as the only argument to \f(CW\*(C`WriteMakefile()\*(C'\fR.
.PP
Note that the \f(CW\*(C`dbd_edit_mm_attribs()\*(C'\fR code will fail if you do not have a
\&\fIt\fR sub-directory containing at least one test case.
.PP
All drivers must use \f(CW\*(C`dbd_postamble()\*(C'\fR or risk running into problems.
.PP
Note the specification of \fI\s-1VERSION_FROM\s0\fR; the named file (\fIDriver.pm\fR) will
be scanned for the first line that looks like an assignment to \fI\f(CI$VERSION\fI\fR,
and the subsequent text will be used to determine the version number.
Note the commentary in ExtUtils::MakeMaker on the subject of
correctly formatted version numbers.
.PP
If your driver depends upon external software (it usually will), you
will need to add code to ensure that your environment is workable before
the call to \f(CW\*(C`WriteMakefile()\*(C'\fR.
.PP
A full-fledged \fIMakefile.PL\fR can be quite large (for example, the files
for \fBDBD::Oracle\fR and \fBDBD::Informix\fR are both over 1000 lines long, and the
Informix one uses \- and creates \- auxilliary modules too).
.PP
See also ExtUtils::MakeMaker and ExtUtils::MM_Unix. Consider using
CPAN::MakeMaker in place of \fIExtUtils::MakeMaker\fR.
.Sh "\s-1README\s0"
.IX Subsection "README"
The \s-1README\s0 file should describe what the driver is for, the
pre-requisites for the build process, the actual build process, how to
report errors, and who to report them to.
.PP
Users will find ways of breaking the driver build and test process
which you would never even have dreamed to be possible in your worst
nightmares. Therefore, you need to write this document defensively,
precisely and concisely.
.PP
As always, use the \fI\s-1README\s0\fR from one of the established drivers as a basis
for your own; the version in \fBDBD::Informix\fR is worth a look as it has
been quite successful in heading off problems.
.IP "\(bu" 4
Note that users will have versions of Perl and \fB\s-1DBI\s0\fR that are both older
and newer than you expected, but this will seldom cause much trouble.
When it does, it will be because you are using features of \fB\s-1DBI\s0\fR that are
not supported in the version they are using.
.IP "\(bu" 4
Note that users will have versions of the database software that are
both older and newer than you expected. You will save yourself time in
the long run if you can identify the range of versions which have been
tested and warn about versions which are not known to be \s-1OK\s0.
.IP "\(bu" 4
Note that many people trying to install your driver will not be experts
in the database software.
.IP "\(bu" 4
Note that many people trying to install your driver will not be experts
in C or Perl.
.Sh "\s-1MANIFEST\s0"
.IX Subsection "MANIFEST"
The \fI\s-1MANIFEST\s0\fR will be used by the Makefile's dist target to build the
distribution tar file that is uploaded to \s-1CPAN\s0. It should list every
file that you want to include in your distribution, one per line.
.Sh "lib/Bundle/DBD/Driver.pm"
.IX Subsection "lib/Bundle/DBD/Driver.pm"
The \s-1CPAN\s0 module provides an extremely powerful bundle mechanism that
allows you to specify pre-requisites for your driver.
.PP
The primary pre-requisite is \fBBundle::DBI\fR; you may want or need to add
some more. With the bundle set up correctly, the user can type:
.PP
.Vb 1
\&        perl \-MCPAN \-e \*(Aqinstall Bundle::DBD::Driver\*(Aq
.Ve
.PP
and Perl will download, compile, test and install all the Perl modules
needed to build your driver.
.PP
The prerequisite modules are listed in the \f(CW\*(C`CONTENTS\*(C'\fR section, with the
official name of the module followed by a dash and an informal name or
description.
.IP "\(bu" 4
Listing \fBBundle::DBI\fR as the main pre-requisite simplifies life.
.IP "\(bu" 4
Don't forget to list your driver.
.IP "\(bu" 4
Note that unless the \s-1DBMS\s0 is itself a Perl module, you cannot list it as
a pre-requisite in this file.
.IP "\(bu" 4
You should keep the version of the bundle the same as the version of
your driver.
.IP "\(bu" 4
You should add configuration management, copyright, and licencing
information at the top.
.PP
A suitable skeleton for this file is shown below.
.PP
.Vb 1
\&  package Bundle::DBD::Driver;
\&
\&  $VERSION = \*(Aq0.01\*(Aq;
\&
\&  1;
\&
\&  _\|_END_\|_
\&
\&  =head1 NAME
\&
\&  Bundle::DBD::Driver \- A bundle to install all DBD::Driver related modules
\&
\&  =head1 SYNOPSIS
\&
\&  C<perl \-MCPAN \-e \*(Aqinstall Bundle::DBD::Driver\*(Aq>
\&
\&  =head1 CONTENTS
\&
\&  Bundle::DBI  \- Bundle for DBI by TIMB (Tim Bunce)
\&
\&  DBD::Driver  \- DBD::Driver by YOU (Your Name)
\&
\&  =head1 DESCRIPTION
\&
\&  This bundle includes all the modules used by the Perl Database
\&  Interface (DBI) driver for Driver (DBD::Driver), assuming the
\&  use of DBI version 1.13 or later, created by Tim Bunce.
\&
\&  If you\*(Aqve not previously used the CPAN module to install any
\&  bundles, you will be interrogated during its setup phase.
\&  But when you\*(Aqve done it once, it remembers what you told it.
\&  You could start by running:
\&
\&    C<perl \-MCPAN \-e \*(Aqinstall Bundle::CPAN\*(Aq>
\&
\&  =head1 SEE ALSO
\&
\&  Bundle::DBI
\&
\&  =head1 AUTHOR
\&
\&  Your Name E<lt>F<[e-mail]>E<gt>
\&
\&  =head1 THANKS
\&
\&  This bundle was created by ripping off Bundle::libnet created by
\&  Graham Barr E<lt>F<[e-mail]>E<gt>, and radically simplified
\&  with some information from Jochen Wiedmann E<lt>F<[e-mail]>E<gt>.
\&  The template was then included in the DBI::DBD documentation by
\&  Jonathan Leffler E<lt>F<[e-mail]>E<gt>.
\&
\&  =cut
.Ve
.Sh "lib/DBD/Driver/Summary.pm"
.IX Subsection "lib/DBD/Driver/Summary.pm"
There is no substitute for taking the summary file from a driver that
was documented in the Perl book (such as \fBDBD::Oracle\fR or \fBDBD::Informix\fR or
\&\fB\s-1DBD::ODBC\s0\fR, to name but three), and adapting it to describe the
facilities available via \fBDBD::Driver\fR when accessing the Driver database.
.Sh "Pure Perl version of Driver.pm"
.IX Subsection "Pure Perl version of Driver.pm"
The \fIDriver.pm\fR file defines the Perl module \fBDBD::Driver\fR for your driver.
It will define a package \fBDBD::Driver\fR along with some version information,
some variable definitions, and a function \f(CW\*(C`driver()\*(C'\fR which will have a more
or less standard structure.
.PP
It will also define three sub-packages of \fBDBD::Driver\fR:
.IP "DBD::Driver::dr" 4
.IX Item "DBD::Driver::dr"
with methods \f(CW\*(C`connect()\*(C'\fR, \f(CW\*(C`data_sources()\*(C'\fR and \f(CW\*(C`disconnect_all()\*(C'\fR;
.IP "DBD::Driver::db" 4
.IX Item "DBD::Driver::db"