251 lines
12 KiB
HTML
251 lines
12 KiB
HTML
<!DOCTYPE html>
|
|
<html><head>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
|
|
<link href="../sqlite.css" rel="stylesheet">
|
|
<title>Binding Values To Prepared Statements</title>
|
|
<!-- path=../ -->
|
|
</head>
|
|
<body>
|
|
<div class=nosearch>
|
|
<a href="../index.html">
|
|
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite" border="0">
|
|
</a>
|
|
<div><!-- IE hack to prevent disappearing logo --></div>
|
|
<div class="tagline desktoponly">
|
|
Small. Fast. Reliable.<br>Choose any three.
|
|
</div>
|
|
<div class="menu mainmenu">
|
|
<ul>
|
|
<li><a href="../index.html">Home</a>
|
|
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
|
|
<li class='wideonly'><a href='../about.html'>About</a>
|
|
<li class='desktoponly'><a href="../docs.html">Documentation</a>
|
|
<li class='desktoponly'><a href="../download.html">Download</a>
|
|
<li class='wideonly'><a href='../copyright.html'>License</a>
|
|
<li class='desktoponly'><a href="../support.html">Support</a>
|
|
<li class='desktoponly'><a href="../prosupport.html">Purchase</a>
|
|
<li class='search' id='search_menubutton'>
|
|
<a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
|
|
</ul>
|
|
</div>
|
|
<div class="menu submenu" id="submenu">
|
|
<ul>
|
|
<li><a href='../about.html'>About</a>
|
|
<li><a href='../docs.html'>Documentation</a>
|
|
<li><a href='../download.html'>Download</a>
|
|
<li><a href='../support.html'>Support</a>
|
|
<li><a href='../prosupport.html'>Purchase</a>
|
|
</ul>
|
|
</div>
|
|
<div class="searchmenu" id="searchmenu">
|
|
<form method="GET" action="../search">
|
|
<select name="s" id="searchtype">
|
|
<option value="d">Search Documentation</option>
|
|
<option value="c">Search Changelog</option>
|
|
</select>
|
|
<input type="text" name="q" id="searchbox" value="">
|
|
<input type="submit" value="Go">
|
|
</form>
|
|
</div>
|
|
</div>
|
|
<script>
|
|
function toggle_div(nm) {
|
|
var w = document.getElementById(nm);
|
|
if( w.style.display=="block" ){
|
|
w.style.display = "none";
|
|
}else{
|
|
w.style.display = "block";
|
|
}
|
|
}
|
|
function toggle_search() {
|
|
var w = document.getElementById("searchmenu");
|
|
if( w.style.display=="block" ){
|
|
w.style.display = "none";
|
|
} else {
|
|
w.style.display = "block";
|
|
setTimeout(function(){
|
|
document.getElementById("searchbox").focus()
|
|
}, 30);
|
|
}
|
|
}
|
|
function div_off(nm){document.getElementById(nm).style.display="none";}
|
|
window.onbeforeunload = function(e){div_off("submenu");}
|
|
/* Disable the Search feature if we are not operating from CGI, since */
|
|
/* Search is accomplished using CGI and will not work without it. */
|
|
if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
|
|
document.getElementById("search_menubutton").style.display = "none";
|
|
}
|
|
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */
|
|
function hideorshow(btn,obj){
|
|
var x = document.getElementById(obj);
|
|
var b = document.getElementById(btn);
|
|
if( x.style.display!='none' ){
|
|
x.style.display = 'none';
|
|
b.innerHTML='show';
|
|
}else{
|
|
x.style.display = '';
|
|
b.innerHTML='hide';
|
|
}
|
|
return false;
|
|
}
|
|
</script>
|
|
</div>
|
|
<!-- keywords: {SQL parameter} {SQL parameters} {host parameter} {host parameter name} {host parameters} {parameter binding} sqlite3_bind_blob sqlite3_bind_blob64 sqlite3_bind_double sqlite3_bind_int sqlite3_bind_int64 sqlite3_bind_null sqlite3_bind_pointer sqlite3_bind_text sqlite3_bind_text16 sqlite3_bind_text64 sqlite3_bind_value sqlite3_bind_zeroblob sqlite3_bind_zeroblob64 -->
|
|
<div class=nosearch>
|
|
<a href="intro.html"><h2>SQLite C Interface</h2></a>
|
|
<h2>Binding Values To Prepared Statements</h2>
|
|
</div>
|
|
<blockquote><pre>
|
|
int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
|
|
int sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64,
|
|
void(*)(void*));
|
|
int sqlite3_bind_double(sqlite3_stmt*, int, double);
|
|
int sqlite3_bind_int(sqlite3_stmt*, int, int);
|
|
int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
|
|
int sqlite3_bind_null(sqlite3_stmt*, int);
|
|
int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*));
|
|
int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
|
|
int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64,
|
|
void(*)(void*), unsigned char encoding);
|
|
int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
|
|
int sqlite3_bind_pointer(sqlite3_stmt*, int, void*, const char*,void(*)(void*));
|
|
int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
|
|
int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64);
|
|
</pre></blockquote>
|
|
<p>
|
|
In the SQL statement text input to <a href="../c3ref/prepare.html">sqlite3_prepare_v2()</a> and its variants,
|
|
literals may be replaced by a <a href="../lang_expr.html#varparam">parameter</a> that matches one of following
|
|
templates:</p>
|
|
|
|
<p><ul>
|
|
<li> ?
|
|
<li> ?NNN
|
|
<li> :VVV
|
|
<li> @VVV
|
|
<li> $VVV
|
|
</ul></p>
|
|
|
|
<p>In the templates above, NNN represents an integer literal,
|
|
and VVV represents an alphanumeric identifier. The values of these
|
|
parameters (also called "host parameter names" or "SQL parameters")
|
|
can be set using the sqlite3_bind_*() routines defined here.</p>
|
|
|
|
<p>The first argument to the sqlite3_bind_*() routines is always
|
|
a pointer to the <a href="../c3ref/stmt.html">sqlite3_stmt</a> object returned from
|
|
<a href="../c3ref/prepare.html">sqlite3_prepare_v2()</a> or its variants.</p>
|
|
|
|
<p>The second argument is the index of the SQL parameter to be set.
|
|
The leftmost SQL parameter has an index of 1. When the same named
|
|
SQL parameter is used more than once, second and subsequent
|
|
occurrences have the same index as the first occurrence.
|
|
The index for named parameters can be looked up using the
|
|
<a href="../c3ref/bind_parameter_index.html">sqlite3_bind_parameter_index()</a> API if desired. The index
|
|
for "?NNN" parameters is the value of NNN.
|
|
The NNN value must be between 1 and the <a href="../c3ref/limit.html">sqlite3_limit()</a>
|
|
parameter <a href="../c3ref/c_limit_attached.html#sqlitelimitvariablenumber">SQLITE_LIMIT_VARIABLE_NUMBER</a> (default value: 32766).</p>
|
|
|
|
<p>The third argument is the value to bind to the parameter.
|
|
If the third parameter to sqlite3_bind_text() or sqlite3_bind_text16()
|
|
or sqlite3_bind_blob() is a NULL pointer then the fourth parameter
|
|
is ignored and the end result is the same as sqlite3_bind_null().
|
|
If the third parameter to sqlite3_bind_text() is not NULL, then
|
|
it should be a pointer to well-formed UTF8 text.
|
|
If the third parameter to sqlite3_bind_text16() is not NULL, then
|
|
it should be a pointer to well-formed UTF16 text.
|
|
If the third parameter to sqlite3_bind_text64() is not NULL, then
|
|
it should be a pointer to a well-formed unicode string that is
|
|
either UTF8 if the sixth parameter is SQLITE_UTF8, or UTF16
|
|
otherwise.</p>
|
|
|
|
<p><a name="byteorderdeterminationrules"></a>
|
|
The byte-order of
|
|
UTF16 input text is determined by the byte-order mark (BOM, U+FEFF)
|
|
found in first character, which is removed, or in the absence of a BOM
|
|
the byte order is the native byte order of the host
|
|
machine for sqlite3_bind_text16() or the byte order specified in
|
|
the 6th parameter for sqlite3_bind_text64().
|
|
If UTF16 input text contains invalid unicode
|
|
characters, then SQLite might change those invalid characters
|
|
into the unicode replacement character: U+FFFD.</p>
|
|
|
|
<p>In those routines that have a fourth argument, its value is the
|
|
number of bytes in the parameter. To be clear: the value is the
|
|
number of <u>bytes</u> in the value, not the number of characters.
|
|
If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16()
|
|
is negative, then the length of the string is
|
|
the number of bytes up to the first zero terminator.
|
|
If the fourth parameter to sqlite3_bind_blob() is negative, then
|
|
the behavior is undefined.
|
|
If a non-negative fourth parameter is provided to sqlite3_bind_text()
|
|
or sqlite3_bind_text16() or sqlite3_bind_text64() then
|
|
that parameter must be the byte offset
|
|
where the NUL terminator would occur assuming the string were NUL
|
|
terminated. If any NUL characters occurs at byte offsets less than
|
|
the value of the fourth parameter then the resulting string value will
|
|
contain embedded NULs. The result of expressions involving strings
|
|
with embedded NULs is undefined.</p>
|
|
|
|
<p>The fifth argument to the BLOB and string binding interfaces
|
|
is a destructor used to dispose of the BLOB or
|
|
string after SQLite has finished with it. The destructor is called
|
|
to dispose of the BLOB or string even if the call to the bind API fails,
|
|
except the destructor is not called if the third parameter is a NULL
|
|
pointer or the fourth parameter is negative.
|
|
If the fifth argument is
|
|
the special value <a href="../c3ref/c_static.html">SQLITE_STATIC</a>, then SQLite assumes that the
|
|
information is in static, unmanaged space and does not need to be freed.
|
|
If the fifth argument has the value <a href="../c3ref/c_static.html">SQLITE_TRANSIENT</a>, then
|
|
SQLite makes its own private copy of the data immediately, before
|
|
the sqlite3_bind_*() routine returns.</p>
|
|
|
|
<p>The sixth argument to sqlite3_bind_text64() must be one of
|
|
<a href="../c3ref/c_any.html">SQLITE_UTF8</a>, <a href="../c3ref/c_any.html">SQLITE_UTF16</a>, <a href="../c3ref/c_any.html">SQLITE_UTF16BE</a>, or <a href="../c3ref/c_any.html">SQLITE_UTF16LE</a>
|
|
to specify the encoding of the text in the third parameter. If
|
|
the sixth argument to sqlite3_bind_text64() is not one of the
|
|
allowed values shown above, or if the text encoding is different
|
|
from the encoding specified by the sixth parameter, then the behavior
|
|
is undefined.</p>
|
|
|
|
<p>The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
|
|
is filled with zeroes. A zeroblob uses a fixed amount of memory
|
|
(just an integer to hold its size) while it is being processed.
|
|
Zeroblobs are intended to serve as placeholders for BLOBs whose
|
|
content is later written using
|
|
<a href="../c3ref/blob_open.html">incremental BLOB I/O</a> routines.
|
|
A negative value for the zeroblob results in a zero-length BLOB.</p>
|
|
|
|
<p>The sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter in
|
|
<a href="../c3ref/stmt.html">prepared statement</a> S to have an SQL value of NULL, but to also be
|
|
associated with the pointer P of type T. D is either a NULL pointer or
|
|
a pointer to a destructor function for P. SQLite will invoke the
|
|
destructor D with a single argument of P when it is finished using
|
|
P. The T parameter should be a static string, preferably a string
|
|
literal. The sqlite3_bind_pointer() routine is part of the
|
|
<a href="../bindptr.html">pointer passing interface</a> added for SQLite 3.20.0.</p>
|
|
|
|
<p>If any of the sqlite3_bind_*() routines are called with a NULL pointer
|
|
for the <a href="../c3ref/stmt.html">prepared statement</a> or with a prepared statement for which
|
|
<a href="../c3ref/step.html">sqlite3_step()</a> has been called more recently than <a href="../c3ref/reset.html">sqlite3_reset()</a>,
|
|
then the call will return <a href="../rescode.html#misuse">SQLITE_MISUSE</a>. If any sqlite3_bind_()
|
|
routine is passed a <a href="../c3ref/stmt.html">prepared statement</a> that has been finalized, the
|
|
result is undefined and probably harmful.</p>
|
|
|
|
<p>Bindings are not cleared by the <a href="../c3ref/reset.html">sqlite3_reset()</a> routine.
|
|
Unbound parameters are interpreted as NULL.</p>
|
|
|
|
<p>The sqlite3_bind_* routines return <a href="../rescode.html#ok">SQLITE_OK</a> on success or an
|
|
<a href="../rescode.html">error code</a> if anything goes wrong.
|
|
<a href="../rescode.html#toobig">SQLITE_TOOBIG</a> might be returned if the size of a string or BLOB
|
|
exceeds limits imposed by <a href="../c3ref/limit.html">sqlite3_limit</a>(<a href="../c3ref/c_limit_attached.html#sqlitelimitlength">SQLITE_LIMIT_LENGTH</a>) or
|
|
<a href="../limits.html#max_length">SQLITE_MAX_LENGTH</a>.
|
|
<a href="../rescode.html#range">SQLITE_RANGE</a> is returned if the parameter
|
|
index is out of range. <a href="../rescode.html#nomem">SQLITE_NOMEM</a> is returned if malloc() fails.</p>
|
|
|
|
<p>See also: <a href="../c3ref/bind_parameter_count.html">sqlite3_bind_parameter_count()</a>,
|
|
<a href="../c3ref/bind_parameter_name.html">sqlite3_bind_parameter_name()</a>, and <a href="../c3ref/bind_parameter_index.html">sqlite3_bind_parameter_index()</a>.
|
|
</p><p>See also lists of
|
|
<a href="objlist.html">Objects</a>,
|
|
<a href="constlist.html">Constants</a>, and
|
|
<a href="funclist.html">Functions</a>.</p>
|