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().