Author: timbo
Date: Mon Dec 6 05:39:58 2004
New Revision: 599
Modified:
dbi/trunk/lib/DBI/DBD.pm
Log:
Switch to using =head3/=head4
Modified: dbi/trunk/lib/DBI/DBD.pm
==============================================================================
--- dbi/trunk/lib/DBI/DBD.pm (original)
+++ dbi/trunk/lib/DBI/DBD.pm Mon Dec 6 05:39:58 2004
@@ -5,7 +5,6 @@
$VERSION = sprintf("%d.%02d", q$Revision: 11.21 $ =~ /(\d+)\.(\d+)/o);
-
# $Id: DBD.pm,v 11.21 2004/02/01 11:16:16 timbo Exp $
#
# Copyright (c) 1997-2003 Jonathan Leffler, Jochen Wiedmann, Steffen
@@ -14,41 +13,6 @@
# You may distribute under the terms of either the GNU General Public
# License or the Artistic License, as specified in the Perl README file.
-########################################################################
-# JL 2002-12-30 - Ouch!
-# NB: In Perl 5.6.x and earlier, POD only supports =head1 and =head2,
-# whereas in Perl 5.8.0 and later, POD supports =head3 and =head4 too.
-# This document reads better in HTML if =head3 and =head4 are used.
-# To convert this document to Perl 5.8.0 POD markup, run this script:
-#
-##!/bin/perl -w
-##
-## Remove Perl 5.6.x and earlier POD markup, leaving Perl 5.8.0 POD
-## markup (=head3, =head4) visible.
-#
-#while (<>)
-#{
-# if (m/^#=POD-Perl-5.6.x=begin/o)
-# {
-# while (<>)
-# {
-# last if m/^#=POD-Perl-5.6.x=end/o;
-# }
-# next;
-# }
-# elsif (m/^#=head[34]\s/o)
-# {
-# s/^#//o;
-# $_ = "=pod\n\n$_\n=cut\n\n";
-# }
-# print $_;
-#}
-#
-# NBB: POD does not provide a mechanism for embedding comments in POD
-# material. Hence the convoluted =cut, # comments, and =pod directives
-# (which are supported as far back as Perl 5.005_03).
-########################################################################
-
=head1 NAME
DBI::DBD - Perl DBI Database Driver Writer's Guide
@@ -204,40 +168,25 @@
There are no extra files needed only by a pure Perl driver, but there are
several extra files needed only by a C/XS driver.
-=cut
-
-#=head3 Files common to pure Perl and C/XS drivers
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=over 2
-
-=item Files common to pure Perl and C/XS drivers
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head3 Files common to pure Perl and C/XS drivers
Assuming that your driver is called DBD::Driver, these files are:
=over 4
-=item Makefile.PL
+=item * Makefile.PL
-=item README
+=item * README
-=item MANIFEST
+=item * MANIFEST
-=item Driver.pm
+=item * Driver.pm
-=item lib/Bundle/DBD/Driver.pm
+=item * lib/Bundle/DBD/Driver.pm
-=item lib/DBD/Driver/Summary.pm
+=item * lib/DBD/Driver/Summary.pm
-=item t/*.t
+=item * t/*.t
=back
@@ -297,47 +246,33 @@
All such sub-modules should themselves be version stamped (see the
discussions far below).
-=cut
-
-#=head3 Extra files needed by C/XS drivers
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item Extra files needed by C/XS drivers
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head3 Extra files needed by C/XS drivers
The software for a C/XS driver will typically contain at least four
extra files that are not relevant to a pure Perl driver.
=over 4
-=item Driver.xs
+=item * Driver.xs
-=item Driver.h
+=item * Driver.h
-=item dbdimp.h
+=item * dbdimp.h
-=item dbdimp.c
+=item * dbdimp.c
=back
The Driver.xs 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.
+
The Driver.h header is a stylized header that ensures you can access the
necessary Perl and DBI macros, types, and function declarations.
+
The dbdimp.h is used to specify which functions have been implemented by
your driver.
+
The dbdimp.c 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.
@@ -349,20 +284,6 @@
Obviously, you can add extra source code files to the list.
-=cut
-
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
-
=head2 Requirements on a driver and driver writer
To be remotely useful, your driver must be implemented in a format that
@@ -465,8 +386,8 @@
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(3)> and L<ExtUtils::MM_Unix(3)>.
-Consider using L<CPAN::MakeMaker(3)> in place of ExtUtils::MakeMaker.
+See also L<ExtUtils::MakeMaker> and L<ExtUtils::MM_Unix>.
+Consider using L<CPAN::MakeMaker> in place of ExtUtils::MakeMaker.
=head2 README
@@ -641,41 +562,9 @@
We ignore things that are common to any module (even non-DBI modules)
or really specific to the DBD::File package.
-=cut
-
-#=head3 The DBD::Driver package
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=over 2
-
-=item The DBD::Driver package
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
-
-=cut
-
-#=head4 The header
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The header
-
-=cut
-
-#=POD-Perl-5.6.x=end
+=head3 The DBD::Driver package
-=pod
+=head4 The header
package DBD::File;
@@ -719,24 +608,7 @@
This is where the driver handle will be stored, once created.
Note that you may assume there is only one handle for your driver.
-=cut
-
-#=head4 The driver constructor
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The driver constructor
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=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
@@ -808,43 +680,9 @@
undef $rdh;
}
-=cut
-
-#=head3 The DBD::Driver::dr package
-#=POD-Perl-5.6.x=begin
-
-=pod
+=head3 The DBD::Driver::dr package
-=back
-
-=over 2
-
-=item The DBD::Driver::dr package
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
-
-=cut
-
-#=head4 The database handle constructor
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The database handle constructor
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head4 The database handle constructor
The next lines of code look as follows:
@@ -892,7 +730,7 @@
This is mostly the same as in the I<driver handle constructor> above.
The arguments are described in the DBI man page.
-See L<DBI(3)>.
+See L<DBI>.
The constructor _new_dbh is called, returning a database handle.
The constructor's prototype is:
@@ -916,24 +754,7 @@
read via $h->FETCH($attrib) and set via $h->STORE($attrib, $value).
If in any doubt, use these methods.
-=cut
-
-#=head4 The data_sources method
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The data_sources method
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head4 The data_sources method
The data_sources method must populate and return a list of valid data
sources, prefixed with the "dbi:Driver" incantation that allows them to
@@ -954,24 +775,7 @@
return @list;
}
-=cut
-
-#=head4 Error handling
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item Error handling
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head4 Error handling
It is quite likely that something fails in the connect method.
With DBD::File for example, you might catch an error when setting the
@@ -992,86 +796,18 @@
return $h->set_err($err, $errmsg, $state) if ...;
-=cut
-
-#=head4 The disconnect_all method
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The disconnect_all method
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head4 The disconnect_all method
If you need to release any resources when the driver is unloaded, you
can provide a disconnect_all method.
-=cut
-
-#=head4 Other driver handle methods
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item Other driver handle methods
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head4 Other driver handle methods
If you need any other driver handle methods, they can follow here.
-=cut
-
-#=head3 The DBD::Driver::db package
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The DBD::Driver::db package
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
-
-=cut
-
-#=head4 The statement handle constructor
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The statement handle constructor
+=head3 The DBD::Driver::db package
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head4 The statement handle constructor
There's nothing much new in the statement handle constructor.
@@ -1110,24 +846,7 @@
the DBI specification explicitly allows a driver to defer this, but then
the user could not call I<bind_param>.
-=cut
-
-#=head4 Transaction handling
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item Transaction handling
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head4 Transaction handling
Pure Perl drivers will rarely support transactions. Thus your I<commit>
and I<rollback> methods will typically be quite simple:
@@ -1154,24 +873,7 @@
The DBI's default begin_work method can be used by inheritance.
-=cut
-
-#=head4 The STORE and FETCH methods
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The STORE and FETCH methods
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head4 The STORE and FETCH methods
These methods (that we have already used, see above) are called for
you, whenever the user does a:
@@ -1182,7 +884,7 @@
$val = $dbh->{$attr};
-See L<perltie(1)> for details on tied hash refs to understand why these
+See L<perltie> for details on tied hash refs to understand why these
methods are required.
The DBI will handle most attributes for you, in particular attributes
@@ -1234,24 +936,7 @@
Unless your driver documentation indicates otherwise, the return value of
the STORE method is unspecified and the caller shouldn't use that value.
-=cut
-
-#=head4 Other database handle methods
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item Other database handle methods
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head4 Other database handle methods
As with the driver package, other database handle methods may follow
here.
@@ -1279,43 +964,9 @@
All private flag names must be lowercase, and all private flags
must be in the top 8 of the 32 bits.
-=cut
-
-#=head3 The DBD::Driver::st package
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The DBD::Driver::st package
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
-
-=cut
-
-#=head4 The execute method
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The execute method
-
-=cut
-
-#=POD-Perl-5.6.x=end
+=head3 The DBD::Driver::st package
-=pod
+=head4 The execute method
This is perhaps the most difficult method because we have to consider
parameter bindings here. We present a simplified implementation by
@@ -1375,24 +1026,7 @@
$sth->execute() or die $sth->errstr;
-=cut
-
-#=head4 Fetching data
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item Fetching data
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head4 Fetching data
We should not implement the methods I<fetchrow_array>, I<fetchall_arrayref>,
... because these are already part of DBI.
@@ -1424,24 +1058,7 @@
can't be fetched then Active should be turned off
before the method returns.
-=cut
-
-#=head4 Statement attributes
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item Statement attributes
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head4 Statement attributes
The main difference between dbh and sth attributes is, that you
should implement a lot of attributes here that are required by
@@ -1450,24 +1067,7 @@
Besides that the STORE and FETCH methods are mainly the same
as above for dbh's.
-=cut
-
-#=head4 Other statement methods
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item Other statement methods
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head4 Other statement methods
A trivial C<finish> method to discard the stored data and do
$sth->SUPER::finish;
@@ -1487,20 +1087,6 @@
registered prefix so they can be installed using install_method().
-=cut
-
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
-
=head2 Tests
The test process should conform as closely as possibly to the Perl
@@ -1632,22 +1218,7 @@
heavily to remove idiosyncrasies) as an example.
We also ignore things that are already discussed for pure Perl drivers.
-=cut
-
-#=head3 The connect method
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=over 2
-
-=item The connect method
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head3 The connect method
The connect method is the database handle constructor.
You could write either of two versions of this method: either one which
@@ -1687,91 +1258,36 @@
I<dbd_db_login6> from I<dbdimp.c>.
See below for details.
-=over 4
-
-*FIX ME* Discuss removing attributes from hash reference as an optimization
-to skip later calls to $dbh->STORE made by DBI->connect.
+ *FIX ME* Discuss removing attributes from hash reference as an optimization
+ to skip later calls to $dbh->STORE made by DBI->connect.
-*FIX ME* Discuss removing attributes in Perl code.
+ *FIX ME* Discuss removing attributes in Perl code.
-*FIX ME* Discuss removing attributes in C code.
+ *FIX ME* Discuss removing attributes in C code.
-=back
+=head3 The disconnect_all method
-=cut
+ *FIX ME* T.B.S
-#=head3 The disconnect_all method
-#=POD-Perl-5.6.x=begin
+=head3 The data_sources method
-=pod
+If your I<data_sources> method can be implemented in pure Perl, then do
+so because it is easier than doing it in XS code (see the section above
+for pure Perl drivers).
+If your I<data_sources> method must call onto compiled functions, then
+you will need to define dbd_dr_data_sources in your dbdimp.h file, which
+will trigger Driver.xst (in DBI v1.33 or greater) to generate the XS
+code that calls your actual C function (see the discussion below for
+details) and you do not code anything in Driver.pm to handle it.
-=back
+=head3 The prepare method
-=over 2
+The prepare method is the statement handle constructor, and most of it
+is not new.
+Like the I<connect> method, it now has a C callback:
-=item The disconnect_all method
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
-
-*FIX ME* T.B.S
-
-=cut
-
-#=head3 The data_sources method
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The data_sources method
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
-
-If your I<data_sources> method can be implemented in pure Perl, then do
-so because it is easier than doing it in XS code (see the section above
-for pure Perl drivers).
-If your I<data_sources> method must call onto compiled functions, then
-you will need to define dbd_dr_data_sources in your dbdimp.h file, which
-will trigger Driver.xst (in DBI v1.33 or greater) to generate the XS
-code that calls your actual C function (see the discussion below for
-details) and you do not code anything in Driver.pm to handle it.
-
-=cut
-
-#=head3 The prepare method
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The prepare method
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
-
-The prepare method is the statement handle constructor, and most of it
-is not new.
-Like the I<connect> method, it now has a C callback:
-
- package DBD::Driver::db; # ====== DATABASE ======
- use strict;
+ package DBD::Driver::db; # ====== DATABASE ======
+ use strict;
sub prepare
{
@@ -1791,82 +1307,17 @@
$sth;
}
-=cut
-
-#=head3 The execute method
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The execute method
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
-
-*FIX ME* T.B.S
-
-=cut
-
-#=head3 The fetchrow_arrayref method
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The fetchrow_arrayref method
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
-
-*FIX ME* T.B.S
-
-=cut
-
-#=head3 Other methods?
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item Other methods?
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
-
-*FIX ME* T.B.S
-
-=cut
-
-#=POD-Perl-5.6.x=begin
+=head3 The execute method
-=pod
+ *FIX ME* T.B.S
-=back
+=head3 The fetchrow_arrayref method
-=cut
+ *FIX ME* T.B.S
-#=POD-Perl-5.6.x=end
+=head3 Other methods?
-=pod
+ *FIX ME* T.B.S
=head2 Driver.xs
@@ -1906,7 +1357,7 @@
use DBI qw(:sql_types);
-*FIX ME* T.B.S
+ *FIX ME* T.B.S
=head2 Driver.h
@@ -2071,22 +1522,7 @@
Then you should only implement one of the alternatives, and generally
the newer one of the alternatives.
-=cut
-
-#=head3 The dbd_init method
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=over 2
-
-=item The dbd_init method
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head3 The dbd_init method
#include "Driver.h"
@@ -2105,24 +1541,7 @@
Note that DBISTATE_INIT requires the name of the argument to I<dbd_init>
to be called I<dbistate>.
-=cut
-
-#=head3 The dbd_drv_error method
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The dbd_drv_error method
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head3 The dbd_drv_error method
You need a function to record errors so DBI can access them properly.
You can call it whatever you like, but we'll call it C<dbd_drv_error>
@@ -2187,24 +1606,7 @@
DBIc_TRACE_FLAGS(imp), that is: 0xFF000000. See the parse_trace_flag() method
elsewhere in this document.
-=cut
-
-#=head3 The dbd_dr_data_sources method
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The dbd_dr_data_sources method
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head3 The dbd_dr_data_sources method
This method is optional; the support for it was added in DBI v1.33.
@@ -2242,24 +1644,7 @@
return(av);
}
-=cut
-
-#=head3 The dbd_db_login6 method
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The dbd_db_login6 method
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head3 The dbd_db_login6 method
int dbd_db_login6(SV* dbh, imp_dbh_t* imp_dbh, char* dbname,
char* user, char* auth, SV *attr);
@@ -2340,24 +1725,7 @@
There are ways to work around the missing attributes, but they are
ungainly; it is much better to use the 6-argument form.
-=cut
-
-#=head3 The dbd_db_commit and dbd_db_rollback methods
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The dbd_db_commit and dbd_db_rollback methods
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head3 The dbd_db_commit and dbd_db_rollback methods
int dbd_db_commit(SV *dbh, imp_dbh_t *imp_dbh);
int dbd_db_rollback(SV* dbh, imp_dbh_t* imp_dbh);
@@ -2371,24 +1739,7 @@
These functions should return TRUE for success, FALSE otherwise.
-=cut
-
-#=head3 The dbd_db_disconnect method
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The dbd_db_disconnect method
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head3 The dbd_db_disconnect method
This is your private part of the I<disconnect> method. Any dbh with
the I<ACTIVE> flag on must be disconnected. (Note that you have to set
@@ -2424,24 +1775,7 @@
This function should return TRUE for success, FALSE otherwise, but
it is not clear what anything can do about a failure.
-=cut
-
-#=head3 The dbd_db_discon_all method
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The dbd_db_discon_all method
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head3 The dbd_db_discon_all method
int dbd_discon_all (SV *drh, imp_drh_t *imp_drh);
@@ -2453,24 +1787,7 @@
This function should return TRUE for success, FALSE otherwise, but
it is not clear what anything can do about a failure.
-=cut
-
-#=head3 The dbd_db_destroy method
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The dbd_db_destroy method
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head3 The dbd_db_destroy method
This is your private part of the database handle destructor. Any dbh with
the I<IMPSET> flag on must be destroyed, so that you can safely free
@@ -2491,24 +1808,7 @@
do keep references to their parents. So a database handle won't be
DESTROY'd until all its children have been DESTROY'd.
-=cut
-
-#=head3 The dbd_db_STORE_attrib method
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The dbd_db_STORE_attrib method
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head3 The dbd_db_STORE_attrib method
This function handles
@@ -2533,7 +1833,7 @@
I cannot recommend a general way of going on, if I<dbd_drv_error> returns,
but there are examples where even the DBI specification expects that
-you croak(). (See the I<AutoCommit> method in L<DBI(3)>.)
+you croak(). (See the I<AutoCommit> method in L<DBI>.)
If you have to store attributes, you should either use your private
data structure imp_xxx, the handle hash (via (HV*)SvRV(dbh)), or use
@@ -2545,24 +1845,7 @@
The private imp_data is an additional SV attached to the handle. You
could think of it as an unnamed handle attribute. It's not normally used.
-=cut
-
-#=head3 The dbd_db_FETCH_attrib method
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The dbd_db_FETCH_attrib method
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head3 The dbd_db_FETCH_attrib method
This is the counterpart of dbd_db_STORE_attrib, needed for:
@@ -2583,24 +1866,7 @@
if (cacheit) /* cache value for later DBI 'quick' fetch? */
hv_store((HV*)SvRV(dbh), key, kl, cachesv, 0);
-=cut
-
-#=head3 The dbd_st_prepare method
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The dbd_st_prepare method
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head3 The dbd_st_prepare method
This is the private part of the I<prepare> method. Note that you
B<must not> really execute the statement here. You may, for example,
@@ -2627,24 +1893,7 @@
DBIc_IMPSET_on(imp_sth);
-=cut
-
-#=head3 The dbd_st_execute method
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The dbd_st_execute method
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head3 The dbd_st_execute method
This is where a statement will really be executed.
@@ -2704,24 +1953,7 @@
I<dbd_ix_preparse> in DBD::Informix I<dbdimp.ec> and the related
functions in I<iustoken.c> and I<sqltoken.c>.
-=cut
-
-#=head3 The dbd_st_fetch method
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The dbd_st_fetch method
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head3 The dbd_st_fetch method
This function fetches a row of data. The row is stored in in an array,
of SV's that DBI prepares for you. This has two advantages: it is fast
@@ -2769,36 +2001,15 @@
The function returns the AV prepared by DBI for success or C<Nullav>
otherwise.
-=over 4
-
-*FIX ME* Discuss what happens when there's no more data to fetch.
-Are errors permitted if another fetch occurs after the first fetch
-that reports no more data. (Permitted, not required.)
-
-=back
+ *FIX ME* Discuss what happens when there's no more data to fetch.
+ Are errors permitted if another fetch occurs after the first fetch
+ that reports no more data. (Permitted, not required.)
If an error occurs which leaves the $sth in a state where remaining
rows can't be fetched then Active should be turned off before the
method returns.
-=cut
-
-#=head3 The dbd_st_finish3 method
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The dbd_st_finish3 method
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head3 The dbd_st_finish3 method
The C<$sth-E<gt>finish> method can be called if the user wishes to
indicate that no more rows will be fetched even if the database has more
@@ -2839,24 +2050,7 @@
The function returns TRUE for success, FALSE otherwise, but there isn't
a lot anyone can do to recover if there is an error.
-=cut
-
-#=head3 The dbd_st_destroy method
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The dbd_st_destroy method
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head3 The dbd_st_destroy method
This function is the private part of the statement handle destructor.
@@ -2868,24 +2062,7 @@
The DBI Driver.xst code will call dbd_st_finish for you, if the sth has
the ACTIVE flag set, before calling dbd_st_destroy.
-=cut
-
-#=head3 The dbd_st_STORE_attrib and dbd_st_FETCH_attrib methods
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The dbd_st_STORE_attrib and dbd_st_FETCH_attrib methods
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head3 The dbd_st_STORE_attrib and dbd_st_FETCH_attrib methods
These functions correspond to dbd_db_STORE and dbd_db_FETCH attrib
above, except that they are for statement handles.
@@ -2895,24 +2072,7 @@
SV* valuesv);
SV* dbd_st_FETCH_attrib(SV* sth, imp_sth_t* imp_sth, SV* keysv);
-=cut
-
-#=head3 The dbd_bind_ph method
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item The dbd_bind_ph method
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head3 The dbd_bind_ph method
This function is internally used by the I<bind_param> method, the
I<bind_param_inout> method and by the DBI Driver.xst code if C<execute>
@@ -2936,24 +2096,7 @@
the value in a parameter array and use it later in I<dbd_st_execute>.
See the I<DBD::mysql> driver for an example.
-=cut
-
-#=head3 Implementing bind_param_inout support
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item Implementing bind_param_inout support
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head3 Implementing bind_param_inout support
To provide support for parameters bound by reference rather than by
value, the driver must do a number of things. First, and most
@@ -2974,20 +2117,6 @@
@values. These calls are indistinguishable from explicit user calls to
bind_param.
-=cut
-
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
-
=head2 C/XS version of Makefile.PL
The I<Makefile.PL> file for a C/XS driver is similar to the code needed
@@ -3109,22 +2238,7 @@
The DBI::DBD::Metadata module is a good semi-automatic way for the developer
of a DBD module to
write the get_info and type_info functions quickly and accurately.
-=cut
-
-#=head3 Generating the get_info method
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=over 2
-
-=item Generating the get_info method
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head3 Generating the get_info method
Prior to DBI v1.33, this existed as the method write_getinfo_pm in the
DBI::DBD module.
@@ -3150,24 +2264,7 @@
lib/DBD/Driver/GetInfo.pm.
You should review the output to ensure that it is sensible.
-=cut
-
-#=head3 Generating the type_info method
-#=POD-Perl-5.6.x=begin
-
-=pod
-
-=back
-
-=over 2
-
-=item Generating the type_info method
-
-=cut
-
-#=POD-Perl-5.6.x=end
-
-=pod
+=head3 Generating the type_info method
Given the idea of the write_getinfo_pm method, it was not hard to devise
a parallel method, write_typeinfo_pm, which does the analogous job for the
@@ -3190,8 +2287,6 @@
lib/DBD/Driver/TypeInfo.pm.
You should review the output to ensure that it is sensible.
-=back
-
=head2 Writing DBD::Driver::db::get_info
If you use the DBI::DBD::Metadata module, then the code you need is
@@ -3230,48 +2325,28 @@
=head2 Writing DBD::Driver::db::table_info
-=over 4
-
-*FIX ME* The guidelines on writing this method have not been written yet.
-No sample implementation is available.
-
-=back
+ *FIX ME* The guidelines on writing this method have not been written yet.
+ No sample implementation is available.
=head2 Writing DBD::Driver::db::column_info
-=over 4
-
-*FIX ME* The guidelines on writing this method have not been written yet.
-No sample implementation is available.
-
-=back
+ *FIX ME* The guidelines on writing this method have not been written yet.
+ No sample implementation is available.
=head2 Writing DBD::Driver::db::primary_key_info
-=over 4
-
-*FIX ME* The guidelines on writing this method have not been written yet.
-No sample implementation is available.
-
-=back
+ *FIX ME* The guidelines on writing this method have not been written yet.
+ No sample implementation is available.
=head2 Writing DBD::Driver::db::primary_key
-=over 4
-
-*FIX ME* The guidelines on writing this method have not been written yet.
-No sample implementation is available.
-
-=back
+ *FIX ME* The guidelines on writing this method have not been written yet.
+ No sample implementation is available.
=head2 Writing DBD::Driver::db::foreign_key_info
-=over 4
-
-*FIX ME* The guidelines on writing this method have not been written yet.
-No sample implementation is available.
-
-=back
+ *FIX ME* The guidelines on writing this method have not been written yet.
+ No sample implementation is available.
=head2 Writing DBD::Driver::db::tables
