12.3. DBI Methods
The
following methods are available under DBI.
@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
$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.
@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
$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.
$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.
$arrayref = $st_handle->fetchall_arrayref
Fetches all data from a prepared statement
and returns a reference to an array of references.
$array = $st_handle->fetchrow_array
Fetches the next row of data, returning an
array with the field values.
$arrayref = $st_handle->fetchrow_arrayref
Fetches the next row of data, returning an
array reference with the field values. Synonym for
fetch.
$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.
$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.
$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 , .
$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 = $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.
 |  |  |
| 12.2. Design of DBI |  | 12.4. DBI Environment Variables |
Copyright © 2002 O'Reilly & Associates. All rights reserved.