Функция SQLExecDirect
Соответствие
Представлена версия: соответствие стандартам ODBC 1.0: ISO 92
Сводка
SQLExecDirect выполняет препарабельную инструкцию, используя текущие значения переменных маркера параметра, если какие-либо параметры существуют в инструкции. SQLExecDirect — самый быстрый способ отправки инструкции SQL для однократного выполнения.
Синтаксис
SQLRETURN SQLExecDirect(
SQLHSTMT StatementHandle,
SQLCHAR * StatementText,
SQLINTEGER TextLength);
Аргументы
ОператорHandle
[Входные данные] Дескриптор инструкции.
StatementText
[Входные данные] Инструкция SQL для выполнения.
TextLength
[Входные данные] Длина *StatementText в символах.
Возвраты
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_STILL_EXECUTING, SQL_ERROR, SQL_NO_DATA, SQL_INVALID_HANDLE или SQL_PARAM_DATA_AVAILABLE.
Диагностика
Когда SQLExecDirect возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить путем вызова SQLGetDiagRec с помощью HandleType SQL_HANDLE_STMT и handle of StatementHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLExecDirect и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемым диспетчером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.
| SQLSTATE | Ошибка | Описание |
|---|---|---|
| 01000 | Общее предупреждение | Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 01001 | Конфликт операций курсора | *StatementText содержал позиционированную инструкцию обновления или удаления, а строки или несколько строк не были обновлены или удалены. (Дополнительные сведения об обновлениях нескольких строк см. в описании SQL_ATTR_SIMULATE_CURSOR Атрибут в SQLSetStmtAttr.) (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 01003 | Значение NULL, устраненное в функции set | Аргумент StatementText содержал функцию set (например, AVG, MAX, MIN и т. д.), но не функцию count set, а значения аргументов NULL были устранены до применения функции. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 01004 | Строковые данные, усеченные справа | Строковые или двоичные данные, возвращаемые для входного или выходного параметра, привели к усечению небланковых символов или ненулевых двоичных данных. Если это строковое значение, оно было усечено по правому краю. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 01006 | Привилегии не отозваны | *StatementText содержал инструкцию REVOKE , и у пользователя не было указанной привилегии. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 01007 | Привилегии не предоставлены | *StatementText — это инструкция GRANT , и пользователю не удалось предоставить указанные привилегии. |
| 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.) |
| 01S07 | Дробное усечение | Данные, возвращаемые для входного или выходного параметра, усечены таким образом, чтобы дробная часть числового типа данных была усечена или дробной частью компонента времени, метки времени или типа данных интервала. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 07002 | Неправильное поле COUNT | Число параметров, указанных в SQLBindParameter , меньше количества параметров в инструкции SQL, содержащейся в *StatementText. SQLBindParameter был вызван с параметром ParameterValuePtr , который имеет значение NULL, StrLen_or_IndPtr не задано значение SQL_NULL_DATA или SQL_DATA_AT_EXEC, и InputOutputType не задано значение SQL_PARAM_OUTPUT, чтобы число параметров, указанных в SQLBindParameter , было больше количества параметров в инструкции SQL, содержащейся в файле *StatementText. |
| 07006 | Нарушение атрибута ограниченного типа данных | Значение данных, определяемое аргументом ValueType в SQLBindParameter для связанного параметра, не может быть преобразовано в тип данных, определенный аргументом ParameterType в SQLBindParameter. Значение данных, возвращаемое для параметра, привязанного к SQL_PARAM_INPUT_OUTPUT или SQL_PARAM_OUTPUT, не может быть преобразовано в тип данных, определенный аргументом ValueType в SQLBindParameter. (Если значения данных для одной или нескольких строк не удалось преобразовать, но одна или несколько строк были успешно возвращены, эта функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 07007 | Нарушение ограниченного значения параметра | Тип параметра SQL_PARAM_INPUT_OUTPUT_STREAM используется только для параметра, который отправляет и получает данные в частях. Для этого типа параметра не допускается входной привязанный буфер. Эта ошибка возникает, если тип параметра SQL_PARAM_INPUT_OUTPUT, и если параметр *StrLen_or_IndPtr , указанный в SQLBindParameter , не равен SQL_NULL_DATA, SQL_DEFAULT_PARAM, SQL_LEN_DATA_AT_EXEC(len) или SQL_DATA_AT_EXEC. |
| 07S01 | Недопустимое использование параметра по умолчанию | Значение параметра, заданное с помощью SQLBindParameter, было SQL_DEFAULT_PARAM, а соответствующий параметр не имеет значения по умолчанию. |
| 08S01 | Сбой связи | Связь между драйвером и источником данных, к которому был подключен драйвер, произошел сбой до завершения обработки функции. |
| 21S01 | Список вставок значений не соответствует списку столбцов | *StatementText содержал инструкцию INSERT , а количество вставленных значений не соответствовало степени производной таблицы. |
| 21S02 | Степень производной таблицы не соответствует списку столбцов | *StatementText содержит инструкцию CREATE VIEW и список неквалифицированных столбцов (количество столбцов, указанных для представления в аргументах идентификатора столбца инструкции SQL), содержит больше имен, чем количество столбцов в производной таблице, определенной аргументом спецификации запроса инструкции SQL. |
| 22001 | Строковые данные, правое усечение | Назначение символа или двоичного значения столбцу привело к усечению небланковых символьных данных или ненулевого двоичного значения. |
| 22002 | Переменная индикатора, требуемая, но не указанная | Данные NULL были привязаны к выходному параметру, StrLen_or_IndPtr заданный SQLBindParameter был указателем NULL. |
| 22003 | Числовое значение вне диапазона | *StatementText содержит инструкцию SQL, содержащую привязанный числовый параметр или литерал, и значение привело ко всей части (в отличие от дробной) части числа, усеченной при назначении связанному столбцу таблицы. Возвращая числовое значение (как числовое или строковое) для одного или нескольких входных или выходных параметров, было бы вызвано усечение всей части (в отличие от дробной) части числа. |
| 22007 | Недопустимый формат datetime | *StatementText содержал инструкцию SQL, содержащую структуру даты, времени или метки времени в качестве привязанного параметра, а параметр был соответственно недопустимым датой, временем или меткой времени. Входной или выходной параметр привязан к структуре даты, времени или метки времени, а значение в возвращаемом параметре было соответственно недопустимой датой, временем или меткой времени. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 22008 | Переполнение поля Datetime | *StatementText содержит инструкцию SQL, содержащую выражение datetime, которое при вычислении привело к недопустимой структуре меток даты, времени или метки времени. Выражение даты и времени, вычисленное для входного или выходного параметра, привело к недопустимой структуре даты, времени или метки времени. |
| 22012 | Деление по нулю | *StatementText содержит инструкцию SQL, содержащую арифметическое выражение, которое вызвало деление на ноль. Арифметическое выражение, вычисляемое для входного или выходного параметра, приводит к делении на нулю. |
| 22015 | Переполнение поля интервала | *StatementText содержит точный числовый или интервальный параметр, который при преобразовании в тип данных SQL интервала вызвал потерю значительных цифр. *StatementText содержал параметр интервала с несколькими полями, которые при преобразовании в числовый тип данных в столбце не имели представления в числовом типе данных. *StatementText содержит данные параметров, назначенные типу SQL интервала, и не было представления значения типа C в типе SQL интервала. Назначение входного или выходного параметра, который был точным числовым или интервалным типом SQL для типа C интервала C, приводил к потере значительных цифр. При назначении входного или выходного параметра структуре C интервала не было представления данных в структуре данных интервала. |
| 22018 | Недопустимое значение символа для спецификации приведения | *StatementText содержал тип C, который был точным или приблизительным числом, датой и интервалом, типом данных SQL столбца был символьный тип данных, а значение в столбце не было допустимым литералом привязанного типа C. При возврате входного или выходного параметра тип SQL был точным или приблизительным числом, датой или типом данных интервала; Тип C был SQL_C_CHAR; значение в столбце не является допустимым литералом связанного типа SQL. |
| 22019 | Недопустимый escape-символ | *StatementText содержит инструкцию SQL, содержащую предикат LIKE с ESCAPE в предложении WHERE , а длина escape-символа после ESCAPE не равна 1. |
| 22025 | Недопустимая последовательность escape-адресов | *StatementText содержит инструкцию SQL, содержащую "ESCAPE-символ значения шаблона LIKE" в предложении WHERE, а символ, следующий за escape-символом в значении шаблона, не был одним из "%" или "_". |
| 23000 | Нарушение ограничений целостности | *StatementText содержит инструкцию SQL, содержащую параметр или литерал. Значение параметра было NULL для столбца, определенного как NOT NULL в связанном столбце таблицы, повторяющееся значение было предоставлено для столбца, ограниченного только уникальными значениями, или другое ограничение целостности было нарушено. |
| 24000 | Недопустимое состояние курсора | Курсор был размещен на ОператорHandle SQLFetch или SQLFetchScroll. Эта ошибка возвращается диспетчером драйверов, если SQLFetch или SQLFetchScroll не вернул SQL_NO_DATA и возвращается драйвером, если SQLFetch или SQLFetchScroll вернул SQL_NO_DATA. Курсор был открыт, но не расположен на ОператорHandle. *StatementText содержал позиционированную инструкцию обновления или удаления, а курсор был размещен до начала результирующий набор или после окончания результирующий набор. |
| 34000 | Недопустимое имя курсора | *StatementText содержал позиционный оператор обновления или удаления, и курсор, на который ссылается выполняемая инструкция, не был открыт. |
| 3D000 | Недопустимое имя каталога | Имя каталога, указанное в StatementText , было недопустимым. |
| 3F000 | Недопустимое имя схемы | Недопустимое имя схемы, указанное в StatementText . |
| 40001 | Сбой сериализации | Транзакция была откатена из-за взаимоблокировки ресурсов с другой транзакцией. |
| 40003 | Неизвестное завершение инструкции | Связанное соединение завершилось сбоем во время выполнения этой функции, и состояние транзакции невозможно определить. |
| 42 000 | Синтаксическая ошибка или нарушение доступа | *StatementText содержал инструкцию SQL, которая не была предварительной или содержала синтаксическую ошибку. У пользователя не было разрешения на выполнение инструкции 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 , а таблица, указанная в ограничении (ссылающаяся на таблицу, не созданную) не существовала. *StatementText содержал инструкцию CREATE SCHEMA , а указанное имя таблицы или имя представления не существовало. |
| 42S11 | Индекс уже существует | *StatementText содержит инструкцию CREATE INDEX , а указанное имя индекса уже существует. *StatementText содержит инструкцию CREATE SCHEMA , а указанное имя индекса уже существует. |
| 42S12 | Индекс не найден | *StatementText содержал инструкцию DROP INDEX , и указанное имя индекса не существовало. |
| 42S21 | Столбец уже существует | *StatementText содержит инструкцию ALTER TABLE, а столбец, указанный в предложении ADD, не является уникальным или идентифицирует существующий столбец в базовой таблице. |
| 42S22 | Столбец не найден | *StatementText содержал инструкцию CREATE INDEX , а один или несколько имен столбцов, указанных в списке столбцов, не существовали. *StatementText содержал инструкцию GRANT или REVOKE , а указанное имя столбца не существовало. *StatementText содержит инструкцию SELECT, DELETE, INSERT или UPDATE, а указанное имя столбца не существует. *StatementText содержал инструкцию CREATE TABLE , а столбец, указанный в ограничении (ссылающийся на таблицу, не созданную) не существовал. *StatementText содержит инструкцию CREATE SCHEMA , а указанное имя столбца не существует. |
| 44000 | Нарушение параметра WITH CHECK OPTION | Аргумент StatementText содержит инструкцию INSERT, выполняемую в просмотре таблицу или таблицу, полученную из просматриваемой таблицы, созданной путем указания WITH CHECK OPTION, таким образом, что одна или несколько строк, затронутых инструкцией INSERT, больше не будут присутствовать в просматриваемой таблице. Аргумент StatementText содержал инструкцию UPDATE, выполняемую в просматриваемой таблице или таблице, полученной из просматриваемой таблицы, созданной путем указания WITH CHECK OPTION, таким образом, что одна или несколько строк, затронутых инструкцией UPDATE, больше не будут присутствовать в просматриваемой таблице. |
| HY000 | Общая ошибка | Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину. |
| HY001 | Ошибка выделения памяти | Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции. |
| HY008 | Операция отменена | Асинхронная обработка была включена для ОператораHandle. Функция была вызвана и до завершения выполнения, SQLCancel или SQLCancelHandle была вызвана на ОператорHandle. Затем функция снова была вызвана на ОператорHandle. Функция была вызвана и до завершения выполнения SQLCancel или SQLCancelHandle была вызвана оператором StatementHandle из другого потока в многопотоковом приложении. |
| HY009 | Недопустимое использование указателя NULL | (DM) *StatementText — это указатель null. |
| HY010 | Ошибка последовательности функций | (DM) Асинхронно выполняющаяся функция была вызвана для дескриптора соединения, связанного с ОператоромHandle. Эта асинхронная функция по-прежнему выполнялась при вызове функции SQLExecDirect . (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. Значение параметра, заданное с помощью SQLBindParameter, было пустым указателем, и значение длины параметра не равно 0, SQL_NULL_DATA, SQL_DATA_AT_EXEC, SQL_DEFAULT_PARAM или меньше или равно SQL_LEN_DATA_AT_EXEC_OFFSET. Значение параметра, заданное с помощью SQLBindParameter, не было указателем NULL; тип данных C был SQL_C_BINARY или SQL_C_CHAR; и значение длины параметра было меньше 0, но не было SQL_NTS, SQL_NULL_DATA, SQL_DATA_AT_EXEC, SQL_DEFAULT_PARAM или меньше или равно SQL_LEN_DATA_AT_EXEC_OFFSET. Значение длины параметра, привязанное к SQLBindParameter , было задано значение SQL_DATA_AT_EXEC; тип SQL был либо SQL_LONGVARCHAR, SQL_LONGVARBINARY, либо длинный тип данных для конкретного источника данных; а тип сведений SQL_NEED_LONG_DATA_LEN в SQLGetInfo был "Y". |
| HY105 | Недопустимый тип параметра | Значение, указанное для аргумента InputOutputType в SQLBindParameter , было SQL_PARAM_OUTPUT, и параметр был входным параметром. |
| HY109 | Недопустимое положение курсора | *StatementText содержал позиционированную инструкцию обновления или удаления, и курсор был размещен ( SQLSetPos или SQLFetchScroll) в строке, которая была удалена или не удалось получить. |
| HY117 | Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения. | (DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function. |
| HYC00 | Необязательный компонент не реализован | Сочетание текущих параметров SQL_ATTR_CONCURRENCY и атрибутов инструкции SQL_ATTR_CURSOR_TYPE не поддерживается драйвером или источником данных. Для атрибута инструкции 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 должен вызываться на дескрипторе для выполнения последующей обработки и завершения операции. |
Комментарии
Приложение вызывает SQLExecDirect для отправки инструкции SQL в источник данных. Дополнительные сведения о прямом выполнении см. в разделе "Прямое выполнение". Драйвер изменяет инструкцию для использования формы SQL, используемой источником данных, а затем отправляет его в источник данных. В частности, драйвер изменяет escape-последовательности, используемые для определения определенных функций в SQL. Синтаксис escape-последовательностей см. в разделе "Escape-последовательности" в ODBC.
Приложение может включать один или несколько маркеров параметров в инструкцию SQL. Чтобы включить маркер параметра, приложение внедряет вопросительный знак (?) в инструкцию SQL по соответствующей позиции. Сведения о параметрах см. в разделе "Параметры инструкции".
Если инструкция SQL является инструкцией SELECT и если приложение с именем SQLSetCursorName связывает курсор с инструкцией, драйвер использует указанный курсор. В противном случае драйвер создает имя курсора.
Если источник данных находится в режиме ручной фиксации (требующий явного запуска транзакции) и транзакция еще не была инициирована, драйвер инициирует транзакцию перед отправкой инструкции SQL. Дополнительные сведения см. в режиме ручной фиксации.
Если приложение использует SQLExecDirect для отправки инструкции COMMIT или ROLLBACK , она не будет взаимодействовать между продуктами СУБД. Для фиксации или отката транзакции приложение вызывает SQLEndTran.
Если SQLExecDirect сталкивается с параметром выполнения данных, он возвращает SQL_NEED_DATA. Приложение отправляет данные с помощью SQLParamData и SQLPutData. См. статью SQLBindParameter, SQLParamData, SQLPutData и отправка длинных данных.
Если SQLExecDirect выполняет поисковую инструкцию обновления, вставки или удаления, которая не влияет на строки в источнике данных, вызов SQLExecDirect возвращает SQL_NO_DATA.
Если значение атрибута инструкции SQL_ATTR_PARAMSET_SIZE больше 1, а инструкция SQL содержит по крайней мере один маркер параметра, SQLExecDirect будет выполнять инструкцию SQL один раз для каждого набора значений параметров из массивов, на которые указывает аргумент ParameterValuePointer в вызове SQLBindParameter. Дополнительные сведения см. в разделе "Массивы значений параметров".
Если закладки включены и выполняется запрос, который не поддерживает закладки, драйвер должен попытаться принудить среду к одной, поддерживающей закладки, изменив значение атрибута и возвращая значение SQLSTATE 01S02 (значение параметра изменено). Если атрибут нельзя изменить, драйвер должен вернуть SQLSTATE HY024 (недопустимое значение атрибута).
Примечание.
При использовании пула подключений приложение не должно выполнять инструкции SQL, которые изменяют базу данных или контекст базы данных, например инструкцию USE database в SQL Server, которая изменяет каталог, используемый источником данных.
Пример кода
См. статью SQLBindCol, SQLGetData и пример программы ODBC.
Связанные функции
| Сведения | Смотрите |
|---|---|
| Привязка буфера к столбцу в результирующем наборе | Функция SQLBindCol |
| Отмена обработки инструкций | Функция SQLCancel |
| Выполнение операции фиксации или отката | Функция SQLEndTran |
| Выполнение подготовленной инструкции SQL | Функция SQLExecute |
| Получение нескольких строк данных | Функция SQLFetch |
| Получение блока данных или прокрутка результирующий набор | Функция SQLFetchScroll |
| Возврат имени курсора | Функция SQLGetCursorName |
| Извлечение части или всех столбцов данных | Функция SQLGetData |
| Возврат следующего параметра для отправки данных | Функция SQLParamData |
| Подготовка инструкции для выполнения | Функция SQLPrepare |
| Отправка данных параметров во время выполнения | Функция SQLPutData |
| Задание имени курсора | Функция SQLSetCursorName |
| Задание атрибута инструкции | Функция SQLSetStmtAttr |