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
|
<!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>Evaluate 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>Evaluate An SQL Statement</h2><blockquote><pre>int sqlite3_step(sqlite3_stmt*);
</pre></blockquote><p>
After a <a href="../c3ref/stmt.html">prepared statement</a> has been prepared using either
<a href="../c3ref/prepare.html">sqlite3_prepare_v2()</a> or <a href="../c3ref/prepare.html">sqlite3_prepare16_v2()</a> or one of the legacy
interfaces <a href="../c3ref/prepare.html">sqlite3_prepare()</a> or <a href="../c3ref/prepare.html">sqlite3_prepare16()</a>, this function
must be called one or more times to evaluate the statement.</p>
<p>The details of the behavior of the sqlite3_step() interface depend
on whether the statement was prepared using the newer "v2" interface
<a href="../c3ref/prepare.html">sqlite3_prepare_v2()</a> and <a href="../c3ref/prepare.html">sqlite3_prepare16_v2()</a> or the older legacy
interface <a href="../c3ref/prepare.html">sqlite3_prepare()</a> and <a href="../c3ref/prepare.html">sqlite3_prepare16()</a>. The use of the
new "v2" interface is recommended for new applications but the legacy
interface will continue to be supported.</p>
<p>In the legacy interface, the return value will be either <a href="../rescode.html#busy">SQLITE_BUSY</a>,
<a href="../rescode.html#done">SQLITE_DONE</a>, <a href="../rescode.html#row">SQLITE_ROW</a>, <a href="../rescode.html#error">SQLITE_ERROR</a>, or <a href="../rescode.html#misuse">SQLITE_MISUSE</a>.
With the "v2" interface, any of the other <a href="../rescode.html">result codes</a> or
<a href="../rescode.html#extrc">extended result codes</a> might be returned as well.</p>
<p><a href="../rescode.html#busy">SQLITE_BUSY</a> means that the database engine was unable to acquire the
database locks it needs to do its job. If the statement is a <a href="../lang_transaction.html">COMMIT</a>
or occurs outside of an explicit transaction, then you can retry the
statement. If the statement is not a <a href="../lang_transaction.html">COMMIT</a> and occurs within an
explicit transaction then you should rollback the transaction before
continuing.</p>
<p><a href="../rescode.html#done">SQLITE_DONE</a> means that the statement has finished executing
successfully. sqlite3_step() should not be called again on this virtual
machine without first calling <a href="../c3ref/reset.html">sqlite3_reset()</a> to reset the virtual
machine back to its initial state.</p>
<p>If the SQL statement being executed returns any data, then <a href="../rescode.html#row">SQLITE_ROW</a>
is returned each time a new row of data is ready for processing by the
caller. The values may be accessed using the <a href="../c3ref/column_blob.html">column access functions</a>.
sqlite3_step() is called again to retrieve the next row of data.</p>
<p><a href="../rescode.html#error">SQLITE_ERROR</a> means that a run-time error (such as a constraint
violation) has occurred. sqlite3_step() should not be called again on
the VM. More information may be found by calling <a href="../c3ref/errcode.html">sqlite3_errmsg()</a>.
With the legacy interface, a more specific error code (for example,
<a href="../rescode.html#interrupt">SQLITE_INTERRUPT</a>, <a href="../rescode.html#schema">SQLITE_SCHEMA</a>, <a href="../rescode.html#corrupt">SQLITE_CORRUPT</a>, and so forth)
can be obtained by calling <a href="../c3ref/reset.html">sqlite3_reset()</a> on the
<a href="../c3ref/stmt.html">prepared statement</a>. In the "v2" interface,
the more specific error code is returned directly by sqlite3_step().</p>
<p><a href="../rescode.html#misuse">SQLITE_MISUSE</a> means that the this routine was called inappropriately.
Perhaps it was called on a <a href="../c3ref/stmt.html">prepared statement</a> that has
already been <a href="../c3ref/finalize.html">finalized</a> or on one that had
previously returned <a href="../rescode.html#error">SQLITE_ERROR</a> or <a href="../rescode.html#done">SQLITE_DONE</a>. Or it could
be the case that the same database connection is being used by two or
more threads at the same moment in time.</p>
<p>For all versions of SQLite up to and including 3.6.23.1, a call to
<a href="../c3ref/reset.html">sqlite3_reset()</a> was required after sqlite3_step() returned anything
other than <a href="../rescode.html#row">SQLITE_ROW</a> before any subsequent invocation of
sqlite3_step(). Failure to reset the prepared statement using
<a href="../c3ref/reset.html">sqlite3_reset()</a> would result in an <a href="../rescode.html#misuse">SQLITE_MISUSE</a> return from
sqlite3_step(). But after version 3.6.23.1, sqlite3_step() began
calling <a href="../c3ref/reset.html">sqlite3_reset()</a> automatically in this circumstance rather
than returning <a href="../rescode.html#misuse">SQLITE_MISUSE</a>. This is not considered a compatibility
break because any application that ever receives an SQLITE_MISUSE error
is broken by definition. The <a href="../compile.html#omit_autoreset">SQLITE_OMIT_AUTORESET</a> compile-time option
can be used to restore the legacy behavior.</p>
<p><b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step()
API always returns a generic error code, <a href="../rescode.html#error">SQLITE_ERROR</a>, following any
error other than <a href="../rescode.html#busy">SQLITE_BUSY</a> and <a href="../rescode.html#misuse">SQLITE_MISUSE</a>. You must call
<a href="../c3ref/reset.html">sqlite3_reset()</a> or <a href="../c3ref/finalize.html">sqlite3_finalize()</a> in order to find one of the
specific <a href="../rescode.html">error codes</a> that better describes the error.
We admit that this is a goofy design. The problem has been fixed
with the "v2" interface. If you prepare all of your SQL statements
using either <a href="../c3ref/prepare.html">sqlite3_prepare_v2()</a> or <a href="../c3ref/prepare.html">sqlite3_prepare16_v2()</a> instead
of the legacy <a href="../c3ref/prepare.html">sqlite3_prepare()</a> and <a href="../c3ref/prepare.html">sqlite3_prepare16()</a> interfaces,
then the more specific <a href="../rescode.html">error codes</a> are returned directly
by sqlite3_step(). The use of the "v2" interface is recommended.
</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>
|
