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