dbd.pm

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

function correctly (see L</Statement attributes> below).

We present a simplified implementation by using the I<drv_params>
attribute from above:

  sub bind_param
  {
      my ($sth, $pNum, $val, $attr) = @_;
      my $type = (ref $attr) ? $attr->{TYPE} : $attr;
      if ($type) {
          my $dbh = $sth->{Database};
          $val = $dbh->quote($sth, $type);
      }
      my $params = $sth->{drv_params};
      $params->[$pNum-1] = $val;
      1;
  }

  sub execute
  {
      my ($sth, @bind_values) = @_;

      # start of by finishing any previous execution if still active
      $sth->finish if $sth->FETCH('Active');

      my $params = (@bind_values) ?
          \@bind_values : $sth->{drv_params};
      my $numParam = $sth->FETCH('NUM_OF_PARAMS');
      return $sth->set_err($DBI::stderr, "Wrong number of parameters")
          if @$params != $numParam;
      my $statement = $sth->{'Statement'};
      for (my $i = 0;  $i < $numParam;  $i++) {
          $statement =~ s/?/$params->[$i]/; # XXX doesn't deal with quoting etc!
      }
      # Do anything ... we assume that an array ref of rows is
      # created and store it:
      $sth->{'drv_data'} = $data;
      $sth->{'drv_rows'} = @$data; # number of rows
      $sth->STORE('NUM_OF_FIELDS') = $numFields;
      $sth->{Active} = 1;
      @$data || '0E0';
  }

There are a number of things you should note here.

We initialize the I<NUM_OF_FIELDS> and I<Active> attributes here,
because they are essential for C<bind_columns()> to work.

We use attribute C<$sth-E<gt>{Statement}> which we created
within C<prepare()>. The attribute C<$sth-E<gt>{Database}>, which is
nothing else than the I<dbh>, was automatically created by B<DBI>.

Finally, note that (as specified in the B<DBI> specification) we return the
string C<'0E0'> instead of the number 0, so that the result tests true but
equal to zero.

  $sth->execute() or die $sth->errstr;

=head4 The execute_array(), execute_for_fetch() and bind_param_array() methods

In general, DBD's only need to implement C<execute_for_fetch()> and
C<bind_param_array>. DBI's default C<execute_array()> will invoke the
DBD's C<execute_for_fetch()> as needed.

The following sequence describes the interaction between
DBI C<execute_array> and a DBD's C<execute_for_fetch>:

=over

=item 1

App calls C<$sth-E<gt>execute_array(\%attrs, @array_of_arrays)>

=item 2

If C<@array_of_arrays> was specified, DBI processes C<@array_of_arrays> by calling
DBD's C<bind_param_array()>. Alternately, App may have directly called
C<bind_param_array()>

=item 3

DBD validates and binds each array

=item 4

DBI retrieves the validated param arrays from DBD's ParamArray attribute

=item 5

DBI calls DBD's C<execute_for_fetch($fetch_tuple_sub, \@tuple_status)>,
where C<&$fetch_tuple_sub> is a closure to iterate over the
returned ParamArray values, and C<\@tuple_status> is an array to receive
the disposition status of each tuple.

=item 6

DBD iteratively calls C<&$fetch_tuple_sub> to retrieve parameter tuples
to be added to its bulk database operation/request.

=item 7

when DBD reaches the limit of tuples it can handle in a single database
operation/request, or the C<&$fetch_tuple_sub> indicates no more
tuples by returning undef, the DBD executes the bulk operation, and
reports the disposition of each tuple in \@tuple_status.

=item 8

DBD repeats steps 6 and 7 until all tuples are processed.

=back

E.g., here's the essence of L<DBD::Oracle>'s execute_for_fetch:

       while (1) {
           my @tuple_batch;
           for (my $i = 0; $i < $batch_size; $i++) {
                push @tuple_batch, [ @{$fetch_tuple_sub->() || last} ];
           }
           last unless @tuple_batch;
           my $res = ora_execute_array($sth, \@tuple_batch,
              scalar(@tuple_batch), $tuple_batch_status);
           push @$tuple_status, @$tuple_batch_status;
       }

Note that DBI's default execute_array()/execute_for_fetch() implementation
requires the use of positional (i.e., '?') placeholders. Drivers
which B<require> named placeholders must either emulate positional
placeholders (e.g., see L<DBD::Oracle>), or must implement their own
execute_array()/execute_for_fetch() methods to properly sequence bound
parameter arrays.

=head4 Fetching data

Only one method needs to be written for fetching data, C<fetchrow_arrayref()>.
The other methods, C<fetchrow_array()>, C<fetchall_arrayref()>, etc, as well
as the database handle's C<select*> methods are part of B<DBI>, and call
C<fetchrow_arrayref()> as necessary.

  sub fetchrow_arrayref
  {
      my ($sth) = @_;
      my $data = $sth->{drv_data};
      my $row = shift @$data;
      if (!$row) {
          $sth->STORE(Active => 0); # mark as no longer active
          return undef;
      }
      if ($sth->FETCH('ChopBlanks')) {
          map { $_ =~ s/\s+$//; } @$row;
      }
      return $sth->_set_fbav($row);
  }
  *fetch = \&fetchrow_arrayref; # required alias for fetchrow_arrayref

Note the use of the method C<_set_fbav()> -- this is required so that
C<bind_col()> and C<bind_columns()> work.

If an error occurs which leaves the I<$sth> in a state where remaining rows
can't be fetched then I<Active> should be turned off before the method returns.

The C<rows()> method for this driver can be implemented like this:

  sub rows { shift->{drv_rows} }

because it knows in advance how many rows it has fetched.
Alternatively you could delete that method and so fallback
to the B<DBI>'s own method which does the right thing based
on the number of calls to C<_set_fbav()>.

=head4 The more_results method

If your driver doesn't support multiple result sets, then don't even implement this method.

Otherwise, this method needs to get the statement handle ready to fetch results
from the next result set, if there is one. Typically you'd start with:

    $sth->finish;

then you should delete all the attributes from the attribute cache that may no
longer be relevant for the new result set:

    delete $sth->{$_}
        for qw(NAME TYPE PRECISION SCALE ...);

for drivers written in C use:

    hv_delete((HV*)SvRV(sth), "NAME", 4, G_DISCARD);
    hv_delete((HV*)SvRV(sth), "NULLABLE", 8, G_DISCARD);
    hv_delete((HV*)SvRV(sth), "NUM_OF_FIELDS", 13, G_DISCARD);
    hv_delete((HV*)SvRV(sth), "PRECISION", 9, G_DISCARD);
    hv_delete((HV*)SvRV(sth), "SCALE", 5, G_DISCARD);
    hv_delete((HV*)SvRV(sth), "TYPE", 4, G_DISCARD);

Don't forget to also delete, or update, any driver-private attributes that may
not be correct for the next resultset.

The NUM_OF_FIELDS attribute is a special case. It should be set using STORE:

    $sth->STORE(NUM_OF_FIELDS => 0); /* for DBI <= 1.53 */
    $sth->STORE(NUM_OF_FIELDS => $new_value);

for drivers written in C use this incantation:

    /* Adjust NUM_OF_FIELDS - which also adjusts the row buffer size */
    DBIc_NUM_FIELDS(imp_sth) = 0; /* for DBI <= 1.53 */
    DBIc_STATE(imp_xxh)->set_attr_k(sth, sv_2mortal(newSVpvn("NUM_OF_FIELDS",13)), 0,
        sv_2mortal(newSViv(mysql_num_fields(imp_sth->result)))
    );

For DBI versions prior to 1.54 you'll also need to explicitly adjust the
number of elements in the row buffer array (C<DBIc_FIELDS_AV(imp_sth)>)
to match the new result set. Fill any new values with newSV(0) not &sv_undef.
Alternatively you could free DBIc_FIELDS_AV(imp_sth) and set it to null,
but that would mean bind_columns() woudn't work across result sets.


=head4 Statement attributes

The main difference between I<dbh> and I<sth> attributes is, that you
should implement a lot of attributes here that are required by
the B<DBI>, such as I<NAME>, I<NULLABLE>, I<TYPE>, etc. See
L<DBI/Statement Handle Attributes> for a complete list.

Pay attention to attributes which are marked as read only, such as
I<NUM_OF_PARAMS>. These attributes can only be set the first time
a statement is executed. If a statement is prepared, then executed
multiple times, warnings may be generated.

You can protect against these warnings, and prevent the recalculation
of attributes which might be expensive to calculate (such as the
I<NAME> and I<NAME_*> attributes):

    my $storedNumParams = $sth->FETCH('NUM_OF_PARAMS');
    if (!defined $storedNumParams or $storedNumFields < 0) {
        $sth->STORE('NUM_OF_PARAMS') = $numParams;

        # Set other useful attributes that only need to be set once
        # for a statement, like $sth->{NAME} and $sth->{TYPE}
    }

One particularly important attribute to set correctly (mentioned in
L<DBI/ATTRIBUTES COMMON TO ALL HANDLES> is I<Active>. Many B<DBI> methods,
including C<bind_columns()>, depend on this attribute.

Besides that the C<STORE()> and C<FETCH()> methods are mainly the same
as above for I<dbh>'s.

=head4 Other statement methods

A trivial C<finish()> method to discard stored data, reset any attributes
(such as I<Active>) and do C<$sth-E<gt>SUPER::finish()>.

If you've defined a C<parse_trace_flag()> method in B<::db> you'll also want
it in B<::st>, so just alias it in:

  *parse_trace_flag = \&DBD::foo:db::parse_trace_flag;

And perhaps some other methods that are not part of the B<DBI>
specification, in particular to make metadata available.
Remember that they must have names that begin with your drivers
registered prefix so they can be installed using C<install_method()>.

If C<DESTROY()> is called on a statement handle that's still active
(C<$sth-E<gt>{Active}> is true) then it should effectively call C<finish()>.

    sub DESTROY {
        my $sth = shift;
        $sth->finish if $sth->FETCH('Active');
    }

=head2 Tests

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

In particular, most (all) of the tests should be run in the F<t> sub-directory,
and should simply produce an C<ok> when run under C<make test>.
For details on how this is done, see the Camel book and the section in
Chapter 7, "The Standard Perl Library" on L<Test::Harness>.

The tests may need to adapt to the type of database which is being used
for testing, and to the privileges of the user testing the driver. For
example, the B<DBD::Informix> test code has to adapt in a number of
places to the type of database to which it is connected as different
Informix databases have different capabilities: some of the tests are
for databases without transaction logs; others are for databases with a
transaction log; some versions of the server have support for blobs, or
stored procedures, or user-defined data types, and others do not.

When a complete file of tests must be skipped, you can provide a reason
in a pseudo-comment:

    if ($no_transactions_available)
    {
        print "1..0 # Skip: No transactions available\n";
        exit 0;
    }

Consider downloading the B<DBD::Informix> code and look at the code in
F<DBD/Informix/TestHarness.pm> which is used throughout the
B<DBD::Informix> tests in the F<t> sub-directory.

=head1 CREATING A C/XS DRIVER

Creating a new C/XS driver from scratch will always be a daunting task.
You can and should greatly simplify your task by taking a good
reference driver implementation and modifying that to match the
database product for which you are writing a driver.

The de facto reference driver has been the one for B<DBD::Oracle> written
by Tim Bunce, who is also the author of the B<DBI> package. The B<DBD::Oracle>
module is a good example of a driver implemented around a C-level API.

Nowadays it it seems better to base on B<DBD::ODBC>, another driver
maintained by Tim and Jeff Urlwin, because it offers a lot of metadata
and seems to become the guideline for the future development. (Also as
B<DBD::Oracle> digs deeper into the Oracle 8 OCI interface it'll get even
more hairy than it is now.)

The B<DBD::Informix> driver is one driver implemented using embedded SQL
instead of a function-based API.
B<DBD::Ingres> may also be worth a look.

=head2 C/XS version of Driver.pm

A lot of the code in the F<Driver.pm> file is very similar to the code for pure Perl modules
- see above.  However,
there are also some subtle (and not so subtle) differences, including:

=over 8

=item *

The variables I<$DBD::Driver::{dr|db|st}::imp_data_size> are not defined
here, but in the XS code, because they declare the size of certain
C structures.

=item *

Some methods are typically moved to the XS code, in particular
C<prepare()>, C<execute()>, C<disconnect()>, C<disconnect_all()> and the
C<STORE()> and C<FETCH()> methods.

=item *

Other methods are still part of F<Driver.pm>, but have callbacks to
the XS code.

=item *

If the driver-specific parts of the I<imp_drh_t> structure need to be
formally initialized (which does not seem to be a common requirement),
then you need to add a call to an appropriate XS function in the driver
method of C<DBD::Driver::driver()>, and you define the corresponding function
in F<Driver.xs>, and you define the C code in F<dbdimp.c> and the prototype in
F<dbdimp.h>.

For example, B<DBD::Informix> has such a requirement, and adds the
following call after the call to C<_new_drh()> in F<Informix.pm>:

  DBD::Informix::dr::driver_init($drh);

and the following code in F<Informix.xs>:

  # Initialize the DBD::Informix driver data structure
  void
  driver_init(drh)
      SV *drh
      CODE: