107 lines
4.3 KiB
Groff
107 lines
4.3 KiB
Groff
.Dd March 11, 2017
|
|
.Dt SQLITE3_STEP 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm sqlite3_step
|
|
.Nd Evaluate An SQL Statement
|
|
.Sh SYNOPSIS
|
|
.Ft int
|
|
.Fo sqlite3_step
|
|
.Fa "sqlite3_stmt*"
|
|
.Fc
|
|
.Sh DESCRIPTION
|
|
After a prepared statement has been prepared using
|
|
either sqlite3_prepare_v2() or sqlite3_prepare16_v2()
|
|
or one of the legacy interfaces sqlite3_prepare()
|
|
or sqlite3_prepare16(), this function must be called
|
|
one or more times to evaluate the statement.
|
|
.Pp
|
|
The details of the behavior of the sqlite3_step() interface depend
|
|
on whether the statement was prepared using the newer "v2" interface
|
|
sqlite3_prepare_v2() and sqlite3_prepare16_v2()
|
|
or the older legacy interface sqlite3_prepare() and
|
|
sqlite3_prepare16().
|
|
The use of the new "v2" interface is recommended for new applications
|
|
but the legacy interface will continue to be supported.
|
|
.Pp
|
|
In the legacy interface, the return value will be either SQLITE_BUSY,
|
|
SQLITE_DONE, SQLITE_ROW, SQLITE_ERROR,
|
|
or SQLITE_MISUSE.
|
|
With the "v2" interface, any of the other result codes
|
|
or extended result codes might be returned as
|
|
well.
|
|
.Pp
|
|
SQLITE_BUSY means that the database engine was unable to
|
|
acquire the database locks it needs to do its job.
|
|
If the statement is a COMMIT or occurs outside of an explicit
|
|
transaction, then you can retry the statement.
|
|
If the statement is not a COMMIT and occurs within an explicit
|
|
transaction then you should rollback the transaction before continuing.
|
|
.Pp
|
|
SQLITE_DONE means that the statement has finished executing
|
|
successfully.
|
|
sqlite3_step() should not be called again on this virtual machine without
|
|
first calling sqlite3_reset() to reset the virtual machine
|
|
back to its initial state.
|
|
.Pp
|
|
If the SQL statement being executed returns any data, then SQLITE_ROW
|
|
is returned each time a new row of data is ready for processing by
|
|
the caller.
|
|
The values may be accessed using the column access functions.
|
|
sqlite3_step() is called again to retrieve the next row of data.
|
|
.Pp
|
|
SQLITE_ERROR 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 sqlite3_errmsg().
|
|
With the legacy interface, a more specific error code (for example,
|
|
SQLITE_INTERRUPT, SQLITE_SCHEMA, SQLITE_CORRUPT,
|
|
and so forth) can be obtained by calling sqlite3_reset()
|
|
on the prepared statement.
|
|
In the "v2" interface, the more specific error code is returned directly
|
|
by sqlite3_step().
|
|
.Pp
|
|
SQLITE_MISUSE means that the this routine was called inappropriately.
|
|
Perhaps it was called on a prepared statement that
|
|
has already been finalized or on one that had previously
|
|
returned SQLITE_ERROR or SQLITE_DONE.
|
|
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.
|
|
.Pp
|
|
For all versions of SQLite up to and including 3.6.23.1, a call to
|
|
sqlite3_reset() was required after sqlite3_step() returned
|
|
anything other than SQLITE_ROW before any subsequent invocation
|
|
of sqlite3_step().
|
|
Failure to reset the prepared statement using sqlite3_reset()
|
|
would result in an SQLITE_MISUSE return from sqlite3_step().
|
|
But after version 3.6.23.1 (dateof:3.6.23.1,
|
|
sqlite3_step() began calling sqlite3_reset() automatically
|
|
in this circumstance rather than returning SQLITE_MISUSE.
|
|
This is not considered a compatibility break because any application
|
|
that ever receives an SQLITE_MISUSE error is broken by definition.
|
|
The SQLITE_OMIT_AUTORESET compile-time option
|
|
can be used to restore the legacy behavior.
|
|
.Pp
|
|
\fBGoofy Interface Alert:\fP In the legacy interface, the sqlite3_step()
|
|
API always returns a generic error code, SQLITE_ERROR,
|
|
following any error other than SQLITE_BUSY and SQLITE_MISUSE.
|
|
You must call sqlite3_reset() or sqlite3_finalize()
|
|
in order to find one of the specific error codes 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 sqlite3_prepare_v2()
|
|
or sqlite3_prepare16_v2() instead of the legacy
|
|
sqlite3_prepare() and sqlite3_prepare16()
|
|
interfaces, then the more specific error codes are returned
|
|
directly by sqlite3_step().
|
|
The use of the "v2" interface is recommended.
|
|
.Sh SEE ALSO
|
|
.Xr sqlite3_column_blob 3 ,
|
|
.Xr sqlite3_stmt 3 ,
|
|
.Xr sqlite3_errcode 3 ,
|
|
.Xr sqlite3_finalize 3 ,
|
|
.Xr sqlite3_prepare 3 ,
|
|
.Xr sqlite3_reset 3 ,
|
|
.Xr SQLITE_OK 3
|