Методы подготовленных операторов
После того, как подготовленный SQL- оператор создан с помощью db:prepare , возвращенный объект оператора должен использоваться для всех последующих обращений к методам такого оператора. Объекты операторов поддерживают следующие методы.
stmt:bind(n[,value])
Привязывает значение value к параметру n оператора. Если тип значения – строка или число, это значение привязывается соответственно как строка или DOUBLE. Если value – BOOLEAN, nil или опущено, любая предшествующая привязка удаляется. Функция возвращает sqlite3.OK в случае успешной привязки или код ошибки в противном случае (см. Результирующие коды и коды ошибок ).
stmt:bind_blob(n,blob)
Привязывает строку blob (которая может быть бинарной строкой) как бинарный объект к параметру n оператора. Функция возвращает sqlite3.OK в случае успешной привязки или код ошибки в противном случае (см. Результирующие коды и коды ошибок ).
stmt:bind_names(nametable)
Привязывает значения в nametable к параметрам оператора. Если параметры оператора именованы (т.е. имеют форму ":AAA" или "$AAA"), функция ищет в nametable поля с подходящими именами; если параметры оператора не именованы, функция ищет поля от 1 до <число параметров оператора>. Функция возвращает sqlite3.OK в случае успешной привязки или код ошибки в противном случае (см. Результирующие коды и коды ошибок ).
stmt:bind_parameter_count()
Возвращает наибольший индекс параметра в подготовленном операторе stmt. Если параметры оператора – в форме ":AAA" или "?", им присваиваются последовательно увеличивающиеся номера, начинающиеся с 1, так что возвращаемое значение есть число параметров. Однако всем параметрам с одинаковым именем присваивается один и тот же номер, так что возвращаемое значение есть число уникальных имен параметров оператора.
Если используются параметры оператора в форме "?NNN" (NNN – целое), то могут быть промежутки в нумерации, а возвращаемое значение есть наибольший индекс параметра оператора.
stmt:bind_parameter_name(n)
Возвращает имя n-го параметра в подготовленном операторе stmt. Параметры оператора в форме ":AAA", "@AAA" или "$VVV" имеют имя, которое есть строка ":AAA", "@AAA" или "$VVV".Другими словами, начальное ":", "$" или "@" включается как часть имени. Параметры в форме "?" или "?NNN" не имеют имени. Первый привязанный параметр имеет индекс 1. Если значение n – вне границ диапазона или если n-й параметр не имеет имени, возвращается nil. Функция возвращает sqlite3.OK в случае успешного выполнения или код ошибки в противном случае (см. Результирующие коды и коды ошибок )
stmt:bind_values(value1,value2,...,valueN)
Привязывает заданные значения к параметрам оператора. Функция возвращает sqlite3.OK в случае успешного выполнения или код ошибки в противном случае (см. Результирующие коды и коды ошибок ).
stmt:columns()
Возвращает число столбцов в итоговой выборке, возвращенной оператором stmt, или 0, если оператор не возвращает данных (например, UPDATE).
stmt:finalize()
Эта функция освобождает подготовленный оператор stmt. Если оператор был выполнен успешно или вообще не выполнялся, возвращается sqlite3.OK, в противном случае возвращается код ошибки.
stmt:get_name(n)
Возвращает имя столбца n в итоговой выборке оператора stmt (самый левый столбец имеет номер 0).
stmt:get_named_types()
Возвращает таблицу имен и типов всех столбцов в итоговой выборке оператора stmt.
stmt:get_named_values()
Возвращает таблицу имен и значений всех столбцов в текущей итоговой строке запроса.
stmt:get_names()
Возвращает массив имен всех столбцов в итоговой выборке оператора stmt.
stmt:get_type(n)
Возвращает тип столбца n в итоговой выборке оператора stmt (самый левый столбец имеет номер 0).
stmt:get_types()
Возвращает массив типов всех столбцов в выборке, возвращенной оператором stmt.
stmt:get_unames()
Возвращает список имен всех столбцов в выборке, возвращенной оператором stmt.
stmt:get_utypes()
Возвращает список типов всех столбцов в выборке, возвращенной оператором stmt.
stmt:get_uvalues()
Возвращает список значений всех столбцов в текущей итоговой строке запроса.
stmt:get_value(n)
Возвращает значение столбца n в выборке оператора stmt (самый левый столбец имеет номер 0).
stmt:get_values()
Возвращает массив значений всех столбцов в выборке, возвращаемой оператором stmt.
stmt:isopen()
Возвращает TRUE, если stmt еще не освобожден, или FALSE в противном случае.
stmt:nrows()
Подготовленный эквивалент db:nrows . Возвращает функцию, которая выполняет итерации с именами и значениями выборки оператора stmt. Каждая итерация возвращает таблицу имен и значений текущей строки .
stmt:reset()
Сбрасывает SQL-оператор stmt, и он снова готов к выполнению. Все переменные оператора, которые имели значения, привязанные с помощью функций stmt:bind*() , сохраняют эти значения.
stmt:rows()
Подготовленный эквивалент db:rows . Возвращает функцию, которая выполняет итерации со значениями выборки оператора stmt. Каждая итерация возвращает массив значений текущей строки.
stmt:step()
Эта функция должна быть вызвана для оценки подготовленного оператора stmt или его следующей итерации. Функция возвращает одно из следующих значений:
sqlite3.BUSY: БД-процессор не может запросить необходимые блокировки. Если оператор – это COMMIT вне явной транзакции, Вы можете повторить попытку выполнить оператор. Если оператор – не COMMIT и находится внутри явной транзакции, нужно выполнить откат транзакции перед тем, как продолжить.
sqlite3.DONE: выполнение оператора закончено успешно. stmt:step не следует вызывать повторно без предварительного вызова stmt:reset для сброса виртуальной машины в первоначальное состояние.
sqlite3.ROW: возвращается каждый раз, когда новая строка данных готова к обработке вызывающим оператором. Для доступа к значениям можно использовать функции доступа к столбцам. stmt:step может быть вызвана снова для извлечения следующей строки данных.
sqlite3.ERROR: ошибка режима реального времени (такая, как нарушение ограничивающих условий). stmt:step не должна вызываться вновь. Дополнительная информация может быть получена с помощью db:errmsg . Уточненный код ошибки может быть получен с помощью stmt:reset .
sqlite3.MISUSE: функция была вызвана неверно, возможно, потому, что оператор был уже освобожден или предшествующий вызов stmt:step вернул sqlite3.ERROR или sqlite3.DONE.
stmt:urows()
Подготовленный эквивалент db:urows . Возвращает функцию, которая выполняет итерции со значениями выборки оператора stmt. Каждая итерация возвращает значения текущей строки.