DBI Methods (Perl in a Nutshell, 2nd Edition)

home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam

Book Home

12.3. DBI Methods

The following methods are available under DBI.

available_drivers

@drivers = DBI->available_drivers([nowarn])

Returns a list of available drivers by searching @INC for the presence of DBD::* modules.

nowarn: A Boolean value specifying whether to suppress warnings if some drivers are hidden by others of the same name in earlier directories. Default is false (don't suppress).

$result = $st_handle->bind_col(col, \variable [, \%attr ])

Binds a field of a select statement to a variable, to be updated whenever the row is fetched.

col: The column number to bind
\variable: A reference to the variable to bind
\%attr: Attributes to set for the statement handle

bind_columns

$result = $st_handle->bind_columns(\%attr, @reflist )

Runs bind_col on each column of the statement.

\%attr: Attributes to set for the statement handle
@reflist: A list of references to the variables to bind

$result = $st_handle->bind_param(n, value [, type ])

Binds a value with a placeholder in a prepared statement.

n: The parameter number to bind.
value: The value to associate with parameter n.
type: The data type for the placeholder. The type can also be specified as an anonymous list ({TYPE => type}).

$result = $db_handle->commit

Commits the most recent changes. See also the AutoCommit attribute.

$db_handle = DBI->connect(data_source, user, passwd,[\%attr])

Connects to the specified database, returning a database handle object. The connect method automatically installs the driver if it has not already been installed.

data_source: A string identifying the driver to connect to, and any other additional driver-specific information needed to identify the driver (e.g., a port number). The driver name is written in the form dbi:driver_name, e.g., dbi:mysql. (Default value is taken from the DBI_DSN environment variable.) For example, a connection string for the MySQL driver always starts with dbi:mysql:. The second colon should be followed by any information required by the driver to make the database connection. In the case of MySQL, you must supply a database name (bookdb in the following example), a hostname (localhost), and the port number of the database server (1114):

DBI:$driver:database=$database;host=$hostname;port= $port
user: The username for the database connection. (Default value is taken from the DBI_USER environment variable.)
passwd: The password for the database connection. (Default value is taken from the DBI_PASS environment variable. Set this value at your own risk.)
\%attr: A hash reference defining attributes for the database handle.

data_sources

@drivers = DBI->data_sources(driver)

Returns a list of all databases available for the named driver. (The database server must be running for data_sources to return any results.)

driver: The driver to list. If unspecified, the value of DBI_DRIVER is used.

$result = $db_handle->disconnect

Disconnects the database.

$rows = $db_handle->do(statement [, \%attr, @bind_values ])

Prepares and executes a statement, returning the number of rows affected.

statement: The statement to execute
\%attr: Attributes to set for the new statement
@bind_values: Bind values for placeholder substitution

dump_results

$rows = DBI::dump_results(st_handle, maxlen, ldelim, fdelim, fileh)

Runs DBI::neat( ) on all the rows of a statement handle and prints them for testing purposes.

st_handle: The statement handle to retrieve.
maxlen: The length at which to truncate with "...". Default is 35.
ldelim: The delimiter between rows. Default is \n.
fdelim: The delimiter between individual fields. Default is , .
fileh: The filehandle to print to. Default is STDOUT.

err

$handle->err

Returns the error code from the last driver function called.

$handle->errstr

Returns the error message from the last driver function called.

$result = $st_handle->execute([@bind_values])

Executes a prepared statement.

@bind_values: Binds values for placeholder substitution

$arrayref = $st_handle->fetch

Fetches the next row of data, returning an array reference with the field values.

fetchall_arrayref

$arrayref = $st_handle->fetchall_arrayref

Fetches all data from a prepared statement and returns a reference to an array of references.

fetchrow_array

$array = $st_handle->fetchrow_array

Fetches the next row of data, returning an array with the field values.

fetchrow_arrayref

$arrayref = $st_handle->fetchrow_arrayref

Fetches the next row of data, returning an array reference with the field values. Synonym for fetch.

fetchrow_hashref

$hashref = $st_handle->fetchrow_hashref

Fetches the next row of data, returning a hash reference containing the field values. The keys of the hash are the same as $st_handle->{NAME}.

$result = $st_handle->finish

Disables further fetching from a statement.

func

$handle->func(@arguments, function)

Calls a private nonportable method on the specific handle.

@arguments: The arguments to the function.
function: The function name. Note that the function name is specified last.

neat

$newstring = DBI::neat(string, maxlength)

Converts a string to one with quoted strings, null values shown as undef, and unprintable characters shown as ".".

string: The string to convert
maxlength: The length at which to truncate the string with "..."

$newstring = DBI::neat_list(\@list, maxlength, delim)

Converts each element of a list with DBI::neat and returns it as a string.

\@list: A reference to the list to convert.
maxlength: The length at which to truncate the string with "...".
delim: The delimiter to use between list elements in the new string. Default is , .

ping

$result = $db_handle->ping

Determines if the database is still connected.

$st_handle = $db_handle->prepare(statement [, \%attr ])

Prepares a statement for execution and returns a reference to a statement handle object.

statement: The statement to prepare
\%attr: Attributes to set for the assigned statement handle

$sql = $db_handle->quote(string)

Escapes special characters in a string for use in a SQL statement.

string: The string to convert

$result = $db_handle->rollback

Undoes the most recent database changes if not yet committed.

rows

$rows = $st_handle->rows

Returns the number of rows affected by the last change to the database.

$handle->state

Returns an error code in a five-character format.

DBI->trace(n, filename)

Traces the execution of DBI.

n: An integer indicating the level of trace/debugging information, as follows:

0

Disable the trace.

1

Trace the execution of the DBI.

2

Output detailed call trace information including parameters and return values.
filename: The file to append trace information to

$handle->trace(n, filename)

Same as the class method DBI->trace, but for a specific database, statement, or driver handle.

Library Navigation Links

Copyright © 2002 O'Reilly & Associates. All rights reserved.