Attributes Common to All Handles (Programming the Perl DBI)

A.5. Attributes Common to All Handles

These attributes are common to all types of DBI handles.

Some attributes are inherited by child handles. That is, the value of an inherited attribute in a newly created statement handle is the same as the value in the parent database handle. Changes to attributes in the new statement handle do not affect the parent database handle and changes to the database handle do not affect existing statement handles, only future ones.

Attempting to set or get the value of an unknown attribute is fatal, except for private driver-specific attributes (which all have names starting with a lowercase letter).

For example:

$h->{AttributeName} = ...;    # set/write
... = $h->{AttributeName};    # get/read

Warn ( boolean, inherited)

Enables useful warnings for certain bad practices. Enabled by default. Some emulation layers, especially those for Perl 4 interfaces, disable warnings. Since warnings are generated using the Perl warn function, they can be intercepted using the Perl $SIG{_ _WARN_ _} hook.

Active ( boolean, read-only)

True if the handle object is "active." This is rarely used in applications. The exact meaning of active is somewhat vague at the moment. For a database handle, it typically means that the handle is connected to a database ($dbh->disconnect sets Active off ). For a statement handle, it typically means that the handle is a SELECT that may have more data to fetch. (Fetching all the data or calling $sth->finish sets Active off.)

Kids (integer, read-only)

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.

ActiveKids (integer, read-only)

Like Kids, but only counting those that are Active (as above).

CachedKids (hash ref)

For a database handle, returns a reference to the cache (hash) of statement handles created by the prepare_cached method. For a driver handle, returns a reference to the cache (hash) of database handles created by the connect_cached method.

CompatMode ( boolean, inherited)

Used by emulation layers (such as Oraperl) to enable compatible behavior in the underlying driver (e.g., DBD::Oracle) for this handle. Not normally set by application code.

InactiveDestroy ( boolean)

This attribute can be used to disable the database engine related effect of destroying a handle (which would normally close a prepared statement or disconnect from the database, etc.).

For a database handle, this attribute does not disable an explicit call to the disconnect method, only the implicit call from DESTROY.

This attribute is specifically designed for use in Unix applications that "fork" child processes. Either the parent or the child process, but not both, should set InactiveDestroy on all their shared handles.

PrintError ( boolean, inherited)

This attribute can be used to force errors to generate warnings (using warn) in addition to returning error codes in the normal way. When set "on," any method that results in an error occurring will cause the DBI to effectively do a warn("$class $method failed: $DBI::errstr") where $class is the driver class, and $method is the name of the method which failed.

For example:

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

By default, DBI->connect sets PrintError to "on."

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

RaiseError ( boolean, inherited)

This 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 to "on", any method that results in an error will cause the DBI to effectively do a die("$class $method failed: $DBI::errstr"), where $class is the driver class, and $method is the name of the method that failed. For example:

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

If PrintError is also on, then the PrintError is done before the RaiseError unless no _ _DIE_ _ handler has been defined, in which case PrintError is skipped, since the die will print the message.

If you want to temporarily turn 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 PrintError.

Sadly, this doesn't work for Perl versions up to and including 5.004_04. For backwards compatibility, you could just use eval { ... } instead.

ChopBlanks ( boolean, inherited)

This attribute can be used to control the trimming of trailing space characters from fixed-width character (CHAR) fields. No other field types are affected, even where field values have trailing spaces.

The default is false (although it is possible that the default may change). Applications that need specific behavior should set the attribute as needed. Emulation interfaces should set the attribute to match the behavior of the interface they are emulating.

Drivers are not required to support this attribute, but any driver that does not support it must arrange to return undef as the attribute value.

LongReadLen (unsigned integer, inherited)

This attribute may be used to control the maximum length of long fields ("blob," "memo," etc.), which the driver will read from the database automatically when it fetches each row of data. The LongReadLen attribute relates only to fetching and reading long values; it is not involved in inserting or updating them.

A value of 0 means not to automatically fetch any long data. (fetch should return undef for long fields when LongReadLen is 0.)

The default is typically 0 (zero) bytes but may vary between drivers. Applications fetching long fields should set this value to slightly larger than the longest long field value to be fetched.

Some databases return some long types encoded as pairs of hex digits. For these types, LongReadLen relates to the underlying data length and not the doubled-up length of the encoded string.

Changing the value of LongReadLen for a statement handle after it has been prepare'd will typically have no effect, so it's common to set LongReadLen on the $dbh before calling prepare.

Note that the value used here has a direct effect on the memory used by the application, so don't be too generous.

See LongTruncOk for more information on truncation behavior.

LongTruncOk ( boolean, inherited)

This attribute may be used to control the effect of fetching a long field value that has been truncated (typically because it's longer than the value of the LongReadLen attribute).

By default, LongTruncOk is false, and so fetching a long value that needs to be truncated will cause the fetch to fail. (Applications should always be sure to check for errors after a fetch loop in case an error, such as a divide by zero or long field truncation, caused the fetch to terminate prematurely.)

If a fetch fails due to a long field truncation when LongTruncOk is false, many drivers will allow you to continue fetching further rows.