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.

Direct Known Subclasses

DBD::MSSQL::Statement

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.



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

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

#[]=(attr, value) ⇒ Object

Set statement attributes. DBD Optional.

Raises:



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

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

#bind_param(param, value, attribs) ⇒ Object

Bind a parameter to the statement. DBD Required.

The parameter number is named in a hash. This corresponds to the parameter symbols (@param_name) in the statement

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:



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

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.



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

def bind_params(bindvars)
  bindvars.each {|k, v| bind_param(k, v, 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.



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

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:



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

def column_info
  raise NotImplementedError
end

#execute ⇒ Object

Execute the statement with the known binds. DBD Required.

Raises:



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

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:



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

def fetch
  raise NotImplementedError
end

#fetch_all ⇒ Object

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



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

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.



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

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.



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

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:



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

def finish
  raise NotImplementedError
end