Debian Codegraph @

www/c3ref/prepare.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>Compiling An SQL Statement</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 statement compiler} sqlite3_prepare sqlite3_prepare16 sqlite3_prepare16_v2 sqlite3_prepare16_v3 sqlite3_prepare_v2 sqlite3_prepare_v3 -->
119 <div class=nosearch>
120 <a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
121 <h2>Compiling An SQL Statement</h2>
122 </div>
123 <blockquote><pre>
124 int sqlite3_prepare(
125 sqlite3 *db, /* Database handle */
126 const char *zSql, /* SQL statement, UTF-8 encoded */
127 int nByte, /* Maximum length of zSql in bytes. */
128 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
129 const char **pzTail /* OUT: Pointer to unused portion of zSql */
130 );
131 int sqlite3_prepare_v2(
132 sqlite3 *db, /* Database handle */
133 const char *zSql, /* SQL statement, UTF-8 encoded */
134 int nByte, /* Maximum length of zSql in bytes. */
135 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
136 const char **pzTail /* OUT: Pointer to unused portion of zSql */
137 );
138 int sqlite3_prepare_v3(
139 sqlite3 *db, /* Database handle */
140 const char *zSql, /* SQL statement, UTF-8 encoded */
141 int nByte, /* Maximum length of zSql in bytes. */
142 unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
143 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
144 const char **pzTail /* OUT: Pointer to unused portion of zSql */
145 );
146 int sqlite3_prepare16(
147 sqlite3 *db, /* Database handle */
148 const void *zSql, /* SQL statement, UTF-16 encoded */
149 int nByte, /* Maximum length of zSql in bytes. */
150 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
151 const void **pzTail /* OUT: Pointer to unused portion of zSql */
152 );
153 int sqlite3_prepare16_v2(
154 sqlite3 *db, /* Database handle */
155 const void *zSql, /* SQL statement, UTF-16 encoded */
156 int nByte, /* Maximum length of zSql in bytes. */
157 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
158 const void **pzTail /* OUT: Pointer to unused portion of zSql */
159 );
160 int sqlite3_prepare16_v3(
161 sqlite3 *db, /* Database handle */
162 const void *zSql, /* SQL statement, UTF-16 encoded */
163 int nByte, /* Maximum length of zSql in bytes. */
164 unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
165 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
166 const void **pzTail /* OUT: Pointer to unused portion of zSql */
167 );
168 </pre></blockquote>
169 <p>
170 To execute an SQL statement, it must first be compiled into a byte-code
171 program using one of these routines. Or, in other words, these routines
172 are constructors for the <a href="../c3ref/stmt.html">prepared statement</a> object.</p>
173
174 <p>The preferred routine to use is <a href="../c3ref/prepare.html">sqlite3_prepare_v2()</a>. The
175 <a href="../c3ref/prepare.html">sqlite3_prepare()</a> interface is legacy and should be avoided.
176 <a href="../c3ref/prepare.html">sqlite3_prepare_v3()</a> has an extra
177 <a href="../c3ref/c_prepare_dont_log.html#sqlitepreparefromddl">"prepFlags" option</a> that is sometimes
178 needed for special purpose or to pass along security restrictions.</p>
179
180 <p>The use of the UTF-8 interfaces is preferred, as SQLite currently
181 does all parsing using UTF-8. The UTF-16 interfaces are provided
182 as a convenience. The UTF-16 interfaces work by converting the
183 input text into UTF-8, then invoking the corresponding UTF-8 interface.</p>
184
185 <p>The first argument, "db", is a <a href="../c3ref/sqlite3.html">database connection</a> obtained from a
186 prior successful call to <a href="../c3ref/open.html">sqlite3_open()</a>, <a href="../c3ref/open.html">sqlite3_open_v2()</a> or
187 <a href="../c3ref/open.html">sqlite3_open16()</a>. The database connection must not have been closed.</p>
188
189 <p>The second argument, "zSql", is the statement to be compiled, encoded
190 as either UTF-8 or UTF-16. The sqlite3_prepare(), sqlite3_prepare_v2(),
191 and sqlite3_prepare_v3()
192 interfaces use UTF-8, and sqlite3_prepare16(), sqlite3_prepare16_v2(),
193 and sqlite3_prepare16_v3() use UTF-16.</p>
194
195 <p>If the nByte argument is negative, then zSql is read up to the
196 first zero terminator. If nByte is positive, then it is the maximum
197 number of bytes read from zSql. When nByte is positive, zSql is read
198 up to the first zero terminator or until the nByte bytes have been read,
199 whichever comes first. If nByte is zero, then no prepared
200 statement is generated.
201 If the caller knows that the supplied string is nul-terminated, then
202 there is a small performance advantage to passing an nByte parameter that
203 is the number of bytes in the input string <i>including</i>
204 the nul-terminator.
205 Note that nByte measures the length of the input in bytes, not
206 characters, even for the UTF-16 interfaces.</p>
207
208 <p>If pzTail is not NULL then *pzTail is made to point to the first byte
209 past the end of the first SQL statement in zSql. These routines only
210 compile the first statement in zSql, so *pzTail is left pointing to
211 what remains uncompiled.</p>
212
213 <p>*ppStmt is left pointing to a compiled <a href="../c3ref/stmt.html">prepared statement</a> that can be
214 executed using <a href="../c3ref/step.html">sqlite3_step()</a>. If there is an error, *ppStmt is set
215 to NULL. If the input text contains no SQL (if the input is an empty
216 string or a comment) then *ppStmt is set to NULL.
217 The calling procedure is responsible for deleting the compiled
218 SQL statement using <a href="../c3ref/finalize.html">sqlite3_finalize()</a> after it has finished with it.
219 ppStmt may not be NULL.</p>
220
221 <p>On success, the sqlite3_prepare() family of routines return <a href="../rescode.html#ok">SQLITE_OK</a>;
222 otherwise an <a href="../rescode.html">error code</a> is returned.</p>
223
224 <p>The sqlite3_prepare_v2(), sqlite3_prepare_v3(), sqlite3_prepare16_v2(),
225 and sqlite3_prepare16_v3() interfaces are recommended for all new programs.
226 The older interfaces (sqlite3_prepare() and sqlite3_prepare16())
227 are retained for backwards compatibility, but their use is discouraged.
228 In the "vX" interfaces, the prepared statement
229 that is returned (the <a href="../c3ref/stmt.html">sqlite3_stmt</a> object) contains a copy of the
230 original SQL text. This causes the <a href="../c3ref/step.html">sqlite3_step()</a> interface to
231 behave differently in three ways:</p>
232
233 <p><ol>
234 <li>
235 If the database schema changes, instead of returning <a href="../rescode.html#schema">SQLITE_SCHEMA</a> as it
236 always used to do, <a href="../c3ref/step.html">sqlite3_step()</a> will automatically recompile the SQL
237 statement and try to run it again. As many as <a href="../compile.html#max_schema_retry">SQLITE_MAX_SCHEMA_RETRY</a>
238 retries will occur before sqlite3_step() gives up and returns an error.
239 </li></p>
240
241 <p><li>
242 When an error occurs, <a href="../c3ref/step.html">sqlite3_step()</a> will return one of the detailed
243 <a href="../rescode.html">error codes</a> or <a href="../rescode.html#extrc">extended error codes</a>. The legacy behavior was that
244 <a href="../c3ref/step.html">sqlite3_step()</a> would only return a generic <a href="../rescode.html#error">SQLITE_ERROR</a> result code
245 and the application would have to make a second call to <a href="../c3ref/reset.html">sqlite3_reset()</a>
246 in order to find the underlying cause of the problem. With the "v2" prepare
247 interfaces, the underlying reason for the error is returned immediately.
248 </li></p>
249
250 <p><li>
251 If the specific value bound to a <a href="../lang_expr.html#varparam">host parameter</a> in the
252 WHERE clause might influence the choice of query plan for a statement,
253 then the statement will be automatically recompiled, as if there had been
254 a schema change, on the first <a href="../c3ref/step.html">sqlite3_step()</a> call following any change
255 to the <a href="../c3ref/bind_blob.html">bindings</a> of that <a href="../lang_expr.html#varparam">parameter</a>.
256 The specific value of a WHERE-clause <a href="../lang_expr.html#varparam">parameter</a> might influence the
257 choice of query plan if the parameter is the left-hand side of a <a href="../lang_expr.html#like">LIKE</a>
258 or <a href="../lang_expr.html#glob">GLOB</a> operator or if the parameter is compared to an indexed column
259 and the <a href="../compile.html#enable_stat4">SQLITE_ENABLE_STAT4</a> compile-time option is enabled.
260 </li>
261 </ol></p>
262
263 <p><p>sqlite3_prepare_v3() differs from sqlite3_prepare_v2() only in having
264 the extra prepFlags parameter, which is a bit array consisting of zero or
265 more of the <a href="../c3ref/c_prepare_dont_log.html#sqlitepreparepersistent">SQLITE_PREPARE_*</a> flags. The
266 sqlite3_prepare_v2() interface works exactly the same as
267 sqlite3_prepare_v3() with a zero prepFlags parameter.
268 </p><p>See also lists of
269 <a href="../c3ref/objlist.html">Objects</a>,
270 <a href="../c3ref/constlist.html">Constants</a>, and
271 <a href="../c3ref/funclist.html">Functions</a>.</p>
272