Author: timbo
Date: Wed Jun 2 02:14:57 2010
New Revision: 14093
Modified:
dbi/trunk/Changes
dbi/trunk/DBI.pm
Log:
Updated and clarified documentation for finish method.
Reordered Changes to approximately my Fixed/Changed/Added/Docs sequence style.
Modified: dbi/trunk/Changes
==============================================================================
--- dbi/trunk/Changes (original)
+++ dbi/trunk/Changes Wed Jun 2 02:14:57 2010
@@ -9,27 +9,30 @@
=head2 Changes in DBI 1.612 (svn r14075) 28th May 2010
Fixed DBD::DBM breakage with SQL::Statement (Jens Rehsack)
- Fixed DBD::File leaks file handles (Jens Rehsack)
+ Fixed DBD::File file handle leak (Jens Rehsack)
+ Fixed problems in 50dbm.t when running tests with multiple
+ dbms (Martin J. Evans)
+ Fixed DBD::DBM bugs found during tests (Jens Rehsack)
+ Changed Makefile.PL to modernize with CONFLICTS, recommended dependencies
+ and resources (Jens Rehsack)
Changed DBI::ProfileDumper to rename any existing profile file by
appending .prev, instead of overwriting it.
Changed DBI::ProfileDumper::Apache to work in more configurations
including vhosts using PerlOptions +Parent.
- Fixed problems in 50dbm.t when running tests with multiple
- dbms (Martin J. Evans)
+
Added more tests to 50dbm_simple.t to prove optimizations in
DBI::SQL::Nano and SQL::Statement (Jens Rehsack)
Updated tests to cover optional installed SQL::Statement (Jens Rehsack)
Synchronize between SQL::Statement and DBI::SQL::Nano (Jens Rehsack)
Added basic test for DBD::File (H. Merijn Brand)
- Modernize Makefile.PL with CONFLICTS, recommended dependencies and
- resources (Jens Rehsack)
+
+ Updated and clarified documentation for finish method (Tim Bunce).
Changes to DBD::File for better English and hopefully better
explanation (Martin J. Evans)
Update documentation of DBD::DBM to cover current implementation,
tried to explain some things better and changes most examples to
preferred style of Merijn and myself (Jens Rehsack)
- DBD::DBM fixes found during tests (Jens Rehsack)
=head2 Changes in DBI 1.611 (svn r13935) 29th April 2010
Modified: dbi/trunk/DBI.pm
==============================================================================
--- dbi/trunk/DBI.pm (original)
+++ dbi/trunk/DBI.pm Wed Jun 2 02:14:57 2010
@@ -6381,28 +6381,27 @@
$rc = $sth->finish;
Indicate that no more data will be fetched from this statement handle
-before it is either executed again or destroyed. The C<finish> method
-is rarely needed, and frequently overused, but can sometimes be
-helpful in a few very specific situations to allow the server to free
-up resources (such as sort buffers).
-
-When all the data has been fetched from a C<SELECT> statement, the
-driver should automatically call C<finish> for you. So you should
-I<not> normally need to call it explicitly I<except> when you know
-that you've not fetched all the data from a statement handle.
-The most common example is when you only want to fetch one row,
-but in that case the C<selectrow_*> methods are usually better anyway.
-Adding calls to C<finish> after each fetch loop is a common mistake,
+before it is either executed again or destroyed. You almost certainly
+do I<not> need to call this method.
+
+Adding calls to C<finish> after loop that fetches all rows is a common mistake,
don't do it, it can mask genuine problems like uncaught fetch errors.
+When all the data has been fetched from a C<SELECT> statement, the driver will
+automatically call C<finish> for you. So you should I<not> call it explicitly
+I<except> when you know that you've not fetched all the data from a statement
+handle I<and> the handle won't be destroyed soon.
+
+The most common example is when you only want to fetch just one row,
+but in that case the C<selectrow_*> methods are usually better anyway.
+
Consider a query like:
- SELECT foo FROM table WHERE bar=? ORDER BY foo
+ SELECT foo FROM table WHERE bar=? ORDER BY baz
-where you want to select just the first (smallest) "foo" value from a
-very large table. When executed, the database server will have to use
+on a very large table. When executed, the database server will have to use
temporary buffer space to store the sorted rows. If, after executing
-the handle and selecting one row, the handle won't be re-executed for
+the handle and selecting just a few rows, the handle won't be re-executed for
some time and won't be destroyed, the C<finish> method can be used to tell
the server that the buffer space can be freed.
