Удобные процедуры для выполнения запросов

int sqlite3_get_table(
  sqlite3 *db,          /* An open database */
  const char *zSql,     /* SQL to be evaluated */
  char ***pazResult,    /* Results of the query */
  int *pnRow,           /* Number of result rows written here */
  int *pnColumn,        /* Number of result columns written here */
  char **pzErrmsg       /* Error msg written here */
);
void sqlite3_free_table(char **result);

Это устаревший интерфейс, который сохраняется для обратной совместимости. Использование этого интерфейса не рекомендуется.

Определение: таблица результатов — это структура данных в памяти, созданная интерфейсом sqlite3_get_table(). Таблица результатов записывает полные результаты запроса из одного или нескольких запросов.

Таблица концептуально имеет ряд строк и столбцов. Но эти числа не являются частью самой таблицы результатов. Эти числа получаются отдельно. Пусть N — количество строк, а M — количество столбцов.

Таблица результатов представляет собой массив указателей на строки UTF-8 с нулевым завершением. В массиве содержится (N+1)*M элементов. Первые M указателей указывают на строки с нулевым завершением, содержащие имена столбцов. Остальные записи указывают на результаты запроса. Значения NULL приводят к нулевым указателям. Все остальные значения представлены в их представлении в виде нуль-терминированной строки UTF-8, как возвращает sqlite3_column_text().

Таблица результатов может состоять из одного или нескольких выделений памяти. Не безопасно передавать таблицу результатов напрямую в sqlite3_free(). Таблица результатов должна быть освобождена с помощью sqlite3_free_table().

В качестве примера формата таблицы результатов предположим, что результат запроса выглядит следующим образом:

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

Есть два столбца (M==2) и три строки (N==3). Таким образом, таблица результатов содержит 8 записей. Предположим, что таблица результатов хранится в массиве с именем azResult. Тогда azResult содержит это содержимое:

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

Функция sqlite3_get_table() вычисляет одну или несколько SQL-выражений, разделенных точкой с запятой, в строке UTF-8 с нулевым завершением своего второго параметра и возвращает таблицу результатов указателю, заданному в его третьем параметре.

После того, как приложение завершило работу с результатом из sqlite3_get_table(), оно должно передать указатель на таблицу результатов в sqlite3_free_table(), чтобы освободить выделенную память. Из-за того, как происходит выделение памяти sqlite3_malloc() внутри sqlite3_get_table(), вызывающая функция не должна пытаться вызвать sqlite3_free() напрямую. Только sqlite3_free_table() может правильно и безопасно освободить память.

Интерфейс sqlite3_get_table() реализован как обертка вокруг sqlite3_exec(). Процедура sqlite3_get_table() не имеет доступа к внутренним структурам данных SQLite. Она использует только публичный интерфейс, определенный здесь. Вследствие этого ошибки, возникающие в слое обертки вне вызова внутреннего sqlite3_exec(), не отражаются в последующих вызовах sqlite3_errcode() или sqlite3_errmsg().

См. также списки Объектов, Констант и Функций.