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
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html><head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Compiling An SQL Statement</title>
<style type="text/css">
body {
margin: auto;
font-family: Verdana, sans-serif;
padding: 8px 1%;
}
a { color: #044a64 }
a:visited { color: #734559 }
.logo { position:absolute; margin:3px; }
.tagline {
float:right;
text-align:right;
font-style:italic;
width:300px;
margin:12px;
margin-top:58px;
}
.menubar {
clear: both;
border-radius: 8px;
background: #044a64;
padding: 0px;
margin: 0px;
cell-spacing: 0px;
}
.toolbar {
text-align: center;
line-height: 1.6em;
margin: 0;
padding: 0px 8px;
}
.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }
.toolbar a:visited { color: white; }
.toolbar a:hover { color: #044a64; background: white; }
.content { margin: 5%; }
.content dt { font-weight:bold; }
.content dd { margin-bottom: 25px; margin-left:20%; }
.content ul { padding:0px; padding-left: 15px; margin:0px; }
/* Things for "fancyformat" documents start here. */
.fancy img+p {font-style:italic}
.fancy .codeblock i { color: darkblue; }
.fancy h1,.fancy h2,.fancy h3,.fancy h4 {font-weight:normal;color:#044a64}
.fancy h2 { margin-left: 10px }
.fancy h3 { margin-left: 20px }
.fancy h4 { margin-left: 30px }
.fancy th {white-space:nowrap;text-align:left;border-bottom:solid 1px #444}
.fancy th, .fancy td {padding: 0.2em 1ex; vertical-align:top}
.fancy #toc a { color: darkblue ; text-decoration: none }
.fancy .todo { color: #AA3333 ; font-style : italic }
.fancy .todo:before { content: 'TODO:' }
.fancy p.todo { border: solid #AA3333 1px; padding: 1ex }
.fancy img { display:block; }
.fancy :link:hover, .fancy :visited:hover { background: wheat }
.fancy p,.fancy ul,.fancy ol { margin: 1em 5ex }
.fancy li p { margin: 1em 0 }
/* End of "fancyformat" specific rules. */
</style>
</head>
<body>
<div><!-- container div to satisfy validator -->
<a href="../index.html">
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite Logo"
border="0"></a>
<div><!-- IE hack to prevent disappearing logo--></div>
<div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div>
<table width=100% class="menubar"><tr>
<td width=100%>
<div class="toolbar">
<a href="../about.html">About</a>
<a href="../sitemap.html">Sitemap</a>
<a href="../docs.html">Documentation</a>
<a href="../download.html">Download</a>
<a href="../copyright.html">License</a>
<a href="../news.html">News</a>
<a href="../support.html">Support</a>
</div>
<script>
gMsg = "Search SQLite Docs..."
function entersearch() {
var q = document.getElementById("q");
if( q.value == gMsg ) { q.value = "" }
q.style.color = "black"
q.style.fontStyle = "normal"
}
function leavesearch() {
var q = document.getElementById("q");
if( q.value == "" ) {
q.value = gMsg
q.style.color = "#044a64"
q.style.fontStyle = "italic"
}
}
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>
<td>
<div style="padding:0 1em 0px 0;white-space:nowrap">
<form name=f method="GET" action="http://www.sqlite.org/search">
<input id=q name=q type=text
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...">
<input type=submit value="Go" style="border:solid white 1px;background-color:#044a64;color:white;font-size:0.9em;padding:0 1ex">
</form>
</div>
</table>
<div class=startsearch></div>
<a href="intro.html"><h2>SQLite C Interface</h2></a><h2>Compiling An SQL Statement</h2><blockquote><pre>int sqlite3_prepare(
sqlite3 *db, /* Database handle */
const char *zSql, /* SQL statement, UTF-8 encoded */
int nByte, /* Maximum length of zSql in bytes. */
sqlite3_stmt **ppStmt, /* OUT: Statement handle */
const char **pzTail /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare_v2(
sqlite3 *db, /* Database handle */
const char *zSql, /* SQL statement, UTF-8 encoded */
int nByte, /* Maximum length of zSql in bytes. */
sqlite3_stmt **ppStmt, /* OUT: Statement handle */
const char **pzTail /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare16(
sqlite3 *db, /* Database handle */
const void *zSql, /* SQL statement, UTF-16 encoded */
int nByte, /* Maximum length of zSql in bytes. */
sqlite3_stmt **ppStmt, /* OUT: Statement handle */
const void **pzTail /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare16_v2(
sqlite3 *db, /* Database handle */
const void *zSql, /* SQL statement, UTF-16 encoded */
int nByte, /* Maximum length of zSql in bytes. */
sqlite3_stmt **ppStmt, /* OUT: Statement handle */
const void **pzTail /* OUT: Pointer to unused portion of zSql */
);
</pre></blockquote><p>
To execute an SQL query, it must first be compiled into a byte-code
program using one of these routines.</p>
<p>The first argument, "db", is a <a href="../c3ref/sqlite3.html">database connection</a> obtained from a
prior successful call to <a href="../c3ref/open.html">sqlite3_open()</a>, <a href="../c3ref/open.html">sqlite3_open_v2()</a> or
<a href="../c3ref/open.html">sqlite3_open16()</a>. The database connection must not have been closed.</p>
<p>The second argument, "zSql", is the statement to be compiled, encoded
as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2()
interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2()
use UTF-16.</p>
<p>If the nByte argument is less than zero, then zSql is read up to the
first zero terminator. If nByte is non-negative, then it is the maximum
number of bytes read from zSql. When nByte is non-negative, the
zSql string ends at either the first '\000' or '\u0000' character or
the nByte-th byte, whichever comes first. If the caller knows
that the supplied string is nul-terminated, then there is a small
performance advantage to be gained by passing an nByte parameter that
is equal to the number of bytes in the input string <i>including</i>
the nul-terminator bytes as this saves SQLite from having to
make a copy of the input string.</p>
<p>If pzTail is not NULL then *pzTail is made to point to the first byte
past the end of the first SQL statement in zSql. These routines only
compile the first statement in zSql, so *pzTail is left pointing to
what remains uncompiled.</p>
<p>*ppStmt is left pointing to a compiled <a href="../c3ref/stmt.html">prepared statement</a> that can be
executed using <a href="../c3ref/step.html">sqlite3_step()</a>. If there is an error, *ppStmt is set
to NULL. If the input text contains no SQL (if the input is an empty
string or a comment) then *ppStmt is set to NULL.
The calling procedure is responsible for deleting the compiled
SQL statement using <a href="../c3ref/finalize.html">sqlite3_finalize()</a> after it has finished with it.
ppStmt may not be NULL.</p>
<p>On success, the sqlite3_prepare() family of routines return <a href="../rescode.html#ok">SQLITE_OK</a>;
otherwise an <a href="../rescode.html">error code</a> is returned.</p>
<p>The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
recommended for all new programs. The two older interfaces are retained
for backwards compatibility, but their use is discouraged.
In the "v2" interfaces, the prepared statement
that is returned (the <a href="../c3ref/stmt.html">sqlite3_stmt</a> object) contains a copy of the
original SQL text. This causes the <a href="../c3ref/step.html">sqlite3_step()</a> interface to
behave differently in three ways:</p>
<p><ol>
<li>
If the database schema changes, instead of returning <a href="../rescode.html#schema">SQLITE_SCHEMA</a> as it
always used to do, <a href="../c3ref/step.html">sqlite3_step()</a> will automatically recompile the SQL
statement and try to run it again. As many as <a href="../compile.html#max_schema_retry">SQLITE_MAX_SCHEMA_RETRY</a>
retries will occur before sqlite3_step() gives up and returns an error.
</li></p>
<p><li>
When an error occurs, <a href="../c3ref/step.html">sqlite3_step()</a> will return one of the detailed
<a href="../rescode.html">error codes</a> or <a href="../rescode.html#extrc">extended error codes</a>. The legacy behavior was that
<a href="../c3ref/step.html">sqlite3_step()</a> would only return a generic <a href="../rescode.html#error">SQLITE_ERROR</a> result code
and the application would have to make a second call to <a href="../c3ref/reset.html">sqlite3_reset()</a>
in order to find the underlying cause of the problem. With the "v2" prepare
interfaces, the underlying reason for the error is returned immediately.
</li></p>
<p><li>
If the specific value bound to <a href="../lang_expr.html#varparam">host parameter</a> in the
WHERE clause might influence the choice of query plan for a statement,
then the statement will be automatically recompiled, as if there had been
a schema change, on the first <a href="../c3ref/step.html">sqlite3_step()</a> call following any change
to the <a href="../c3ref/bind_blob.html">bindings</a> of that <a href="../lang_expr.html#varparam">parameter</a>.
The specific value of WHERE-clause <a href="../lang_expr.html#varparam">parameter</a> might influence the
choice of query plan if the parameter is the left-hand side of a <a href="../lang_expr.html#like">LIKE</a>
or <a href="../lang_expr.html#glob">GLOB</a> operator or if the parameter is compared to an indexed column
and the <a href="../compile.html#enable_stat3">SQLITE_ENABLE_STAT3</a> compile-time option is enabled.
</li>
</ol>
</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>
|
