dbi::dbd.3

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

.Vb 10
\&       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, \e@tuple_batch,
\&              scalar(@tuple_batch), $tuple_batch_status);
\&           push @$tuple_status, @$tuple_batch_status;
\&       }
.Ve
.PP
Note that \s-1DBI\s0's default \fIexecute_array()\fR/\fIexecute_for_fetch()\fR implementation
requires the use of positional (i.e., '?') placeholders. Drivers
which \fBrequire\fR named placeholders must either emulate positional
placeholders (e.g., see DBD::Oracle), or must implement their own
\&\fIexecute_array()\fR/\fIexecute_for_fetch()\fR methods to properly sequence bound
parameter arrays.
.PP
Fetching data
.IX Subsection "Fetching data"
.PP
Only one method needs to be written for fetching data, \f(CW\*(C`fetchrow_arrayref()\*(C'\fR.
The other methods, \f(CW\*(C`fetchrow_array()\*(C'\fR, \f(CW\*(C`fetchall_arrayref()\*(C'\fR, etc, as well
as the database handle's \f(CW\*(C`select*\*(C'\fR methods are part of \fB\s-1DBI\s0\fR, and call
\&\f(CW\*(C`fetchrow_arrayref()\*(C'\fR as necessary.
.PP
.Vb 10
\&  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(\*(AqChopBlanks\*(Aq)) {
\&          map { $_ =~ s/\es+$//; } @$row;
\&      }
\&      return $sth\->_set_fbav($row);
\&  }
\&  *fetch = \e&fetchrow_arrayref; # required alias for fetchrow_arrayref
.Ve
.PP
Note the use of the method \f(CW\*(C`_set_fbav()\*(C'\fR \*(-- this is required so that
\&\f(CW\*(C`bind_col()\*(C'\fR and \f(CW\*(C`bind_columns()\*(C'\fR work.
.PP
If an error occurs which leaves the \fI\f(CI$sth\fI\fR in a state where remaining rows
can't be fetched then \fIActive\fR should be turned off before the method returns.
.PP
The \f(CW\*(C`rows()\*(C'\fR method for this driver can be implemented like this:
.PP
.Vb 1
\&  sub rows { shift\->{drv_rows} }
.Ve
.PP
because it knows in advance how many rows it has fetched.
Alternatively you could delete that method and so fallback
to the \fB\s-1DBI\s0\fR's own method which does the right thing based
on the number of calls to \f(CW\*(C`_set_fbav()\*(C'\fR.
.PP
The more_results method
.IX Subsection "The more_results method"
.PP
If your driver doesn't support multiple result sets, then don't even implement this method.
.PP
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:
.PP
.Vb 1
\&    $sth\->finish;
.Ve
.PP
then you should delete all the attributes from the attribute cache that may no
longer be relevant for the new result set:
.PP
.Vb 2
\&    delete $sth\->{$_}
\&        for qw(NAME TYPE PRECISION SCALE ...);
.Ve
.PP
for drivers written in C use:
.PP
.Vb 6
\&    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);
.Ve
.PP
Don't forget to also delete, or update, any driver-private attributes that may
not be correct for the next resultset.
.PP
The \s-1NUM_OF_FIELDS\s0 attribute is a special case. It should be set using \s-1STORE:\s0
.PP
.Vb 2
\&    $sth\->STORE(NUM_OF_FIELDS => 0); /* for DBI <= 1.53 */
\&    $sth\->STORE(NUM_OF_FIELDS => $new_value);
.Ve
.PP
for drivers written in C use this incantation:
.PP
.Vb 5
\&    /* 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)))
\&    );
.Ve
.PP
For \s-1DBI\s0 versions prior to 1.54 you'll also need to explicitly adjust the
number of elements in the row buffer array (\f(CW\*(C`DBIc_FIELDS_AV(imp_sth)\*(C'\fR)
to match the new result set. Fill any new values with \fInewSV\fR\|(0) not &sv_undef.
Alternatively you could free DBIc_FIELDS_AV(imp_sth) and set it to null,
but that would mean \fIbind_columns()\fR woudn't work across result sets.
.PP
Statement attributes
.IX Subsection "Statement attributes"
.PP
The main difference between \fIdbh\fR and \fIsth\fR attributes is, that you
should implement a lot of attributes here that are required by
the \fB\s-1DBI\s0\fR, such as \fI\s-1NAME\s0\fR, \fI\s-1NULLABLE\s0\fR, \fI\s-1TYPE\s0\fR, etc. See
\&\*(L"Statement Handle Attributes\*(R" in \s-1DBI\s0 for a complete list.
.PP
Pay attention to attributes which are marked as read only, such as
\&\fI\s-1NUM_OF_PARAMS\s0\fR. 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.
.PP
You can protect against these warnings, and prevent the recalculation
of attributes which might be expensive to calculate (such as the
\&\fI\s-1NAME\s0\fR and \fINAME_*\fR attributes):
.PP
.Vb 3
\&    my $storedNumParams = $sth\->FETCH(\*(AqNUM_OF_PARAMS\*(Aq);
\&    if (!defined $storedNumParams or $storedNumFields < 0) {
\&        $sth\->STORE(\*(AqNUM_OF_PARAMS\*(Aq) = $numParams;
\&
\&        # Set other useful attributes that only need to be set once
\&        # for a statement, like $sth\->{NAME} and $sth\->{TYPE}
\&    }
.Ve
.PP
One particularly important attribute to set correctly (mentioned in
\&\*(L"\s-1ATTRIBUTES\s0 \s-1COMMON\s0 \s-1TO\s0 \s-1ALL\s0 \s-1HANDLES\s0\*(R" in \s-1DBI\s0 is \fIActive\fR. Many \fB\s-1DBI\s0\fR methods,
including \f(CW\*(C`bind_columns()\*(C'\fR, depend on this attribute.
.PP
Besides that the \f(CW\*(C`STORE()\*(C'\fR and \f(CW\*(C`FETCH()\*(C'\fR methods are mainly the same
as above for \fIdbh\fR's.
.PP
Other statement methods
.IX Subsection "Other statement methods"
.PP
A trivial \f(CW\*(C`finish()\*(C'\fR method to discard stored data, reset any attributes
(such as \fIActive\fR) and do \f(CW\*(C`$sth\->SUPER::finish()\*(C'\fR.
.PP
If you've defined a \f(CW\*(C`parse_trace_flag()\*(C'\fR method in \fB::db\fR you'll also want
it in \fB::st\fR, so just alias it in:
.PP
.Vb 1
\&  *parse_trace_flag = \e&DBD::foo:db::parse_trace_flag;
.Ve
.PP
And perhaps some other methods that are not part of the \fB\s-1DBI\s0\fR
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 \f(CW\*(C`install_method()\*(C'\fR.
.PP
If \f(CW\*(C`DESTROY()\*(C'\fR is called on a statement handle that's still active
(\f(CW\*(C`$sth\->{Active}\*(C'\fR is true) then it should effectively call \f(CW\*(C`finish()\*(C'\fR.
.PP
.Vb 4
\&    sub DESTROY {
\&        my $sth = shift;
\&        $sth\->finish if $sth\->FETCH(\*(AqActive\*(Aq);
\&    }
.Ve
.Sh "Tests"
.IX Subsection "Tests"
The test process should conform as closely as possibly to the Perl
standard test harness.
.PP
In particular, most (all) of the tests should be run in the \fIt\fR sub-directory,
and should simply produce an \f(CW\*(C`ok\*(C'\fR when run under \f(CW\*(C`make test\*(C'\fR.
For details on how this is done, see the Camel book and the section in
Chapter 7, \*(L"The Standard Perl Library\*(R" on Test::Harness.
.PP
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 \fBDBD::Informix\fR 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.
.PP
When a complete file of tests must be skipped, you can provide a reason
in a pseudo-comment:
.PP
.Vb 5
\&    if ($no_transactions_available)
\&    {
\&        print "1..0 # Skip: No transactions available\en";
\&        exit 0;
\&    }
.Ve
.PP
Consider downloading the \fBDBD::Informix\fR code and look at the code in
\&\fIDBD/Informix/TestHarness.pm\fR which is used throughout the
\&\fBDBD::Informix\fR tests in the \fIt\fR sub-directory.
.SH "CREATING A C/XS DRIVER"
.IX Header "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.
.PP
The de facto reference driver has been the one for \fBDBD::Oracle\fR written
by Tim Bunce, who is also the author of the \fB\s-1DBI\s0\fR package. The \fBDBD::Oracle\fR
module is a good example of a driver implemented around a C\-level \s-1API\s0.
.PP
Nowadays it it seems better to base on \fB\s-1DBD::ODBC\s0\fR, 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
\&\fBDBD::Oracle\fR digs deeper into the Oracle 8 \s-1OCI\s0 interface it'll get even
more hairy than it is now.)
.PP
The \fBDBD::Informix\fR driver is one driver implemented using embedded \s-1SQL\s0
instead of a function-based \s-1API\s0.
\&\fBDBD::Ingres\fR may also be worth a look.
.Sh "C/XS version of Driver.pm"
.IX Subsection "C/XS version of Driver.pm"
A lot of the code in the \fIDriver.pm\fR 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:
.IP "\(bu" 8
The variables \fI\f(CI$DBD::Driver::\fI{dr|db|st}::imp_data_size\fR are not defined
here, but in the \s-1XS\s0 code, because they declare the size of certain
C structures.
.IP "\(bu" 8
Some methods are typically moved to the \s-1XS\s0 code, in particular
\&\f(CW\*(C`prepare()\*(C'\fR, \f(CW\*(C`execute()\*(C'\fR, \f(CW\*(C`disconnect()\*(C'\fR, \f(CW\*(C`disconnect_all()\*(C'\fR and the
\&\f(CW\*(C`STORE()\*(C'\fR and \f(CW\*(C`FETCH()\*(C'\fR methods.
.IP "\(bu" 8
Other methods are still part of \fIDriver.pm\fR, but have callbacks to
the \s-1XS\s0 code.
.IP "\(bu" 8
If the driver-specific parts of the \fIimp_drh_t\fR 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 \s-1XS\s0 function in the driver
method of \f(CW\*(C`DBD::Driver::driver()\*(C'\fR, and you define the corresponding function
in \fIDriver.xs\fR, and you define the C code in \fIdbdimp.c\fR and the prototype in
\&\fIdbdimp.h\fR.
.Sp
For example, \fBDBD::Informix\fR has such a requirement, and adds the
following call after the call to \f(CW\*(C`_new_drh()\*(C'\fR in \fIInformix.pm\fR:
.Sp
.Vb 1
\&  DBD::Informix::dr::driver_init($drh);
.Ve
.Sp
and the following code in \fIInformix.xs\fR:
.Sp
.Vb 6
\&  # Initialize the DBD::Informix driver data structure
\&  void
\&  driver_init(drh)
\&      SV *drh
\&      CODE:
\&      ST(0) = dbd_ix_dr_driver_init(drh) ? &sv_yes : &sv_no;
.Ve
.Sp
and the code in \fIdbdimp.h\fR declares:
.Sp
.Vb 1
\&  extern int dbd_ix_dr_driver_init(SV *drh);
.Ve
.Sp
and the code in \fIdbdimp.ec\fR (equivalent to \fIdbdimp.c\fR) defines:
.Sp
.Vb 11
\&  /* Formally initialize the DBD::Informix driver structure */
\&  int
\&  dbd_ix_dr_driver(SV *drh)
\&  {
\&      D_imp_drh(drh);
\&      imp_drh\->n_connections = 0;       /* No active connections */
\&      imp_drh\->current_connection = 0;  /* No current connection */
\&      imp_drh\->multipleconnections = (ESQLC_VERSION >= 600) ? True : False;
\&      dbd_ix_link_newhead(&imp_drh\->head);  /* Empty linked list of connections */
\&      return 1;
\&  }
.Ve
.Sp
\&\fBDBD::Oracle\fR has a similar requirement but gets around it by checking
whether the private data part of the driver handle is all zeroed out,
rather than add extra functions.
.PP
Now let's take a closer look at an excerpt from \fIOracle.pm\fR (revised
heavily to remove idiosyncrasies) as an example, ignoring things that
were already discussed for pure Perl drivers.
.PP
\fIThe connect method\fR
.IX Subsection "The connect method"
.PP
The connect method is the database handle constructor.
You could write either of two versions of this method: either one which
takes connection attributes (new code) and one which ignores them (old
code only).
.PP
If you ignore the connection attributes, then you omit all mention of
the \fI\f(CI$auth\fI\fR variable (which is a reference to a hash of attributes), and
the \s-1XS\s0 system manages the differences for you.
.PP
.Vb 3
\&  sub connect
\&  {
\&      my ($drh, $dbname, $user, $auth, $attr) = @_;
\&
\&      # Some database specific verifications, default settings
\&      # and the like following here. This should only include
\&      # syntax checks or similar stuff where it\*(Aqs legal to