NAME

Exception::Class::DBI - DBI Exception objects

SYNOPSIS

use DBI;
use Exception::Class::DBI;

my $dbh = DBI->connect( $data_source, $username, $auth,
                        { PrintError => 0,
                          RaiseError => 0,
                          HandleError => Exception::Class::DBI->handler
                        });

eval { $dbh->do($sql) };

if (my $ex = $@) {
    print STDERR "DBI Exception:\n";
    print STDERR "  Exception Type: ", ref $ex, "\n";
    print STDERR "  Error: ", $ex->error, "\n";
    print STDERR "  Err: ", $ex->err, "\n";
    print STDERR "  Errstr: " $ex->errstr, "\n";
    print STDERR "  State: ", $ex->state, "\n";
    my $ret = $ex->retval;
    $ret = 'undef' unless defined $ret;
    print STDERR "  Return Value: $ret\n";
}

DESCRIPTION

This module offers a set of DBI-specific exception classes. They inherit from Exception::Class, the base class for all exception objects created by the Exception::Class module from the CPAN. Exception::Class::DBI itself offers a single class method, handler(), that returns a code reference appropriate for passing the DBI HandleError attribute.

The exception classes created by Exception::Class::DBI are designed to be thrown in certain DBI contexts; the code reference returned by handler() and passed to the DBI HandleError attribute determines the context, assembles the necessary metadata, and throws the apopropriate exception.

Each of the Exception::Class::DBI classes offers a set of object accessor methods in addition to those provided by Exception::Class. These can be used to output detailed output in the event of an exception.

INTERFACE

Exception::Class::DBI inherits from Exception::Class, and thus its entire interface. Refer to the Exception::Class documentation for details.

Class Method

handler

my $dbh = DBI->connect( $data_source, $username, $auth,
                        { PrintError => 0,
                          RaiseError => 0,
                          HandleError => Exception::Class::DBI->handler
                        });

This method returns a code reference appropriate for passing to the DBI HandleError attribute. When DBI encounters an error, it checks its PrintError, RaiseError, and HandleError attributes to decide what to do about it. When HandleError has been set to a code reference, DBI executes it, passing it the error string that would be printed for PrintError, the DBI handle object that was executing the method call that triggered the error, and the return value of that method call (usually undef). Using these arguments, the code reference provided by handler() determines what type of exception to throw. Exception::Class::DBI contains the subclasses detailed below, each relevant to the DBI handle that triggered the error.

CLASSES

Exception::Class::DBI creates a number of exception classes, each one specific to a particular DBI error context. Most of the object methods described below correspond to like-named attributes in the DBI itself. Thus the documentation below summarizes the DBI attribute documentation, so you should refer to DBI itself for more in-depth information.

Exception::Class::DBI

All of the Exception::Class::DBI classes documented below inherit from Exception::Class::DBI. It offers the several object methods in addition to those it inherits from its parent, Exception::Class. These methods correspond to the DBI dynamic attributes, as well as to the values passed to the handler() exception handler via the DBI HandleError attribute. Exceptions of this base class are only thrown when there is no DBI handle object executing, e.g. in the DBI connect() method. Note: This functionality is not yet implemented in DBI -- see the discusion that starts here: http://archive.develooper.com/dbi-dev@perl.org/msg01438.html.

error

my $error = $ex->error;

Exception::Class::DBI actually inherits this method from Exception::Class. It contains the error string that DBI prints when its PrintError attribute is enabled, or dies with when its <RaiseError> attribute is enabled.

err

my $err = $ex->err;

Corresponds to the $DBI::err dynamic attribute. Returns the native database engine error code from the last driver method called.

errstr

my $errstr = $ex->errstr;

Corresponds to the $DBI::errstr dynamic attribute. Returns the native database engine error message from the last driver method called.

state

my $state = $ex->state;

Corresponds to the $DBI::state dynamic attribute. Returns an error code in the standard SQLSTATE five character format.

retval

my $retval = $ex->retval;

The first value being returned by the DBI method that failed (typically undef).

Exception::Class::DBI::H

This class inherits from Exception::Class::DBI, and is the base class for all DBI handle exceptions (see below). It will not be thrown directly. Its methods correspond to the DBI attributes common to all handles.

warn

my $warn = $ex->warn;

Boolean value indicating whether DBI warnings have been enabled. Corresponds to the DBI Warn attribute.

active

my $active = $ex->active;

Boolean value indicating whether the DBI handle that encountered the error is active. Corresponds to the DBI Active attribute.

kids

my $kids = $ex->kids;

For a driver handle, Kids is the number of currently existing database handles that were created from that driver handle. For a database handle, Kids is the number of currently existing statement handles that were created from that database handle. Corresponds to the DBI Kids attribute.

active_kids

my $active_kids = $ex->active_kids;

Like kids, but only counting those that are active (as above). Corresponds to the DBI ActiveKids attribute.

compat_mode

my $compat_mode = $ex->compat_mode;

Boolean value indicating whether an emulation layer (such as Oraperl) enables compatible behavior in the underlying driver (e.g., DBD::Oracle) for this handle. Corresponds to the DBI CompatMode attribute.

inactive_destroy

my $inactive_destroy = $ex->inactive_destroy;

Boolean value indicating whether the DBI has disabled the database engine related effect of DESTROYing a handle. Corresponds to the DBI InactiveDestroy attribute.

trace_level

my $trace_level = $ex->trace_level;

Returns the DBI trace level set on the handle that encountered the error. Corresponds to the DBI TraceLevel attribute.

fetch_hash_key_name

my $fetch_hash_key_name = $ex->fetch_hash_key_name;

Returns the attribute name the DBI fetchrow_hashref() method should use to get the field names for the hash keys. Corresponds to the DBI FetchHashKeyName attribute.

chop_blanks

my $chop_blanks = $ex->chop_blanks;

Boolean value indicating whether DBI trims trailing space characters from fixed width character (CHAR) fields. Corresponds to the DBI ChopBlanks attribute.

long_read_len

my $long_read_len = $ex->long_read_len;

Returns the maximum length of long fields ("blob", "memo", etc.) which the DBI driver will read from the database automatically when it fetches each row of data. Corresponds to the DBI LongReadLen attribute.

long_trunc_ok

my $long_trunc_ok = $ex->long_trunc_ok;

Boolean value indicating whether the DBI will truncate values it retrieves from long fields that are longer than the value returned by long_read_len(). Corresponds to the DBI LongTruncOk attribute.

taint

my $taint = $ex->taint;

Boolean value indicating whether data fetched from the database is considered tainted. Corresponds to the DBI Taint attribute.

Exception::Class::DBI::DRH

DBI driver handle exceptions objects. This class inherits from Exception::Class::DBI::H, and offers no extra methods of its own.

Exception::Class::DBI::DBH

DBI database handle exceptions objects. This class inherits from Exception::Class::DBI::H Its methods correspond to the DBI database handle attributes.

auto_commit

my $auto_commit = $ex->auto_commit;

Returns true if the database handle AutoCommit attribute is enabled. meaning that database changes cannot be rolled back. Corresponds to the DBI database handle AutoCommit attribute.

db_name

my $db_name = $ex->db_name;

Returns the "name" of the database. Corresponds to the DBI database handle Name attribute.

statement

my $statement = $ex->statement;

Returns the statement string passed to the most recent call to the DBI prepare() method in this database handle. If it was the prepare() method that encountered the error and triggered the exception, the statement string will be the statement passed to prepare(). Corresponds to the DBI database handle Statement attribute.

row_cache_size

my $row_cache_size = $ex->row_cache_size;

Returns the hint to the database driver indicating the size of the local row cache that the application would like the driver to use for future SELECT statements. Corresponds to the DBI database handle RowCacheSize attribute.

Exception::Class::DBI::STH

DBI statement handle exceptions objects. This class inherits from Exception::Class::DBI::H Its methods correspond to the DBI statement handle attributes.

num_of_fields

my $num_of_fields = $ex->num_of_fields;

Returns the number of fields (columns) the prepared statement will return. Corresponds to the DBI statement handle NUM_OF_FIELDS attribute.

num_of_params

my $num_of_params = $ex->num_of_params;

Returns the number of parameters (placeholders) in the prepared statement. Corresponds to the DBI statement handle NUM_OF_PARAMS attribute.

field_names

my $field_names = $ex->field_names;

Returns a reference to an array of field names for each column. Corresponds to the DBI statement handle NAME attribute.

type

my $type = $ex->type;

Returns a reference to an array of integer values for each column. The value indicates the data type of the corresponding column. Corresponds to the DBI statement handle TYPE attribute.

precision

my $precision = $ex->precision;

Returns a reference to an array of integer values for each column. For non-numeric columns, the value generally refers to either the maximum length or the defined length of the column. For numeric columns, the value refers to the maximum number of significant digits used by the data type (without considering a sign character or decimal point). Corresponds to the DBI statement handle PRECISION attribute.

scale

my $scale = $ex->scale;

Returns a reference to an array of integer values for each column. Corresponds to the DBI statement handle SCALE attribute.

nullable

my $nullable = $ex->nullable;

Returns a reference to an array indicating the possibility of each column returning a null. Possible values are 0 (or an empty string) = no, 1 = yes, 2 = unknown. Corresponds to the DBI statement handle NULLABLE attribute.

cursor_name

my $cursor_name = $ex->cursor_name;

Returns the name of the cursor associated with the statement handle, if available. Corresponds to the DBI statement handle CursorName attribute.

param_values

my $param_values = $ex->param_values;

Returns a reference to a hash containing the values currently bound to placeholders. Corresponds to the DBI statement handle ParamValues attribute.

statement

my $statement = $ex->statement;

Returns the statement string passed to the DBI prepare() method. Corresponds to the DBI statement handle Statement attribute.

rows_in_cache

my $rows_in_cache = $ex->rows_in_cache;

the number of unfetched rows in the cache if the driver supports a local row cache for SELECT statements. Corresponds to the DBI statement handle RowsInCache attribute.

Exception::Class::DBI::Unknown

Exceptions of this class are thrown when the context for a DBI error cannot be determined. Inherits from Exception::Class::DBI, but implements no methods of its own.

NOTE

Note: Not all of the attributes offered by the DBI are exploited by these exception classes. For example, the PrintError and RaiseError attributes seemed redundant. But if folks think it makes sense to include the missing attributes for the sake of completeness, let me know. Enough interest will motivate me to get them in.

TO DO

I need to figure out a non-database specific way of testing STH exceptions. DBD::ExampleP works well for DRH and DBH exceptions, but not so well for STH exceptions.

BUGS

Report all bugs via the CPAN Request Tracker at http://rt.cpan.org/NoAuth/Bugs.html?Dist=Exception-Class-DBI.

AUTHOR

David Wheeler <david@wheeler.net>

SEE ALSO

You should really only be using this module in conjunction with Tim Bunce's DBI, so it pays to be familiar with its documentation.

See the documentation for Dave Rolsky's Exception::Class module for details on the methods this module's classes inherit from it. There's lots more information in these exception objects, so use them!

COPYRIGHT AND LICENSE

Copyright (c) 2002, David Wheeler. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Exception::Class::DBI

perl -MCPAN -e shell
install Exception::Class::DBI