sqlite.h


Compilar una sentencia SQL

int sqlite3_prepare(
  sqlite3 *db,            /* Manipulador de base de datos */
  const char *zSql,       /* Sentencia SQL, codificada en UTF-8 */
  int nByte,              /* Longitud máxima de zSql en bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Manipulador de sentencia */
  const char **pzTail     /* OUT: Puntero a la porción sin usar de zSql */
);
int sqlite3_prepare_v2(
  sqlite3 *db,            /* Manipulador de base de datos */
  const char *zSql,       /* Sentencia SQL, codificada en UTF-8 */
  int nByte,              /* Longitud máxima de zSql en bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Manipulador de sentencia */
  const char **pzTail     /* OUT: Puntero a la porción sin usar de zSql */
);
int sqlite3_prepare16(
  sqlite3 *db,            /* Manipulador de base de datos */
  const void *zSql,       /* Sentencia SQL, codificada en UTF-16 */
  int nByte,              /* Longitud máxima de zSql en bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Manipulador de sentencia */
  const void **pzTail     /* OUT: Puntero a la porción sin usar de zSql */
);
int sqlite3_prepare16_v2(
  sqlite3 *db,            /* Manipulador de base de datos */
  const void *zSql,       /* Sentencia SQL, codificada en UTF-16 */
  int nByte,              /* Longitud máxima de zSql en bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Manipulador de sentencia */
  const void **pzTail     /* OUT: Puntero a la porción sin usar de zSql */
);

Para ejecutar una consulta SQL, primero debe ser compilada en un programa codificado en bytes usando una de estas funciones.

El primer argumento, db, es una conexión de base de datos obtenida de una llamada previa con éxito a sqlite3_open(), sqlite3_open_v2() o sqlite3_open16(). La conexión de base de datos no debe haber sido cerrada.

El segundo argumento, zSql, es la sentencia a compilar, codificada como UTF-8 o UTF-16. Las funciones sqlite3_prepare() y sqlite3_prepare_v2() usan UTF-8, y sqlite3_prepare16() y sqlite3_prepare16_v2() usan UTF-16.

Si el argumento nByte es menor de cero, zSql es leído hasta el primer cero terminador. Si nByte no es negativo, entonces es el número máximo de bytes a leer desde zSql. Cuando nByte no es negativo, la cadena zSql termina en el primer carácter '\000' o '\u0000', o en el byte nByte, lo que pase primero. Si el proceso que llama conoce que la cadena suministrada es una cadena terminada con cero, hay una pequeña ventaja de rendimiento si se pasa un parámetro nByte que sea igual al número de bytes en la cadena de entrada, incluyendo el byte terminador nulo, ya que eso ahorra a SQLite el tener que hacer una copia de la cadena de entrada.

Si pzTailno es NULL entonces se hace que *pzTail apunte al primer byte posterior al final de la primera sentencia en zSql. Estas funciones sólo compilan la primera sentencia en zSql, de modo que *pzTail es un puntero a lo que queda sin compilar.

*ppStmt se deja apuntando a la sentencia preparada compilada que puede ser ejecutada usando sqlite3_step(). Si hay un error, se asigna NULL a *ppStmt. Si el texto de entrada no contiene SQL (si la entrada es una cadena vacía o un comentario) se asigna NULL a *ppStmt. El procedimiento que llama es responsable de borrar la sentencia SQL compilada usando sqlite3_finalize() después de finalizar con ella. ppStmt no puede ser NULL.

Si tiene éxito, la familia de funciones sqlite3_prepare() retornan SQLITE_OK; en caso contrario se devuelve un código de error.

Para todos los nuevos programas se recomiendan las funciones sqlite3_prepare_v2() y sqlite3_prepare16_v2(). Las dos viejas funciones se conservan por compatibilidad hacia atrás, pero su uso está desaconsejado. En las funciones "v2", la sentencia preparada que se retorna (el objeto sqlite3_stmt) contiene una copia del texto SQL original. Esto provoca que la función sqlite3_step() se comporte de manera diferente en tres formas:

  1. Si el esquema de base de datos cambia, en lugar de retornar SQLITE_SCHEMA como solía hacer siempre, sqlite3_step() recompilará automáticamente la sentencia SQL e intentará ejecutarla de nuevo.
  2. Cuando se produce un error, sqlite3_step() retornará uno de los códigos de error detallados o un código de error extendido. El comportamiento heredado es que sqlite3_step() devuelva sólo un código de error genérico SQLITE_ERROR y la aplicación debería hacer una segunda llamada a sqlite3_reset() para encontrar la causa subyacente del problema. Con las funciones "v2", el motivo subyacente del error se devuelve inmediatamente.
  3. Si el valor especificado para contener el parámetro en la cláusila WHERE puede influir en la elección del plan de la consulta para la sentencia, entonces la sentencia será automáticamente recompilada, como si hubiera habido un cambio de esquema, en la primera llamada a sqlite3_step() después de cualquier cambio en los enlaces de ese parámetro. El valor especificado del parámetro de la cláusula WHERE puede influir en la elección del plan de consulta si el parámetro está en el lado izquierdo de un operador LIKE o GLOB o si el parámetro es comparado con una columna con índice y la opción de compilación SQLITE_ENABLE_STAT3 está activa.