Current File : /home/rs/ruby/1.8/lib/ruby/site_ruby/1.8/dbi/handles/statement.rb
module DBI
#
# StatementHandle is the interface the consumer sees after successfully
# issuing a DatabaseHandle#prepare. They may also be exposed through other
# methods that send statements to the database.
#
# Almost all methods in this class will raise InterfaceError if the
# statement is already finished.
#
class StatementHandle < Handle
include Enumerable
attr_accessor :dbh
attr_accessor :raise_error
def initialize(handle, fetchable=false, prepared=true, convert_types=true, executed=false)
super(handle)
@fetchable = fetchable
@prepared = prepared # only false if immediate execute was used
@executed = executed # only true if the statement was already executed.
@cols = nil
@coltypes = nil
@convert_types = convert_types
if @fetchable
@row = DBI::Row.new(column_names, column_types, nil, @convert_types)
else
@row = nil
end
end
# Returns true if the StatementHandle has had #finish called on it,
# explicitly or otherwise.
def finished?
@handle.nil?
end
# Returns true if the statement is believed to return data upon #fetch.
#
# The current reliability of this (and the concept in general) is
# suspect.
def fetchable?
@fetchable
end
#
# Instruct successive calls to #fetch to cast the type returned into
# `type`, for row position `pos`. Like all bind_* calls, `pos` indexes
# starting at 1.
#
# `type` is an object with the DBI::Type calling convention.
#
# This call must be called after #execute has successfully ran,
# otherwise it will raise InterfaceError.
#
# Example:
# # `foo` is an integer and this statement will return two rows.
# sth = dbh.prepare("select foo from bar")
# # would raise InterfaceError if called here
# sth.execute
#
# sth.bind_coltype(1, DBI::Type::Varchar)
# # would normally use DBI::Type::Integer and return a Fixnum. We'll make it a string.
# sth.fetch => ["1"]
#
# # Here we coerce it to Float.
# sth.bind_coltype(1, DBI::Type::Float)
# sth.fetch => [1.0]
# sth.finish
#
def bind_coltype(pos, type)
sanity_check({:prepared => true, :executed => true})
coltypes = column_types
if (pos - 1) < 0
raise InterfaceError, "bind positions index starting at 1"
end
coltypes[pos-1] = type
@row = DBI::Row.new(column_names, coltypes, nil, @convert_types)
end
#
# Just like BaseStatement#bind_param, but will attempt to convert the
# type if it's supposed to, adhering to the DBD's current ruleset.
#
def bind_param(param, value, attribs=nil)
sanity_check({ :prepared => true })
if @convert_types
value = DBI::Utils::ConvParam.conv_param(dbh.driver_name, value)[0]
end
@handle.bind_param(param, value, attribs)
end
# Execute the statement.
#
# This generally means that the statement will be sent to the database
# and some form of result cursor will be obtained, but is ultimately
# driver-dependent.
#
# If arguments are supplied, these are fed to #bind_param.
def execute(*bindvars)
cancel # cancel before
sanity_check({:prepared => true })
if @convert_types
bindvars = DBI::Utils::ConvParam.conv_param(dbh.driver_name, *bindvars)
end
@handle.bind_params(*bindvars)
@handle.execute
@fetchable = true
@executed = true
# TODO:?
#if @row.nil?
@row = DBI::Row.new(column_names, column_types, nil, @convert_types)
#end
return nil
end
#
# Finish the statement, causing the database to release all assets
# related to it (any result cursors, normally).
#
# StatementHandles that have already been finished will normally be
# inoperable and unavailable for further use.
#
def finish
sanity_check
@handle.finish
@handle = nil
end
#
# Cancel the query, closing any open result cursors and truncating any result sets.
#
# The difference between this and #finish is that cancelled statements
# may be re-executed.
#
def cancel
sanity_check
@handle.cancel if @fetchable
@fetchable = false
end
#
# Obtains the column names for this query as an array.
#
def column_names
sanity_check
return @cols unless @cols.nil?
@cols = @handle.column_info.collect {|col| col['name'] }
end
#
# Obtain the type mappings for the columns in this query based on
# ColumnInfo data on the query.
#
# The result will be a position-dependent array of objects that conform
# to the DBI::Type calling syntax.
#
def column_types
sanity_check
return @coltypes unless @coltypes.nil?
@coltypes = @handle.column_info.collect do |col|
if col['dbi_type']
col['dbi_type']
else
DBI::TypeUtil.type_name_to_module(col['type_name'])
end
end
end
#
# See BaseStatement#column_info.
#
def column_info
sanity_check
@handle.column_info.collect {|col| ColumnInfo.new(col) }
end
#
# Should return the row modified count as the result of statement execution.
#
# However, some low-level drivers do not supply this information or
# supply misleading information (> 0 rows for read-only select
# statements, f.e.)
#
def rows
sanity_check
@handle.rows
end
#
# See BaseStatement#fetch.
#
# fetch can also take a block which will be applied to each row in a
# similar fashion to Enumerable#collect. See #each.
#
def fetch(&p)
sanity_check({ :fetchable => true, :prepared => true, :executed => true })
if block_given?
while (res = @handle.fetch) != nil
@row = @row.dup
@row.set_values(res)
yield @row
end
@handle.cancel
@fetchable = false
return nil
else
res = @handle.fetch
if res.nil?
@handle.cancel
@fetchable = false
else
@row = @row.dup
@row.set_values(res)
res = @row
end
return res
end
end
#
# Synonym for #fetch with a block.
#
def each(&p)
sanity_check({:fetchable => true, :prepared => true, :executed => true})
raise InterfaceError, "No block given" unless block_given?
fetch(&p)
end
#
# Similar to #fetch, but returns Array of Array instead of Array of
# DBI::Row objects (and therefore does not perform type mapping). This
# is basically a way to get the raw data from the DBD.
#
def fetch_array
sanity_check({:fetchable => true, :prepared => true, :executed => true})
if block_given?
while (res = @handle.fetch) != nil
yield res
end
@handle.cancel
@fetchable = false
return nil
else
res = @handle.fetch
if res.nil?
@handle.cancel
@fetchable = false
end
return res
end
end
#
# Map the columns and results into an Array of Hash resultset.
#
# No type conversion is performed here. Expect this to change in 0.6.0.
#
def fetch_hash
sanity_check({:fetchable => true, :prepared => true, :executed => true})
cols = column_names
if block_given?
while (row = @handle.fetch) != nil
hash = {}
row.each_with_index {|v,i| hash[cols[i]] = v}
yield hash
end
@handle.cancel
@fetchable = false
return nil
else
row = @handle.fetch
if row.nil?
@handle.cancel
@fetchable = false
return nil
else
hash = {}
row.each_with_index {|v,i| hash[cols[i]] = v}
return hash
end
end
end
#
# Fetch `cnt` rows. Result is array of DBI::Row
#
def fetch_many(cnt)
sanity_check({:fetchable => true, :prepared => true, :executed => true})
cols = column_names
rows = @handle.fetch_many(cnt)
if rows.nil? or rows.empty?
@handle.cancel
@fetchable = false
return []
else
return rows.collect{|r| tmp = @row.dup; tmp.set_values(r); tmp }
end
end
#
# Fetch the entire result set. Result is array of DBI::Row.
#
def fetch_all
sanity_check({:fetchable => true, :prepared => true, :executed => true})
cols = column_names
fetched_rows = []
begin
while row = fetch do
fetched_rows.push(row)
end
rescue Exception
end
@handle.cancel
@fetchable = false
return fetched_rows
end
#
# See BaseStatement#fetch_scroll.
#
def fetch_scroll(direction, offset=1)
sanity_check({:fetchable => true, :prepared => true, :executed => true})
row = @handle.fetch_scroll(direction, offset)
if row.nil?
#@handle.cancel
#@fetchable = false
return nil
else
@row.set_values(row)
return @row
end
end
# Get an attribute from the StatementHandle object.
def [] (attr)
sanity_check
@handle[attr]
end
# Set an attribute on the StatementHandle object.
def []= (attr, val)
sanity_check
@handle[attr] = val
end
protected
def sanity_check(params={})
raise InterfaceError, "Statement was already closed!" if @handle.nil?
params.each_key do |key|
case key
when :fetchable
check_fetchable
when :executed
check_executed
when :prepared
check_prepared
when :statement
check_statement(params[:statement])
end
end
end
def check_prepared
raise InterfaceError, "Statement wasn't prepared before." unless @prepared
end
def check_fetchable
if !@fetchable and @raise_error
raise InterfaceError, "Statement does not have any data for fetching."
end
end
def check_executed
raise InterfaceError, "Statement hasn't been executed yet." unless @executed
end
# basic sanity checks for statements
def check_statement(stmt)
raise InterfaceError, "Statement is empty, or contains nothing but whitespace" if stmt !~ /\S/
end
end # class StatementHandle
end
Mini Shell