Documentation / Error checking

(A bit long)
(Bottom line: is it, or is it not, enough to always check DBI::err)

Hello

The documentation for how to check the success of various DBI calls, and in
particular do(), selectrow_foo() and selectall_foo() is unclear and not
precise, at least for me. Actually I am not sure, after scrutinizing, how
exactly to check for errors.

Specific problems:

Looking at the doc for "err", we see: "The DBI resets $h->err to undef
before most DBI method calls", note the "most". Since the documentation for
specific methods does not say which do *not* reset err, I have no way of
knowing which do and which don't.

Also: looking at (for example) the doc for selectall_hashref(), we can find:
"If any method except fetchrow_hashref fails, and "RaiseError" is not set,
selectall_hashref will return undef. If fetchrow_hashref fails and
"RaiseError" is not set, then it will return with whatever data it has
fetched thus far. $DBI::err should be checked to catch that".
selectall_arrayref() and selectcol_arrayref() have similar documentation.

To me this looks like the correct way to check selectall_hashref() is then:
my $hr = $dbh->selectall_hashref( ... ); (!defined $hr || defined $DBI::err)
&& die( ... );

Justification: error returns undef, so we need to see whether the result is
defined at all. Checking DBI::err is to test "that" -- only some rows were
returned. It does *not* say explicitly that err is reset before hand, so I
can't be sure that testing err alone is enough!

Looking at selectrow_hashref() says that error is indicated by undef. It
does *not* say err will be set. So I can only assume I need to:

my $hr = $dbh->selectrow_hashref( ... ); !defined $hr && die( "..." );

Again it does not say err is reset before, so I cannot assume I can trust
err for telling me about errors. The docs only explicitly mention the return
value.

To summarize:

My understand of the docs as written is that errors for selectall_ and
selectcol_ methods should be checked as:

(!defined $return_value || defined $DBI::err) && die( ... );

.... that errors for selectrow_ methods should be checked as:

(defined $return_value) || die( ... );

.... and that errors for do() should be checked as:

($return_value) || die( ... );

Is that correct? Is it really not possible to only check for (defined
DBI::err) always?

Can someone verify, or clarify the docs?

Much obligied,
Nitzan


.

Relevant Pages