dbd.pm

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

For Emacs users, I recommend the I<libscan> method, which removes
Emacs backup files (file names which end with a tilde '~') from lists of
files.

Now an example, I use the word C<Driver> wherever you should insert
your driver's name:

  # -*- perl -*-

  use DBI 1.03;
  use DBI::DBD;
  use ExtUtils::MakeMaker;

  WriteMakefile(
      dbd_edit_mm_attribs( {
          'NAME'         => 'DBD::Driver',
          'VERSION_FROM' => 'Driver.pm',
          'INC'          => $DBI_INC_DIR,
          'dist'         => { 'SUFFIX'   => '.gz',
                              'COMPRESS' => 'gzip -9f' },
          'realclean'    => { FILES => '*.xsi' },
      },
      { create_pp_tests => 1})
  );

  package MY;
  sub postamble { return main::dbd_postamble(@_); }
  sub libscan {
      my ($self, $path) = @_;
      ($path =~ m/\~$/) ? undef : $path;
  }

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
F<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 I<VERSION_FROM>; the named file (F<Driver.pm>) will
be scanned for the first line that looks like an assignment to I<$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 I<Makefile.PL> can be quite large (for example, the files
for B<DBD::Oracle> and B<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 I<ExtUtils::MakeMaker>.

=head2 README

The L<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.

As always, use the F<README> from one of the established drivers as a basis
for your own; the version in B<DBD::Informix> is worth a look as it has
been quite successful in heading off problems.

=over 4

=item *

Note that users will have versions of Perl and B<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 B<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 F<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 B<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.

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.

=over 4

=item *

Listing B<Bundle::DBI> as the main pre-requisite simplifies life.

=item *

Don't forget to list your driver.

=item *

Note that unless the DBMS is itself a Perl module, you cannot list it as
a pre-requisite in this file.

=item *

You should keep the version of the bundle the same as the version of
your driver.

=item *

You should add configuration management, copyright, and licencing
information at the top.

=back

A suitable skeleton for this file is shown below.

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

=head2 Pure Perl version of Driver.pm

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

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

=over 4

=item DBD::Driver::dr

with methods C<connect()>, C<data_sources()> and C<disconnect_all()>;

=item DBD::Driver::db

with methods such as C<prepare()>;

=item DBD::Driver::st

with methods such as C<execute()> and C<fetch()>.

=back

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

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

Now let's take a closer look at an excerpt of F<File.pm> as an example.
We ignore things that are common to any module (even non-DBI modules)
or really specific to the B<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, and is
where F<Makefile.PL> looks for this information. Please ensure that any
other modules added with your driver are also version stamped so that
CPAN does not get confused.

It is recommended that you use a two-part (1.23) or three-part (1.23.45)
version number. 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 Subversion you could use:

  $VERSION = sprintf("12.%06d", q$Revision: 12345 $ =~ /(\d+)/o);

(use lots of leading zeros on the second portion so if you move the code to a
shared repository like svn.perl.org the much larger revision numbers won't
cause a problem, at least not for a few years).  For RCS or CVS you can use:

  $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

The C<driver()> method is the driver handle constructor. Note that
the C<driver()> method is in the B<DBD::Driver> package, not in
one of the sub-packages B<DBD::Driver::dr>, B<DBD::Driver::db>, or
B<DBD::Driver::db>.

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

      $class .= "::dr";

      DBD::Driver::db->install_method('drv_example_dbh_method');
      DBD::Driver::st->install_method('drv_example_sth_method');

      # 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;
  }

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

The prototype of C<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 C<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 B<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.
B<DBI> will store them and otherwise leave them alone.

=back

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


=head4 Using install_method() to expose driver-private methods

    DBD::Foo::db->install_method($method_name, \%attr);

Installs the driver-private method named by $method_name into the
DBI method dispatcher so it can be called directly, avoiding the
need to use the func() method.

It is called as a static method on the driver class to which the
method belongs. The method name must begin with the corresponding
registered driver-private prefix. For example, for DBD::Oracle