Функция SQLPrepare
Соответствие
Представлена версия: соответствие стандартам ODBC 1.0: ISO 92
Сводка
SQLPrepare подготавливает строку SQL для выполнения.
Синтаксис
SQLRETURN SQLPrepare(
SQLHSTMT StatementHandle,
SQLCHAR * StatementText,
SQLINTEGER TextLength);
Аргументы
ОператорHandle
[Входные данные] Дескриптор инструкции.
StatementText
[Входные данные] Текстовая строка SQL.
TextLength
[Входные данные] Длина *StatementText в символах.
Возвраты
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR или SQL_INVALID_HANDLE.
Диагностика
Когда SQLPrepare возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить путем вызова SQLGetDiagRec с помощью HandleType SQL_HANDLE_STMT и handle of StatementHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLPrepare и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемым диспетчером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.
| SQLSTATE | Ошибка | Описание |
|---|---|---|
| 01000 | Общее предупреждение | Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 01S02 | Изменено значение параметра | Указанный атрибут инструкции был недопустим из-за условий работы реализации, поэтому аналогичное значение временно заменено. (SQLGetStmtAttr можно вызвать, чтобы определить, что такое временно замененное значение.) Значение замены допустимо для оператора StatementHandle , пока курсор не будет закрыт. Атрибуты инструкции, которые можно изменить: SQL_ATTR_CONCURRENCY SQL_ATTR_CURSOR_TYPE SQL_ATTR_KEYSET_SIZE SQL_ATTR_MAX_LENGTH SQL_ATTR_MAX_ROWS SQL_ATTR_QUERY_TIMEOUT SQL_ATTR_SIMULATE_CURSOR (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 08S01 | Сбой связи | Связь между драйвером и источником данных, к которому был подключен драйвер, произошел сбой до завершения обработки функции. |
| 21S01 | Список вставок значений не соответствует списку столбцов | *StatementText содержал инструкцию INSERT , а количество вставленных значений не соответствовало степени производной таблицы. |
| 21S02 | Степень производной таблицы не соответствует списку столбцов | *StatementText содержит инструкцию CREATE VIEW , а число указанных имен не совпадает с производной таблицей, определенной спецификацией запроса. |
| 22018 | Недопустимое значение символа для спецификации приведения | *StatementText содержит инструкцию SQL, содержащую литерал или параметр, и значение несовместимо с типом данных связанного столбца таблицы. |
| 22019 | Недопустимый escape-символ | Аргумент StatementText содержал предикат LIKE с ESCAPE в предложении WHERE, а длина escape-символа после ESCAPE не равна 1. |
| 22025 | Недопустимая последовательность escape-адресов | Аргумент StatementText содержит escape-символ "LIKE pattern value ESCAPE" в предложении WHERE, а символ, следующий за escape-символом в значении шаблона, не был ни "%", ни "_". |
| 24000 | Недопустимое состояние курсора | (DM) Курсор был открыт на ОператорHandle, а SQLFetch или SQLFetchScroll был вызван. Курсор был открыт на операторе StatementHandle, но не был вызван SQLFetch или SQLFetchScroll . |
| 34000 | Недопустимое имя курсора | *StatementText содержал позиционированный DELETE или позиционированный UPDATE, а курсор, на который ссылается подготовленный оператор, не был открыт. |
| 3D000 | Недопустимое имя каталога | Имя каталога, указанное в StatementText , было недопустимым. |
| 3F000 | Недопустимое имя схемы | Недопустимое имя схемы, указанное в StatementText . |
| 42 000 | Синтаксическая ошибка или нарушение доступа | *StatementText содержал инструкцию SQL, которая не была предварительной или содержала синтаксическую ошибку. *StatementText содержал инструкцию, для которой у пользователя не было необходимых привилегий. |
| 42S01 | Базовая таблица или представление уже существует | *StatementText содержит инструкцию CREATE TABLE или CREATE VIEW, а имя таблицы или имя представления уже существует. |
| 42S02 | Базовая таблица или представление не найдено | *StatementText содержал инструкцию DROP TABLE или DROP VIEW , а указанное имя таблицы или имя представления не существовало. *StatementText содержит инструкцию ALTER TABLE , а указанное имя таблицы не существует. *StatementText содержит инструкцию CREATE VIEW , а имя таблицы или представления, определенное спецификацией запроса, не существует. *StatementText содержал инструкцию CREATE INDEX , и указанное имя таблицы не существовало. *StatementText содержал инструкцию GRANT или REVOKE , а указанное имя таблицы или имя представления не существовало. *StatementText содержал инструкцию SELECT , а указанное имя таблицы или имя представления не существовало. *StatementText содержал инструкцию DELETE, INSERT или UPDATE , а указанное имя таблицы не существовало. *StatementText содержал инструкцию CREATE TABLE , а таблица, указанная в ограничении (ссылающаяся на таблицу, не созданную) не существовала. |
| 42S11 | Индекс уже существует | *StatementText содержит инструкцию CREATE INDEX , а указанное имя индекса уже существует. |
| 42S12 | Индекс не найден | *StatementText содержал инструкцию DROP INDEX , и указанное имя индекса не существовало. |
| 42S21 | Столбец уже существует | *StatementText содержит инструкцию ALTER TABLE, а столбец, указанный в предложении ADD, не является уникальным или идентифицирует существующий столбец в базовой таблице. |
| 42S22 | Столбец не найден | *StatementText содержал инструкцию CREATE INDEX , а один или несколько имен столбцов, указанных в списке столбцов, не существовали. *StatementText содержал инструкцию GRANT или REVOKE , а указанное имя столбца не существовало. *StatementText содержит инструкцию SELECT, DELETE, INSERT или UPDATE, а указанное имя столбца не существует. *StatementText содержал инструкцию CREATE TABLE , а столбец, указанный в ограничении (ссылающийся на таблицу, не созданную) не существовал. |
| HY000 | Общая ошибка | Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину. |
| HY001 | Ошибка выделения памяти | Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции. |
| HY008 | Операция отменена | Асинхронная обработка была включена для ОператораHandle. Функция была вызвана и до завершения выполнения, SQLCancel или SQLCancelHandle была вызвана в операторе StatementHandle, а затем функция была вызвана снова на ОператорHandle. Функция была вызвана и до завершения выполнения SQLCancel или SQLCancelHandle была вызвана оператором StatementHandle из другого потока в многопотоковом приложении. |
| HY009 | Недопустимое использование указателя NULL | (DM) StatementText — это указатель null. |
| HY010 | Ошибка последовательности функций | (DM) Асинхронно выполняющаяся функция была вызвана для дескриптора соединения, связанного с ОператоромHandle. Эта асинхронная функция по-прежнему выполнялась при вызове функции SQLPrepare . (DM) SQLExecute, SQLExecDirect или SQLMoreResults был вызван для ОператораHandle и возвращен SQL_PARAM_DATA_AVAILABLE. Эта функция была вызвана до получения данных для всех потоковых параметров. (DM) асинхронно выполняющаяся функция (не эта) была вызвана для StatementHandle и по-прежнему выполнялась при вызове этой функции. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos были вызваны для ОператораHandle и возвращены SQL_NEED_DATA. Эта функция была вызвана до отправки данных для всех параметров выполнения или столбцов. |
| HY013 | Ошибка управления памятью | Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти. |
| HY090 | Недопустимая длина строки или буфера | (DM) Аргумент TextLength был меньше или равен 0, но не равен SQL_NTS. |
| HY117 | Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения. | (DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function. |
| HYC00 | Необязательный компонент не реализован | Параметр параллелизма недопустим для определенного типа курсора. Для атрибута инструкции SQL_ATTR_USE_BOOKMARKS задано значение SQL_UB_VARIABLE, а для атрибута инструкции SQL_ATTR_CURSOR_TYPE задан тип курсора, для которого драйвер не поддерживает закладки. |
| HYT00 | Время ожидания истекло. | Срок ожидания истек, прежде чем источник данных вернул результирующий набор. Период времени ожидания задается через SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT. |
| HYT01 | Время ожидания для подключения истекло | Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Драйвер не поддерживает эту функцию | (DM) Драйвер, связанный с StatementHandle , не поддерживает функцию. |
| IM017 | Опрос отключен в асинхронном режиме уведомлений | При использовании модели уведомлений опрос отключается. |
| IM018 | SQLCompleteAsync не был вызван для выполнения предыдущей асинхронной операции с этим дескриптором. | Если предыдущий вызов функции дескриптора возвращает SQL_STILL_EXECUTING и если включен режим уведомлений, sqlCompleteAsync должен вызываться на дескрипторе для выполнения последующей обработки и завершения операции. |
Комментарии
Приложение вызывает SQLPrepare для отправки инструкции SQL в источник данных для подготовки. Дополнительные сведения о подготовленном выполнении см. в разделе "Подготовленное выполнение". Приложение может включать один или несколько маркеров параметров в инструкцию SQL. Чтобы включить маркер параметра, приложение внедряет вопросительный знак (?) в строку SQL по соответствующей позиции. Сведения о параметрах см. в разделе "Параметры инструкции".
Примечание.
Если приложение использует SQLPrepare для подготовки и SQLExecute для отправки инструкции COMMIT или ROLLBACK , взаимодействие между продуктами СУБД не будет. Чтобы зафиксировать или откат транзакции, вызовите SQLEndTran.
Драйвер может изменить инструкцию, чтобы использовать форму SQL, используемую источником данных, а затем отправить ее в источник данных для подготовки. В частности, драйвер изменяет escape-последовательности, используемые для определения синтаксиса SQL для определенных функций. (Описание грамматики инструкции SQL см. в разделе Escape-последовательности в ODBC и приложении C: грамматика SQL.) Для драйвера дескриптор инструкции аналогичен идентификатору инструкции в внедренном коде SQL. Если источник данных поддерживает идентификаторы инструкций, драйвер может отправить идентификатор оператора и значения параметров в источник данных.
После подготовки инструкции приложение использует дескриптор инструкции для ссылки на инструкцию в последующих вызовах функций. Подготовленная инструкция, связанная с дескриптором инструкции, может быть повторно выполнена путем вызова SQLExecute, пока приложение не освобождает инструкцию с вызовом SQLFreeStmt с параметром SQL_DROP или до тех пор, пока дескриптор инструкции не будет использоваться в вызове SQLPrepare, SQLExecDirect или одной из функций каталога (SQLColumns, SQLTables и т. д.). После подготовки инструкции приложение может запросить сведения о формате результирующий набор. Для некоторых реализаций вызов SQLDescribeCol или SQLDescribeParam после SQLPrepare может не быть столь эффективным, как вызов функции после SQLExecute или SQLExecDirect.
Некоторые драйверы не могут возвращать синтаксические ошибки или нарушения доступа, когда приложение вызывает SQLPrepare. Драйвер может обрабатывать синтаксические ошибки и нарушения доступа, только синтаксические ошибки или ни синтаксические ошибки, ни нарушения доступа. Поэтому приложение должно иметь возможность обрабатывать эти условия при вызове последующих связанных функций, таких как SQLNumResultCols, SQLDescribeCol, SQLColAttribute и SQLExecute.
В зависимости от возможностей драйвера и источника данных сведения о параметрах (например, типы данных) могут проверяться при подготовке инструкции (если все параметры привязаны) или при выполнении (если все параметры не привязаны). Для максимальной совместимости приложение должно отменить привязку всех параметров, примененных к старой инструкции SQL, прежде чем подготовить новую инструкцию SQL для одной инструкции. Это предотвращает ошибки, которые возникают из-за старых сведений о параметрах, применяемых к новой инструкции.
Внимание
Фиксация транзакции путем явного вызова SQLEndTran или путем работы в режиме автоматической фиксации может привести к удалению источников данных планов доступа для всех инструкций подключения. Дополнительные сведения см. в SQL_CURSOR_COMMIT_BEHAVIOR и SQL_CURSOR_ROLLBACK_BEHAVIOR типах сведений в SQLGetInfo и эффекте транзакций на курсорах и подготовленных инструкциях.
Пример кода
См. статью SQLBindParameter, SQLPutData и SQLSetPos.
Связанные функции
| Сведения | Смотрите |
|---|---|
| Выделение дескриптора инструкций | Функция SQLAllocHandle |
| Привязка буфера к столбцу в результирующем наборе | Функция SQLBindCol |
| Привязка буфера к параметру | Функция SQLBindParameter |
| Отмена обработки инструкций | Функция SQLCancel |
| Выполнение операции фиксации или отката | Функция SQLEndTran |
| Выполнение инструкции SQL | Функция SQLExecDirect |
| Выполнение подготовленной инструкции SQL | Функция SQLExecute |
| Возврат количества строк, затронутых инструкцией | Функция SQLRowCount |
| Задание имени курсора | Функция SQLSetCursorName |