Module | SQLite::API |
In: |
ext/sqlite-api.c
|
This is a one-to-one bridge between Ruby code and the C interface for SQLite. It defines (more-or-less) one method per function (with set_result being one exception). It is generally not advisable to use these methods directly; instead, you should use the SQLite::Database class and related interfaces, which provide a more object-oriented view of this interface.
VERSION | = | rb_str_new2( sqlite_libversion() ) |
ENCODING | = | rb_str_new2( sqlite_libencoding() ) |
NUMERIC | = | INT2FIX( SQLITE_NUMERIC ) |
TEXT | = | INT2FIX( SQLITE_TEXT ) |
ARGS | = | INT2FIX( SQLITE_ARGS ) |
Returns the aggregate context for the given function. This context is a Hash object that is allocated on demand and is available only to the current invocation of the function. It may be used by aggregate functions to accumulate data over multiple rows, prior to being finalized.
The func parameter must be an opaque function handle as given to the callbacks for create_aggregate.
See create_aggregate and aggregate_count.
Returns the number of rows that have been processed so far by the current aggregate function. This always includes the current row, so that number that is returned will always be at least 1.
The func parameter must be an opaque function handle as given to the callbacks for create_aggregate.
Installs a callback to be invoked whenever a request cannot be honored because a database is busy. The handler should take two parameters: a string naming the resource that was being accessed, and an integer indicating how many times the current request has failed due to the resource being busy.
If the handler returns false, the operation will be aborted, with a SQLite::BusyException being raised. Otherwise, SQLite will attempt to access the resource again.
See busy_timeout for an easier way to manage the common case.
Specifies the number of milliseconds that SQLite should wait before retrying to access a busy resource. Specifying zero milliseconds restores the default behavior.
Returns the number of changed rows affected by the last operation. (Note: doing a "delete from table" without a where clause does not affect the result of this method—see the documentation for SQLite itself for the reason behind this.)
Closes the given opaque database handle. The handle must be one that was returned by a call to open.
Compiles the given SQL statement and returns a new virtual machine handle for executing it. Returns a tuple: [ vm, remainder ], where remainder is any text that follows the first complete SQL statement in the sql parameter.
Returns true if the given SQL text is complete (parsable), and false otherwise.
Defines a new aggregate function that may be invoked from within an SQL statement. The args parameter specifies how many arguments the function expects—use -1 to specify variable arity.
The step parameter specifies a proc object that will be invoked for each row that the function processes. It should accept an opaque handle to the function object, followed by its expected arguments:
step = proc do |func, *args| ... end
The finalize parameter specifies a proc object that will be invoked after all rows have been processed. This gives the function an opportunity to aggregate and finalize the results. It should accept a single parameter: the opaque function handle:
finalize = proc do |func| ... end
The function object is used when calling the set_result, set_result_error, aggregate_context, and aggregate_count methods.
Defines a new function that may be invoked from within an SQL statement. The args parameter specifies how many arguments the function expects—use -1 to specify variable arity. The proc parameter must be a proc that expects args + 1 parameters, with the first parameter being an opaque handle to the function object itself:
proc do |func, *args| ... end
The function object is used when calling the set_result and set_result_error methods.
Destroys the given virtual machine and releases any associated memory. Once finalized, the VM should not be used.
Allows you to specify the type of the data that the named function returns. If type is SQLite::API::NUMERIC, then the function is expected to return a numeric value. If it is SQLite::API::TEXT, then the function is expected to return a textual value. If it is SQLite::API::ARGS, then the function returns whatever its arguments are. And if it is a positive (or zero) integer, then the function returns whatever type the argument at that position is.
Sets the result of the given function to the given value. This is typically called in the callback function for create_function or the finalize callback in create_aggregate. The result must be either a string, an integer, or a double.
The func parameter must be the opaque function handle as given to the callback functions mentioned above.
Sets the result of the given function to be the error message given in the string parameter. The func parameter must be an opaque function handle as given to the callback function for create_function or create_aggregate.
Steps through a single result for the given virtual machine. Returns a Hash object. If there was a valid row returned, the hash will contain a :row key, which maps to an array of values for that row. In addition, the hash will (nearly) always contain a :columns key (naming the columns in the result) and a :types key (giving the data types for each column).
This will return nil if there was an error previously.