Class: DBI::BaseStatement

Inherits:
Base
  • Object
show all
Defined in:
lib/dbi/base_classes/statement.rb

Overview

StatementHandles are used to encapsulate the process of managing a statement (DDL or DML) and its parameters, sending it to the database, and gathering any results from the execution of that statement.

As with the other Base classes, the terms “DBD Required” and “DBD Optional” are defined in DBI::BaseDatabase.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(attr = nil) ⇒ BaseStatement

Returns a new instance of BaseStatement.



14
15
16
 
# File 'lib/dbi/base_classes/statement.rb', line 14

def initialize(attr=nil)
    @attr = attr || {}
end

Instance Attribute Details

#raise_error ⇒ Object

Returns the value of attribute raise_error.



12
13
14
 
# File 'lib/dbi/base_classes/statement.rb', line 12

def raise_error
  @raise_error
end

Instance Method Details

#[](attr) ⇒ Object

Get statement attributes.



159
160
161
162
 
# File 'lib/dbi/base_classes/statement.rb', line 159

def [](attr)
    @attr ||= { }
    @attr[attr]
end

#[]=(attr, value) ⇒ Object

Set statement attributes. DBD Optional.

Raises:



167
168
169
 
# File 'lib/dbi/base_classes/statement.rb', line 167

def []=(attr, value)
    raise NotSupportedError
end

#bind_param(param, value, attribs) ⇒ Object

Bind a parameter to the statement. DBD Required.

The parameter number is numeric and indexes starting at 1. This corresponds to the question marks (?) in the statement from the left-most part of the statement moving forward.

The value may be any ruby type. How these are handled is DBD-dependent, but the vast majority of DBDs will convert these to string inside the query.

Raises:



29
30
31
 
# File 'lib/dbi/base_classes/statement.rb', line 29

def bind_param(param, value, attribs)
    raise NotImplementedError
end

#bind_params(*bindvars) ⇒ Object

Take a list of bind variables and bind them successively using bind_param.



74
75
76
77
 
# File 'lib/dbi/base_classes/statement.rb', line 74

def bind_params(*bindvars)
    bindvars.each_with_index {|val,i| bind_param(i+1, val, nil) }
    self
end

#cancel ⇒ Object

Cancel any result cursors. DBD Optional, but intentionally does not raise any exception as it’s used internally to maintain consistency.



83
84
 
# File 'lib/dbi/base_classes/statement.rb', line 83

def cancel
end

#column_info ⇒ Object

returns result-set column information as array of hashs, where each hash represents one column. See BaseDatabase#columns. DBD Required.

Raises:



63
64
65
 
# File 'lib/dbi/base_classes/statement.rb', line 63

def column_info
    raise NotImplementedError
end

#execute ⇒ Object

Execute the statement with the known binds. DBD Required.

Raises:



36
37
38
 
# File 'lib/dbi/base_classes/statement.rb', line 36

def execute
    raise NotImplementedError
end

#fetch ⇒ Object

Fetch the next row in the result set. DBD Required.

DBI::Row is responsible for formatting the data the DBD provides it.

Raises:



54
55
56
 
# File 'lib/dbi/base_classes/statement.rb', line 54

def fetch
    raise NotImplementedError
end

#fetch_all ⇒ Object

Fetch all available rows. Result is Array of DBI::Row.



141
142
143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/dbi/base_classes/statement.rb', line 141

def fetch_all
    rows = []
    loop do
        row = fetch
        break if row.nil?
        rows << row.dup
    end

    if rows.empty?
        nil
    else
        rows
    end
end

#fetch_many(cnt) ⇒ Object

fetch x rows. The result is Array of DBI::Row.



123
124
125
126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/dbi/base_classes/statement.rb', line 123

def fetch_many(cnt)
    rows = []
    cnt.times do
        row = fetch
        break if row.nil?
        rows << row.dup
    end

    if rows.empty?
        nil
    else
        rows
    end
end

#fetch_scroll(direction, offset) ⇒ Object

fetch_scroll is provided with a direction and offset and works similar to how seek() is used on files.

The constants available for direction are as follows:

  • SQL_FETCH_NEXT: fetch the next result.

  • SQL_FETCH_LAST: fetch the last result, period.

  • SQL_FETCH_RELATIVE: fetch the result at the offset.

Other constants can be used, but if this method is not supplied by the driver, they will result in a raise of DBI::NotSupportedError.



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/dbi/base_classes/statement.rb', line 100

def fetch_scroll(direction, offset)
    case direction
    when SQL_FETCH_NEXT
        return fetch
    when SQL_FETCH_LAST
        last_row = nil
        while (row=fetch) != nil
            last_row = row
        end
        return last_row
    when SQL_FETCH_RELATIVE
        raise NotSupportedError if offset <= 0
        row = nil
        offset.times { row = fetch; break if row.nil? }
        return row
    else
        raise NotSupportedError
    end
end

#finish ⇒ Object

Close the statement and any result cursors. DBD Required.

Note

Most implementations will fail miserably if you forget to finish your statement handles.

Raises:



45
46
47
 
# File 'lib/dbi/base_classes/statement.rb', line 45

def finish
    raise NotImplementedError
end