sqlite.h


Funciones de apoyo para ejecutar consultas

int sqlite3_get_table(
  sqlite3 *db,          /* Una base de datos abierta */
  const char *zSql,     /* Sentencia SQL a evaluar */
  char ***pazResult,    /* Resultados de la consulta */
  int *pnRow,           /* Número de filas de resultados escritas */
  int *pnColumn,        /* Número de columnas de resultaados escritas */
  char **pzErrmsg       /* Mensaje de error */
);
void sqlite3_free_table(char **result);

Estas funciones heredadas de versiones anteriores se conservan por compatibilidad hacia atrás. Su uso no está recomendado.

Definición: Una tabla de resultados es una estructura de datos en memoria creada por la función sqlite3_get_table(). Una tabla de resultados almacena los resultados completos de consulta de una o varias consultas.

Conteptualmente la tabla tiene un número de filas y columnas. Pero esos números no son parte de la tabla de resultados misma. Esos números se obtienen por separado. Sea N el número de filas y M el número de columnas.

La tabla de resultados es un array de punteros a cadenas UTF-8 terminadas en cero. Hay (N+1)*M elementos en el array. Los primeros M punteros apuntan a cadenas que contienen los nombres de las columnas. Las entradas restantes apuntan a los resultados de la consulta. Los valores NULL producen punteros NULL. Todos los demás valores son la representación en cadenas UTF-8 terminadas en cero retornadas por sqlite3_column_text().

Una tabla de resultados puede consistir en una o más bloques de memoria. No es seguro pasar la tabla de resultados directametne a sqlite3_free(). Una tabla de resultados debe ser liberada usando sqlite3_free_table().

Como un ejemplo del formato de tabla de resultados, supongamos un resultado de consulta como el siguiente:

    Name        | Age
    -----------------------
    Alice       | 43
    Bob         | 28
    Cindy       | 21

Hay dos columnas (M==2) y tres filas (N==3). De modo que la tabla de resultados tendrá 8 entradas. Supongamos que la tabla se almacena en un array llamado azResult. Entonces azResult tendrá este contenido:

    azResult[0] = "Name";
    azResult[1] = "Age";
    azResult[2] = "Alice";
    azResult[3] = "43";
    azResult[4] = "Bob";
    azResult[5] = "28";
    azResult[6] = "Cindy";
    azResult[7] = "21";

La función sqlite3_get_table() evalúa una o más sentencias SQL separadas con punto y comat en la cadena UTF-8 terminada en cero del segundo parámetro y devolvará una tabla de resultados en el puntero dado por el tercer parámetro.

Después de que la aplicación haya terminado con el resultado de sqlite3_get_table(), debe pasar el puntero a la tabla a sqlite3_free_table() para liberar la memoria que fue reservada. Debido al modo en que sqlite3_malloc() se usa dentro de sqlite3_get_table(), la aplicación no debe intentar llamar a sqlite3_free() directamente. Sólo sqlite3_free_table() es capaz de liberar la memoria apropiadamente y con seguridad.

La función sqlite3_get_table() está implementada como una envoltura alrededor de sqlite3_exec(). EL código de sqlite3_get_table() no tiene acceso a ninguna estructura de datos interna de SQLite. Sólo usa las funciones públicas del API. Como consecuencia, los errores que se produzcan en la capa exterior de la envoltura de sqlite3_exec() no se reflejan en subsiguientes llamadas a sqlite3_errcode() o sqlite3_errmsg().