Methods Common to All Handles

The following methods can be used by all types of DBI handles:

$rv = $h->err;

Returns the native database engine error code from the last driver method called. The code is typically an integer, but you should not assume that.

The DBI resets $h->err to undef before most DBI method calls, so the value has only a short lifespan. Also, most drivers share the same error variables across all their handles, so calling a method on one handle will typically reset the error on all the other handles that are children of that driver.

If you need to test for individual errors and have your program be portable to different database engines, then you'll need to determine what the corresponding error codes are for all those engines, and test for all of them.

$str = $h->errstr;

Returns the native database engine error message from the last driver method called. This has the same lifespan issues as the err method described above.

$str = $h->state;

Returns an error code in the standard SQLSTATE five-character format. Note that the specific success code is translated to (false). If the driver does not support SQLSTATE (and most don't), then state will return S1000 (General Error) for all errors.

$h->trace($trace_level); $h->trace($trace_level, $trace_filename);

DBI trace information can be enabled for a specific handle (and any future children of that handle) by setting the trace level using the trace method.

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 (up to 9) are best reserved for investigating a specific problem, when you need to see "inside" the driver and DBI. Set $trace_level to to disable the trace.

The trace output is detailed and typically very useful. Much of the trace output is formatted using the neat function, so strings may be edited and truncated.

Initially, trace output is written to STDERR. If $trace_filename is specified, then the file is opened in append mode and all trace output (including that from other handles) is redirected to that file. Further calls to trace without a $trace_filename do not alter where the trace output is sent. If $trace_filename is undefined, then trace output is sent to STDERR and the previous trace file is closed.

See also the DBI->trace method for information about the DBI_TRACE environment variable.

$h->trace_msg($message_text); $h->trace_msg($message_text, $min_level);

Writes $message_text to the trace file if trace is enabled for $h or for the DBI as a whole. Can also be called as DBI- >trace_msg($msg). See trace.

If $min_level is defined, then the message is output only if the trace level is equal to or greater than that level. $min_level defaults to .

$h->func(@func_arguments, $func_name);

The func method can be used to call private non-standard and non-portable methods implemented by the driver. Note that the function name is given as the last argument.

This method is not directly related to calling stored procedures. Calling stored procedures is currently not defined by the DBI. Some drivers, such as DBD::Oracle, support it in non-portable ways.

See driver documentation for more details.