Evaluar una sentencia SQL
int sqlite3_step(sqlite3_stmt*);
Después de que una sentencia haya sido preparada usando sqlite3_prepare_v2() o sqlite3_prepare16_v2() o una de las funciones heredadas sqlite3_prepare() o sqlite3_prepare16(), esta función debe ser invocada una o más veces para evaluar la sentencia. Los detalles del comportamiento de sqlite3_step() dependen de si la sentencia fue preparada usando una de las versines nuevas "v2" o una de las antiguas heredeadas. Se recomienda el uso de las nuevas "v2" para aplicaciones nueveas pero las heredadas continúan siendo soportadas.
En las función heredada, el valor de retorno puede ser SQLITE_BUSY, SQLITE_DONE, SQLITE_ROW, SQLITE_ERROR o SQLITE_MISUSE. Con la versión "v2", puede ser devuelto cualquier otro código de resultado o código de resultado extendido.
SQLITE_BUSY significa que el motor de base de datos fue incapaz de adquirir los bloqueos de base de datos que becesita para trabaja. Si la sentencia es un COMMIT o se produce fuera de una transacción explícita, se podrá reintentar la sentencia. Si la sentencia no es un COMMIT y se produce en el interior de una transacción explícita se debe deshacer la transacción antes de continuar.
SQLITE_DONE significa que la sentencia ha finalizado la ejecución con éxito. sqlite3_step() no podrá ser invocada de nuevo en esta máquina virtual sin llamar antes a sqlite3_reset() para restablecer la máquina virtual a su estado inicial.
Si la sentencia SQL que se está ejecutando devuelve algún dato, entonces se devuevle SQLITE_ROW cada vez que una fila de datos está preparada para ser procesada por la aplicación. Se puede acceder a los valores usando las funciones de acceso a columna. sqlite3_step() es invocada de nuevo para recuperar la siguiente fila de datos.
SQLITE_ERROR significa que se ha producido un error de ejecución (como una violación de restricción). sqlite3_step() no debe ser invocada de nuevo en la máquina virtual. Se puede encontrar más información llamando a sqlite3_errmsg(). Con la función heredada, se puede obtener un código de error más específico (por ejemplo, SQLITE_INTERRUPT, SQLITE_SCHEMA, SQLITE_CORRUPT, etc) llamando a sqlite3_reset() con la sentencia preparada. En la función "v2", el código de error más específico es devuelto directamente por sqlite3_step().
SQLITE_MISUSE significa que esta función fue invocada inapropiadamente. Tal vez due llamada en una sentencia preparada que ya ha finalizado o en una que ha devuelto previamente SQLITE_ERROR o SQLITE_DONE. O podría ser el caso de que la misma conexión de base de datos esté siendo usada por dos o más hilos en el mismo momemto.
Para todas las versiones de SQLite hasta la 3.6.23.1 incluída, se necesita una llamada a sqlite3_reset() después de que sqlite3_step() retorne cualquier valor que no sea SQLITE_ROW antes de subsiguientes llamadas a sqlite3_step(). Si no se restablece la sentencia preparada usando sqlite3_reset() se retornará un valor SQLITE_MISUSE desde sqlite3_step(). Pero desde la versión 3.6.23.1, sqlite3_step() empezó a llamar a sqlite3_reset() automaticamente en esa circunstancia en lugar de retornar SQLITE_MISUSE. Esto no se considera una ruptura de compatibilidad porque cualquier aplicación cualquier aplicación que que reciva un error SQLITE_MISUSE está rota por definición. Se puede usar la opción de compilación SQLITE_OMIT_AUTORESET para restaurar el comportamiento anterior.
Alerta de función ridícula: En la versión heredada, la función sqlite3_step() siempre devuelve un código de error genérico, SQLITE_ERROR, después de un error distinto de SQLITE_BUSY y SQLITE_MISUSE. Se debe invocar a sqlite3_reset() o sqlite3_finalize() para encontrar uno de los códigos de error específicos que describan mejor el error. Admitimos que esto es un diseño ridículo. El problema se ha corregido en la versión "v2" de la función. Si se preparan todas las sentencias SQL usando sqlite3_prepare_v2() o sqlite3_prepare16_v2() en lugar de las funciones heredadas sqlite3_prepare() y sqlite3_prepare16(), se devuelven códigos de error más específicos desde sqlite3_step(). Se recomienda el uso de la función "v2".