Оценить SQL-запрос

int sqlite3_step(sqlite3_stmt*);

После подготовки подготовленного запроса с помощью подготовленного оператора, используя любой из sqlite3_prepare_v2(), sqlite3_prepare_v3(), sqlite3_prepare16_v2() или sqlite3_prepare16_v3(), или один из устаревших интерфейсов sqlite3_prepare() или sqlite3_prepare16(), эту функцию необходимо вызвать один или несколько раз для оценки оператора.

Подробности поведения интерфейса sqlite3_step() зависят от того, был ли запрос подготовлен с использованием новых интерфейсов «vX» sqlite3_prepare_v3(), sqlite3_prepare_v2(), sqlite3_prepare16_v3(), sqlite3_prepare16_v2() или устаревших интерфейсов sqlite3_prepare() и sqlite3_prepare16(). Использование нового интерфейса «vX» рекомендуется для новых приложений, но интерфейс устаревшего типа будет по-прежнему поддерживаться.

В устаревшем интерфейсе возвращаемое значение может быть SQLITE_BUSY, SQLITE_DONE, SQLITE_ROW, SQLITE_ERROR или SQLITE_MISUSE. С интерфейсом «v2» могут быть возвращены и другие коды результатов или расширенные коды результатов.

SQLITE_BUSY означает, что движок базы данных не смог получить необходимые для работы блокировки базы данных. Если оператор является COMMIT или выполняется вне явного транзакции, то вы можете повторить оператор. Если оператор не является COMMIT и выполняется в рамках явной транзакции, то вы должны откатить транзакцию перед продолжением.

SQLITE_DONE означает, что оператор завершил выполнение успешно. sqlite3_step() не следует вызывать повторно на этой виртуальной машине без предварительного вызова sqlite3_reset() для сброса виртуальной машины в исходное состояние.

Если выполняемый SQL-запрос возвращает какие-либо данные, то SQLITE_ROW возвращается каждый раз, когда новая строка данных готова к обработке вызывающим объектом. Значения могут быть получены с помощью функций доступа к столбцам. sqlite3_step() вызывается повторно для получения следующей строки данных.

SQLITE_ERROR означает, что произошла ошибка во время выполнения (например, нарушение ограничения). sqlite3_step() не следует вызывать повторно на ВМ. Дополнительную информацию можно получить, вызвав sqlite3_errmsg(). С устаревшим интерфейсом более конкретный код ошибки (например, SQLITE_INTERRUPT, SQLITE_SCHEMA, SQLITE_CORRUPT и т. д.) можно получить, вызвав sqlite3_reset() для подготовленного оператора. В интерфейсе «v2» более конкретный код ошибки возвращается напрямую sqlite3_step().

SQLITE_MISUSE означает, что этот метод был вызван неуместно. Возможно, он был вызван для подготовленного оператора, который уже был завершён или для оператора, который ранее возвращал SQLITE_ERROR или SQLITE_DONE. Или же возможно, что к одной и той же базе данных подключаются два или более потоков одновременно.

Для всех версий SQLite до и включая 3.6.23.1 вызов sqlite3_reset() был необходим после того, как sqlite3_step() возвращал любой результат, кроме SQLITE_ROW, перед любым последующим вызовом sqlite3_step(). Отсутствие сброса подготовленного оператора с помощью sqlite3_reset() приведёт к возврату SQLITE_MISUSE из sqlite3_step(). Но после версии 3.6.23.1 (26 марта 2010 г.) sqlite3_step() начал автоматически вызывать sqlite3_reset() в этом случае, а не возвращать SQLITE_MISUSE. Это не считается нарушением совместимости, потому что любое приложение, получающее ошибку SQLITE_MISUSE, по определению является некорректным. Опция компиляции SQLITE_OMIT_AUTORESET может быть использована для восстановления устаревшего поведения.

ВНИМАНИЕ: Нелогичный интерфейс: В устаревшем интерфейсе API sqlite3_step() всегда возвращает общий код ошибки SQLITE_ERROR после любой ошибки, кроме SQLITE_BUSY и SQLITE_MISUSE. Для нахождения одного из конкретных кодов ошибок, лучше описывающих ошибку, необходимо вызвать sqlite3_reset() или sqlite3_finalize(). Мы признаём, что это нелогичный дизайн. Проблема была решена с интерфейсом «v2». Если вы готовите все свои SQL-запросы, используя sqlite3_prepare_v3() или sqlite3_prepare_v2() или sqlite3_prepare16_v2() или sqlite3_prepare16_v3() вместо устаревших sqlite3_prepare() и sqlite3_prepare16() интерфейсов, то более конкретные коды ошибок возвращаются напрямую sqlite3_step(). Использование интерфейсов «vX» рекомендуется.

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