A statement represents a prepared-but-unexecuted SQL query. It will rarely (if ever) be instantiated directly by a client, and is most often obtained via the Database#prepare method.

Methods
Attributes
[R] handle The underlying opaque handle used to access the SQLite @driver.
[R] remainder This is any text that followed the first valid SQL statement in the text with which the statement was initialized. If there was no trailing text, this will be the empty string.
Public Class methods
new( db, sql, utf16=false )

Create a new statement attached to the given Database instance, and which encapsulates the given SQL text. If the text contains more than one statement (i.e., separated by semicolons), then the remainder property will be set to the trailing text.

    # File lib/sqlite3/statement.rb, line 65
65:     def initialize( db, sql, utf16=false )
66:       @db = db
67:       @driver = @db.driver
68:       @closed = false
69:       result, @handle, @remainder = @driver.prepare( @db.handle, sql )
70:       Error.check( result, @db )
71:     end
Public Instance methods
bind_param( param, value )

Binds value to the named (or positional) placeholder. If param is a Fixnum, it is treated as an index for a positional placeholder. Otherwise it is used as the name of the placeholder to bind to.

See also bind_params.

     # File lib/sqlite3/statement.rb, line 116
116:     def bind_param( param, value )
117:       must_be_open!
118:       if Fixnum === param
119:         case value
120:           when Integer then
121:             @driver.bind_int( @handle, param, value )
122:           when Numeric then
123:             @driver.bind_double( @handle, param, value.to_f )
124:           when Blob then
125:             @driver.bind_blob( @handle, param, value )
126:           when nil then
127:             @driver.bind_null( @handle, param )
128:           else
129:             @driver.bind_text( @handle, param, value )
130:         end
131:       else
132:         index = @driver.bind_parameter_index(
133:           @handle, param.to_s )
134:         raise Exception, "no such bind parameter '#{param}'" if index == 0
135:         bind_param index, value
136:       end
137:     end
bind_params( *bind_vars )

Binds the given variables to the corresponding placeholders in the SQL text.

See Database#execute for a description of the valid placeholder syntaxes.

Example:

  stmt = db.prepare( "select * from table where a=? and b=?" )
  stmt.bind_params( 15, "hello" )

See also execute, bind_param, Statement#bind_param, and Statement#bind_params.

     # File lib/sqlite3/statement.rb, line 99
 99:     def bind_params( *bind_vars )
100:       index = 1
101:       bind_vars.flatten.each do |var|
102:         if Hash === var
103:           var.each { |key, val| bind_param key, val }
104:         else
105:           bind_param index, var
106:           index += 1
107:         end
108:       end
109:     end
close()

Closes the statement by finalizing the underlying statement handle. The statement must not be used after being closed.

    # File lib/sqlite3/statement.rb, line 75
75:     def close
76:       must_be_open!
77:       @closed = true
78:       @driver.finalize( @handle )
79:     end
closed?()

Returns true if the underlying statement has been closed.

    # File lib/sqlite3/statement.rb, line 82
82:     def closed?
83:       @closed
84:     end
columns()

Return an array of the column names for this statement. Note that this may execute the statement in order to obtain the metadata; this makes it a (potentially) expensive operation.

     # File lib/sqlite3/statement.rb, line 197
197:     def columns
198:       get_metadata unless @columns
199:       return @columns
200:     end
execute( *bind_vars ) {|@results| ...}

Execute the statement. This creates a new ResultSet object for the statement’s virtual machine. If a block was given, the new ResultSet will be yielded to it; otherwise, the ResultSet will be returned.

Any parameters will be bound to the statement using bind_params.

Example:

  stmt = db.prepare( "select * from table" )
  stmt.execute do |result|
    ...
  end

See also bind_params, execute!.

     # File lib/sqlite3/statement.rb, line 153
153:     def execute( *bind_vars )
154:       must_be_open!
155:       @driver.reset( @handle ) if @results
156: 
157:       bind_params *bind_vars unless bind_vars.empty?
158:       @results = ResultSet.new( @db, self )
159: 
160:       if block_given?
161:         yield @results
162:       else
163:         return @results
164:       end
165:     end
execute!( *bind_vars ) {|row| ...}

Execute the statement. If no block was given, this returns an array of rows returned by executing the statement. Otherwise, each row will be yielded to the block.

Any parameters will be bound to the statement using bind_params.

Example:

  stmt = db.prepare( "select * from table" )
  stmt.execute! do |row|
    ...
  end

See also bind_params, execute.

     # File lib/sqlite3/statement.rb, line 181
181:     def execute!( *bind_vars )
182:       result = execute( *bind_vars )
183:       rows = [] unless block_given?
184:       while row = result.next
185:         if block_given?
186:           yield row
187:         else
188:           rows << row
189:         end
190:       end
191:       rows
192:     end
types()

Return an array of the data types for each column in this statement. Note that this may execute the statement in order to obtain the metadata; this makes it a (potentially) expensive operation.

     # File lib/sqlite3/statement.rb, line 205
205:     def types
206:       get_metadata unless @types
207:       return @types
208:     end

[Validate]