Debian Codegraph @

www/c3ref/bind_blob.html

raw
1 <!DOCTYPE html>
2 <html><head>
3 <meta name="viewport" content="width=device-width, initial-scale=1.0">
4 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
5 <link href="../sqlite.css" rel="stylesheet">
6 <title>Binding Values To Prepared Statements</title>
7 <!-- path=../ -->
8 </head>
9 <body>
10 <div class=nosearch>
11 <a href="../index.html">
12 <img class="logo" src="../images/sqlite370_banner.svg" alt="SQLite" border="0">
13 </a>
14 <div><!-- IE hack to prevent disappearing logo --></div>
15 <div class="tagline desktoponly">
16 Small. Fast. Reliable.<br>Choose any three.
17 </div>
18 <div class="menu mainmenu">
19 <ul>
20 <li><a href="../index.html">Home</a>
21 <li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
22 <li class='wideonly'><a href='../about.html'>About</a>
23 <li class='desktoponly'><a href="../docs.html">Documentation</a>
24 <li class='desktoponly'><a href="../download.html">Download</a>
25 <li class='wideonly'><a href='../copyright.html'>License</a>
26 <li class='desktoponly'><a href="../support.html">Support</a>
27 <li class='desktoponly'><a href="../prosupport.html">Purchase</a>
28 <li class='search' id='search_menubutton'>
29 <a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
30 </ul>
31 </div>
32 <div class="menu submenu" id="submenu">
33 <ul>
34 <li><a href='../about.html'>About</a>
35 <li><a href='../docs.html'>Documentation</a>
36 <li><a href='../download.html'>Download</a>
37 <li><a href='../support.html'>Support</a>
38 <li><a href='../prosupport.html'>Purchase</a>
39 </ul>
40 </div>
41 <div class="searchmenu" id="searchmenu">
42 <form method="GET" action="../search">
43 <select name="s" id="searchtype">
44 <option value="d">Search Documentation</option>
45 <option value="c">Search Changelog</option>
46 </select>
47 <input type="text" name="q" id="searchbox" value="">
48 <input type="submit" value="Go">
49 </form>
50 </div>
51 </div>
52 <script>
53 function toggle_div(nm) {
54 var w = document.getElementById(nm);
55 if( w.style.display=="block" ){
56 w.style.display = "none";
57 }else{
58 w.style.display = "block";
59 }
60 }
61 function toggle_search() {
62 var w = document.getElementById("searchmenu");
63 if( w.style.display=="block" ){
64 w.style.display = "none";
65 } else {
66 w.style.display = "block";
67 setTimeout(function(){
68 document.getElementById("searchbox").focus()
69 }, 30);
70 }
71 }
72 function div_off(nm){document.getElementById(nm).style.display="none";}
73 window.onbeforeunload = function(e){div_off("submenu");}
74 /* Disable the Search feature if we are not operating from CGI, since */
75 /* Search is accomplished using CGI and will not work without it. */
76 if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
77 document.getElementById("search_menubutton").style.display = "none";
78 }
79 /* Used by the Hide/Show button beside syntax diagrams, to toggle the */
80 function hideorshow(btn,obj){
81 var x = document.getElementById(obj);
82 var b = document.getElementById(btn);
83 if( x.style.display!='none' ){
84 x.style.display = 'none';
85 b.innerHTML='show';
86 }else{
87 x.style.display = '';
88 b.innerHTML='hide';
89 }
90 return false;
91 }
92 var antiRobot = 0;
93 function antiRobotGo(){
94 if( antiRobot!=3 ) return;
95 antiRobot = 7;
96 var j = document.getElementById("mtimelink");
97 if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
98 }
99 function antiRobotDefense(){
100 document.body.onmousedown=function(){
101 antiRobot |= 2;
102 antiRobotGo();
103 document.body.onmousedown=null;
104 }
105 document.body.onmousemove=function(){
106 antiRobot |= 2;
107 antiRobotGo();
108 document.body.onmousemove=null;
109 }
110 setTimeout(function(){
111 antiRobot |= 1;
112 antiRobotGo();
113 }, 100)
114 antiRobotGo();
115 }
116 antiRobotDefense();
117 </script>
118 <!-- 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 -->
119 <div class=nosearch>
120 <a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
121 <h2>Binding Values To Prepared Statements</h2>
122 </div>
123 <blockquote><pre>
124 int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
125 int sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64,
126 void(*)(void*));
127 int sqlite3_bind_double(sqlite3_stmt*, int, double);
128 int sqlite3_bind_int(sqlite3_stmt*, int, int);
129 int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
130 int sqlite3_bind_null(sqlite3_stmt*, int);
131 int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*));
132 int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
133 int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64,
134 void(*)(void*), unsigned char encoding);
135 int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
136 int sqlite3_bind_pointer(sqlite3_stmt*, int, void*, const char*,void(*)(void*));
137 int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
138 int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64);
139 </pre></blockquote>
140 <p>
141 In the SQL statement text input to <a href="../c3ref/prepare.html">sqlite3_prepare_v2()</a> and its variants,
142 literals may be replaced by a <a href="../lang_expr.html#varparam">parameter</a> that matches one of the following
143 templates:</p>
144
145 <p><ul>
146 <li> ?
147 <li> ?NNN
148 <li> :VVV
149 <li> @VVV
150 <li> $VVV
151 </ul></p>
152
153 <p>In the templates above, NNN represents an integer literal,
154 and VVV represents an alphanumeric identifier. The values of these
155 parameters (also called "host parameter names" or "SQL parameters")
156 can be set using the sqlite3_bind_*() routines defined here.</p>
157
158 <p>The first argument to the sqlite3_bind_*() routines is always
159 a pointer to the <a href="../c3ref/stmt.html">sqlite3_stmt</a> object returned from
160 <a href="../c3ref/prepare.html">sqlite3_prepare_v2()</a> or its variants.</p>
161
162 <p>The second argument is the index of the SQL parameter to be set.
163 The leftmost SQL parameter has an index of 1. When the same named
164 SQL parameter is used more than once, second and subsequent
165 occurrences have the same index as the first occurrence.
166 The index for named parameters can be looked up using the
167 <a href="../c3ref/bind_parameter_index.html">sqlite3_bind_parameter_index()</a> API if desired. The index
168 for "?NNN" parameters is the value of NNN.
169 The NNN value must be between 1 and the <a href="../c3ref/limit.html">sqlite3_limit()</a>
170 parameter <a href="../c3ref/c_limit_attached.html#sqlitelimitvariablenumber">SQLITE_LIMIT_VARIABLE_NUMBER</a> (default value: 32766).</p>
171
172 <p>The third argument is the value to bind to the parameter.
173 If the third parameter to sqlite3_bind_text() or sqlite3_bind_text16()
174 or sqlite3_bind_blob() is a NULL pointer then the fourth parameter
175 is ignored and the end result is the same as sqlite3_bind_null().
176 If the third parameter to sqlite3_bind_text() is not NULL, then
177 it should be a pointer to well-formed UTF8 text.
178 If the third parameter to sqlite3_bind_text16() is not NULL, then
179 it should be a pointer to well-formed UTF16 text.
180 If the third parameter to sqlite3_bind_text64() is not NULL, then
181 it should be a pointer to a well-formed unicode string that is
182 either UTF8 if the sixth parameter is SQLITE_UTF8 or SQLITE_UTF8_ZT,
183 or UTF16 otherwise.</p>
184
185 <p><a name="byteorderdeterminationrules"></a>
186 The byte-order of
187 UTF16 input text is determined by the byte-order mark (BOM, U+FEFF)
188 found in the first character, which is removed, or in the absence of a BOM
189 the byte order is the native byte order of the host
190 machine for sqlite3_bind_text16() or the byte order specified in
191 the 6th parameter for sqlite3_bind_text64().
192 If UTF16 input text contains invalid unicode
193 characters, then SQLite might change those invalid characters
194 into the unicode replacement character: U+FFFD.</p>
195
196 <p>In those routines that have a fourth argument, its value is the
197 number of bytes in the parameter. To be clear: the value is the
198 number of <u>bytes</u> in the value, not the number of characters.
199 If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16()
200 is negative, then the length of the string is
201 the number of bytes up to the first zero terminator.
202 If the fourth parameter to sqlite3_bind_blob() is negative, then
203 the behavior is undefined.
204 If a non-negative fourth parameter is provided to sqlite3_bind_text()
205 or sqlite3_bind_text16() or sqlite3_bind_text64() then
206 that parameter must be the byte offset
207 where the NUL terminator would occur assuming the string were NUL
208 terminated. If any NUL characters occur at byte offsets less than
209 the value of the fourth parameter then the resulting string value will
210 contain embedded NULs. The result of expressions involving strings
211 with embedded NULs is undefined.</p>
212
213 <p>The fifth argument to the BLOB and string binding interfaces controls
214 or indicates the lifetime of the object referenced by the third parameter.
215 These three options exist:
216 (1) A destructor to dispose of the BLOB or string after SQLite has finished
217 with it may be passed. It is called to dispose of the BLOB or string even
218 if the call to the bind API fails, except the destructor is not called if
219 the third parameter is a NULL pointer or the fourth parameter is negative.
220 (2) The special constant, <a href="../c3ref/c_static.html">SQLITE_STATIC</a>, may be passed to indicate that
221 the application remains responsible for disposing of the object. In this
222 case, the object and the provided pointer to it must remain valid until
223 either the prepared statement is finalized or the same SQL parameter is
224 bound to something else, whichever occurs sooner.
225 (3) The constant, <a href="../c3ref/c_static.html">SQLITE_TRANSIENT</a>, may be passed to indicate that the
226 object is to be copied prior to the return from sqlite3_bind_*(). The
227 object and pointer to it must remain valid until then. SQLite will then
228 manage the lifetime of its private copy.</p>
229
230 <p>The sixth argument (the E argument)
231 to sqlite3_bind_text64(S,K,Z,N,D,E) must be one of
232 <a href="../c3ref/c_any.html#sqliteutf8">SQLITE_UTF8</a>, <a href="../c3ref/c_any.html#sqliteutf8zt">SQLITE_UTF8_ZT</a>, <a href="../c3ref/c_any.html#sqliteutf16">SQLITE_UTF16</a>, <a href="../c3ref/c_any.html#sqliteutf16be">SQLITE_UTF16BE</a>,
233 or <a href="../c3ref/c_any.html#sqliteutf16le">SQLITE_UTF16LE</a> to specify the encoding of the text in the
234 third parameter, Z. The special value <a href="../c3ref/c_any.html#sqliteutf8zt">SQLITE_UTF8_ZT</a> means that the
235 string argument is both UTF-8 encoded and is zero-terminated. In other
236 words, SQLITE_UTF8_ZT means that the Z array is allocated to hold at
237 least N+1 bytes and that the Z&#91;N&#93; byte is zero. If
238 the E argument to sqlite3_bind_text64(S,K,Z,N,D,E) is not one of the
239 allowed values shown above, or if the text encoding is different
240 from the encoding specified by the sixth parameter, then the behavior
241 is undefined.</p>
242
243 <p>The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
244 is filled with zeroes. A zeroblob uses a fixed amount of memory
245 (just an integer to hold its size) while it is being processed.
246 Zeroblobs are intended to serve as placeholders for BLOBs whose
247 content is later written using
248 <a href="../c3ref/blob_open.html">incremental BLOB I/O</a> routines.
249 A negative value for the zeroblob results in a zero-length BLOB.</p>
250
251 <p>The sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter in
252 <a href="../c3ref/stmt.html">prepared statement</a> S to have an SQL value of NULL, but to also be
253 associated with the pointer P of type T. D is either a NULL pointer or
254 a pointer to a destructor function for P. SQLite will invoke the
255 destructor D with a single argument of P when it is finished using
256 P, even if the call to sqlite3_bind_pointer() fails. Due to a
257 historical design quirk, results are undefined if D is
258 SQLITE_TRANSIENT. The T parameter should be a static string,
259 preferably a string literal. The sqlite3_bind_pointer() routine is
260 part of the <a href="../bindptr.html">pointer passing interface</a> added for SQLite 3.20.0.</p>
261
262 <p>If any of the sqlite3_bind_*() routines are called with a NULL pointer
263 for the <a href="../c3ref/stmt.html">prepared statement</a> or with a prepared statement for which
264 <a href="../c3ref/step.html">sqlite3_step()</a> has been called more recently than <a href="../c3ref/reset.html">sqlite3_reset()</a>,
265 then the call will return <a href="../rescode.html#misuse">SQLITE_MISUSE</a>. If any sqlite3_bind_()
266 routine is passed a <a href="../c3ref/stmt.html">prepared statement</a> that has been finalized, the
267 result is undefined and probably harmful.</p>
268
269 <p>Bindings are not cleared by the <a href="../c3ref/reset.html">sqlite3_reset()</a> routine.
270 Unbound parameters are interpreted as NULL.</p>
271
272 <p>The sqlite3_bind_* routines return <a href="../rescode.html#ok">SQLITE_OK</a> on success or an
273 <a href="../rescode.html">error code</a> if anything goes wrong.
274 <a href="../rescode.html#toobig">SQLITE_TOOBIG</a> might be returned if the size of a string or BLOB
275 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
276 <a href="../limits.html#max_length">SQLITE_MAX_LENGTH</a>.
277 <a href="../rescode.html#range">SQLITE_RANGE</a> is returned if the parameter
278 index is out of range. <a href="../rescode.html#nomem">SQLITE_NOMEM</a> is returned if malloc() fails.</p>
279
280 <p>See also: <a href="../c3ref/bind_parameter_count.html">sqlite3_bind_parameter_count()</a>,
281 <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>.
282 </p><p>See also lists of
283 <a href="../c3ref/objlist.html">Objects</a>,
284 <a href="../c3ref/constlist.html">Constants</a>, and
285 <a href="../c3ref/funclist.html">Functions</a>.</p>
286