Re: Documentation / Error checking

On Fri, Nov 18, 2005 at 02:15:50PM +0200, Nitzan Shaked wrote:
> (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.

I'll clarify the docs. Basically all methods calls reset err except for
just a few special cases such as err and errstr, obviously, and FETCH
(eg $foo = $h->{SomeAttribute}).

For the record, here's the current list of methods that don't reset err:

DBI::common::CLEAR
DBI::common::DESTROY
DBI::common::EXISTS
DBI::common::FETCH
DBI::common::FIRSTKEY
DBI::common::NEXTKEY
DBI::common::STORE
DBI::common::debug
DBI::common::dump_handle
DBI::common::err
DBI::common::errstr
DBI::common::func
DBI::common::parse_trace_flag
DBI::common::parse_trace_flags
DBI::common::private_data
DBI::common::state
DBI::common::trace
DBI::common::trace_msg
DBI::db::ping
DBI::db::rows
DBI::st::rows

This is a fuzzy area of the DBI and I'm not guaranteeing that this list
won't change over time.

> 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( ... );

Well, if you're going to die() I'd just set RaiseError and forget about it.
If there's some good reason you don't want to use RaiseError then this
would do:

my $hr = $dbh->selectall_hashref( ... );
die(...) if $DBI::err;

> 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( "..." );

my $hr = $dbh->selectrow_hashref( ... ) or die(...);

Tim.
.