1.Dd December 19, 2018 2.Dt SQLITE3_STEP 3 3.Os 4.Sh NAME 5.Nm sqlite3_step 6.Nd Evaluate An SQL Statement 7.Sh SYNOPSIS 8.Ft int 9.Fo sqlite3_step 10.Fa "sqlite3_stmt*" 11.Fc 12.Sh DESCRIPTION 13After a prepared statement has been prepared using 14any of sqlite3_prepare_v2(), sqlite3_prepare_v3(), 15sqlite3_prepare16_v2(), or sqlite3_prepare16_v3() 16or one of the legacy interfaces sqlite3_prepare() 17or sqlite3_prepare16(), this function must be called 18one or more times to evaluate the statement. 19.Pp 20The details of the behavior of the sqlite3_step() interface depend 21on whether the statement was prepared using the newer "vX" interfaces 22sqlite3_prepare_v3(), sqlite3_prepare_v2(), 23sqlite3_prepare16_v3(), sqlite3_prepare16_v2() 24or the older legacy interfaces sqlite3_prepare() and 25sqlite3_prepare16(). 26The use of the new "vX" interface is recommended for new applications 27but the legacy interface will continue to be supported. 28.Pp 29In the legacy interface, the return value will be either SQLITE_BUSY, 30SQLITE_DONE, SQLITE_ROW, SQLITE_ERROR, 31or SQLITE_MISUSE. 32With the "v2" interface, any of the other result codes 33or extended result codes might be returned as 34well. 35.Pp 36SQLITE_BUSY means that the database engine was unable to 37acquire the database locks it needs to do its job. 38If the statement is a COMMIT or occurs outside of an explicit 39transaction, then you can retry the statement. 40If the statement is not a COMMIT and occurs within an explicit 41transaction then you should rollback the transaction before continuing. 42.Pp 43SQLITE_DONE means that the statement has finished executing 44successfully. 45sqlite3_step() should not be called again on this virtual machine without 46first calling sqlite3_reset() to reset the virtual machine 47back to its initial state. 48.Pp 49If the SQL statement being executed returns any data, then SQLITE_ROW 50is returned each time a new row of data is ready for processing by 51the caller. 52The values may be accessed using the column access functions. 53sqlite3_step() is called again to retrieve the next row of data. 54.Pp 55SQLITE_ERROR means that a run-time error (such as a constraint 56violation) has occurred. 57sqlite3_step() should not be called again on the VM. 58More information may be found by calling sqlite3_errmsg(). 59With the legacy interface, a more specific error code (for example, 60SQLITE_INTERRUPT, SQLITE_SCHEMA, SQLITE_CORRUPT, 61and so forth) can be obtained by calling sqlite3_reset() 62on the prepared statement. 63In the "v2" interface, the more specific error code is returned directly 64by sqlite3_step(). 65.Pp 66SQLITE_MISUSE means that the this routine was called inappropriately. 67Perhaps it was called on a prepared statement that 68has already been finalized or on one that had previously 69returned SQLITE_ERROR or SQLITE_DONE. 70Or it could be the case that the same database connection is being 71used by two or more threads at the same moment in time. 72.Pp 73For all versions of SQLite up to and including 3.6.23.1, a call to 74sqlite3_reset() was required after sqlite3_step() returned 75anything other than SQLITE_ROW before any subsequent invocation 76of sqlite3_step(). 77Failure to reset the prepared statement using sqlite3_reset() 78would result in an SQLITE_MISUSE return from sqlite3_step(). 79But after version 3.6.23.1 (dateof:3.6.23.1, 80sqlite3_step() began calling sqlite3_reset() automatically 81in this circumstance rather than returning SQLITE_MISUSE. 82This is not considered a compatibility break because any application 83that ever receives an SQLITE_MISUSE error is broken by definition. 84The SQLITE_OMIT_AUTORESET compile-time option 85can be used to restore the legacy behavior. 86.Pp 87\fBGoofy Interface Alert:\fP In the legacy interface, the sqlite3_step() 88API always returns a generic error code, SQLITE_ERROR, 89following any error other than SQLITE_BUSY and SQLITE_MISUSE. 90You must call sqlite3_reset() or sqlite3_finalize() 91in order to find one of the specific error codes that better 92describes the error. 93We admit that this is a goofy design. 94The problem has been fixed with the "v2" interface. 95If you prepare all of your SQL statements using sqlite3_prepare_v3() 96or sqlite3_prepare_v2() or sqlite3_prepare16_v2() 97or sqlite3_prepare16_v3() instead of the legacy 98sqlite3_prepare() and sqlite3_prepare16() 99interfaces, then the more specific error codes are returned 100directly by sqlite3_step(). 101The use of the "vX" interfaces is recommended. 102.Sh SEE ALSO 103.Xr sqlite3_column_blob 3 , 104.Xr sqlite3_stmt 3 , 105.Xr sqlite3_errcode 3 , 106.Xr sqlite3_finalize 3 , 107.Xr sqlite3_prepare 3 , 108.Xr sqlite3_reset 3 , 109.Xr SQLITE_OK 3 110