Компилирование SQL-оператора

int sqlite3_prepare(
  sqlite3 *db,            /* Database handle */
  const char *zSql,       /* SQL statement, UTF-8 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare_v2(
  sqlite3 *db,            /* Database handle */
  const char *zSql,       /* SQL statement, UTF-8 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare_v3(
  sqlite3 *db,            /* Database handle */
  const char *zSql,       /* SQL statement, UTF-8 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare16(
  sqlite3 *db,            /* Database handle */
  const void *zSql,       /* SQL statement, UTF-16 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare16_v2(
  sqlite3 *db,            /* Database handle */
  const void *zSql,       /* SQL statement, UTF-16 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare16_v3(
  sqlite3 *db,            /* Database handle */
  const void *zSql,       /* SQL statement, UTF-16 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
);

Чтобы выполнить SQL-оператор, это должно сначала быть собрано в программу байт-код, используя одну из этих функций. Или другими словами эти хранимые процедуры это конструкторы для объекта подготовленного запроса.

Предпочтительная процедура, чтобы использовать, это sqlite3_prepare_v2(). Интерфейс sqlite3_prepare() устарел и лучше его не трогать. sqlite3_prepare_v3() имеет дополнительный параметр "prepFlags", который используется для особых целей.

Использование интерфейсов UTF-8 предпочтено, поскольку SQLite в настоящее время делает весь парсинг, используя UTF-8. Интерфейсы UTF-16 обеспечиваются как удобство. UTF-16 соединяет работу, преобразовывая входной текст в UTF-8, затем вызывая соответствующий интерфейс UTF-8.

Первым аргументом, "db", является соединение с базой данных, полученное от предшествующего успешного вызова sqlite3_open(), sqlite3_open_v2() или sqlite3_open16(). Соединение с базой данных не должно быть закрыто.

Вторым аргументом, "zSql", является запрос для сборки, закодированный как UTF-8 или UTF-16. sqlite3_prepare(), sqlite3_prepare_v2() и sqlite3_prepare_v3() используют UTF-8, а sqlite3_prepare16(), sqlite3_prepare16_v2() и sqlite3_prepare16_v3() используют UTF-16.

Если nByte отрицателен, zSql прочитан до первого нулевого терминатора. Если nByte положительный, то это число байтов, прочитанных из zSql. Если nByte = 0, то никакой подготовленный запрос не произведен. Если вызывающий знает, что предоставленная строка nul-закончена, то есть небольшое исполнительное преимущество для прохождения nByte параметра, который является числом байтов во входной строке включая nul-терминатор.

Если pzTail не NULL, *pzTail указывает на первый байт после конца первого SQL-оператора в zSql. Эта хранимая процедура только собирает первый запрос в zSql, таким образом, *pzTail указывает налево к тому, что остается несобранным.

*ppStmt указывает налево к собранному подготовленному запросу, который может быть выполнен, используя sqlite3_step(). Если есть ошибка, *ppStmt установлен в NULL. Если входной текст не содержит SQL (если вход пустая строка или комментарий), тогда *ppStmt = NULL. Процедура запроса ответственна за удаление собранного SQL-оператора, используя sqlite3_finalize() после того, как это закончило работу с ним. ppStmt может не быть NULL.

При успехе sqlite3_prepare() вернет SQLITE_OK, иначе код ошибки.

sqlite3_prepare_v2(), sqlite3_prepare_v3(), sqlite3_prepare16_v2() и sqlite3_prepare16_v3() рекомендуются для всех новых программ. Более старые интерфейсы (sqlite3_prepare() и sqlite3_prepare16()) сохраняются для обратной совместимости, но их использование не рекомендуется. В интерфейсах "vX" подготовленный запрос, который возвращен (объект sqlite3_stmt) содержит копию оригинального кода на SQL. Это заставляет sqlite3_step() вести себя по-другому тремя путями:

1. Если схема базы данных изменится, вместо того, чтобы возвратить SQLITE_SCHEMA как это всегда раньше делало, sqlite3_step() автоматически повторно соберет SQL-оператор и делает попытку управлять им снова. Будет SQLITE_MAX_SCHEMA_RETRY попыток прежде, чем sqlite3_step() сдается и возвращает ошибку.
2. Когда ошибка произойдет, sqlite3_step() возвратит одни из подробных кодов ошибки или расширенных кодов ошибки. Устаревшее поведение состояло в том, что sqlite3_step() возвратит только универсальный код результата SQLITE_ERROR и приложение должно было сделать второй вызов sqlite3_reset(), чтобы найти первопричину проблемы. С интерфейсами "v2" основная причина ошибки немедленно возвращена.
3. Если определенное значение, связанное с параметром хоста в WHERE, могло бы влиять на выбор плана запроса, запрос будет автоматически повторно собран, как будто было изменение схемы на первом вызове sqlite3_step() после любого изменения привязок параметров. Определенное значение WHERE-параметра могло бы влиять на выбор плана запросов, если параметр левая сторона LIKE или GLOB, или если параметр сравнивается с индексированным столбцом и включен выбор времени компиляции SQLITE_ENABLE_STAT4.

sqlite3_prepare_v3() отличается от sqlite3_prepare_v2() только наличием дополнительного параметра prepFlags, который является маленьким множеством, состоящим из ноля или большего количества флагов SQLITE_PREPARE_*. sqlite3_prepare_v2() работает аналогично sqlite3_prepare_v3() с нулевым параметром prepFlags.