capi3ref.html

这是sqlite3.56的文档。拿来给大家阅读使用

when SQLite is in the middle of a large transaction where all the
changes will not fit into the in-memory cache.  SQLite will
already hold a RESERVED lock on the database file, but it needs
to promote this lock to EXCLUSIVE so that it can spill cache
pages into the database file without harm to concurrent
readers.  If it is unable to promote the lock, then the in-memory
cache will be left in an inconsistent state and so the error
code is promoted from the relatively benign 
<a href="#SQLITE_ABORT">SQLITE_BUSY</a> to
the more severe 
<a href="#SQLITE_IOERR_BLOCKED">SQLITE_IOERR_BLOCKED</a>.  This error code promotion
forces an automatic rollback of the changes.  See the
<a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError">
CorruptionFollowingBusyError</a> wiki page for a discussion of why
this is important.</p>

<p>There can only be a single busy handler defined for each database
connection.  Setting a new busy handler clears any previous one.
Note that calling 
<a href="#sqlite3_busy_timeout">sqlite3_busy_timeout()</a> will also set or clear
the busy handler.</p>

<p><h3>Invariants:</h3>
<table border="0" cellpadding="5" cellspacing="0">
<tr><td valign="top">F12311</td> 
<td valign="top">
The 
<a href="#sqlite3_busy_handler">sqlite3_busy_handler()</a> function replaces the busy handler
callback in the database connection identified by the 1st
parameter with a new busy handler identified by the 2nd and 3rd
parameters.</td></tr>
<tr><td valign="top">F12312</td> 
<td valign="top">
The default busy handler for new database connections is NULL.</td></tr>
<tr><td valign="top">F12314</td> 
<td valign="top">
When two or more database connection share a common cache,
the busy handler for the database connection currently using
the cache is invoked when the cache encounters a lock.</td></tr>
<tr><td valign="top">F12316</td> 
<td valign="top">
If a busy handler callback returns zero, then the SQLite
interface that provoked the locking event will return

<a href="#SQLITE_ABORT">SQLITE_BUSY</a>.</td></tr>
<tr><td valign="top">F12318</td> 
<td valign="top">
SQLite will invokes the busy handler with two argument which
are a copy of the pointer supplied by the 3rd parameter to

<a href="#sqlite3_busy_handler">sqlite3_busy_handler()</a> and a count of the number of prior
invocations of the busy handler for the same locking event.</td></tr>
</table></p>

<p><h3>Limitations:</h3>
<table border="0" cellpadding="5" cellspacing="0">
<tr><td valign="top">U12319</td> 
<td valign="top">
A busy handler should not call close the database connection
or prepared statement that invoked the busy handler.</td></tr>
</table>
</p>
<hr>
<a name="sqlite3_busy_timeout"></a>
<h2>Set A Busy Timeout</h2>
<blockquote><pre>
int sqlite3_busy_timeout(sqlite3*, int ms);

</pre></blockquote>
<p>
This routine sets a 
<a href="#sqlite3_busy_handler">busy handler</a>
that sleeps for a while when a
table is locked.  The handler will sleep multiple times until
at least "ms" milliseconds of sleeping have been done. After
"ms" milliseconds of sleeping, the handler returns 0 which
causes 
<a href="#sqlite3_step">sqlite3_step()</a> to return 
<a href="#SQLITE_ABORT">SQLITE_BUSY</a> or 
<a href="#SQLITE_IOERR_BLOCKED">SQLITE_IOERR_BLOCKED</a>.</p>

<p>Calling this routine with an argument less than or equal to zero
turns off all busy handlers.</p>

<p>There can only be a single busy handler for a particular database
connection.  If another busy handler was defined
(using 
<a href="#sqlite3_busy_handler">sqlite3_busy_handler()</a>) prior to calling
this routine, that other busy handler is cleared.</p>

<p><h3>Invariants:</h3>
<table border="0" cellpadding="5" cellspacing="0">
<tr><td valign="top">F12341</td> 
<td valign="top">
The 
<a href="#sqlite3_busy_timeout">sqlite3_busy_timeout()</a> function overrides any prior

<a href="#sqlite3_busy_timeout">sqlite3_busy_timeout()</a> or 
<a href="#sqlite3_busy_handler">sqlite3_busy_handler()</a> setting
on the same database connection.</td></tr>
<tr><td valign="top">F12343</td> 
<td valign="top">
If the 2nd parameter to 
<a href="#sqlite3_busy_timeout">sqlite3_busy_timeout()</a> is less than
or equal to zero, then the busy handler is cleared so that
all subsequent locking events immediately return 
<a href="#SQLITE_ABORT">SQLITE_BUSY</a>.</td></tr>
<tr><td valign="top">F12344</td> 
<td valign="top">
If the 2nd parameter to 
<a href="#sqlite3_busy_timeout">sqlite3_busy_timeout()</a> is a positive
number N, then a busy handler is set that repeatedly calls
the xSleep() method in the VFS interface until either the
lock clears or until the cumulative sleep time reported back
by xSleep() exceeds N milliseconds.</td></tr>
</table>
</p>
<hr>
<a name="sqlite3_changes"></a>
<h2>Count The Number Of Rows Modified</h2>
<blockquote><pre>
int sqlite3_changes(sqlite3*);

</pre></blockquote>
<p>
This function returns the number of database rows that were changed
or inserted or deleted by the most recently completed SQL statement
on the connection specified by the first parameter.  Only
changes that are directly specified by the INSERT, UPDATE, or
DELETE statement are counted.  Auxiliary changes caused by
triggers are not counted. Use the 
<a href="#sqlite3_total_changes">sqlite3_total_changes()</a> function
to find the total number of changes including changes caused by triggers.</p>

<p>A "row changes" is a change to a single row of a single table
caused by an INSERT, DELETE, or UPDATE statement.  Rows that
are changed as side effects of REPLACE constraint resolution,
rollback, ABORT processing, DROP TABLE, or by any other
mechanisms do not count as direct row changes.</p>

<p>A "trigger context" is a scope of execution that begins and
ends with the script of a trigger.  Most SQL statements are
evaluated outside of any trigger.  This is the "top level"
trigger context.  If a trigger fires from the top level, a
new trigger context is entered for the duration of that one
trigger.  Subtriggers create subcontexts for their duration.</p>

<p>Calling 
<a href="#sqlite3_exec">sqlite3_exec()</a> or 
<a href="#sqlite3_step">sqlite3_step()</a> recursively does
not create a new trigger context.</p>

<p>This function returns the number of direct row changes in the
most recent INSERT, UPDATE, or DELETE statement within the same
trigger context.</p>

<p>So when called from the top level, this function returns the
number of changes in the most recent INSERT, UPDATE, or DELETE
that also occurred at the top level.
Within the body of a trigger, the sqlite3_changes() interface
can be called to find the number of
changes in the most recently completed INSERT, UPDATE, or DELETE
statement within the body of the same trigger.
However, the number returned does not include in changes
caused by subtriggers since they have their own context.</p>

<p>SQLite implements the command "DELETE FROM table" without
a WHERE clause by dropping and recreating the table.  (This is much
faster than going through and deleting individual elements from the
table.)  Because of this optimization, the deletions in
"DELETE FROM table" are not row changes and will not be counted
by the sqlite3_changes() or 
<a href="#sqlite3_total_changes">sqlite3_total_changes()</a> functions.
To get an accurate count of the number of rows deleted, use
"DELETE FROM table WHERE 1" instead.</p>

<p><h3>Invariants:</h3>
<table border="0" cellpadding="5" cellspacing="0">
<tr><td valign="top">F12241</td> 
<td valign="top">
The 
<a href="#sqlite3_changes">sqlite3_changes()</a> function returns the number of
row changes caused by the most recent INSERT, UPDATE,
or DELETE statement on the same database connection and
within the same trigger context, or zero if there have
not been any qualifying row changes.</td></tr>
</table></p>

<p><h3>Limitations:</h3>
<table border="0" cellpadding="5" cellspacing="0">
<tr><td valign="top">U12252</td> 
<td valign="top">
If a separate thread makes changes on the same database connection
while 
<a href="#sqlite3_changes">sqlite3_changes()</a> is running then the value returned
is unpredictable and unmeaningful.</td></tr>
</table>
</p>
<hr>
<a name="sqlite3_clear_bindings"></a>
<h2>Reset All Bindings On A Prepared Statement</h2>
<blockquote><pre>
int sqlite3_clear_bindings(sqlite3_stmt*);

</pre></blockquote>
<p>
Contrary to the intuition of many, 
<a href="#sqlite3_reset">sqlite3_reset()</a> does not
reset the 
<a href="#sqlite3_bind_blob">bindings</a> on a

<a href="#sqlite3_stmt">prepared statement</a>.  Use this routine to
reset all host parameters to NULL.</p>

<p><h3>Invariants:</h3>
<table border="0" cellpadding="5" cellspacing="0">
<tr><td valign="top">F13661</td> 
<td valign="top">
The 
<a href="#sqlite3_clear_bindings">sqlite3_clear_bindings(S)</a> interface resets all
SQL parameter bindings in 
<a href="#sqlite3_stmt">prepared statement</a> S
back to NULL.</td></tr>
</table>
</p>
<hr>
<a name="sqlite3_close"></a>
<h2>Closing A Database Connection</h2>
<blockquote><pre>
int sqlite3_close(sqlite3 *);

</pre></blockquote>
<p>
This routine is the destructor for the 
<a href="#sqlite3">sqlite3</a> object.</p>

<p>Applications should 
<a href="#sqlite3_finalize">finalize</a> all

<a href="#sqlite3_stmt">prepared statements</a> and

<a href="#sqlite3_blob_close">close</a> all 
<a href="#sqlite3_blob">BLOBs</a>
associated with the 
<a href="#sqlite3">sqlite3</a> object prior
to attempting to close the 
<a href="#sqlite3">sqlite3</a> object.</p>

<p><font color="red">(TODO: What happens to pending transactions?  Are they
rolled back, or abandoned?)</font></p>

<p><h3>Invariants:</h3>
<table border="0" cellpadding="5" cellspacing="0">
<tr><td valign="top">F12011</td> 
<td valign="top">
The 
<a href="#sqlite3_close">sqlite3_close()</a> interface destroys an 
<a href="#sqlite3">sqlite3</a> object
allocated by a prior call to 
<a href="#sqlite3_open">sqlite3_open()</a>,

<a href="#sqlite3_open">sqlite3_open16()</a>, or 
<a href="#sqlite3_open">sqlite3_open_v2()</a>.</td></tr>
<tr><td valign="top">F12012</td> 
<td valign="top">
The 
<a href="#sqlite3_close">sqlite3_close()</a> function releases all memory used by the
connection and closes all open files.</td></tr>
<tr><td valign="top">F12013</td> 
<td valign="top">
If the database connection contains

<a href="#sqlite3_stmt">prepared statements</a> that have not been
finalized by 
<a href="#sqlite3_finalize">sqlite3_finalize()</a>, then 
<a href="#sqlite3_close">sqlite3_close()</a>
returns 
<a href="#SQLITE_ABORT">SQLITE_BUSY</a> and leaves the connection open.</td></tr>
<tr><td valign="top">F12014</td> 
<td valign="top">
Giving sqlite3_close() a NULL pointer is a harmless no-op.</td></tr>
</table></p>

<p><h3>Limitations:</h3>
<table border="0" cellpadding="5" cellspacing="0">
<tr><td valign="top">U12015</td> 
<td valign="top">
The parameter to 
<a href="#sqlite3_close">sqlite3_close()</a> must be an 
<a href="#sqlite3">sqlite3</a> object
pointer previously obtained from 
<a href="#sqlite3_open">sqlite3_open()</a> or the
equivalent, or NULL.</td></tr>
<tr><td valign="top">U12016</td> 
<td valign="top">
The parameter to 
<a href="#sqlite3_close">sqlite3_close()</a> must not have been previously
closed.</td></tr>
</table>
</p>
<hr>
<a name="sqlite3_column_count"></a>
<h2>Number Of Columns In A Result Set</h2>
<blockquote><pre>
int sqlite3_column_count(sqlite3_stmt *pStmt);

</pre></blockquote>
<p>
Return the number of columns in the result set returned by the

<a href="#sqlite3_stmt">prepared statement</a>. This routine returns 0
if pStmt is an SQL statement that does not return data (for
example an UPDATE).</p>

<p><h3>Invariants:</h3>
<table border="0" cellpadding="5" cellspacing="0">
<tr><td valign="top">F13711</td> 
<td valign="top">
The 
<a href="#sqlite3_column_count">sqlite3_column_count(S)</a> interface returns the number of
columns in the result set generated by the

<a href="#sqlite3_stmt">prepared statement</a> S, or 0 if S does not generate
a result set.</td></tr>
</table>
</p>
<hr>
<a name="sqlite3_data_count"></a>
<h2>Number of columns in a result set</h2>
<blockquote><pre>
int sqlite3_data_count(sqlite3_stmt *pStmt);

</pre></blockquote>
<p>
Return the number of values in the current row of the result set.</p>

<p><h3>Invariants:</h3>
<table border="0" cellpadding="5" cellspacing="0">
<tr><td valign="top">F13771</td> 
<td valign="top">
After a call to 
<a href="#sqlite3_step">sqlite3_step(S)</a> that returns

<a href="#SQLITE_ABORT">SQLITE_ROW</a>, the 
<a href="#sqlite3_data_count">sqlite3_data_count(S)</a> routine
will return the same value as the

<a href="#sqlite3_column_count">sqlite3_column_count(S)</a> function.</td></tr>
<tr><td valign="top">F13772</td> 
<td valign="top">
After 
<a href="#sqlite3_step">sqlite3_step(S)</a> has returned any value other than

<a href="#SQLITE_ABORT">SQLITE_ROW</a> or before 
<a href="#sqlite3_step">sqlite3_step(S)</a> has been
called on the 
<a href="#sqlite3_stmt">prepared statement</a> for
the first time since it was 
<a href="#sqlite3_prepare">prepared</a>
or 
<a href="#sqlite3_reset">reset</a>, the 
<a href="#sqlite3_data_count">sqlite3_data_count(S)</a>
routine returns zero.</td></tr>
</table>
</p>
<hr>
<a name="sqlite3_db_handle"></a>
<h2>Find The Database Handle Of A Prepared Statement</h2>
<blockquote><pre>
sqlite3 *sqlite3_db_handle(sqlite3_stmt*);

</pre></blockquote>
<p>
 The sqlite3_db_handle interface
returns the 
<a href="#sqlite3">sqlite3*</a> database handle to which a

<a href="#sqlite3_stmt">prepared statement</a> belongs.
 th