Summary
Creates a callback function
Prototype
db:create_function(name,nargs,func)
Description
This function creates a callback function. Callback function are called by SQLite3 once for every row in a query. name is a string with the name of the callback function as given in an SQL statement; nargs is the number of arguments this call will provide. func is the actual Lua function that gets called once for every row; it should accept a function context (see below for callback contexts) plus the same number of parameters as given in nargs. Here is an example:
db:exec'CREATE TABLE test(col1,col2,col3)'
db:exec'INSERT INTO test VALUES(1,2,4)'
db:exec'INSERT INTO test VALUES(2,4,9)'
db:exec'INSERT INTO test VALUES(3,6,16)'
db:create_function('sum_cols',3,function(ctx,a,b,c)
ctx:result_number(a+b+c)
end))
for col1,col2,col3,sum in db:urows('SELECT *,sum_cols(col1,col2,col3) FROM test') do
print (string.format ('%2i+%2i+%2i=%2i\n',col1,col2,col3,sum))
end
CALLBACK CONTEXTS
A callback context is available as a parameter inside the callback functions db:create_aggregate() and db:create_function(). It can be used to get further information about the state of a query.
The various context functions are:
context:aggregate_count
context:get_aggregate_data
context:result
context:result_blob
context:result_error
context:result_int
context:result_null
context:result_number
context:result_text
context:set_aggregate_data
context:user_data
See Also ...
Lua functions
context:aggregate_count - Returns the number of calls to the aggregate step function.
context:get_aggregate_data - Returns the user-definable data field for callback functions.
context:result - This function sets the result of a callback function to res.
context:result_blob - This function sets the result of a callback function to the binary string in blob.
context:result_error - This function sets the result of a callback function to the error value in err.
context:result_int - This function sets the result of a callback function to the integer value in number
context:result_null - This function sets the result of a callback function to nil.
context:result_number - This function sets the result of a callback function to the value number.
context:result_text - This function sets the result of a callback function to the string in str.
context:set_aggregate_data - Set the user-definable data field for callback functions to udata.
context:user_data - Returns the userdata parameter given in the call to install the callback function.
db:busy_handler - Sets or removes a busy handler for a database
db:busy_timeout - Sets a busy handler
db:changes - Returns number of changes by the most recent SQL statement
db:close - Closes a database
db:close_vm - Finalizes all statements that have not been explicitly finalized
db:create_aggregate - Creates an aggregate callback function
db:create_collation - Creates a collation callback
db:errcode - Returns the most recent result code
db:errmsg - Returns the most recent error message
db:exec - Executes SQL statements
db:interrupt - Interrupts any pending operation
db:isopen - Tests if the database is open
db:last_insert_rowid - Returns the key of the most recent insert into the database
db:nrows - Creates an iterator that returns a table of rows from a SELECT - keyed by name
db:prepare - Compiles an SQL statement
db:progress_handler - Installs a progress callback function
db:rows - Creates an iterator that returns a table of rows from a SELECT - numerically keyed
db:total_changes - Returns total number of changes
db:trace - Installs debug trace callback
db:urows - Creates an iterator that returns the rows from a SELECT
sqlite3.complete - Checks for a complete SQL statement
sqlite3.open - Opens or creates a database
sqlite3.open_memory - Opens a database in memory
sqlite3.version - Returns the SQLite version
stmt:bind - Binds a value to a parameter
stmt:bind_blob - Binds a blob to a parameter
stmt:bind_names - Binds values in a table to parameters
stmt:bind_parameter_count - Returns the largest parameter index
stmt:bind_parameter_name - Returns the name of the n'th paremeter
stmt:bind_values - Binds values to parameters
stmt:columns - Returns number of columns in the result set
stmt:finalize - Frees a prepared statement
stmt:get_name - Returns the name of a column in a result set
stmt:get_named_types - Returns a table of names and types for the columns in a result set
stmt:get_named_values - Returns a table of names and values for the columns in a result set
stmt:get_names - Returns a table of the names of all columns in a result set
stmt:get_type - Returns the type of a column in a result set
stmt:get_types - Returns a table of the types of all columns in a result set
stmt:get_unames - Returns a list of names of the columns in a result set
stmt:get_utypes - Returns a list of types of the columns in a result set
stmt:get_uvalues - Returns a list of values of the columns in a result set
stmt:get_value - Returns the value of a column in a result set
stmt:get_values - Returns a table of the values of all columns in a result set
stmt:isopen - Checks if the statement is open
stmt:nrows - Creates an iterator that returns a table of rows from a SELECT - keyed by name
stmt:reset - Resets an SQL statement, so it can be executed again
stmt:rows - Creates an iterator that returns a table of rows from a SELECT - numerically keyed
stmt:step - Executes a previously-prepared SQL statement
stmt:urows - Creates an iterator that returns the rows from a SELECT
Topics
Database (SQLite)
Lua script extensions
Lua SQLite (database) interface
Lua syntax
Scripting
Scripting callbacks - plugins
(Help topic: lua=db:create_function)