1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
|
<!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;
}
var antiRobot = 0;
function antiRobotGo(){
if( antiRobot!=3 ) return;
antiRobot = 7;
var j = document.getElementById("mtimelink");
if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
}
function antiRobotDefense(){
document.body.onmousedown=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousedown=null;
}
document.body.onmousemove=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousemove=null;
}
setTimeout(function(){
antiRobot |= 1;
antiRobotGo();
}, 100)
antiRobotGo();
}
antiRobotDefense();
</script>
<!-- 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 controls
or indicates the lifetime of the object referenced by the third parameter.
These three options exist:
(1) A destructor to dispose of the BLOB or string after SQLite has finished
with it may be passed. It 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.
(2) The special constant, <a href="../c3ref/c_static.html">SQLITE_STATIC</a>, may be passsed to indicate that
the application remains responsible for disposing of the object. In this
case, the object and the provided pointer to it must remain valid until
either the prepared statement is finalized or the same SQL parameter is
bound to something else, whichever occurs sooner.
(3) The constant, <a href="../c3ref/c_static.html">SQLITE_TRANSIENT</a>, may be passed to indicate that the
object is to be copied prior to the return from sqlite3_bind_*(). The
object and pointer to it must remain valid until then. SQLite will then
manage the lifetime of its private copy.</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>
|
