Tim,
Here's a patch to the DBI::DBD documentation module, based on the
version shipped with DBI 1.21.
It's done some simple uncontroversial things, such as fix up URLs and
mailing list addresses (and fixed my email address). There are a few
basically non-controversial grammatical corrections.
There are a number of places where I've used the format:
=over 4
*FIX ME* ...some string of questions or comments...
=back 4
Someone, possibly you, Tim, needs to address those questions and give
me an answer, and I'll try to get those merged back into the document.
There's nowhere where I think the changes I've made are truly
controversial, though if anyone cares to correct me on which version of
Perl required prototypes in the C compiler (I said 5.6), then that
detail can be fixed.
If the attachment gets munged somewhere along the line, I'll resend in
any suitable alternative format.
--
Jonathan Leffler #include <disclaimer.h>
STSM, Informix Database Engineering, IBM Data Management Solutions
Phone: +1 650-926-6921 Tie-line: 630-6921
Email: [EMAIL PROTECTED] ([EMAIL PROTECTED])
Notes ID: Jonathan Leffler/Menlo Park/IBM@IBMUS
Guardian of DBD::Informix v1.00.PC1 -- http://dbi.perl.org
*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
Please update your address book to use [EMAIL PROTECTED] because
[EMAIL PROTECTED] will not work starting 2002-07-01. Expect
slower responses because I can't use Lotus Notes as fast as Unix
email. One day, this signature will shrink!
--- DBD.pm.old Tue Feb 12 16:13:02 2002
+++ DBD.pm Tue Feb 12 16:53:41 2002
@@ -1,8 +1,8 @@
# $Id: DBD.pm,v 11.2 2001/08/24 22:10:44 timbo Exp $
#
-# Copyright (c) 1997-2000 Jonathan Leffler, Jochen Wiedmann and Tim Bunce
+# Copyright (c) 1997-2002 Jonathan Leffler, Jochen Wiedmann and Tim Bunce
#
# You may distribute under the terms of either the GNU General Public
# License or the Artistic License, as specified in the Perl README file.
=head1 NAME
@@ -16,11 +16,11 @@
=head1 VERSION and VOLATILITY
$Revision: 11.2 $
$Date: 2001/08/24 22:10:44 $
-This document is a minimal draft which is in need of further work.
+This document is I<still> a minimal draft which is in need of further work.
The changes will occur both because the DBI specification is changing
and hence the requirements on DBD drivers change, and because feedback
from people reading this document will suggest improvements to it.
@@ -43,32 +43,33 @@
If in I<any> doubt at all, please do contact the dbi-dev mailing list
(details given below) where Tim Bunce and other driver authors can help.
The primary web-site for locating DBI software and information is
- http://www.symbolstone.org/technology/perl/DBI
+ http://dbi.perl.org/
There are 2 main and one auxilliary mailing lists for people working
-with DBI. The primary lists are [EMAIL PROTECTED] for general users
-of DBI and DBD drivers, and [EMAIL PROTECTED] mainly for DBD driver
+with DBI. The primary lists are [EMAIL PROTECTED] for general users
+of DBI and DBD drivers, and [EMAIL PROTECTED] mainly for DBD driver
writers (don't join the dbi-dev list unless you have a good reason).
-The auxilliary list is [EMAIL PROTECTED] for announcing new
+The auxilliary list is [EMAIL PROTECTED] for announcing new
releases of DBI or DBD drivers.
You can join these lists by accessing the web-site
-L<http://www.isc.org/dbi-lists.html>.
+L<http://dbi.perl.org/>.
The lists are closed so you cannot send email to any of the lists
unless you join the list first.
You should also consider monitoring the comp.lang.perl.* newsgroups.
=head1 BOOK
-The definitive book on Perl DBI is 'Programming the Perl DBI: Database
-programming with Perl' by Alligator Descartes and Tim Bunce, published
-by O'Reilly Associates, February 2000, ISBN 1-56592-699-4. Buy it now
-if you have not already done so.
+The definitive book on how to use the Perl DBI is 'Programming the Perl
+DBI: Database Programming with Perl' by Alligator Descartes and Tim
+Bunce, published by O'Reilly Associates, February 2000, ISBN
+1-56592-699-4.
+Buy it now if you have not already done so.
=head1 REGISTERING A NEW DRIVER
Before writing a new driver, it is in your interests to find out
whether there already is a driver for your database. If there is such
@@ -127,11 +128,11 @@
Of special importance for DBI drivers is the I<postamble> method from
the C<ExtUtils::MM_Unix> man page. And for Emacs users I recommend
the I<libscan> method.
Now an example, I use the word C<Driver> wherever you should insert
-your drivers name:
+your driver's name:
# -*- perl -*-
use DBI 1.03;
use DBI::DBD;
@@ -160,19 +161,19 @@
The README file should describe what the driver is for, the
pre-requisites for the build process, the actual build process, and how
to report errors. Users will find ways of breaking the driver build and
test process which you would never even dreamed to be possible in your
-nightmares. :-) Therefore, you need to write this document defensively
+nightmares. Therefore, you need to write this document defensively
and precisely. 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.
=head2 MANIFEST
-The MANIFEST will be used by the Makefile'd dist target to build the
+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
@@ -510,10 +511,15 @@
warn("Rollback ineffective while AutoCommit is on");
}
0;
}
+=over 4
+
+*FIX ME* discuss the new begin_work method!
+
+=back
=item The STORE and FETCH methods
These methods (that we have already used, see above) are called for
you, whenever the user does a
@@ -766,11 +772,11 @@
=head2 Driver.pm
The Driver.pm file is the same as for Pure Perl modules, see above.
-However, there are some subtile differences:
+However, there are some subtle differences:
=over 8
=item *
@@ -830,10 +836,18 @@
it) and calls I<dbd_db_login> from I<dbdimp.c>. See below for details.
Since the DBI::_new_xxh methods can't fail in normal situations, we
don't both checking $dbh before calling _login.
+=over 4
+
+*FIX ME* Discuss login6 as a way to get at attributes during login.
+
+*FIX ME* Discuss removing attributes from hash reference as an optimization.
+
+=back
+
=item The statement handle constructor
There's nothing much new in the statement handle constructor. Like
the I<connect> method it now has a C callback:
@@ -959,27 +973,33 @@
#define dbd_init ora_init
#define dbd_db_login ora_db_login
#define dbd_db_do ora_db_do
... many more here ...
-This structures implement your private part of the handles. You I<have>
+=over 4
+
+*FIX ME* Should mention dbd_db_login6.
+
+*FIX ME* Should use hypothetical drv_ prefix instead of ora_ prefix.
+
+=back
+
+These structures implement your private part of the handles. You I<have>
to use the name I<imp_dbh_dr|db|st> and the first field I<must> be of
-type I<dbih_drc|dbc|stc_t>. You should never access this fields directly,
+type I<dbih_drc|dbc|stc_t>. You should never access these fields directly,
except of using the I<DBIc_xxx> macros below.
=head2 Implementation source dbdimp.c
This is the main implementation file. I will drop a short note on any
function here that's used in the I<Driver.xsi> template and thus B<has>
to be implemented. Of course you can add private or better static
functions here.
-Note that most people are still using Kernighan & Ritchie syntax here.
-I personally don't like this and especially in this documentation it
-cannot be of harm, so let's use ANSI. Finally Tim Bunce has announced
-interest in moving the DBI sources to ANSI as well.
+Since Perl 5.6 requires support for function prototypes (ANSI or ISO or
+Standard C), you should write your code using function prototypes too.
=over 2
=item Initialization
@@ -994,15 +1014,29 @@
dbd_init will be called when your driver is first loaded. These
statements are needed for use of the DBI macros. They will include your
private header file I<dbdimp.h> in turn.
+=over 4
+
+*FIX ME* Is recommended practice to use the unmapped DBI-specified names
+or to use your driver-specific function names in the source code? DBD::Informix
+uses the driver-specific names in the source; the header deals with the mapping.
+
+=back
+
=item do_error
You need a function to handle recording of errors. You can call it
whatever you like, but we'll call it C<do_error> here.
+=over 4
+
+*FIX ME* Should this be a file static function? Why not?
+
+=back
+
void do_error(SV* h, int rc, char* what) {
Note that I<h> is a generic handle, may it be a driver handle, a
database or a statement handle.
@@ -1090,10 +1124,18 @@
handle is destroyed.
The dbd_db_login function should return TRUE for success, FALSE otherwise.
+=item dbd_db_login6
+
+=over 4
+
+*FIX ME* Details TBS
+
+=back
+
=item dbd_db_commit
=item dbd_db_rollback
int dbd_db_commit( SV* dbh, imp_dbh_t* imp_dbh );
@@ -1104,10 +1146,19 @@
The arguments I<dbh> and I<imp_dbh> are like above, I will omit
describing them in what follows, as they appear always.
+=item dbd_db_begin_work
+
+=over 4
+
+*FIX ME* Details TBS
+
+=back
+
+
=item dbd_db_disconnect
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
it in I<dbd_db_connect> above.)
@@ -1150,23 +1201,31 @@
if the handle is still 'active', before calling dbd_db_destroy.
Before returning the function must switch IMPSET to off, so DBI knows
that the destructor was called.
+=over 4
+
+*FIX ME* If there are statements 'active' when the $dbh is destroyed,
+does DBI arrange to destroy those statement handles, or does the driver need to
+do the work itself?
+
+=back
+
=item dbd_db_STORE_attrib
This function handles
$dbh->{$key} = $value;
-its prototype is
+Its prototype is:
int dbd_db_STORE_attrib(SV* dbh, imp_dbh_t* imp_dbh, SV* keysv,
SV* valuesv);
-You do not handle all attributes, in contrary you should not handle
+You do not handle all attributes; on the contrary, you should not handle
DBI attributes here: Leave this to DBI. (There's one exception,
I<AutoCommit>, which you should care about.)
The return value is TRUE, if you have handled the attribute or FALSE
otherwise. If you are handling an attribute and something fails, you
@@ -1224,10 +1283,17 @@
A typical, simple possibility is just to store the statement in the
imp_data hash ref and use it in dbd_st_execute. If you can, you should
setup attributes like NUM_OF_FIELDS, NAME, ... here, but DBI
doesn't require that. However, if you do, document it.
+=over 4
+
+*FIX ME* What about NUM_OF_PARAMS? That has to be set by $dbh->prepare()
+so that you can call execute with the correct number of values.
+
+=back
+
In any case you should set the IMPSET flag, as you did in
I<dbd_db_connect> above:
DBIc_IMPSET_on(imp_sth);
@@ -1263,32 +1329,36 @@
/* quotes and the like ... :-( */
/* See DBD::mysql for an example. (Don't look too deep into */
/* the example, you will notice where I was lazy ...) */
}
-The next thing is you really execute the statement. Note that you must
-prepare the attributes NUM_OF_FIELDS, NAME, ... when the statement is
-successfully executed if you have not already done so: They may be used even before a
potential
-I<fetchrow>. In particular you have to tell DBI the number of fields,
-that the statement has, because it will be used by DBI internally.
+The next thing is you really execute the statement.
+Note that you must prepare the attributes NUM_OF_PARAMS, NUM_OF_FIELDS,
+NAME, etc when the statement is successfully executed if the driver has
+not already done so.
+They may be used even before a potential I<fetchrow>.
+In particular you have to tell DBI the number of fields, that the
+statement has, because it will be used by DBI internally.
Thus the function will typically ends with:
if (isSelectStatement) {
DBIc_NUM_FIELDS(imp_sth) = numFields;
DBIc_ACTIVE_on(imp_sth);
}
-It is important that the ACTIVE flag only be set for select statements.
+It is important that the ACTIVE flag only be set for select statements
+(or any other statements that can return multiple sets of values from
+the database using a cursor-like mechanism).
See I<dbd_st_preparse> and I<dbd_db_connect> above for more explanations.
=item dbd_st_fetch
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
+of SV's that DBI prepares for you. This has two advantages: it is fast
(you even reuse the SV's, so they don't have to be created after the
-first fetchrow) and it guarantees, that DBI handles I<bind_cols> for
+first fetchrow), and it guarantees that DBI handles I<bind_cols> for
you.
What you do is the following:
AV* av;
@@ -1327,10 +1397,17 @@
SvOK_off(AvARRAY(av)[i]);
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.
+
+=back
=item dbd_st_finish
This function can be called if the user wishes to indicate that no
more rows will be fetched even if the server has more rows to offer.
@@ -1347,10 +1424,19 @@
return 1;
}
The function returns TRUE for success, FALSE otherwise.
+=over 4
+
+*FIX ME* What happens if the user calls $sth->finish before $sth->execute?
+What happens if the user calls $sth->finish twice? What happens if the user
+calls $sth->execute on a SELECT statement twice with no intervening $sth->finish?
+What happens if the user calls $sth->finish before fetching any data?
+
+=back
+
=item dbd_st_destroy
This function is the private part of the statement handle destructor.
@@ -1735,13 +1821,13 @@
DBD::Oracle driver.
=head1 AUTHORS
-Jonathan Leffler <[EMAIL PROTECTED]>,
+Jonathan Leffler <[EMAIL PROTECTED]> (previously <[EMAIL PROTECTED]>),
Jochen Wiedmann <[EMAIL PROTECTED]>,
-and Tim Bunce.
+and Tim Bunce <[EMAIL PROTECTED]>.
=cut
package DBI::DBD;
