dbd.pm

SinFP是一种新的识别对方计算机操作系统类型的工具

Note the calls to C<dbd_edit_mm_attribs>() and C<dbd_postamble>().
The second hash reference in the call to C<dbd_edit_mm_attribs>
(containing C<create_pp_tests>) is optional; you should not use it
unless your driver is a pure Perl driver (that is, it does not use C and
XS code).
Therefore, the call to C<dbd_edit_mm_attribs> is not relevant for C/XS
drivers and may be omitted; simply use the (single) hash reference
containing NAME etc as the only argument to C<WriteMakefile>().
Note that the C<dbd_edit_mm_attribs> code will fail if you do not have a
C<t> sub-directory containing at least one test case.
All drivers must use C<dbd_postamble> or risk running into problems.

Note the specification of VERSION_FROM; the named file (Driver.pm) will
be scanned for the first line that looks like an assignment to $VERSION,
and the subsequent text will be used to determine the version number.
Note the commentary in L<ExtUtils::MakeMaker> on the subject of
correctly formatted version numbers.

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 C<WriteMakefile>().
A full-fledged Makefile.PL can be quite large (for example, the files
for DBD::Oracle and DBD::Informix are both over 1000 lines long, and the
Informix one uses - and creates - auxilliary modules too).

See also L<ExtUtils::MakeMaker> and L<ExtUtils::MM_Unix>.
Consider using L<CPAN::MakeMaker> in place of ExtUtils::MakeMaker.

=head2 README

The README 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.
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.
Also, it is in your interests to ensure that your tests work as widely
as possible.
As always, use the README from one of the established drivers as a basis
for your own; the version in DBD::Informix is worth a look as it has
been quite successful in heading off problems.

=over 2

=item *

Note that users will have versions of Perl and DBI 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 DBI that are
not supported in the version they are using.

=item *

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 OK.

=item *

Note that many people trying to install your driver will not be experts
in the database software.

=item *

Note that many people trying to install your driver will not be experts
in C or Perl.

=back

=head2 MANIFEST

The MANIFEST will be used by the Makefile's dist target to build the
distribution tar file that is uploaded to CPAN. It should list every
file that you want to include in your distribution, one per line.

=head2 lib/Bundle/DBD/Driver.pm

The CPAN module provides an extremely powerful bundle mechanism that
allows you to specify pre-requisites for your driver.
The primary pre-requisite is Bundle::DBI; you may want or need to add
some more.
With the bundle set up correctly, the user can type:

        perl -MCPAN -e 'install Bundle::DBD::Driver'

and Perl will download, compile, test and install all the Perl modules
needed to build your driver.

A suitable skeleton for this file is shown below.
The prerequisite modules are listed in the C<CONTENTS> section, with the
official name of the module followed by a dash and an informal name or
description.
Listing Bundle::DBI as the main pre-requisite simplifies life.
Don't forget to list your driver.
Note that unless the DBMS is itself a Perl module, you cannot list it as
a pre-requisite in this file.
You should keep the version of the bundle the same as the version of
your driver.
You should add configuration management, copyright, and licencing
information at the top.

  package Bundle::DBD::Driver;

  $VERSION = '0.01';

  1;

  __END__

  =head1 NAME

  Bundle::DBD::Driver - A bundle to install all DBD::Driver related modules

  =head1 SYNOPSIS

  C<perl -MCPAN -e 'install Bundle::DBD::Driver'>

  =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've not previously used the CPAN module to install any
  bundles, you will be interrogated during its setup phase.
  But when you've done it once, it remembers what you told it.
  You could start by running:

    C<perl -MCPAN -e 'install Bundle::CPAN'>

  =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

=head2 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 DBD::Oracle or DBD::Informix or
DBD::ODBC, to name but three), and adapting it to describe the
facilities available via DBD::Driver when accessing the Driver database.

=head2 Pure Perl version of Driver.pm

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

It will also define three sub-packages of DBD::Driver:

=over 2

=item DBD::Driver::dr

with methods connect(), data_sources() and disconnect_all();

=item DBD::Driver::db

with methods such as prepare();

=item DBD::Driver::st

with methods such as execute() and fetch().

=back

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

In a pure Perl driver, the Driver.pm file is the core of the
implementation.
You will need to provide all the key methods needed by DBI.

Now let's take a closer look at an excerpt of File.pm as an example.
We ignore things that are common to any module (even non-DBI modules)
or really specific to the DBD::File package.

=head3 The DBD::Driver package

=head4 The header

  package DBD::File;

  use strict;
  use vars qw($VERSION $drh);

  $VERSION = "1.23.00"  # Version number of DBD::File

This is where the version number of your driver is specified.
The code in Makefile.PL is told to look in this file for the
information.
It is recommended that you use a two-part (1.23) or three-part (1.23.45)
version number.
Please ensure that any other modules added with your driver are also
version stamped so that CPAN does not get confused.
Also consider the CPAN system, which gets confused and considers
version 1.10 to precede version 1.9, so that using a raw CVS, RCS or
SCCS version number is probably not appropriate (despite being very
common). For RCS or CVS you can use this code:

  $VERSION = sprintf "%d.%02d", '$Revision: 11.21 $ ' =~ /(\d+)\.(\d+)/;

which pads out the fractional part with leading zeros so all is well
(so long as you don't go past x.99)

  $drh = undef;         # holds driver handle once initialized

This is where the driver handle will be stored, once created.
Note that you may assume there is only one handle for your driver.

=head4 The driver constructor

Note that the I<driver> method is in the DBD::Driver package, not in one
of the sub-packages DBD::Driver::dr, DBD::Driver::db, or
DBD::Driver::db.

  sub driver
  {
      return $drh if $drh;      # already created - return same one
      my ($class, $attr) = @_;

      $class .= "::dr";

      # not a 'my' since we use it above to prevent multiple drivers
      $drh = DBI::_new_drh($class, {
              'Name'        => 'File',
              'Version'     => $VERSION,
              'Attribution' => 'DBD::File by Jochen Wiedmann',
          })
          or return undef;

      return $drh;
  }

The I<driver> method is the driver handle constructor. It's a
reasonable example of how DBI implements its handles. There are three
kinds: B<driver handles> (typically stored in C<$drh>; from now on
called C<drh> or C<$drh>), B<database handles> (from now on called C<dbh> or
C<$dbh>) and B<statement handles> (from now on called C<sth> or
C<$sth>).

The prototype of DBI::_new_drh is

  $drh = DBI::_new_drh($class, $public_attrs, $private_attrs);

with the following arguments:

=over 4

=item I<$class>

is typically the class for your driver, (for example, "DBD::File::dr"),
passed as the first argument to the I<driver> method.

=item I<$public_attrs>

is a hash ref to attributes like I<Name>, I<Version>, and I<Attribution>.
These are processed and used by DBI.
You had better not make any assumptions about them nor should you add
private attributes here.

=item I<$private_attrs>

This is another (optional) hash ref with your private attributes.
DBI will store them and otherwise leave them alone.

=back

The I<DBI::new_drh> method and the I<driver> method both return C<undef>
for failure (in which case you must look at $DBI::err and $DBI::errstr
for the failure information, because you have no driver handle to use).

=head4 The CLONE special subroutine

Also needed here, in the DBD::Driver package, is a CLONE() method
that will be called by perl when an intrepreter is cloned. All your
CLONE method needs to do, currently, is clear the cached $drh so
the new interpreter won't start using the cached $drh from the old
interpreter:

  sub CLONE {
    undef $drh;
  }

See L<http://search.cpan.org/dist/perl/pod/perlmod.pod#Making_your_module_threadsafe>
for details.

=head3 The DBD::Driver::dr package

=head4 The database handle constructor

The next lines of code look as follows:

  package DBD::Driver::dr; # ====== DRIVER ======

  $DBD::Driver::dr::imp_data_size = 0;

Note that no @ISA is needed here, or for the other DBD::Driver::*
classes, because the DBI takes care of that for you when the driver is
loaded.

The database handle constructor is a driver method, thus we have
to change the namespace.

  sub connect
  {
      my ($drh, $dr_dsn, $user, $auth, $attr) = @_;

      # Some database specific verifications, default settings
      # and the like can go here. This should only include
      # syntax checks or similar stuff where it's legal to
      # 'die' in case of errors.
      # For example, many database packages requires specific
      # environment variables to be set; this could be where you
      # validate that they are set, or default them if they are not set.

      $my $driver_prefix = "drv_"; # the assigned prefix for this driver

      # Process attributes from the DSN; we assume ODBC syntax
      # here, that is, the DSN looks like var1=val1;...;varN=valN
      foreach my $var ( split /;/, $dr_dsn ) {
          my ($attr_name, $attr_value) = split '=', $var, 2;
	  return $drh->set_err(1, "Can't parse DSN part '$var'")
              unless defined $attr_value;

          # add driver prefix to attribute name if it doesn't have it already
          $attr_name = $driver_prefix.$attr_name
              unless $attr_name =~ /^$driver_prefix/o;

	  # Store attribute into %$attr, replacing any existing value.
          # The DBI will STORE() these into $dbh after we've connected
	  $attr->{$attr_name} = $attr_value;
      }

      # Get the attributes we'll use to connect.
      # We use delete here because these no need to STORE them
      my $db = delete $attr->{drv_database} || delete $attr->{drv_db}
          or return $drh->set_err(1, "No database name given in DSN '$dr_dsn'");
      my $host = delete $attr->{drv_host} || 'localhost';