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

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 указывают на 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 ее 2-го параметра и возвращает таблицу результата указателю в ее 3-м параметре.

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

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