"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "DBI.pm" between
DBI-1.642.tar.gz and DBI-1.643.tar.gz

About: DBI - The Perl Database Interface (requires one or more "driver" modules DBD::* to talk to databases).

DBI.pm  (DBI-1.642):DBI.pm  (DBI-1.643)
skipping to change at page 124, line ? skipping to change at page 124, line ?
# Copyright (c) 1994-2012 Tim Bunce Ireland # Copyright (c) 1994-2012 Tim Bunce Ireland
# #
# See COPYRIGHT section in pod text below for usage and distribution rights. # See COPYRIGHT section in pod text below for usage and distribution rights.
# #
package DBI; package DBI;
require 5.008_001; require 5.008_001;
BEGIN { BEGIN {
our $XS_VERSION = our $VERSION = "1.642"; # ==> ALSO update the version in the p od text below! our $XS_VERSION = our $VERSION = "1.643"; # ==> ALSO update the version in the p od text below!
$VERSION = eval $VERSION; $VERSION = eval $VERSION;
} }
=head1 NAME =head1 NAME
DBI - Database independent interface for Perl DBI - Database independent interface for Perl
=head1 SYNOPSIS =head1 SYNOPSIS
use DBI; use DBI;
skipping to change at page 124, line ? skipping to change at page 124, line ?
keys %$old_dbh; # reset iterator keys %$old_dbh; # reset iterator
while ( my ($k, $v) = each %$old_dbh ) { while ( my ($k, $v) = each %$old_dbh ) {
# ignore non-code refs, i.e., caches, handles, Err etc # ignore non-code refs, i.e., caches, handles, Err etc
next if ref $v && ref $v ne 'CODE'; # HandleError etc next if ref $v && ref $v ne 'CODE'; # HandleError etc
$attr->{$k} = $v; $attr->{$k} = $v;
} }
# explicitly set attributes which are unlikely to be in the # explicitly set attributes which are unlikely to be in the
# attribute cache, i.e., boolean's and some others # attribute cache, i.e., boolean's and some others
$attr->{$_} = $old_dbh->FETCH($_) for (qw( $attr->{$_} = $old_dbh->FETCH($_) for (qw(
AutoCommit ChopBlanks InactiveDestroy AutoInactiveDestroy AutoCommit ChopBlanks InactiveDestroy AutoInactiveDestroy
LongTruncOk PrintError PrintWarn Profile RaiseError LongTruncOk PrintError PrintWarn Profile RaiseError RaiseWarn
ShowErrorStatement TaintIn TaintOut ShowErrorStatement TaintIn TaintOut
)); ));
} }
# use Data::Dumper; warn Dumper([$old_dbh, $attr]); # use Data::Dumper; warn Dumper([$old_dbh, $attr]);
my $new_dbh = &$closure($old_dbh, $attr); my $new_dbh = &$closure($old_dbh, $attr);
unless ($new_dbh) { unless ($new_dbh) {
# need to copy err/errstr from driver back into $old_dbh # need to copy err/errstr from driver back into $old_dbh
my $drh = $old_dbh->{Driver}; my $drh = $old_dbh->{Driver};
return $old_dbh->set_err($drh->err, $drh->errstr, $drh->state); return $old_dbh->set_err($drh->err, $drh->errstr, $drh->state);
skipping to change at page 124, line ? skipping to change at page 124, line ?
for example: for example:
$sth = $dbh->prepare("SELECT foo, bar FROM table WHERE baz=?"); $sth = $dbh->prepare("SELECT foo, bar FROM table WHERE baz=?");
$sth->execute( $baz ); $sth->execute( $baz );
while ( @row = $sth->fetchrow_array ) { while ( @row = $sth->fetchrow_array ) {
print "@row\n"; print "@row\n";
} }
For queries that are not executed many times at once, it is often cleaner
to use the higher level select wrappers:
$row_hashref = $dbh->selectrow_hashref("SELECT foo, bar FROM table WHERE baz=?
", undef, $baz);
$arrayref_of_row_hashrefs = $dbh->selectall_arrayref(
"SELECT foo, bar FROM table WHERE baz BETWEEN ? AND ?",
{ Slice => {} }, $baz_min, $baz_max);
The typical method call sequence for a I<non>-C<SELECT> statement is: The typical method call sequence for a I<non>-C<SELECT> statement is:
prepare, prepare,
execute, execute,
execute, execute,
execute. execute.
for example: for example:
$sth = $dbh->prepare("INSERT INTO table(foo,bar,baz) VALUES (?,?,?)"); $sth = $dbh->prepare("INSERT INTO table(foo,bar,baz) VALUES (?,?,?)");
while(<CSV>) { while(<CSV>) {
chomp; chomp;
my ($foo,$bar,$baz) = split /,/; my ($foo,$bar,$baz) = split /,/;
$sth->execute( $foo, $bar, $baz ); $sth->execute( $foo, $bar, $baz );
} }
The C<do()> method can be used for non repeated I<non>-C<SELECT> statement The C<do()> method is a wrapper of prepare and execute that can be simpler
(or with drivers that don't support placeholders): for non repeated I<non>-C<SELECT> statements (or with drivers that don't
support placeholders):
$rows_affected = $dbh->do("UPDATE your_table SET foo = foo + 1"); $rows_affected = $dbh->do("UPDATE your_table SET foo = foo + 1");
$rows_affected = $dbh->do("DELETE FROM table WHERE foo = ?", undef, $foo);
To commit your changes to the database (when L</AutoCommit> is off): To commit your changes to the database (when L</AutoCommit> is off):
$dbh->commit; # or call $dbh->rollback; to undo changes $dbh->commit; # or call $dbh->rollback; to undo changes
Finally, when you have finished working with the data source, you should Finally, when you have finished working with the data source, you should
L</disconnect> from it: L</disconnect> from it:
$dbh->disconnect; $dbh->disconnect;
=head2 General Interface Rules & Caveats =head2 General Interface Rules & Caveats
skipping to change at page 124, line ? skipping to change at page 124, line ?
contents of these fields. The driver is free to interpret the contents of these fields. The driver is free to interpret the
C<$data_source>, C<$username>, and C<$password> fields in any way, and supply C<$data_source>, C<$username>, and C<$password> fields in any way, and supply
whatever defaults are appropriate for the engine being accessed. whatever defaults are appropriate for the engine being accessed.
(Oracle, for example, uses the ORACLE_SID and TWO_TASK environment (Oracle, for example, uses the ORACLE_SID and TWO_TASK environment
variables if no C<$data_source> is specified.) variables if no C<$data_source> is specified.)
The C<AutoCommit> and C<PrintError> attributes for each connection The C<AutoCommit> and C<PrintError> attributes for each connection
default to "on". (See L</AutoCommit> and L</PrintError> for more information.) default to "on". (See L</AutoCommit> and L</PrintError> for more information.)
However, it is strongly recommended that you explicitly define C<AutoCommit> However, it is strongly recommended that you explicitly define C<AutoCommit>
rather than rely on the default. The C<PrintWarn> attribute defaults to true. rather than rely on the default. The C<PrintWarn> attribute defaults to true.
The C<RaiseWarn> attribute defaults to false.
The C<\%attr> parameter can be used to alter the default settings of The C<\%attr> parameter can be used to alter the default settings of
C<PrintError>, C<RaiseError>, C<AutoCommit>, and other attributes. For example: C<PrintError>, C<RaiseError>, C<AutoCommit>, and other attributes. For example:
$dbh = DBI->connect($data_source, $user, $pass, { $dbh = DBI->connect($data_source, $user, $pass, {
PrintError => 0, PrintError => 0,
AutoCommit => 0 AutoCommit => 0
}); });
The username and password can also be specified using the attributes The username and password can also be specified using the attributes
skipping to change at page 124, line ? skipping to change at page 124, line ?
the normal DBI error handling mechanisms, such as C<RaiseError> and the normal DBI error handling mechanisms, such as C<RaiseError> and
C<HandleError>, if they are enabled, when execution returns from C<HandleError>, if they are enabled, when execution returns from
the DBI back to the application. the DBI back to the application.
Setting C<err> to C<""> indicates an 'information' state, and setting Setting C<err> to C<""> indicates an 'information' state, and setting
it to C<"0"> indicates a 'warning' state. Setting C<err> to C<undef> it to C<"0"> indicates a 'warning' state. Setting C<err> to C<undef>
also sets C<errstr> to undef, and C<state> to C<"">, irrespective also sets C<errstr> to undef, and C<state> to C<"">, irrespective
of the values of the $errstr and $state parameters. of the values of the $errstr and $state parameters.
The $method parameter provides an alternate method name for the The $method parameter provides an alternate method name for the
C<RaiseError>/C<PrintError>/C<PrintWarn> error string instead of C<RaiseError>/C<PrintError>/C<RaiseWarn>/C<PrintWarn> error string instead of
the fairly unhelpful 'C<set_err>'. the fairly unhelpful 'C<set_err>'.
The C<set_err> method normally returns undef. The $rv parameter The C<set_err> method normally returns undef. The $rv parameter
provides an alternate return value. provides an alternate return value.
Some special rules apply if the C<err> or C<errstr> Some special rules apply if the C<err> or C<errstr>
values for the handle are I<already> set... values for the handle are I<already> set...
If C<errstr> is true then: "C< [err was %s now %s]>" is appended if $err is If C<errstr> is true then: "C< [err was %s now %s]>" is appended if $err is
true and C<err> is already true and the new err value differs from the original true and C<err> is already true and the new err value differs from the original
skipping to change at page 124, line ? skipping to change at page 124, line ?
effectively do a C<warn("$class $method failed: $DBI::errstr")> where C<$class> effectively do a C<warn("$class $method failed: $DBI::errstr")> where C<$class>
is the driver class and C<$method> is the name of the method which failed. E.g., is the driver class and C<$method> is the name of the method which failed. E.g.,
DBD::Oracle::db prepare failed: ... error text here ... DBD::Oracle::db prepare failed: ... error text here ...
By default, C<DBI-E<gt>connect> sets C<PrintError> "on". By default, C<DBI-E<gt>connect> sets C<PrintError> "on".
If desired, the warnings can be caught and processed using a C<$SIG{__WARN__}> If desired, the warnings can be caught and processed using a C<$SIG{__WARN__}>
handler or modules like CGI::Carp and CGI::ErrorWrap. handler or modules like CGI::Carp and CGI::ErrorWrap.
=head3 C<RaiseWarn>
Type: boolean, inherited
The C<RaiseWarn> attribute can be used to force warnings to raise exceptions rat
her
then simply printing them. It is "off" by default.
When set "on", any method which sets warning condition will cause
the DBI to effectively do a C<die("$class $method warning: $DBI::errstr")>,
where C<$class> is the driver class and C<$method> is the name of the method
that sets warning condition. E.g.,
DBD::Oracle::db execute warning: ... warning text here ...
If you turn C<RaiseWarn> on then you'd normally turn C<PrintWarn> off.
If C<PrintWarn> is also on, then the C<PrintWarn> is done first (naturally).
This attribute was added in DBI 1.643.
=head3 C<RaiseError> =head3 C<RaiseError>
Type: boolean, inherited Type: boolean, inherited
The C<RaiseError> attribute can be used to force errors to raise exceptions rath er The C<RaiseError> attribute can be used to force errors to raise exceptions rath er
than simply return error codes in the normal way. It is "off" by default. than simply return error codes in the normal way. It is "off" by default.
When set "on", any method which results in an error will cause When set "on", any method which results in an error will cause
the DBI to effectively do a C<die("$class $method failed: $DBI::errstr")>, the DBI to effectively do a C<die("$class $method failed: $DBI::errstr")>,
where C<$class> is the driver class and C<$method> is the name of the method where C<$class> is the driver class and C<$method> is the name of the method
that failed. E.g., that failed. E.g.,
skipping to change at page 124, line ? skipping to change at page 124, line ?
regardless of how the block is exited. regardless of how the block is exited.
The same logic applies to other attributes, including C<PrintError>. The same logic applies to other attributes, including C<PrintError>.
=head3 C<HandleError> =head3 C<HandleError>
Type: code ref, inherited Type: code ref, inherited
The C<HandleError> attribute can be used to provide your own alternative behavio ur The C<HandleError> attribute can be used to provide your own alternative behavio ur
in case of errors. If set to a reference to a subroutine then that in case of errors. If set to a reference to a subroutine then that
subroutine is called when an error is detected (at the same point that subroutine is called when an error is detected (at the same point that
C<RaiseError> and C<PrintError> are handled). C<RaiseError> and C<PrintError> are handled). It is called also when
C<RaiseWarn> is enabled and a warning is detected.
The subroutine is called with three parameters: the error message The subroutine is called with three parameters: the error message
string that C<RaiseError> and C<PrintError> would use, string that C<RaiseError>, C<RaiseWarn> or C<PrintError> would use,
the DBI handle being used, and the first value being returned by the DBI handle being used, and the first value being returned by
the method that failed (typically undef). the method that failed (typically undef).
If the subroutine returns a false value then the C<RaiseError> If the subroutine returns a false value then the C<RaiseError>, C<RaiseWarn>
and/or C<PrintError> attributes are checked and acted upon as normal. and/or C<PrintError> attributes are checked and acted upon as normal.
For example, to C<die> with a full stack trace for any error: For example, to C<die> with a full stack trace for any error:
use Carp; use Carp;
$h->{HandleError} = sub { confess(shift) }; $h->{HandleError} = sub { confess(shift) };
Or to turn errors into exceptions: Or to turn errors into exceptions:
use Exception; # or your own favourite exception module use Exception; # or your own favourite exception module
skipping to change at page 124, line ? skipping to change at page 124, line ?
return 1 if $previous_handler and &$previous_handler(@_); return 1 if $previous_handler and &$previous_handler(@_);
... your code here ... ... your code here ...
}; };
} }
Using a C<my> inside a subroutine to store the previous C<HandleError> Using a C<my> inside a subroutine to store the previous C<HandleError>
value is important. See L<perlsub> and L<perlref> for more information value is important. See L<perlsub> and L<perlref> for more information
about I<closures>. about I<closures>.
It is possible for C<HandleError> to alter the error message that It is possible for C<HandleError> to alter the error message that
will be used by C<RaiseError> and C<PrintError> if it returns false. will be used by C<RaiseError>, C<RaiseWarn> and C<PrintError> if it returns fals e.
It can do that by altering the value of $_[0]. This example appends It can do that by altering the value of $_[0]. This example appends
a stack trace to all errors and, unlike the previous example using a stack trace to all errors and, unlike the previous example using
Carp::confess, this will work C<PrintError> as well as C<RaiseError>: Carp::confess, this will work C<PrintError> as well as C<RaiseError>:
$h->{HandleError} = sub { $_[0]=Carp::longmess($_[0]); 0; }; $h->{HandleError} = sub { $_[0]=Carp::longmess($_[0]); 0; };
It is also possible for C<HandleError> to hide an error, to a limited It is also possible for C<HandleError> to hide an error, to a limited
degree, by using L</set_err> to reset $DBI::err and $DBI::errstr, degree, by using L</set_err> to reset $DBI::err and $DBI::errstr,
and altering the return value of the failed method. For example: and altering the return value of the failed method. For example:
skipping to change at page 124, line ? skipping to change at page 124, line ?
The C<ErrCount> attribute was added in DBI 1.41. Older drivers may The C<ErrCount> attribute was added in DBI 1.41. Older drivers may
not have been updated to use set_err() to record errors and so this not have been updated to use set_err() to record errors and so this
attribute may not be incremented when using them. attribute may not be incremented when using them.
=head3 C<ShowErrorStatement> =head3 C<ShowErrorStatement>
Type: boolean, inherited Type: boolean, inherited
The C<ShowErrorStatement> attribute can be used to cause the relevant The C<ShowErrorStatement> attribute can be used to cause the relevant
Statement text to be appended to the error messages generated by Statement text to be appended to the error messages generated by
the C<RaiseError>, C<PrintError>, and C<PrintWarn> attributes. the C<RaiseError>, C<PrintError>, C<RaiseWarn> and C<PrintWarn> attributes.
Only applies to errors on statement handles Only applies to errors on statement handles
plus the prepare(), do(), and the various C<select*()> database handle methods. plus the prepare(), do(), and the various C<select*()> database handle methods.
(The exact format of the appended text is subject to change.) (The exact format of the appended text is subject to change.)
If C<$h-E<gt>{ParamValues}> returns a hash reference of parameter If C<$h-E<gt>{ParamValues}> returns a hash reference of parameter
(placeholder) values then those are formatted and appended to the (placeholder) values then those are formatted and appended to the
end of the Statement text in the error message. end of the Statement text in the error message.
=head3 C<TraceLevel> =head3 C<TraceLevel>
skipping to change at page 124, line ? skipping to change at page 124, line ?
@ary = $dbh->selectall_array($statement); @ary = $dbh->selectall_array($statement);
@ary = $dbh->selectall_array($statement, \%attr); @ary = $dbh->selectall_array($statement, \%attr);
@ary = $dbh->selectall_array($statement, \%attr, @bind_values); @ary = $dbh->selectall_array($statement, \%attr, @bind_values);
This is a convenience wrapper around L<selectall_arrayref> that returns This is a convenience wrapper around L<selectall_arrayref> that returns
the rows directly as a list, rather than a reference to an array of rows. the rows directly as a list, rather than a reference to an array of rows.
Note that if L</RaiseError> is not set then you can't tell the difference Note that if L</RaiseError> is not set then you can't tell the difference
between returning no rows and an error. Using RaiseError is best practice. between returning no rows and an error. Using RaiseError is best practice.
The C<selectall_array> method was added in DBI 1.635.
=head3 C<selectall_hashref> =head3 C<selectall_hashref>
$hash_ref = $dbh->selectall_hashref($statement, $key_field); $hash_ref = $dbh->selectall_hashref($statement, $key_field);
$hash_ref = $dbh->selectall_hashref($statement, $key_field, \%attr); $hash_ref = $dbh->selectall_hashref($statement, $key_field, \%attr);
$hash_ref = $dbh->selectall_hashref($statement, $key_field, \%attr, @bind_valu es); $hash_ref = $dbh->selectall_hashref($statement, $key_field, \%attr, @bind_valu es);
This utility method combines L</prepare>, L</execute> and This utility method combines L</prepare>, L</execute> and
L</fetchall_hashref> into a single call. It returns a reference to a L</fetchall_hashref> into a single call. It returns a reference to a
hash containing one entry, at most, for each row, as returned by fetchall_hashre f(). hash containing one entry, at most, for each row, as returned by fetchall_hashre f().
 End of changes. 14 change blocks. 
10 lines changed or deleted 46 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)