1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
3
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
4
<title>Binding Values To Prepared Statements</title>
5
<style type="text/css">
8
font-family: Verdana, sans-serif;
13
a:visited { color: #734559 }
15
.logo { position:absolute; margin:3px; }
31
.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }
32
.toolbar a:visited { color: white; }
33
.toolbar a:hover { color: #044a64; background: white; }
35
.content { margin: 5%; }
36
.content dt { font-weight:bold; }
37
.content dd { margin-bottom: 25px; margin-left:20%; }
38
.content ul { padding:0px; padding-left: 15px; margin:0px; }
41
.se { background: url(../images/se.gif) 100% 100% no-repeat #044a64}
42
.sw { background: url(../images/sw.gif) 0% 100% no-repeat }
43
.ne { background: url(../images/ne.gif) 100% 0% no-repeat }
44
.nw { background: url(../images/nw.gif) 0% 0% no-repeat }
46
/* Things for "fancyformat" documents start here. */
47
.fancy img+p {font-style:italic}
48
.fancy .codeblock i { color: darkblue; }
49
.fancy h1,.fancy h2,.fancy h3,.fancy h4 {font-weight:normal;color:#044a64}
50
.fancy h2 { margin-left: 10px }
51
.fancy h3 { margin-left: 20px }
52
.fancy h4 { margin-left: 30px }
53
.fancy th {white-space:nowrap;text-align:left;border-bottom:solid 1px #444}
54
.fancy th, .fancy td {padding: 0.2em 1ex; vertical-align:top}
55
.fancy #toc a { color: darkblue ; text-decoration: none }
56
.fancy .todo { color: #AA3333 ; font-style : italic }
57
.fancy .todo:before { content: 'TODO:' }
58
.fancy p.todo { border: solid #AA3333 1px; padding: 1ex }
59
.fancy img { display:block; }
60
.fancy :link:hover, .fancy :visited:hover { background: wheat }
61
.fancy p,.fancy ul,.fancy ol { margin: 1em 5ex }
62
.fancy li p { margin: 1em 0 }
63
/* End of "fancyformat" specific rules. */
69
<div><!-- container div to satisfy validator -->
71
<a href="../index.html">
72
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite Logo"
74
<div><!-- IE hack to prevent disappearing logo--></div>
75
<div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div>
77
<table width=100% style="clear:both"><tr><td>
78
<div class="se"><div class="sw"><div class="ne"><div class="nw">
79
<table width=100% style="padding:0;margin:0;cell-spacing:0"><tr>
82
<a href="../about.html">About</a>
83
<a href="../sitemap.html">Sitemap</a>
84
<a href="../docs.html">Documentation</a>
85
<a href="../download.html">Download</a>
86
<a href="../copyright.html">License</a>
87
<a href="../news.html">News</a>
88
<a href="../support.html">Support</a>
91
gMsg = "Search SQLite Docs..."
92
function entersearch() {
93
var q = document.getElementById("q");
94
if( q.value == gMsg ) { q.value = "" }
95
q.style.color = "black"
96
q.style.fontStyle = "normal"
98
function leavesearch() {
99
var q = document.getElementById("q");
100
if( q.value == "" ) {
102
q.style.color = "#044a64"
103
q.style.fontStyle = "italic"
108
<div style="padding:0 1em 0px 0;white-space:nowrap">
109
<form name=f method="GET" action="http://www.sqlite.org/search">
110
<input id=q name=q type=text
111
onfocus="entersearch()" onblur="leavesearch()" style="width:24ex;padding:1px 1ex; border:solid white 1px; font-size:0.9em ; font-style:italic;color:#044a64;" value="Search SQLite Docs...">
112
<input type=submit value="Go" style="border:solid white 1px;background-color:#044a64;color:white;font-size:0.9em;padding:0 1ex">
116
</div></div></div></div>
118
<div class=startsearch></div>
120
<a href="intro.html"><h2>SQLite C Interface</h2></a><h2>Binding Values To Prepared Statements</h2><blockquote><pre>int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
121
int sqlite3_bind_double(sqlite3_stmt*, int, double);
122
int sqlite3_bind_int(sqlite3_stmt*, int, int);
123
int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
124
int sqlite3_bind_null(sqlite3_stmt*, int);
125
int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
126
int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
127
int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
128
int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
129
</pre></blockquote><p>
130
In the SQL statement text input to <a href="../c3ref/prepare.html">sqlite3_prepare_v2()</a> and its variants,
131
literals may be replaced by a <a href="../lang_expr.html#varparam">parameter</a> that matches one of following
142
<p>In the templates above, NNN represents an integer literal,
143
and VVV represents an alphanumeric identifier. The values of these
144
parameters (also called "host parameter names" or "SQL parameters")
145
can be set using the sqlite3_bind_*() routines defined here.</p>
147
<p>The first argument to the sqlite3_bind_*() routines is always
148
a pointer to the <a href="../c3ref/stmt.html">sqlite3_stmt</a> object returned from
149
<a href="../c3ref/prepare.html">sqlite3_prepare_v2()</a> or its variants.</p>
151
<p>The second argument is the index of the SQL parameter to be set.
152
The leftmost SQL parameter has an index of 1. When the same named
153
SQL parameter is used more than once, second and subsequent
154
occurrences have the same index as the first occurrence.
155
The index for named parameters can be looked up using the
156
<a href="../c3ref/bind_parameter_index.html">sqlite3_bind_parameter_index()</a> API if desired. The index
157
for "?NNN" parameters is the value of NNN.
158
The NNN value must be between 1 and the <a href="../c3ref/limit.html">sqlite3_limit()</a>
159
parameter <a href="../c3ref/c_limit_attached.html#sqlitelimitvariablenumber">SQLITE_LIMIT_VARIABLE_NUMBER</a> (default value: 999).</p>
161
<p>The third argument is the value to bind to the parameter.</p>
163
<p>In those routines that have a fourth argument, its value is the
164
number of bytes in the parameter. To be clear: the value is the
165
number of <u>bytes</u> in the value, not the number of characters.
166
If the fourth parameter is negative, the length of the string is
167
the number of bytes up to the first zero terminator.
168
If a non-negative fourth parameter is provided to sqlite3_bind_text()
169
or sqlite3_bind_text16() then that parameter must be the byte offset
170
where the NUL terminator would occur assuming the string were NUL
171
terminated. If any NUL characters occur at byte offsets less than
172
the value of the fourth parameter then the resulting string value will
173
contain embedded NULs. The result of expressions involving strings
174
with embedded NULs is undefined.</p>
176
<p>The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
177
sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
178
string after SQLite has finished with it. The destructor is called
179
to dispose of the BLOB or string even if the call to sqlite3_bind_blob(),
180
sqlite3_bind_text(), or sqlite3_bind_text16() fails.
181
If the fifth argument is
182
the special value <a href="../c3ref/c_static.html">SQLITE_STATIC</a>, then SQLite assumes that the
183
information is in static, unmanaged space and does not need to be freed.
184
If the fifth argument has the value <a href="../c3ref/c_static.html">SQLITE_TRANSIENT</a>, then
185
SQLite makes its own private copy of the data immediately, before
186
the sqlite3_bind_*() routine returns.</p>
188
<p>The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
189
is filled with zeroes. A zeroblob uses a fixed amount of memory
190
(just an integer to hold its size) while it is being processed.
191
Zeroblobs are intended to serve as placeholders for BLOBs whose
192
content is later written using
193
<a href="../c3ref/blob_open.html">incremental BLOB I/O</a> routines.
194
A negative value for the zeroblob results in a zero-length BLOB.</p>
196
<p>If any of the sqlite3_bind_*() routines are called with a NULL pointer
197
for the <a href="../c3ref/stmt.html">prepared statement</a> or with a prepared statement for which
198
<a href="../c3ref/step.html">sqlite3_step()</a> has been called more recently than <a href="../c3ref/reset.html">sqlite3_reset()</a>,
199
then the call will return <a href="../c3ref/c_abort.html">SQLITE_MISUSE</a>. If any sqlite3_bind_()
200
routine is passed a <a href="../c3ref/stmt.html">prepared statement</a> that has been finalized, the
201
result is undefined and probably harmful.</p>
203
<p>Bindings are not cleared by the <a href="../c3ref/reset.html">sqlite3_reset()</a> routine.
204
Unbound parameters are interpreted as NULL.</p>
206
<p>The sqlite3_bind_* routines return <a href="../c3ref/c_abort.html">SQLITE_OK</a> on success or an
207
<a href="../c3ref/c_abort.html">error code</a> if anything goes wrong.
208
<a href="../c3ref/c_abort.html">SQLITE_RANGE</a> is returned if the parameter
209
index is out of range. <a href="../c3ref/c_abort.html">SQLITE_NOMEM</a> is returned if malloc() fails.</p>
211
<p>See also: <a href="../c3ref/bind_parameter_count.html">sqlite3_bind_parameter_count()</a>,
212
<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>.
213
</p><p>See also lists of
214
<a href="objlist.html">Objects</a>,
215
<a href="constlist.html">Constants</a>, and
216
<a href="funclist.html">Functions</a>.</p>
added
removed
c3ref/bind_blob.html
