by Michael Neumann (mneumann@fantasy-coders.de)
$Id: DBI_SPEC.html,v 1.1 2006/01/04 02:03:17 francis Exp $
API_VERSION
VERSION
SQL_FETCH_NEXT
SQL_FETCH_PRIOR
SQL_FETCH_FIRST
SQL_FETCH_LAST
SQL_FETCH_ABSOLUTE
StatementHandle#fetch_scroll
.SQL_BIT
SQL_TINYINT
SQL_SMALLINT
SQL_INTEGER
SQL_BIGINT
SQL_FLOAT
SQL_REAL
SQL_DOUBLE
SQL_NUMERIC
SQL_DECIMAL
SQL_CHAR
SQL_VARCHAR
SQL_LONGVARCHAR
SQL_DATE
SQL_TIME
SQL_TIMESTAMP
SQL_BINARY
SQL_VARBINARY
SQL_LONGVARBINARY
SQL_OTHER
Exception classes were "borrowed" from Python API 2.0.
Warning < RuntimeError
Error < RuntimeError
InterfaceError < Error
NotImplementedError < InterfaceError
DatabaseError < Error
Exception for errors related to the database.
Has three attributes: err, errstr and state.
DataError < DatabaseError
OperationalError < DatabaseError
IntegrityError < DatabaseError
InternalError < DatabaseError
ProgrammingError < DatabaseError
NotSupportedError < DatabaseError
DBI.connect( driver_url, user=nil, auth=nil, params=nil )
Connect to the database specified by driver_url, which may look like "dbi:Oracle:oracle.neumann".
Returns a DBI::DatabaseHandle
object, or if called with a code-block,
calls this block with the new DBI::DatabaseHandle
as parameter and
calls disconnect after calling the block if it was not yet disconnected by
the user.
DBI.available_drivers
Array
of all available DBD drivers.
The strings which represent the DBD drivers are partial DSNs
(e.g., "dbi:Oracle:").DBI.data_sources( driver )
DBI.disconnect_all( driver=nil )
nil
.DBI.trace(mode=nil, output=nil)
Sets the trace mode for all subsequently created Handles to these values.
If a parameter is nil
, the value is not changed.
mode defaults to 2 if it is nil
, and output to STDERR
if a value was not
previously set.
For mode, the values 0, 1, 2 or 3 are allowed.
Note: Tracing is only activated if you load the module "dbi/trace", because tracing currently depends on AspectR > 0.3.3.
Abstract base class for all "Handles" (DriverHandle, DatabaseHandle, StatementHandle).
func( function, *values )
trace(mode=nil, output=nil)
Sets the trace mode for this handle as well as for all sub-handles (in the case of DriverHandle and DatabaseHandle).
If a parameter is nil
, the value is not changed.
mode defaults to 2 if it is nil
, and output to STDERR
if a value was not
previously set.
For mode, the values 0, 1, 2 or 3 are allowed.
Note: Tracing is only activated if you load the module "dbi/trace", because tracing currently depends on AspectR > 0.3.3.
DBI::Handle
connected?
true
if the connection was not yet disconnected
by calling disconnect, otherwise false
.disconnect
prepare( stmt )
prepare( stmt ) {|statement_handle| aBlock}
DBI::StatementHandle
, or if called with a code-block,
calls the block with the handle as its parameter and after that
calls #finish
onto the handle to free all resourcesexecute( stmt, *bindvars )
execute( stmt, *bindvars ) {|statement_handle| aBlock}
Immediately executes the SQL statement stmt after binding the values in bindvars to the placeholders in the statement.
Returns a DBI::StatementHandle
, or if called with a code-block,
calls the block with the handle as its parameter and after that
calls #finish
onto the handle to free all resources.
do( stmt, *bindvars )
DBI::StatementHandle
.select_one( stmt, *bindvars)
DBI::Row
object. select_all( stmt, *bindvars)
Executes the statement after binding the values to the parameters, then returns all
resulting rows as an array of DBI::Row
objects.
If called as an iterator, the passed DBI::Row
objects are only references.
tables
columns( table )
DBI::ColumnInfo
object for each column
in the table.ping
Returns true
if the connection is active, otherwise false
.
In contrast to connected?, ping tests if the connection is still active by executing some SQL or doing something else.
quote( value )
commit
rollback
transaction {|database_handle| aBlock}
[attr]
[attr] = val
true
or false
. Attributes are database dependent.DBI::Handle
Enumerable
bind_param( param, value, attribs=nil )
Binds the value value to a placeholder.
The placeholder is represented by param, which is either a
String
representing the name of the
placeholder used in the SQL statement (e.g., Oracle: "SELECT * FROM EMP WHERE ENAME = :ename"),
or an integer that indicates the number of the placeholder.
Placeholder numbers begin at 1.
attribs is not yet used in this version, but could later be a hash containing more information like parameter type, etc.
execute( *bindvars )
finish
cancel
column_names
Array
of all column names.column_info
Array
containing a DBI::ColumnInfo
object for each column
in the result set.rows
nil
if no such exists.fetchable?
true
if you can fetch rows using fetch, etc.fetch
Returns a DBI::Row
object, or nil
if there are
no more rows to fetch.
When called as an iterator, the block is called for each row
until no more rows are available. Each row is passed to the
block as a DBI::Row
object.
Note that the returned or passed DBI::Row
object is only a reference and
should be copied (dup) if it is stored elsewhere.
each {|row| aBlock }
fetch_array
Returns the current row as an Array
or nil
if no more
rows are available.
Can also be called as an iterator.
fetch_hash
Returns the current row as a Hash
or nil
if no more
rows are available.
Can also be called as an iterator.
fetch_many( cnt )
Returns an Array
of the next cnt rows, which are
stored as DBI::Row
objects.
Returns the empty array []
if there are no more rows.
fetch_all
fetch_scroll( direction, offset=1 )
direction is one of the following constants:
offset is a positive or negative number (only when SQL_FETCH_RELATIVE is used).
fetch_scroll does not automatically free the result set if no more rows are available, e.g., if you get the last row.
Returns a DBI::Row
object, or nil
if no row is available.
Note that the returned DBI::Row
object is only a reference and
should be copied (dup) if it is stored elsewhere.
[attr]
[attr] = val