Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Соответствие
Представлена версия: соответствие стандартам 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-символ "LIKEpattern 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 оператор OR 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 |