mirror of
https://github.com/holub/mame
synced 2025-04-21 07:52:35 +03:00
b5475eb38b
Compile Lua as C++. When Lua is compiled as C, it uses setjmp/longjmp for error handling, resulting in failure to unwind intermediate stack frames. Trying to ensure no objects with non-trivial destructors are in scope when raising a Lua error is error-prone. In particular, converting an exception to a Lua error becomes convoluted, and raising a Lua error from a constructor is effectively impossible. Updated Lua to 5.4.4 - this includes a brand-new garbage collector implementation with better performance. The main thing removed is the deprecated bitlib. Updated sol2 to version 3.3.0 - this adds support for Lua 5.4 and fixes a number of issues, including not correctly handling errors when Lua is built as C++. Updated LuaFileSystem to version 1.8.0 - this adds support for symbolic links on Windows, as well as Lua 5.4 compatibility. Updated LuaSQLite3 to version 0.9.5 - this fixes issues in multi-threaded environments, as well as Lua 5.4 compatibility. Fixed double-free after attempting to construct a debugger expression from Lua with an invalid string, and exposed expression error to Lua in a better way. Added warning level print function to Lua. Fixed saving cheats with shift operators in expressions, although this code isn't actually used as there's no cheat editor.
1202 lines
53 KiB
Plaintext
1202 lines
53 KiB
Plaintext
<nowiki>
|
|
<div name="index">
|
|
<p><a name="__index__"></a></p>
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#overview">OVERVIEW</a></li>
|
|
<li><a href="#download">DOWNLOAD</a></li>
|
|
<li><a href="#installation">INSTALLATION</a></li>
|
|
<li><a href="#examples">EXAMPLES</a></li>
|
|
<li><a href="#verification_tests">VERIFICATION TESTS</a></li>
|
|
<li><a href="#reference">REFERENCE</a></li>
|
|
<li><a href="#sqlite3_functions">SQLite3 functions</a></li>
|
|
<ul>
|
|
|
|
<li><a href="#sqlite3_complete">sqlite3.complete</a></li>
|
|
<li><a href="#sqlite3_lversion">sqlite3.lversion</a></li>
|
|
<li><a href="#sqlite3_open">sqlite3.open</a></li>
|
|
<li><a href="#sqlite3_open_memory">sqlite3.open_memory</a></li>
|
|
<li><a href="#sqlite3_open_ptr">sqlite3.open_ptr</a></li>
|
|
<li><a href="#sqlite3_backup_init">sqlite3.backup_init</a></li>
|
|
<li><a href="#sqlite3_temp_directory">sqlite3.temp_directory</a></li>
|
|
<li><a href="#sqlite3_version">sqlite3.version</a></li>
|
|
</ul>
|
|
|
|
<li><a href="#database_methods">Database methods</a></li>
|
|
<ul>
|
|
|
|
<li><a href="#db_busy_handler">db:busy_handler</a></li>
|
|
<li><a href="#db_busy_timeout">db:busy_timeout</a></li>
|
|
<li><a href="#db_changes">db:changes</a></li>
|
|
<li><a href="#db_close">db:close</a></li>
|
|
<li><a href="#db_close_vm">db:close_vm</a></li>
|
|
<li><a href="#db_get_ptr">db:get_ptr</a></li>
|
|
<li><a href="#db_commit_hook">db:commit_hook</a></li>
|
|
<li><a href="#db_create_aggregate">db:create_aggregate</a></li>
|
|
<li><a href="#db_create_collation">db:create_collation</a></li>
|
|
<li><a href="#db_create_function">db:create_function</a></li>
|
|
<li><a href="#db_errcode">db:errcode</a></li>
|
|
<li><a href="#db_errmsg">db:errmsg</a></li>
|
|
<li><a href="#db_exec">db:exec</a></li>
|
|
<li><a href="#db_interrupt">db:interrupt</a></li>
|
|
<li><a href="#db_db_filename">db:db_filename</a></li>
|
|
<li><a href="#db_isopen">db:isopen</a></li>
|
|
<li><a href="#db_last_insert_rowid">db:last_insert_rowid</a></li>
|
|
<li><a href="#db_load_extension">db:load_extension</a></li>
|
|
<li><a href="#db_nrows">db:nrows</a></li>
|
|
<li><a href="#db_prepare">db:prepare</a></li>
|
|
<li><a href="#db_progress_handler">db:progress_handler</a></li>
|
|
<li><a href="#db_rollback_hook">db:rollback_hook</a></li>
|
|
<li><a href="#db_rows">db:rows</a></li>
|
|
<li><a href="#db_total_changes">db:total_changes</a></li>
|
|
<li><a href="#db_trace">db:trace</a></li>
|
|
<li><a href="#db_update_hook">db:update_hook</a></li>
|
|
<li><a href="#db_urows">db:urows</a></li>
|
|
</ul>
|
|
|
|
<li><a href="#methods_for_prepared_statements">Methods for prepared statements</a></li>
|
|
<ul>
|
|
|
|
<li><a href="#stmt_bind">stmt:bind</a></li>
|
|
<li><a href="#stmt_bind_blob">stmt:bind_blob</a></li>
|
|
<li><a href="#stmt_bind_names">stmt:bind_names</a></li>
|
|
<li><a href="#stmt_bind_parameter_count">stmt:bind_parameter_count</a></li>
|
|
<li><a href="#stmt_bind_parameter_name">stmt:bind_parameter_name</a></li>
|
|
<li><a href="#stmt_bind_values">stmt:bind_values</a></li>
|
|
<li><a href="#stmt_columns">stmt:columns</a></li>
|
|
<li><a href="#stmt_finalize">stmt:finalize</a></li>
|
|
<li><a href="#stmt_get_name">stmt:get_name</a></li>
|
|
<li><a href="#stmt_get_named_types">stmt:get_named_types</a></li>
|
|
<li><a href="#stmt_get_named_values">stmt:get_named_values</a></li>
|
|
<li><a href="#stmt_get_names">stmt:get_names</a></li>
|
|
<li><a href="#stmt_get_type">stmt:get_type</a></li>
|
|
<li><a href="#stmt_get_types">stmt:get_types</a></li>
|
|
<li><a href="#stmt_get_unames">stmt:get_unames</a></li>
|
|
<li><a href="#stmt_get_utypes">stmt:get_utypes</a></li>
|
|
<li><a href="#stmt_get_uvalues">stmt:get_uvalues</a></li>
|
|
<li><a href="#stmt_get_value">stmt:get_value</a></li>
|
|
<li><a href="#stmt_get_values">stmt:get_values</a></li>
|
|
<li><a href="#stmt_isopen">stmt:isopen</a></li>
|
|
<li><a href="#stmt_last_insert_rowid">stmt:last_insert_rowid</a></li>
|
|
<li><a href="#stmt_nrows">stmt:nrows</a></li>
|
|
<li><a href="#stmt_reset">stmt:reset</a></li>
|
|
<li><a href="#stmt_rows">stmt:rows</a></li>
|
|
<li><a href="#stmt_step">stmt:step</a></li>
|
|
<li><a href="#stmt_urows">stmt:urows</a></li>
|
|
</ul>
|
|
|
|
<li><a href="#methods_for_callback_contexts">Methods for callback contexts</a></li>
|
|
<ul>
|
|
|
|
<li><a href="#context_aggregate_count">context:aggregate_count</a></li>
|
|
<li><a href="#context_get_aggregate_data">context:get_aggregate_data</a></li>
|
|
<li><a href="#context_set_aggregate_data">context:set_aggregate_data</a></li>
|
|
<li><a href="#context_result">context:result</a></li>
|
|
<li><a href="#context_result_null">context:result_null</a></li>
|
|
<li><a href="#context_result_number">context:result_number</a></li>
|
|
<li><a href="#context_result_int">context:result_int</a></li>
|
|
<li><a href="#context_result_text">context:result_text</a></li>
|
|
<li><a href="#context_result_blob">context:result_blob</a></li>
|
|
<li><a href="#context_result_error">context:result_error</a></li>
|
|
<li><a href="#context_user_data">context:user_data</a></li>
|
|
</ul>
|
|
|
|
<li><a href="#methods_for_online_backup">Methods for Online Backup</a></li>
|
|
<ul>
|
|
|
|
<li><a href="#bu_step">backup:step</a></li>
|
|
<li><a href="#bu_remaining">backup:remaining</a></li>
|
|
<li><a href="#bu_pagecount">backup:pagecount</a></li>
|
|
<li><a href="#bu_finish">backup:finish</a></li>
|
|
</ul>
|
|
|
|
<li><a href="#numerical_error_and_result_codes">Numerical error and result codes</a></li>
|
|
<li><a href="#version">VERSION</a></li>
|
|
<li><a href="#credits">CREDITS</a></li>
|
|
<li><a href="#license">LICENSE</a></li>
|
|
</ul>
|
|
|
|
<hr name="index" />
|
|
</div>
|
|
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p><strong>LuaSQLite 3</strong> - a Lua 5.1 to 5.3 wrapper for the SQLite3 library</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="overview">OVERVIEW</a></h1>
|
|
<p><strong>LuaSQLite 3</strong> is a thin wrapper around the public domain SQLite3
|
|
database engine.</p>
|
|
<p>There are two modules, identical except that one links SQLite3 dynamically, the other
|
|
statically.</p>
|
|
<p>The module <code>lsqlite3</code> links SQLite3 dynamically.
|
|
To use this module you need the SQLite3 library (DLL or .so).
|
|
You can get it from <a href="http://www.sqlite.org/">http://www.sqlite.org/</a>
|
|
</p>
|
|
<p>The module <code>lsqlite3complete</code> links SQLite3 statically.
|
|
The SQLite3 amalgamation source code is included in
|
|
the LuaSQLite 3 distribution.</p>
|
|
<p>Both modules support the creation and manipulation of
|
|
SQLite3 databases. After a <code>sqlite3 = require('lsqlite3')</code>
|
|
(or <code>sqlite3 = require('lsqlite3complete')</code>) the exported
|
|
functions are called with prefix <code>sqlite3</code>. However, most sqlite3
|
|
functions are called via an object-oriented interface to either
|
|
database or SQL statement objects; see below for details.</p>
|
|
<p>This documentation does not attempt to describe how SQLite3 itself
|
|
works, it just describes the Lua binding and the available functions.
|
|
For more information about the SQL features supported by SQLite3 and
|
|
details about the syntax of SQL statements and queries, please see the
|
|
<strong>SQLite3 documentation</strong>
|
|
<a href="http://www.sqlite.org/">http://www.sqlite.org/</a>.
|
|
Using some of the
|
|
advanced features (how to use callbacks, for instance) will require
|
|
some familiarity with the SQLite3 API.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="download">DOWNLOAD</a></h1>
|
|
<p><strong>LuaSQLite 3</strong> source code can be downloaded from its
|
|
Fossil (<a href="http://lua.sqlite.org/">http://lua.sqlite.org/</a>) page.</p>
|
|
<p>For <code>lsqlite3</code> (but not for <code>lsqlite3complete</code>) you will also need to
|
|
build or obtain an SQLite3 loadable library (DLL or .so).
|
|
See <a href="http://www.sqlite.org/">http://www.sqlite.org/</a> for obtaining SQLite3
|
|
source code or downloading a binary SQLite3 library.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="installation">INSTALLATION</a></h1>
|
|
<p>Luarocks (<a href="http://luarocks.org/">http://luarocks.org/</a>) is the preferred mechanism
|
|
to build and install <code>lsqlite3</code> or <code>lsqlite3complete</code>; for
|
|
<code>lsqlite3</code> it assumes an SQLite3 library is already installed. For
|
|
<code>lsqlite3complete</code> no SQLite3 library is needed.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="examples">EXAMPLES</a></h1>
|
|
<p>The distribution contains an <em>examples</em> directory. The unit tests
|
|
also show some example use.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="verification_tests">VERIFICATION TESTS</a></h1>
|
|
<p>The distribution contains a <em>tests</em> directory with some units tests using
|
|
an enhanced version of Michael Roth's <code>lunit</code> called <code>lunitx</code>. Some of the
|
|
tests were also derived from Michael's <strong>lua-sqlite3</strong> module, and more unit tests
|
|
added by Doug Currie. Get <code>lunitx</code> using Luarocks.</p>
|
|
<p>The distribution also contains some functional tests by Tiago.</p>
|
|
<p>This version of <code>lsqlite3</code> was tested with SQLite 3.11.0 and 3.15.1.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="reference">REFERENCE</a></h1>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="sqlite3_functions">SQLite3 functions</a></h1>
|
|
<p>
|
|
</p>
|
|
<h2><a name="sqlite3_complete">sqlite3.complete</a></h2>
|
|
<pre>
|
|
sqlite3.complete(sql)</pre>
|
|
<p>Returns true if the string <code>sql</code> comprises one or more complete SQL
|
|
statements and false otherwise.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="sqlite3_open">sqlite3.open</a></h2>
|
|
<pre>
|
|
sqlite3.open(filename)</pre>
|
|
<p>Opens (or creates if it does not exist) an SQLite database with name
|
|
<code>filename</code> and returns its handle as userdata (the returned object
|
|
should be used for all further method calls in connection with this
|
|
specific database, see <a href="#database_methods">Database methods</a>). Example:</p>
|
|
<pre>
|
|
myDB=sqlite3.open('MyDatabase.sqlite3') -- open
|
|
-- do some database calls...
|
|
myDB:close() -- close</pre>
|
|
<p>In case of an error, the function returns nil, an error code and an
|
|
error message.</p>
|
|
<p>Since 0.9.4, there is a second optional flags argument to <code>sqlite3.open</code>.
|
|
<pre>
|
|
sqlite3.open(filename, flags)</pre></p>
|
|
<p>
|
|
See <a href="https://www.sqlite.org/c3ref/open.html">sqlite3_open_v2</a> for an explanation of
|
|
these flags and options.</p>
|
|
<p>
|
|
Example:
|
|
<pre>
|
|
local db = sqlite3.open('foo.db', sqlite3.OPEN_READWRITE + sqlite3.OPEN_CREATE + sqlite3.OPEN_SHAREDCACHE)
|
|
</pre>
|
|
The default value for flags is <code>sqlite3.OPEN_READWRITE + sqlite3.OPEN_CREATE</code>.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="sqlite3_open_memory">sqlite3.open_memory</a></h2>
|
|
<pre>
|
|
sqlite3.open_memory()</pre>
|
|
<p>Opens an SQLite database <strong>in memory</strong> and returns its handle as
|
|
userdata. In case of an error, the function returns nil, an error code
|
|
and an error message. (In-memory databases are volatile as they are
|
|
never stored on disk.)</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="sqlite3_open_ptr">sqlite3.open_ptr</a></h2>
|
|
<pre>
|
|
sqlite3.open_ptr(db_ptr)</pre>
|
|
<p>Opens the SQLite database corresponding to the light userdata <code>db_ptr</code> and returns
|
|
its handle as userdata. Use <a href="#db_get_ptr"><code>db:get_ptr</code></a> to get
|
|
a <code>db_ptr</code> for an open database.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="sqlite3_backup_init">sqlite3.backup_init</a></h2>
|
|
<pre>
|
|
sqlite3.backup_init(target_db, target_name, source_db, source_name)</pre>
|
|
<p>Starts an SQLite Online Backup from <code>source_db</code> to <code>target_db</code> and
|
|
returns its handle as userdata. The <code>source_db</code> and <code>target_db</code> are
|
|
open databases; they may be in-memory or file-based databases. The <code>target_name</code> and
|
|
<code>source_name</code> are "main" for the main database, "temp" for the temporary database, or
|
|
the name specified after the AS keyword in an ATTACH statement for an attached database.</p>
|
|
<p>The source and target databases must be different, or else the init call will fail with an
|
|
error. A call to <code>sqlite3.backup_init</code> will fail, returning NULL, if there is already
|
|
a read or read-write transaction open on the target database.
|
|
</p>
|
|
<p>If an error occurs within <code>sqlite3.backup_init</code>, then NULL is returned, and an
|
|
error code and error message are stored in <code>target_db</code>. The error code and message
|
|
for the failed call can be retrieved using the <a href="#db_errcode"><code>db:errcode</code></a>,
|
|
or <a href="#db_errmsg"><code>db:errmsg</code></a>.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="sqlite3_temp_directory">sqlite3.temp_directory</a></h2>
|
|
<pre>
|
|
sqlite3.temp_directory([temp])</pre>
|
|
<p>Sets or queries the directory used by SQLite for temporary files. If
|
|
string <code>temp</code> is a directory name or nil, the temporary directory is
|
|
set accordingly and the old value is returned. If <code>temp</code> is missing,
|
|
the function simply returns the current temporary directory.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="sqlite3_version">sqlite3.version</a></h2>
|
|
<pre>
|
|
sqlite3.version()</pre>
|
|
<p>Returns a string with SQLite version information, in the form 'x.y[.z[.p]]'.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="sqlite3_lversion">sqlite3.lversion</a></h2>
|
|
<pre>
|
|
sqlite3.lversion()</pre>
|
|
<p>Returns a string with lsqlite3 library version information, in the form 'x.y[.z]'.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="database_methods">Database methods</a></h1>
|
|
<p>After opening a database with <a href="#sqlite3_open"><code>sqlite3.open()</code></a> or
|
|
<a href="#sqlite3_open_memory"><code>sqlite3.open_memory()</code></a>
|
|
the returned database object should be used for all further method calls
|
|
in connection with that database. An open database object supports the
|
|
following methods.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_busy_handler">db:busy_handler</a></h2>
|
|
<pre>
|
|
db:busy_handler([func[,udata]])</pre>
|
|
<p>Sets or removes a busy handler for a database. <code>func</code> is either a Lua
|
|
function that implements the busy handler or nil to remove a previously
|
|
set handler. This function returns nothing.</p>
|
|
<p>The handler function is called with two parameters: <code>udata</code> and the
|
|
number of (re-)tries for a pending transaction. It should return nil,
|
|
false or 0 if the transaction is to be aborted. All other values will
|
|
result in another attempt to perform the transaction. (See the SQLite
|
|
documentation for important hints about writing busy handlers.)</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_busy_timeout">db:busy_timeout</a></h2>
|
|
<pre>
|
|
db:busy_timeout(t)</pre>
|
|
<p>Sets a busy handler that waits for <code>t</code> milliseconds if a transaction
|
|
cannot proceed. Calling this function will remove any busy handler set
|
|
by <a href="#db_busy_handler"><code>db:busy_handler()</code></a>; calling it with an argument
|
|
less than or equal to 0 will turn off all busy handlers.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_changes">db:changes</a></h2>
|
|
<pre>
|
|
db:changes()</pre>
|
|
<p>This function returns the number of database rows that were changed (or
|
|
inserted or deleted) by the most recent SQL statement. Only changes that
|
|
are directly specified by INSERT, UPDATE, or DELETE statements are
|
|
counted. Auxiliary changes caused by triggers are not counted. Use
|
|
<a href="#db_total_changes"><code>db:total_changes()</code></a> to find the total number of
|
|
changes.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_close">db:close</a></h2>
|
|
<pre>
|
|
db:close()</pre>
|
|
<p>Closes a database. All SQL statements prepared using
|
|
<a href="#db_prepare"><code>db:prepare()</code></a> should
|
|
have been finalized before this function is called. The function returns
|
|
<code>sqlite3.OK</code> on success or else a numerical error code (see the list of
|
|
<a href="#numerical_error_and_result_codes">Numerical error and result codes</a>).</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_close_vm">db:close_vm</a></h2>
|
|
<pre>
|
|
db:close_vm(temponly)</pre>
|
|
<p>Finalizes all statements that have not been explicitly finalized. If
|
|
<code>temponly</code> is true, only internal, temporary statements are finalized.
|
|
This function returns nothing.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_get_ptr">db:get_ptr</a></h2>
|
|
<pre>
|
|
db:get_ptr()</pre>
|
|
<p>Returns a lightuserdata corresponding to the open <code>db</code>. Use with
|
|
<a href="#sqlite3_open_ptr"><code>sqlite3.open_ptr</code></a> to pass a database connection
|
|
between threads. (When using lsqlite3 in a multithreaded environment, each thread has a separate
|
|
Lua environment; full userdata structures can't be passed from one thread to another, but this
|
|
is possible with lightuserdata.)</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_commit_hook">db:commit_hook</a></h2>
|
|
<pre>
|
|
db:commit_hook(func,udata)</pre>
|
|
<p>This function installs a commit_hook callback handler. <code>func</code> is a Lua function
|
|
that is invoked by SQLite3 whenever a transaction is commited. This callback receives one argument:
|
|
the <code>udata</code> argument used when the callback was installed. If <code>func</code> returns <code>false</code>
|
|
or <code>nil</code> the COMMIT is allowed to prodeed, otherwise the COMMIT is converted to a ROLLBACK.</p>
|
|
<p>See: <a href="#db_rollback_hook">db:rollback_hook</a> and <a href="#db_update_hook">db:update_hook</a></p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_create_aggregate">db:create_aggregate</a></h2>
|
|
<pre>
|
|
db:create_aggregate(name,nargs,step,final)</pre>
|
|
<p>This function creates an aggregate callback function. Aggregates perform
|
|
an operation over all rows in a query. <code>name</code> is a string with the name
|
|
of the aggregate function as given in an SQL statement; <code>nargs</code> is the
|
|
number of arguments this call will provide. <code>step</code> is the actual Lua
|
|
function that gets called once for every row; it should accept a function
|
|
context (see <a href="#methods_for_callback_contexts">Methods for callback contexts</a>) plus the same number of
|
|
parameters as given in <code>nargs</code>. <code>final</code> is a function that is called
|
|
once after all rows have been processed; it receives one argument, the
|
|
function context.</p>
|
|
<p>The function context can be used inside the two callback functions to
|
|
communicate with SQLite3. Here is a simple example:</p>
|
|
<pre>
|
|
db:exec[=[
|
|
CREATE TABLE numbers(num1,num2);
|
|
INSERT INTO numbers VALUES(1,11);
|
|
INSERT INTO numbers VALUES(2,22);
|
|
INSERT INTO numbers VALUES(3,33);
|
|
]=]
|
|
local num_sum=0
|
|
local function oneRow(context,num) -- add one column in all rows
|
|
num_sum=num_sum+num
|
|
end
|
|
local function afterLast(context) -- return sum after last row has been processed
|
|
context:result_number(num_sum)
|
|
num_sum=0
|
|
end
|
|
db:create_aggregate("do_the_sums",1,oneRow,afterLast)
|
|
for sum in db:urows('SELECT do_the_sums(num1) FROM numbers') do print("Sum of col 1:",sum) end
|
|
for sum in db:urows('SELECT do_the_sums(num2) FROM numbers') do print("Sum of col 2:",sum) end</pre>
|
|
<p>This prints:</p>
|
|
<pre>
|
|
Sum of col 1: 6
|
|
Sum of col 2: 66</pre>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_create_collation">db:create_collation</a></h2>
|
|
<pre>
|
|
db:create_collation(name,func)</pre>
|
|
<p>This creates a collation callback. A collation callback is used to
|
|
establish a collation order, mostly for string comparisons and sorting
|
|
purposes. <code>name</code> is a string with the name of the collation to be created;
|
|
<code>func</code> is a function that accepts two string arguments, compares them
|
|
and returns 0 if both strings are identical, -1 if the first argument is
|
|
lower in the collation order than the second and 1 if the first argument
|
|
is higher in the collation order than the second. A simple example:</p>
|
|
<pre>
|
|
local function collate(s1,s2)
|
|
s1=s1:lower()
|
|
s2=s2:lower()
|
|
if s1==s2 then return 0
|
|
elseif s1<s2 then return -1
|
|
else return 1 end
|
|
end
|
|
db:exec[=[
|
|
CREATE TABLE test(id INTEGER PRIMARY KEY,content COLLATE CINSENS);
|
|
INSERT INTO test VALUES(NULL,'hello world');
|
|
INSERT INTO test VALUES(NULL,'Buenos dias');
|
|
INSERT INTO test VALUES(NULL,'HELLO WORLD');
|
|
]=]
|
|
db:create_collation('CINSENS',collate)
|
|
for row in db:nrows('SELECT * FROM test') do print(row.id,row.content) end</pre>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_create_function">db:create_function</a></h2>
|
|
<pre>
|
|
db:create_function(name,nargs,func)</pre>
|
|
<p>This function creates a callback function. Callback function are called
|
|
by SQLite3 once for every row in a query. <code>name</code> is a string with the
|
|
name of the callback function as given in an SQL statement; <code>nargs</code> is
|
|
the number of arguments this call will provide. <code>func</code> is the actual Lua
|
|
function that gets called once for every row; it should accept a
|
|
function context (see <a href="#methods_for_callback_contexts">Methods for callback contexts</a>) plus the same
|
|
number of parameters as given in nargs. Here is an example:</p>
|
|
<pre>
|
|
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
|
|
util.printf('%2i+%2i+%2i=%2i\n',col1,col2,col3,sum)
|
|
end</pre>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_load_extension">db:load_extension</a></h2>
|
|
<pre>
|
|
db:load_extension([name,[entrypoint]])</pre>
|
|
|
|
<p>When a <code>name</code> is provided, loads an SQLite extension library from the
|
|
named file into this database connection. The optional <code>entrypoint</code> is the
|
|
library initialization function name; if not supplied, SQLite tries various default
|
|
entrypoint names. Returns <code>true</code> when successful, or <code>false</code> and
|
|
an error string otherwise.
|
|
</p>
|
|
<p>When called with no arguments, disables the load_extension() SQL function, which is
|
|
enabled as a side effect of calling <code>db:load_extension</code> with a
|
|
<code>name</code>.
|
|
</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_errcode">db:errcode</a></h2>
|
|
<pre>
|
|
db:errcode()
|
|
db:error_code()</pre>
|
|
<p>Returns the numerical result code (or extended result code) for the most
|
|
recent failed call associated with database db. See
|
|
<a href="#numerical_error_and_result_codes">Numerical error and result codes</a> for details.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_errmsg">db:errmsg</a></h2>
|
|
<pre>
|
|
db:errmsg()
|
|
db:error_message()</pre>
|
|
<p>Returns a string that contains an error message for the most recent
|
|
failed call associated with database db.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_exec">db:exec</a></h2>
|
|
<pre>
|
|
db:exec(sql[,func[,udata]])
|
|
db:execute(sql[,func[,udata]])</pre>
|
|
<p>Compiles and executes the SQL statement(s) given in string <code>sql</code>. The
|
|
statements are simply executed one after the other and not stored. The
|
|
function returns <code>sqlite3.OK</code> on success or else a numerical error code
|
|
(see <a href="#numerical_error_and_result_codes">Numerical error and result codes</a>).</p>
|
|
<p>If one or more of the SQL statements are queries, then the callback
|
|
function specified in <code>func</code> is invoked once for each row of the query
|
|
result (if <code>func</code> is nil, no callback is invoked). The callback receives
|
|
four arguments: <code>udata</code> (the third parameter of the <code>db:exec()</code> call),
|
|
the number of columns in the row, a table with the column values and
|
|
another table with the column names. The callback function should return
|
|
0. If the callback returns a non-zero value then the query is aborted,
|
|
all subsequent SQL statements are skipped and <code>db:exec()</code> returns
|
|
<code>sqlite3.ABORT</code>. Here is a simple example:</p>
|
|
<pre>
|
|
sql=[=[
|
|
CREATE TABLE numbers(num1,num2,str);
|
|
INSERT INTO numbers VALUES(1,11,"ABC");
|
|
INSERT INTO numbers VALUES(2,22,"DEF");
|
|
INSERT INTO numbers VALUES(3,33,"UVW");
|
|
INSERT INTO numbers VALUES(4,44,"XYZ");
|
|
SELECT * FROM numbers;
|
|
]=]
|
|
function showrow(udata,cols,values,names)
|
|
assert(udata=='test_udata')
|
|
print('exec:')
|
|
for i=1,cols do print('',names[i],values[i]) end
|
|
return 0
|
|
end
|
|
db:exec(sql,showrow,'test_udata')</pre>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_interrupt">db:interrupt</a></h2>
|
|
<pre>
|
|
db:interrupt()</pre>
|
|
<p>This function causes any pending database operation to abort and return
|
|
at the next opportunity. This function returns nothing.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_db_filename">db:db_filename</a></h2>
|
|
<pre>
|
|
db:db_filename(name)</pre>
|
|
<p>This function returns the filename associated with database <code>name</code> of connection
|
|
<code>db</code>. The <code>name</code> may be "main" for the main database file, or
|
|
the name specified after the AS keyword in an ATTACH statement for an attached database.
|
|
If there is no attached database <code>name</code> on the database connection <code>db</code>,
|
|
then no value is returned; if database <code>name</code> is a temporary or in-memory database,
|
|
then an empty string is returned.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_isopen">db:isopen</a></h2>
|
|
<pre>
|
|
db:isopen()</pre>
|
|
<p>Returns true if database db is open, false otherwise.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_last_insert_rowid">db:last_insert_rowid</a></h2>
|
|
<pre>
|
|
db:last_insert_rowid()</pre>
|
|
<p>This function returns the rowid of the most recent INSERT into the
|
|
database. If no inserts have ever occurred, 0 is returned. (Each row in
|
|
an SQLite table has a unique 64-bit signed integer key called the
|
|
'rowid'. This id is always available as an undeclared column named
|
|
ROWID, OID, or _ROWID_. If the table has a column of type INTEGER
|
|
PRIMARY KEY then that column is another alias for the rowid.)</p>
|
|
<p>If an INSERT occurs within a trigger, then the rowid of the inserted row
|
|
is returned as long as the trigger is running. Once the trigger
|
|
terminates, the value returned reverts to the last value inserted before
|
|
the trigger fired.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_nrows">db:nrows</a></h2>
|
|
<pre>
|
|
db:nrows(sql)</pre>
|
|
<p>Creates an iterator that returns the successive rows selected by the SQL
|
|
statement given in string <code>sql</code>. Each call to the iterator returns a
|
|
table in which the named fields correspond to the columns in the database.
|
|
Here is an example:</p>
|
|
<pre>
|
|
db:exec[=[
|
|
CREATE TABLE numbers(num1,num2);
|
|
INSERT INTO numbers VALUES(1,11);
|
|
INSERT INTO numbers VALUES(2,22);
|
|
INSERT INTO numbers VALUES(3,33);
|
|
]=]
|
|
for a in db:nrows('SELECT * FROM numbers') do table.print(a) end</pre>
|
|
<p>This script prints:</p>
|
|
<pre>
|
|
num2: 11
|
|
num1: 1
|
|
num2: 22
|
|
num1: 2
|
|
num2: 33
|
|
num1: 3</pre>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_prepare">db:prepare</a></h2>
|
|
<pre>
|
|
db:prepare(sql)</pre>
|
|
<p>This function compiles the SQL statement in string <code>sql</code> into an internal
|
|
representation and returns this as userdata. The returned object should
|
|
be used for all further method calls in connection with this specific
|
|
SQL statement (see <a href="#methods_for_prepared_statements">Methods for prepared statements</a>).</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_progress_handler">db:progress_handler</a></h2>
|
|
<pre>
|
|
db:progress_handler(n,func,udata)</pre>
|
|
<p>This function installs a callback function <code>func</code> that is invoked
|
|
periodically during long-running calls to <a href="#db_exec"><code>db:exec()</code></a>
|
|
or <a href="#stmt_step"><code>stmt:step()</code></a>. The
|
|
progress callback is invoked once for every <code>n</code> internal operations,
|
|
where <code>n</code> is the first argument to this function. <code>udata</code> is passed to
|
|
the progress callback function each time it is invoked. If a call to
|
|
<code>db:exec()</code> or <code>stmt:step()</code> results in fewer than <code>n</code> operations
|
|
being executed, then the progress callback is never invoked. Only a
|
|
single progress callback function may be registered for each opened
|
|
database and a call to this function will overwrite any previously set
|
|
callback function. To remove the progress callback altogether, pass nil
|
|
as the second argument.</p>
|
|
<p>If the progress callback returns a result other than 0, then the current
|
|
query is immediately terminated, any database changes are rolled back
|
|
and the containing <code>db:exec()</code> or <code>stmt:step()</code> call returns
|
|
<code>sqlite3.INTERRUPT</code>. This feature can be used to cancel long-running
|
|
queries.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_rollback_hook">db:rollback_hook</a></h2>
|
|
<pre>
|
|
db:rollback_hook(func,udata)</pre>
|
|
<p>This function installs a rollback_hook callback handler. <code>func</code> is a Lua function
|
|
that is invoked by SQLite3 whenever a transaction is rolled back. This callback receives one argument:
|
|
the <code>udata</code> argument used when the callback was installed.</p>
|
|
<p>See: <a href="#db_commit_hook">db:commit_hook</a> and <a href="#db_update_hook">db:update_hook</a></p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_rows">db:rows</a></h2>
|
|
<pre>
|
|
db:rows(sql)</pre>
|
|
<p>Creates an iterator that returns the successive rows selected by the SQL
|
|
statement given in string <code>sql</code>. Each call to the iterator returns a table
|
|
in which the numerical indices 1 to n correspond to the selected columns
|
|
1 to n in the database. Here is an example:</p>
|
|
<pre>
|
|
db:exec[=[
|
|
CREATE TABLE numbers(num1,num2);
|
|
INSERT INTO numbers VALUES(1,11);
|
|
INSERT INTO numbers VALUES(2,22);
|
|
INSERT INTO numbers VALUES(3,33);
|
|
]=]
|
|
for a in db:rows('SELECT * FROM numbers') do table.print(a) end</pre>
|
|
<p>This script prints:</p>
|
|
<pre>
|
|
1: 1
|
|
2: 11
|
|
1: 2
|
|
2: 22
|
|
1: 3
|
|
2: 33</pre>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_total_changes">db:total_changes</a></h2>
|
|
<pre>
|
|
db:total_changes()</pre>
|
|
<p>This function returns the number of database rows that have been
|
|
modified by INSERT, UPDATE or DELETE statements since the database was
|
|
opened. This includes UPDATE, INSERT and DELETE statements executed as
|
|
part of trigger programs. All changes are counted as soon as the
|
|
statement that produces them is completed by calling either
|
|
<a href="#stmt_reset"><code>stmt:reset()</code></a> or <a href="#stmt_finalize"><code>stmt:finalize()</code></a>.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_trace">db:trace</a></h2>
|
|
<pre>
|
|
db:trace(func,udata)</pre>
|
|
<p>This function installs a trace callback handler. <code>func</code> is a Lua
|
|
function that is called by SQLite3 just before the evaluation of an SQL
|
|
statement. This callback receives two arguments: the first is the
|
|
<code>udata</code> argument used when the callback was installed; the second is a
|
|
string with the SQL statement about to be executed.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_update_hook">db:update_hook</a></h2>
|
|
<pre>
|
|
db:update_hook(func,udata)</pre>
|
|
<p>This function installs an update_hook Data Change Notification Callback handler.
|
|
<code>func</code> is a Lua function that is invoked by SQLite3 whenever a row is updated,
|
|
inserted or deleted. This callback receives five arguments: the first is the
|
|
<code>udata</code> argument used when the callback was installed; the second is an
|
|
integer indicating the operation that caused the callback to be invoked (one of <code>sqlite3.UPDATE</code>,
|
|
<code>sqlite3.INSERT</code>, or <code>sqlite3.DELETE</code>). The third and fourth arguments
|
|
are the database and table name containing the affected row. The final callback parameter is
|
|
the rowid of the row. In the case of an update, this is the rowid after the update takes place.</p>
|
|
<p>See: <a href="#db_commit_hook">db:commit_hook</a> and <a href="#db_rollback_hook">db:rollback_hook</a></p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="db_urows">db:urows</a></h2>
|
|
<pre>
|
|
db:urows(sql)</pre>
|
|
<p>Creates an iterator that returns the successive rows selected by the SQL
|
|
statement given in string <code>sql</code>. Each call to the iterator returns the
|
|
values that correspond to the columns in the currently selected row.
|
|
Here is an example:</p>
|
|
<pre>
|
|
db:exec[=[
|
|
CREATE TABLE numbers(num1,num2);
|
|
INSERT INTO numbers VALUES(1,11);
|
|
INSERT INTO numbers VALUES(2,22);
|
|
INSERT INTO numbers VALUES(3,33);
|
|
]=]
|
|
for num1,num2 in db:urows('SELECT * FROM numbers') do print(num1,num2) end</pre>
|
|
<p>This script prints:</p>
|
|
<pre>
|
|
1 11
|
|
2 22
|
|
3 33</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="methods_for_prepared_statements">Methods for prepared statements</a></h1>
|
|
<p>After creating a prepared statement with <a href="#db_prepare"><code>db:prepare()</code></a>
|
|
the returned statement object should be used for all further calls in
|
|
connection with that statement. Statement objects support the following
|
|
methods.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stmt_bind">stmt:bind</a></h2>
|
|
<pre>
|
|
stmt:bind(n[,value])</pre>
|
|
<p>Binds value to statement parameter <code>n</code>. If the type of value is string
|
|
it is bound as text. If the type of value is number, then with Lua prior to 5.3
|
|
it is bound as a double, with Lua 5.3 it is bound as an integer or double
|
|
depending on its subtype using <code>lua_isinteger</code>. If <code>value</code> is a
|
|
boolean then it is bound as 0 for <code>false</code> or 1 for <code>true</code>.
|
|
If <code>value</code> is nil or missing, any previous binding is removed. The function
|
|
returns <code>sqlite3.OK</code> on success or else a numerical error code (see
|
|
<a href="#numerical_error_and_result_codes">Numerical error and result codes</a>).</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stmt_bind_blob">stmt:bind_blob</a></h2>
|
|
<pre>
|
|
stmt:bind_blob(n,blob)</pre>
|
|
<p>Binds string <code>blob</code> (which can be a binary string) as a blob to
|
|
statement parameter <code>n</code>. The function returns <code>sqlite3.OK</code> on success
|
|
or else a numerical error code (see <a href="#numerical_error_and_result_codes">Numerical error and result codes</a>).</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stmt_bind_names">stmt:bind_names</a></h2>
|
|
<pre>
|
|
stmt:bind_names(nametable)</pre>
|
|
<p>Binds the values in <code>nametable</code> to statement parameters. If the
|
|
statement parameters are named (i.e., of the form ":AAA" or "$AAA")
|
|
then this function looks for appropriately named fields in <code>nametable</code>;
|
|
if the statement parameters are
|
|
not named, it looks for numerical fields 1 to the number of statement
|
|
parameters. The function returns <code>sqlite3.OK</code> on success or else a
|
|
numerical error code (see <a href="#numerical_error_and_result_codes">Numerical error and result codes</a>).</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stmt_bind_parameter_count">stmt:bind_parameter_count</a></h2>
|
|
<pre>
|
|
stmt:bind_parameter_count()</pre>
|
|
<p>Returns the largest statement parameter index in prepared statement
|
|
<code>stmt</code>. When the statement parameters are of the forms ":AAA" or "?",
|
|
then they are assigned sequentially increasing numbers beginning with
|
|
one, so the value returned is the number of parameters. However if the
|
|
same statement parameter name is used multiple times, each occurrence
|
|
is given the same number, so the value returned is the number of unique
|
|
statement parameter names.</p>
|
|
<p>If statement parameters of the form "?NNN" are used (where NNN is an
|
|
integer) then there might be gaps in the numbering and the value
|
|
returned by this interface is the index of the statement parameter with
|
|
the largest index value.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stmt_bind_parameter_name">stmt:bind_parameter_name</a></h2>
|
|
<pre>
|
|
stmt:bind_parameter_name(n)</pre>
|
|
<p>Returns the name of the <code>n</code>-th parameter in prepared statement <code>stmt</code>.
|
|
Statement parameters of the form ":AAA" or "@AAA" or "$VVV" have a name
|
|
which is the string ":AAA" or "@AAA" or "$VVV". In other words, the
|
|
initial ":" or "$" or "@" is included as part of the name. Parameters
|
|
of the form "?" or "?NNN" have no name. The first bound parameter has
|
|
an index of 1.
|
|
If the value <code>n</code> is out of range or if the <code>n</code>-th parameter is
|
|
nameless, then nil is returned. The function returns <code>sqlite3.OK</code> on
|
|
success or else a numerical error code (see
|
|
<a href="#numerical_error_and_result_codes">Numerical error and result codes</a>)</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stmt_bind_values">stmt:bind_values</a></h2>
|
|
<pre>
|
|
stmt:bind_values(value1,value2,...,valueN)</pre>
|
|
<p>Binds the given values to statement parameters. The function returns
|
|
<code>sqlite3.OK</code> on success or else a numerical error code (see
|
|
<a href="#numerical_error_and_result_codes">Numerical error and result codes</a>).</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stmt_columns">stmt:columns</a></h2>
|
|
<pre>
|
|
stmt:columns()</pre>
|
|
<p>Returns the number of columns in the result set returned by statement
|
|
stmt or 0 if the statement does not return data (for example an UPDATE).</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stmt_finalize">stmt:finalize</a></h2>
|
|
<pre>
|
|
stmt:finalize()</pre>
|
|
<p>This function frees prepared statement stmt. If the statement was
|
|
executed successfully, or not executed at all, then <code>sqlite3.OK</code> is
|
|
returned. If execution of the statement failed then an error code is
|
|
returned.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stmt_get_name">stmt:get_name</a></h2>
|
|
<pre>
|
|
stmt:get_name(n)</pre>
|
|
<p>Returns the name of column <code>n</code> in the result set of statement stmt. (The
|
|
left-most column is number 0.)</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stmt_get_named_types">stmt:get_named_types</a></h2>
|
|
<pre>
|
|
stmt:get_named_types()</pre>
|
|
<p>Returns a table with the names and types of all columns in the result
|
|
set of statement stmt.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stmt_get_named_values">stmt:get_named_values</a></h2>
|
|
<pre>
|
|
stmt:get_named_values()</pre>
|
|
<p>This function returns a table with names and values of all columns in
|
|
the current result row of a query.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stmt_get_names">stmt:get_names</a></h2>
|
|
<pre>
|
|
stmt:get_names()</pre>
|
|
<p>This function returns an array with the names of all columns in the
|
|
result set returned by statement stmt.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stmt_get_type">stmt:get_type</a></h2>
|
|
<pre>
|
|
stmt:get_type(n)</pre>
|
|
<p>Returns the type of column <code>n</code> in the result set of statement stmt. (The
|
|
left-most column is number 0.)</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stmt_get_types">stmt:get_types</a></h2>
|
|
<pre>
|
|
stmt:get_types()</pre>
|
|
<p>This function returns an array with the types of all columns in the
|
|
result set returned by statement stmt.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stmt_get_unames">stmt:get_unames</a></h2>
|
|
<pre>
|
|
stmt:get_unames()</pre>
|
|
<p>This function returns a list with the names of all columns in the result
|
|
set returned by statement stmt.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stmt_get_utypes">stmt:get_utypes</a></h2>
|
|
<pre>
|
|
stmt:get_utypes()</pre>
|
|
<p>This function returns a list with the types of all columns in the result
|
|
set returned by statement stmt.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stmt_get_uvalues">stmt:get_uvalues</a></h2>
|
|
<pre>
|
|
stmt:get_uvalues()</pre>
|
|
<p>This function returns a list with the values of all columns in the
|
|
current result row of a query.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stmt_get_value">stmt:get_value</a></h2>
|
|
<pre>
|
|
stmt:get_value(n)</pre>
|
|
<p>Returns the value of column <code>n</code> in the result set of statement stmt. (The
|
|
left-most column is number 0.)</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stmt_get_values">stmt:get_values</a></h2>
|
|
<pre>
|
|
stmt:get_values()</pre>
|
|
<p>This function returns an array with the values of all columns in the
|
|
result set returned by statement stmt.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stmt_isopen">stmt:isopen</a></h2>
|
|
<pre>
|
|
stmt:isopen()</pre>
|
|
<p>Returns true if stmt has not yet been finalized, false otherwise.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stmt_nrows">stmt:nrows</a></h2>
|
|
<pre>
|
|
stmt:nrows()</pre>
|
|
<p>Returns an function that iterates over the names and values of the
|
|
result set of statement <code>stmt</code>. Each iteration returns a table with the
|
|
names and values for the current row.
|
|
This is the prepared statement equivalent of <a href="#db_nrows"><code>db:nrows()</code></a>.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stmt_reset">stmt:reset</a></h2>
|
|
<pre>
|
|
stmt:reset()</pre>
|
|
<p>This function resets SQL statement <code>stmt</code>, so that it is ready to be
|
|
re-executed. Any statement variables that had values bound to them using
|
|
the <code>stmt:bind*()</code> functions retain their values.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stmt_rows">stmt:rows</a></h2>
|
|
<pre>
|
|
stmt:rows()</pre>
|
|
<p>Returns an function that iterates over the values of the result set of
|
|
statement stmt. Each iteration returns an array with the values for the
|
|
current row.
|
|
This is the prepared statement equivalent of <a href="#db_rows"><code>db:rows()</code></a>.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stmt_step">stmt:step</a></h2>
|
|
<pre>
|
|
stmt:step()</pre>
|
|
<p>This function must be called to evaluate the (next iteration of the)
|
|
prepared statement stmt. It will return one of the following values:</p>
|
|
<ul>
|
|
<li>
|
|
<p><code>sqlite3.BUSY</code>: the engine was unable to acquire the locks needed. If the
|
|
statement is a COMMIT or occurs outside of an explicit transaction, then
|
|
you can retry the statement. If the statement is not a COMMIT and occurs
|
|
within a explicit transaction then you should rollback the transaction
|
|
before continuing.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>sqlite3.DONE</code>: the statement has finished executing successfully.
|
|
<a href="#stmt_step"><code>stmt:step()</code></a> should not be called again on this statement
|
|
without first calling <a href="#stmt_reset"><code>stmt:reset()</code></a> to reset the virtual
|
|
machine back to the initial state.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>sqlite3.ROW</code>: this is returned each time a new row of data is ready for
|
|
processing by the caller. The values may be accessed using the column
|
|
access functions. <a href="#stmt_step"><code>stmt:step()</code></a> can be called again to
|
|
retrieve the next row of data.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>sqlite3.ERROR</code>: a run-time error (such as a constraint violation) has
|
|
occurred. <a href="#stmt_step"><code>stmt:step()</code></a> should not be called again. More
|
|
information may be found by calling <a href="#db_errmsg"><code>db:errmsg()</code></a>. A more
|
|
specific error
|
|
code (can be obtained by calling <a href="#stmt_reset"><code>stmt:reset()</code></a>.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>sqlite3.MISUSE</code>: the function was called inappropriately, perhaps
|
|
because the statement has already been finalized or a previous call to
|
|
<a href="#stmt_step"><code>stmt:step()</code></a> has returned <code>sqlite3.ERROR</code> or
|
|
<code>sqlite3.DONE</code>.</p>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stmt_urows">stmt:urows</a></h2>
|
|
<pre>
|
|
stmt:urows()</pre>
|
|
<p>Returns an function that iterates over the values of the result set of
|
|
statement stmt. Each iteration returns the values for the current row.
|
|
This is the prepared statement equivalent of <a href="#db_urows"><code>db:urows()</code></a>.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stmt_last_insert_rowid">stmt:last_insert_rowid</a></h2>
|
|
<pre>
|
|
stmt:last_insert_rowid()</pre>
|
|
<p>This function returns the rowid of the most recent INSERT into the
|
|
database corresponding to this statement.
|
|
See <a href="#db_last_insert_rowid"><code>db:last_insert_rowid()</code></a>.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="methods_for_callback_contexts">Methods for callback contexts</a></h1>
|
|
<p>A callback context is available as a parameter inside the callback
|
|
functions <a href="#db_create_aggregate"><code>db:create_aggregate()</code></a> and
|
|
<a href="#db_create_function"><code>db:create_function()</code></a>. It can be used
|
|
to get further information about the state of a query.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="context_aggregate_count">context:aggregate_count</a></h2>
|
|
<pre>
|
|
context:aggregate_count()</pre>
|
|
<p>Returns the number of calls to the aggregate step function.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="context_get_aggregate_data">context:get_aggregate_data</a></h2>
|
|
<pre>
|
|
context:get_aggregate_data()</pre>
|
|
<p>Returns the user-definable data field for callback funtions.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="context_set_aggregate_data">context:set_aggregate_data</a></h2>
|
|
<pre>
|
|
context:set_aggregate_data(udata)</pre>
|
|
<p>Set the user-definable data field for callback funtions to <code>udata</code>.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="context_result">context:result</a></h2>
|
|
<pre>
|
|
context:result(res)</pre>
|
|
<p>This function sets the result of a callback function to res. The type of
|
|
the result depends on the type of res and is either a number or a string
|
|
or nil. All other values will raise an error message.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="context_result_null">context:result_null</a></h2>
|
|
<pre>
|
|
context:result_null()</pre>
|
|
<p>This function sets the result of a callback function to nil. It returns
|
|
nothing.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="context_result_number">context:result_number</a></h2>
|
|
<pre>
|
|
context:result_number(number)
|
|
context:result_double(number)</pre>
|
|
<p>This function sets the result of a callback function to the value
|
|
<code>number</code>. It returns nothing.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="context_result_int">context:result_int</a></h2>
|
|
<pre>
|
|
context:result_int(number)</pre>
|
|
<p>This function sets the result of a callback function to the integer
|
|
value in <code>number</code>. It returns nothing.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="context_result_text">context:result_text</a></h2>
|
|
<pre>
|
|
context:result_text(str)</pre>
|
|
<p>This function sets the result of a callback function to the string in
|
|
<code>str</code>. It returns nothing.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="context_result_blob">context:result_blob</a></h2>
|
|
<pre>
|
|
context:result_blob(blob)</pre>
|
|
<p>This function sets the result of a callback function to the binary
|
|
string in <code>blob</code>. It returns nothing.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="context_result_error">context:result_error</a></h2>
|
|
<pre>
|
|
context:result_error(err)</pre>
|
|
<p>This function sets the result of a callback function to the error value
|
|
in <code>err</code>. It returns nothing.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="context_user_data">context:user_data</a></h2>
|
|
<pre>
|
|
context:user_data()</pre>
|
|
<p>Returns the userdata parameter given in the call to install the callback
|
|
function (see <a href="#db_create_aggregate"><code>db:create_aggregate()</code></a> and
|
|
<a href="#db_create_function"><code>db:create_function()</code></a> for details).</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="methods_for_online_backup">Methods for Online Backup</a></h1>
|
|
<p>A backup userdata is created using <code>backup = </code>
|
|
<a href="#sqlite3_backup_init"><code>sqlite3.backup_init(...)</code></a>. It is then
|
|
used to step the backup, or inquire about its progress.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="bu_step">backup:step</a></h2>
|
|
<pre>
|
|
backup:step(nPages)</pre>
|
|
<p>Returns the status of the backup after stepping <code>nPages</code>. It is called one or more
|
|
times to transfer the data between the two databases.</p>
|
|
<p><code>backup:step(nPages)</code> will copy up to <code>nPages</code> pages between the
|
|
source and destination databases specified by <code>backup</code> userdata.
|
|
If <code>nPages</code> is negative, all remaining source pages are copied.
|
|
</p>
|
|
<p> If <code>backup:step(nPages)</code> successfully copies <code>nPages</code> pages and there
|
|
are still more pages to be copied, then the function returns <code>sqlite3.OK</code>.
|
|
If <code>backup:step(nPages)</code> successfully finishes copying all pages from source to
|
|
destination, then it returns <code>sqlite3.DONE</code>. If an error occurs during the step, then
|
|
an error code is returned. such as <code>sqlite3.READONLY</code>, <code>sqlite3.NOMEM</code>,
|
|
<code>sqlite3.BUSY</code>, <code>sqlite3.LOCKED</code>, or an <code>sqlite3.IOERR_XXX</code>
|
|
extended error code.
|
|
</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="bu_remaining">backup:remaining</a></h2>
|
|
<pre>
|
|
backup:remaining()</pre>
|
|
<p>Returns the number of pages still to be backed up at the conclusion of the most recent step.
|
|
</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="bu_pagecount">backup:pagecount</a></h2>
|
|
<pre>
|
|
backup:pagecount()</pre>
|
|
<p>Returns the total number of pages in the source database at the conclusion of the most recent
|
|
step.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="bu_finish">backup:finish</a></h2>
|
|
<pre>
|
|
backup:finish()</pre>
|
|
<p>When <code>backup:step(nPages)</code> has returned <code>sqlite3.DONE</code>, or when the
|
|
application wishes to abandon the backup operation, the application should destroy the backup
|
|
by calling <code>backup:finish()</code>. This releases all resources associated with the backup.
|
|
If <code>backup:step(nPages)</code> has not yet returned <code>sqlite3.DONE</code>, then any
|
|
active write-transaction on the destination database is rolled back. After the call, the backup
|
|
userdata corresponds to a completed backup, and should not be used.
|
|
</p>
|
|
<p>The value returned by <code>backup:finish()</code> is <code>sqlite3.OK</code> if no errors
|
|
occurred, regardless or whether or not the backup completed. If an out-of-memory condition or IO
|
|
error occurred during any prior step on the same backup, then <code>backup:finish()</code>
|
|
returns the corresponding error code.
|
|
</p>
|
|
<p>A return of <code>sqlite3.BUSY</code> or <code>sqlite3.LOCKED</code> from
|
|
<code>backup:step(nPages)</code> is not a permanent error and does not affect the return value
|
|
of <code>backup:finish()</code>.
|
|
</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="numerical_error_and_result_codes">Numerical error and result codes</a></h1>
|
|
<p>The following constants are defined by module sqlite3:</p>
|
|
<pre>
|
|
OK: 0 ERROR: 1 INTERNAL: 2 PERM: 3 ABORT: 4
|
|
BUSY: 5 LOCKED: 6 NOMEM: 7 READONLY: 8 INTERRUPT: 9
|
|
IOERR: 10 CORRUPT: 11 NOTFOUND: 12 FULL: 13 CANTOPEN: 14
|
|
PROTOCOL: 15 EMPTY: 16 SCHEMA: 17 TOOBIG: 18 CONSTRAINT: 19
|
|
MISMATCH: 20 MISUSE: 21 NOLFS: 22 FORMAT: 24 RANGE: 25
|
|
NOTADB: 26 ROW: 100 DONE: 101</pre>
|
|
|
|
<p>plus the Authorizer Action Codes:</p>
|
|
<pre>
|
|
CREATE_INDEX: 1 CREATE_TABLE: 2 CREATE_TEMP_INDEX: 3 CREATE_TEMP_TABLE: 4
|
|
CREATE_TEMP_TRIGGER: 5 CREATE_TEMP_VIEW: 6 CREATE_TRIGGER: 7 CREATE_VIEW: 8
|
|
DELETE: 9 DROP_INDEX: 10 DROP_TABLE: 11 DROP_TEMP_INDEX: 12
|
|
DROP_TEMP_TABLE: 13 DROP_TEMP_TRIGGER: 14 DROP_TEMP_VIEW: 15 DROP_TRIGGER: 16
|
|
DROP_VIEW: 17 INSERT: 18 PRAGMA: 19 READ: 20
|
|
SELECT: 21 TRANSACTION: 22 UPDATE: 23 ATTACH: 24
|
|
DETACH: 25 ALTER_TABLE: 26 REINDEX: 27 ANALYZE: 28
|
|
CREATE_VTABLE: 29 DROP_VTABLE: 30 FUNCTION: 31 SAVEPOINT: 32
|
|
</pre>
|
|
<p>and the Open Flags:</p>
|
|
<pre>
|
|
OPEN_READONLY OPEN_READWRITE OPEN_CREATE OPEN_URI
|
|
OPEN_MEMORY OPEN_NOMUTEX OPEN_FULLMUTEX OPEN_SHAREDCACHE
|
|
OPEN_PRIVATECACHE
|
|
</pre>
|
|
<p>For details about their exact meaning please see the <strong>SQLite3
|
|
documentation</strong> <a href="http://www.sqlite.org/">http://www.sqlite.org/</a>.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="version">VERSION</a></h1>
|
|
<p>This is <code>lsqlite3</code> version "0.9.4", also tagged as <code>fsl_9x</code>.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="credits">CREDITS</a></h1>
|
|
<p><code>lsqlite3</code> was developed by Tiago Dionizio and Doug Currie with
|
|
contributions from Thomas Lauer, Michael Roth, and Wolfgang Oertl.</p>
|
|
<p>This documentation is based on the "(very) preliminary" documents
|
|
for the Idle-SQLite3 database module. Thanks to Thomas Lauer for
|
|
making it available.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="license">LICENSE</a></h1>
|
|
<pre>
|
|
/************************************************************************
|
|
* lsqlite3 *
|
|
* Copyright (C) 2002-2016 Tiago Dionizio, Doug Currie *
|
|
* All rights reserved. *
|
|
* Author : Tiago Dionizio <tiago.dionizio@ist.utl.pt> *
|
|
* Author : Doug Currie <doug.currie@alum.mit.edu> *
|
|
* Library : lsqlite3 - an SQLite 3 database binding for Lua 5 *
|
|
* *
|
|
* Permission is hereby granted, free of charge, to any person obtaining *
|
|
* a copy of this software and associated documentation files (the *
|
|
* "Software"), to deal in the Software without restriction, including *
|
|
* without limitation the rights to use, copy, modify, merge, publish, *
|
|
* distribute, sublicense, and/or sell copies of the Software, and to *
|
|
* permit persons to whom the Software is furnished to do so, subject to *
|
|
* the following conditions: *
|
|
* *
|
|
* The above copyright notice and this permission notice shall be *
|
|
* included in all copies or substantial portions of the Software. *
|
|
* *
|
|
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, *
|
|
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
|
|
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.*
|
|
* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY *
|
|
* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, *
|
|
* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE *
|
|
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
|
|
************************************************************************/
|
|
</pre>
|
|
</nowiki>
|