view release on metacpan or  search on metacpan

DBI.pm  view on Meta::CPAN

level (not handle trace level) is set high enough to show the trace
from the DBI's method dispatcher, e.g. >= 9.

=item C<PrintWarn> (boolean, inherited)

The C<PrintWarn> attribute controls the printing of warnings recorded
by the driver.  When set to a true value the DBI will check method
calls to see if a warning condition has been set. If so, the DBI
will effectively do a C<warn("$class $method warning: $DBI::errstr")>
where C<$class> is the driver class and C<$method> is the name of
the method which failed. E.g.,

  DBD::Oracle::db execute warning: ... warning text here ...

By default, C<DBI-E<gt>connect> sets C<PrintWarn> "on" if $^W is true,
i.e., perl is running with warnings enabled.

If desired, the warnings can be caught and processed using a C<$SIG{__WARN__}>
handler or modules like CGI::Carp and CGI::ErrorWrap.

See also L</set_err> for how warnings are recorded and L</HandleSetErr>
for how to influence it.

Fetching the full details of warnings can require an extra round-trip
to the database server for some drivers. In which case the driver
may opt to only fetch the full details of warnings if the C<PrintWarn>
attribute is true. If C<PrintWarn> is false then these drivers should
still indicate the fact that there were warnings by setting the
warning string to, for example: "3 warnings".

=item C<PrintError> (boolean, inherited)

The C<PrintError> attribute can be used to force errors to generate warnings (using
C<warn>) in addition to returning error codes in the normal way.  When set
"on", any method which results in an error occuring will cause the DBI to
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.,

  DBD::Oracle::db prepare failed: ... error text here ...

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__}>
handler or modules like CGI::Carp and CGI::ErrorWrap.

=item C<RaiseError> (boolean, inherited)

The C<RaiseError> attribute can be used to force errors to raise exceptions rather
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
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
that failed. E.g.,

  DBD::Oracle::db prepare failed: ... error text here ...

If you turn C<RaiseError> on then you'd normally turn C<PrintError> off.
If C<PrintError> is also on, then the C<PrintError> is done first (naturally).

Typically C<RaiseError> is used in conjunction with C<eval { ... }>
to catch the exception that's been thrown and followed by an
C<if ($@) { ... }> block to handle the caught exception.
For example:

  eval {
    ...
    $sth->execute();
    ...
  };
  if ($@) {
    # $sth->err and $DBI::err will be true if error was from DBI
    warn $@; # print the error
    ... # do whatever you need to deal with the error
  }

In that eval block the $DBI::lasth variable can be useful for
diagnosis and reporting if you can't be sure which handle triggered
the error.  For example, $DBI::lasth->{Type} and $DBI::lasth->{Statement}.

See also L</Transactions>.

If you want to temporarily turn C<RaiseError> off (inside a library function
that is likely to fail, for example), the recommended way is like this:

  {
    local $h->{RaiseError};  # localize and turn off for this block
    ...
  }

The original value will automatically and reliably be restored by Perl,
regardless of how the block is exited.
The same logic applies to other attributes, including C<PrintError>.

=item C<HandleError> (code ref, inherited)

The C<HandleError> attribute can be used to provide your own alternative behaviour
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
C<RaiseError> and C<PrintError> are handled).

The subroutine is called with three parameters: the error message
string that C<RaiseError> and C<PrintError> would use,
the DBI handle being used, and the first value being returned by
the method that failed (typically undef).

If the subroutine returns a false value then the C<RaiseError>
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:

  use Carp;
  $h->{HandleError} = sub { confess(shift) };

Or to turn errors into exceptions:

  use Exception; # or your own favourite exception module
  $h->{HandleError} = sub { Exception->new('DBI')->raise($_[0]) };

It is possible to 'stack' multiple HandleError handlers by using
closures:

DBI.pm  view on Meta::CPAN

MySubDBI::db package.

Here's a brief example of a DBI subclass.  A more thorough example
can be found in t/subclass.t in the DBI distribution.

  package MySubDBI;

  use strict;

  use DBI;
  use vars qw(@ISA);
  @ISA = qw(DBI);

  package MySubDBI::db;
  use vars qw(@ISA);
  @ISA = qw(DBI::db);

  sub prepare {
    my ($dbh, @args) = @_;
    my $sth = $dbh->SUPER::prepare(@args)
        or return;
    $sth->{private_mysubdbi_info} = { foo => 'bar' };
    return $sth;
  }

  package MySubDBI::st;
  use vars qw(@ISA);
  @ISA = qw(DBI::st);

  sub fetch {
    my ($sth, @args) = @_;
    my $row = $sth->SUPER::fetch(@args)
        or return;
    do_something_magical_with_row_data($row)
        or return $sth->set_err(1234, "The magic failed", undef, "fetch");
    return $row;
  }

When calling a SUPER::method that returns a handle, be careful to
check the return value before trying to do other things with it in
your overridden method. This is especially important if you want
to set a hash attribute on the handle, as Perl's autovivification
will bite you by (in)conveniently creating an unblessed hashref,
which your method will then return with usually baffling results
later on.  It's best to check right after the call and return undef
immediately on error, just like DBI would and just like the example
above.

If your method needs to record an error it should call the set_err()
method with the error code and error string, as shown in the example
above. The error code and error string will be recorded in the
handle and available via C<$h-E<gt>err> and C<$DBI::errstr> etc.
The set_err() method always returns an undef or empty list as
approriate. Since your method should nearly always return an undef
or empty list as soon as an error is detected it's handy to simply
return what set_err() returns, as shown in the example above.

If the handle has C<RaiseError>, C<PrintError>, or C<HandleError>
etc. set then the set_err() method will honour them. This means
that if C<RaiseError> is set then set_err() won't return in the
normal way but will 'throw an exception' that can be caught with
an C<eval> block.

You can stash private data into DBI handles
via C<$h-E<gt>{private_..._*}>.  See the entry under L</ATTRIBUTES
COMMON TO ALL HANDLES> for info and important caveats.


=head1 TRACING

The DBI has a powerful tracing mechanism built in. It enables you
to see what's going on 'behind the scenes', both within the DBI and
the drivers you're using.

=head2 Trace Settings

Which details are written to the trace output is controlled by a
combination of a I<trace level>, an integer from 0 to 15, and a set
of I<trace flags> that are either on or off. Together these are known
as the I<trace settings> and are stored together in a single integer.
For normal use you only need to set the trace level, and generally
only to a value between 1 and 4.

Each handle has it's own trace settings, and so does the DBI.
When you call a method the DBI merges the handles settings into its
own for the duration of the call: the trace flags of the handle are
OR'd into the trace flags of the DBI, and if the handle has a higher
trace level then the DBI trace level is raised to match it.
The previous DBI trace setings are restored when the called method
returns.

=head2 Trace Levels

Trace I<levels> are as follows:

  0 - Trace disabled.
  1 - Trace DBI method calls returning with results or errors.
  2 - Trace method entry with parameters and returning with results.
  3 - As above, adding some high-level information from the driver
      and some internal information from the DBI.
  4 - As above, adding more detailed information from the driver.
  5 to 15 - As above but with more and more obscure information.

Trace level 1 is best for a simple overview of what's happening.
Trace level 2 is a good choice for general purpose tracing.
Levels 3 and above are best reserved for investigating a specific
problem, when you need to see "inside" the driver and DBI.

The trace output is detailed and typically very useful. Much of the
trace output is formatted using the L</neat> function, so strings
in the trace output may be edited and truncated by that function.

=head2 Trace Flags

Trace I<flags> are used to enable tracing of specific activities
within the DBI and drivers. The DBI defines some trace flags and
drivers can define others. DBI trace flag names begin with a capital
letter and driver specific names begin with a lowercase letter, as
usual.

Curently the DBI only defines two trace flags: