capi3ref.html

嵌入式数据库sqlite 3.5.9的文档

<p><h3>Invariants:</h3>
<table border="0" cellpadding="5" cellspacing="0">
<tr><td valign="top">F13641</td> 
<td valign="top">
The 
<a href="#sqlite3_bind_parameter_index">sqlite3_bind_parameter_index(S,N)</a> interface returns
the index of SQL parameter in 
<a href="#sqlite3_stmt">prepared statement</a>
S whose name matches the UTF-8 string N, or 0 if there is
no match.</td></tr>
</table>
</p>
<hr>
<a name="sqlite3_bind_parameter_name"></a>
<h2>Name Of A Host Parameter</h2>
<blockquote><pre>
const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);

</pre></blockquote>
<p>
This routine returns a pointer to the name of the n-th
SQL parameter in a 
<a href="#sqlite3_stmt">prepared statement</a>.
SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"
have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
respectively.
In other words, the initial ":" or "$" or "@" or "?"
is included as part of the name.
Parameters of the form "?" without a following integer have no name.</p>

<p>The first host parameter has an index of 1, not 0.</p>

<p>If the value n is out of range or if the n-th parameter is
nameless, then NULL is returned.  The returned string is
always in the UTF-8 encoding even if the named parameter was
originally specified as UTF-16 in 
<a href="#sqlite3_prepare">sqlite3_prepare16()</a> or

<a href="#sqlite3_prepare">sqlite3_prepare16_v2()</a>.</p>

<p>See also: 
<a href="#sqlite3_bind_blob">sqlite3_bind()</a>,

<a href="#sqlite3_bind_parameter_count">sqlite3_bind_parameter_count()</a>, and

<a href="#sqlite3_bind_parameter_index">sqlite3_bind_parameter_index()</a>.</p>

<p><h3>Invariants:</h3>
<table border="0" cellpadding="5" cellspacing="0">
<tr><td valign="top">F13621</td> 
<td valign="top">
The 
<a href="#sqlite3_bind_parameter_name">sqlite3_bind_parameter_name(S,N)</a> interface returns
a UTF-8 rendering of the name of the SQL parameter in

<a href="#sqlite3_stmt">prepared statement</a> S having index N, or
NULL if there is no SQL parameter with index N or if the
parameter with index N is an anonymous parameter "?".</td></tr>
</table>
</p>
<hr>
<a name="sqlite3_blob_bytes"></a>
<h2>Return The Size Of An Open BLOB</h2>
<blockquote><pre>
int sqlite3_blob_bytes(sqlite3_blob *);

</pre></blockquote>
<p>
Return the size in bytes of the blob accessible via the open

<a href="#sqlite3_blob">sqlite3_blob</a> object in its only argument.</p>

<p><h3>Invariants:</h3>
<table border="0" cellpadding="5" cellspacing="0">
<tr><td valign="top">F17843</td> 
<td valign="top">
The 
<a href="#sqlite3_blob_bytes">sqlite3_blob_bytes(P)</a> interface returns the size
in bytes of the BLOB that the 
<a href="#sqlite3_blob">sqlite3_blob</a> object P
refers to.</td></tr>
</table>
</p>
<hr>
<a name="sqlite3_blob_close"></a>
<h2>Close A BLOB Handle</h2>
<blockquote><pre>
int sqlite3_blob_close(sqlite3_blob *);

</pre></blockquote>
<p>
Close an open 
<a href="#sqlite3_blob">blob handle</a>.</p>

<p>Closing a BLOB shall cause the current transaction to commit
if there are no other BLOBs, no pending prepared statements, and the
database connection is in autocommit mode.
If any writes were made to the BLOB, they might be held in cache
until the close operation if they will fit.
Closing the BLOB often forces the changes
out to disk and so if any I/O errors occur, they will likely occur
at the time when the BLOB is closed. Any errors that occur during
closing are reported as a non-zero return value.</p>

<p>The BLOB is closed unconditionally.  Even if this routine returns
an error code, the BLOB is still closed.</p>

<p><h3>Invariants:</h3>
<table border="0" cellpadding="5" cellspacing="0">
<tr><td valign="top">F17833</td> 
<td valign="top">
The 
<a href="#sqlite3_blob_close">sqlite3_blob_close(P)</a> interface closes an

<a href="#sqlite3_blob">sqlite3_blob</a> object P previously opened using

<a href="#sqlite3_blob_open">sqlite3_blob_open()</a>.</td></tr>
<tr><td valign="top">F17836</td> 
<td valign="top">
Closing an 
<a href="#sqlite3_blob">sqlite3_blob</a> object using

<a href="#sqlite3_blob_close">sqlite3_blob_close()</a> shall cause the current transaction to
commit if there are no other open 
<a href="#sqlite3_blob">sqlite3_blob</a> objects
or 
<a href="#sqlite3_stmt">prepared statements</a> on the same 
<a href="#sqlite3">database connection</a> and
the 
<a href="#sqlite3">database connection</a> is in

<a href="#sqlite3_get_autocommit">autocommit mode</a>.</td></tr>
<tr><td valign="top">F17839</td> 
<td valign="top">
The 
<a href="#sqlite3_blob_close">sqlite3_blob_close(P)</a> interfaces closes the

<a href="#sqlite3_blob">sqlite3_blob</a> object P unconditionally, even if

<a href="#sqlite3_blob_close">sqlite3_blob_close(P)</a> returns something other than 
<a href="#SQLITE_ABORT">SQLITE_OK</a>.</td></tr>
</table>
</p>
<hr>
<a name="sqlite3_blob_open"></a>
<h2>Open A BLOB For Incremental I/O</h2>
<blockquote><pre>
int sqlite3_blob_open(
  sqlite3*,
  const char *zDb,
  const char *zTable,
  const char *zColumn,
  sqlite3_int64 iRow,
  int flags,
  sqlite3_blob **ppBlob
);

</pre></blockquote>
<p>
This interfaces opens a handle to the blob located
in row iRow, column zColumn, table zTable in database zDb;
in other words,  the same blob that would be selected by:</p>

<p><pre>
SELECT zColumn FROM zDb.zTable WHERE rowid = iRow;
</pre></p>

<p>If the flags parameter is non-zero, the blob is opened for
read and write access. If it is zero, the blob is opened for read
access.</p>

<p>Note that the database name is not the filename that contains
the database but rather the symbolic name of the database that
is assigned when the database is connected using 
<a href="lang_attach.html">ATTACH</a>.
For the main database file, the database name is "main".  For
TEMP tables, the database name is "temp".</p>

<p>On success, 
<a href="#SQLITE_ABORT">SQLITE_OK</a> is returned and the new

<a href="#sqlite3_blob">blob handle</a> is written to *ppBlob.
Otherwise an error code is returned and
any value written to *ppBlob should not be used by the caller.
This function sets the database-handle error code and message
accessible via 
<a href="#sqlite3_errcode">sqlite3_errcode()</a> and 
<a href="#sqlite3_errcode">sqlite3_errmsg()</a>.</p>

<p><h3>Invariants:</h3>
<table border="0" cellpadding="5" cellspacing="0">
<tr><td valign="top">F17813</td> 
<td valign="top">
A successful invocation of the 
<a href="#sqlite3_blob_open">sqlite3_blob_open(D,B,T,C,R,F,P)</a>
interface opens an 
<a href="#sqlite3_blob">sqlite3_blob</a> object P on the blob
in column C of table T in database B on 
<a href="#sqlite3">database connection</a> D.</td></tr>
<tr><td valign="top">F17814</td> 
<td valign="top">
A successful invocation of 
<a href="#sqlite3_blob_open">sqlite3_blob_open(D,...)</a> starts
a new transaction on 
<a href="#sqlite3">database connection</a> D if that connection
is not already in a transaction.</td></tr>
<tr><td valign="top">F17816</td> 
<td valign="top">
The 
<a href="#sqlite3_blob_open">sqlite3_blob_open(D,B,T,C,R,F,P)</a> interface opens the blob
for read and write access if and only if the F parameter
is non-zero.</td></tr>
<tr><td valign="top">F17819</td> 
<td valign="top">
The 
<a href="#sqlite3_blob_open">sqlite3_blob_open()</a> interface returns 
<a href="#SQLITE_ABORT">SQLITE_OK</a> on
success and an appropriate 
<a href="#SQLITE_ABORT">error code</a> on failure.</td></tr>
<tr><td valign="top">F17821</td> 
<td valign="top">
If an error occurs during evaluation of 
<a href="#sqlite3_blob_open">sqlite3_blob_open(D,...)</a>
then subsequent calls to 
<a href="#sqlite3_errcode">sqlite3_errcode(D)</a>,

<a href="#sqlite3_errcode">sqlite3_errmsg(D)</a>, and 
<a href="#sqlite3_errcode">sqlite3_errmsg16(D)</a> will return
information approprate for that error.</td></tr>
</table>
</p>
<hr>
<a name="sqlite3_blob_read"></a>
<h2>Read Data From A BLOB Incrementally</h2>
<blockquote><pre>
int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);

</pre></blockquote>
<p>
This function is used to read data from an open

<a href="#sqlite3_blob">blob-handle</a> into a caller supplied buffer.
N bytes of data are copied into buffer
Z from the open blob, starting at offset iOffset.</p>

<p>If offset iOffset is less than N bytes from the end of the blob,

<a href="#SQLITE_ABORT">SQLITE_ERROR</a> is returned and no data is read.  If N or iOffset is
less than zero 
<a href="#SQLITE_ABORT">SQLITE_ERROR</a> is returned and no data is read.</p>

<p>On success, SQLITE_OK is returned. Otherwise, an

<a href="#SQLITE_ABORT">error code</a> or an 
<a href="#SQLITE_IOERR_BLOCKED">extended error code</a> is returned.</p>

<p><h3>Invariants:</h3>
<table border="0" cellpadding="5" cellspacing="0">
<tr><td valign="top">F17853</td> 
<td valign="top">
The 
<a href="#sqlite3_blob_read">sqlite3_blob_read(P,Z,N,X)</a> interface reads N bytes
beginning at offset X from
the blob that 
<a href="#sqlite3_blob">sqlite3_blob</a> object P refers to
and writes those N bytes into buffer Z.</td></tr>
<tr><td valign="top">F17856</td> 
<td valign="top">
In 
<a href="#sqlite3_blob_read">sqlite3_blob_read(P,Z,N,X)</a> if the size of the blob
is less than N+X bytes, then the function returns 
<a href="#SQLITE_ABORT">SQLITE_ERROR</a>
and nothing is read from the blob.</td></tr>
<tr><td valign="top">F17859</td> 
<td valign="top">
In 
<a href="#sqlite3_blob_read">sqlite3_blob_read(P,Z,N,X)</a> if X or N is less than zero
then the function returns 
<a href="#SQLITE_ABORT">SQLITE_ERROR</a>
and nothing is read from the blob.</td></tr>
<tr><td valign="top">F17862</td> 
<td valign="top">
The 
<a href="#sqlite3_blob_read">sqlite3_blob_read(P,Z,N,X)</a> interface returns 
<a href="#SQLITE_ABORT">SQLITE_OK</a>
if N bytes where successfully read into buffer Z.</td></tr>
<tr><td valign="top">F17865</td> 
<td valign="top">
If the requested read could not be completed,
the 
<a href="#sqlite3_blob_read">sqlite3_blob_read(P,Z,N,X)</a> interface returns an
appropriate 
<a href="#SQLITE_ABORT">error code</a> or 
<a href="#SQLITE_IOERR_BLOCKED">extended error code</a>.</td></tr>
<tr><td valign="top">F17868</td> 
<td valign="top">
If an error occurs during evaluation of 
<a href="#sqlite3_blob_read">sqlite3_blob_read(P,...)</a>
then subsequent calls to 
<a href="#sqlite3_errcode">sqlite3_errcode(D)</a>,

<a href="#sqlite3_errcode">sqlite3_errmsg(D)</a>, and 
<a href="#sqlite3_errcode">sqlite3_errmsg16(D)</a> will return
information approprate for that error, where D is the
database handle that was used to open blob handle P.</td></tr>
</table>
</p>
<hr>
<a name="sqlite3_blob_write"></a>
<h2>Write Data Into A BLOB Incrementally</h2>
<blockquote><pre>
int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);

</pre></blockquote>
<p>
This function is used to write data into an open

<a href="#sqlite3_blob">blob-handle</a> from a user supplied buffer.
n bytes of data are copied from the buffer
pointed to by z into the open blob, starting at offset iOffset.</p>

<p>If the 
<a href="#sqlite3_blob">blob-handle</a> passed as the first argument
was not opened for writing (the flags parameter to 
<a href="#sqlite3_blob_open">sqlite3_blob_open()</a>
was zero), this function returns 
<a href="#SQLITE_ABORT">SQLITE_READONLY</a>.</p>

<p>This function may only modify the contents of the blob; it is
not possible to increase the size of a blob using this API.
If offset iOffset is less than n bytes from the end of the blob,

<a href="#SQLITE_ABORT">SQLITE_ERROR</a> is returned and no data is written.  If n is
less than zero 
<a href="#SQLITE_ABORT">SQLITE_ERROR</a> is returned and no data is written.</p>

<p>On success, SQLITE_OK is returned. Otherwise, an

<a href="#SQLITE_ABORT">error code</a> or an 
<a href="#SQLITE_IOERR_BLOCKED">extended error code</a> is returned.</p>

<p><h3>Invariants:</h3>
<table border="0" cellpadding="5" cellspacing="0">
<tr><td valign="top">F17873</td> 
<td valign="top">
The 
<a href="#sqlite3_blob_write">sqlite3_blob_write(P,Z,N,X)</a> interface writes N bytes
from buffer Z into
the blob that 
<a href="#sqlite3_blob">sqlite3_blob</a> object P refers to
beginning at an offset of X into the blob.</td></tr>
<tr><td valign="top">F17875</td> 
<td valign="top">
The 
<a href="#sqlite3_blob_write">sqlite3_blob_write(P,Z,N,X)</a> interface returns

<a href="#SQLITE_ABORT">SQLITE_READONLY</a> if the 
<a href="#sqlite3_blob">sqlite3_blob</a> object P was

<a href="#sqlite3_blob_open">opened</a> for reading only.</td></tr>
<tr><td valign="top">F17876</td> 
<td valign="top">
In 
<a href="#sqlite3_blob_write">sqlite3_blob_write(P,Z,N,X)</a> if the size of the blob
is less than N+X bytes, then the function returns 
<a href="#SQLITE_ABORT">SQLITE_ERROR</a>
and nothing is written into the blob.</td></tr>
<tr><td valign="top">F17879</td> 
<td valign="top">
In 
<a href="#sqlite3_blob_write">sqlite3_blob_write(P,Z,N,X)</a> if X or N is less than zero
then the function returns 
<a href="#SQLITE_ABORT">SQLITE_ERROR</a>
and nothing is written into the blob.</td></tr>
<tr><td valign