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
|
<!DOCTYPE html>
<html><head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<link href="../sqlite.css" rel="stylesheet">
<title>Evaluate An SQL Statement</title>
<!-- path=../ -->
</head>
<body>
<div class=nosearch>
<a href="../index.html">
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite" border="0">
</a>
<div><!-- IE hack to prevent disappearing logo --></div>
<div class="tagline desktoponly">
Small. Fast. Reliable.<br>Choose any three.
</div>
<div class="menu mainmenu">
<ul>
<li><a href="../index.html">Home</a>
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
<li class='wideonly'><a href='../about.html'>About</a>
<li class='desktoponly'><a href="../docs.html">Documentation</a>
<li class='desktoponly'><a href="../download.html">Download</a>
<li class='wideonly'><a href='../copyright.html'>License</a>
<li class='desktoponly'><a href="../support.html">Support</a>
<li class='desktoponly'><a href="../prosupport.html">Purchase</a>
<li class='search' id='search_menubutton'>
<a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
</ul>
</div>
<div class="menu submenu" id="submenu">
<ul>
<li><a href='../about.html'>About</a>
<li><a href='../docs.html'>Documentation</a>
<li><a href='../download.html'>Download</a>
<li><a href='../support.html'>Support</a>
<li><a href='../prosupport.html'>Purchase</a>
</ul>
</div>
<div class="searchmenu" id="searchmenu">
<form method="GET" action="../search">
<select name="s" id="searchtype">
<option value="d">Search Documentation</option>
<option value="c">Search Changelog</option>
</select>
<input type="text" name="q" id="searchbox" value="">
<input type="submit" value="Go">
</form>
</div>
</div>
<script>
function toggle_div(nm) {
var w = document.getElementById(nm);
if( w.style.display=="block" ){
w.style.display = "none";
}else{
w.style.display = "block";
}
}
function toggle_search() {
var w = document.getElementById("searchmenu");
if( w.style.display=="block" ){
w.style.display = "none";
} else {
w.style.display = "block";
setTimeout(function(){
document.getElementById("searchbox").focus()
}, 30);
}
}
function div_off(nm){document.getElementById(nm).style.display="none";}
window.onbeforeunload = function(e){div_off("submenu");}
/* Disable the Search feature if we are not operating from CGI, since */
/* Search is accomplished using CGI and will not work without it. */
if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
document.getElementById("search_menubutton").style.display = "none";
}
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */
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;
}
var antiRobot = 0;
function antiRobotGo(){
if( antiRobot!=3 ) return;
antiRobot = 7;
var j = document.getElementById("mtimelink");
if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
}
function antiRobotDefense(){
document.body.onmousedown=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousedown=null;
}
document.body.onmousemove=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousemove=null;
}
setTimeout(function(){
antiRobot |= 1;
antiRobotGo();
}, 100)
antiRobotGo();
}
antiRobotDefense();
</script>
<!-- keywords: sqlite3_step -->
<div class=nosearch>
<a href="intro.html"><h2>SQLite C Interface</h2></a>
<h2>Evaluate An SQL Statement</h2>
</div>
<blockquote><pre>
int sqlite3_step(sqlite3_stmt*);
</pre></blockquote>
<p>
After a <a href="../c3ref/stmt.html">prepared statement</a> has been prepared using any of
<a href="../c3ref/prepare.html">sqlite3_prepare_v2()</a>, <a href="../c3ref/prepare.html">sqlite3_prepare_v3()</a>, <a href="../c3ref/prepare.html">sqlite3_prepare16_v2()</a>,
or <a href="../c3ref/prepare.html">sqlite3_prepare16_v3()</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 "vX" interfaces
<a href="../c3ref/prepare.html">sqlite3_prepare_v3()</a>, <a href="../c3ref/prepare.html">sqlite3_prepare_v2()</a>, <a href="../c3ref/prepare.html">sqlite3_prepare16_v3()</a>,
<a href="../c3ref/prepare.html">sqlite3_prepare16_v2()</a> or the older legacy
interfaces <a href="../c3ref/prepare.html">sqlite3_prepare()</a> and <a href="../c3ref/prepare.html">sqlite3_prepare16()</a>. The use of the
new "vX" 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 <a href="../releaselog/3_6_23_1.html">version 3.6.23.1</a> (2010-03-26,
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 <a href="../c3ref/prepare.html">sqlite3_prepare_v3()</a> or <a href="../c3ref/prepare.html">sqlite3_prepare_v2()</a>
or <a href="../c3ref/prepare.html">sqlite3_prepare16_v2()</a> or <a href="../c3ref/prepare.html">sqlite3_prepare16_v3()</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 "vX" interfaces 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>
|
