Функция SQLCancelHandle
Соответствия
Представлена версия: соответствие стандартам ODBC 3.8: нет
Ожидается, что большинство драйверов ODBC 3.8 (и более поздних версий) реализуют эту функцию. Если драйвер не работает, вызов SQLCancelHandle с дескриптором подключения в параметре Handle вернет SQL_ERROR с SQLSTATE IM001 и сообщением "Драйвер не поддерживает эту функцию" Вызов SQLCancelHandle с дескриптором инструкции, так как параметр Handle будет сопоставлен с вызовом SQLCancel диспетчером драйверов и может быть обработан, если драйвер реализует SQLCancel. Приложение может использовать SQLGetFunctions для определения того, поддерживает ли драйвер SQLCancelHandle.
Сводка
SQLCancelHandle отменяет обработку подключения или инструкции. Диспетчер драйверов сопоставляет вызов SQLCancelHandle с вызовом SQLCancel, когда HandleType SQL_HANDLE_STMT.
Синтаксис
SQLRETURN SQLCancelHandle(
SQLSMALLINT HandleType,
SQLHANDLE Handle);
Аргументы
HandleType
[Входные данные] Тип дескриптора, на котором выполняется обработка цель. Допустимые значения : SQL_HANDLE_DBC или SQL_HANDLE_STMT.
Дескриптор
[Входные данные] Дескриптор, на котором требуется отменить обработку.
Если Handle не является допустимым дескриптором типа, заданного HandleType, SQLCancelHandle возвращает SQL_INVALID_HANDLE.
Возвраты
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR или SQL_INVALID_HANDLE.
Диагностика
Когда SQLCancelHandle возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить путем вызова SQLGetDiagRec с обработчиком SQL_HANDLE_STMT и дескриптором инструкции или дескрипторомдескриптора SQL_HANDLE_DBC и дескриптором соединения.
В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLCancelHandle и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемых диспетчером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.
| SQLSTATE | Error | Description |
|---|---|---|
| 01000 | Общее предупреждение | Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| HY000 | Общая ошибка | Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере аргумента *MessageText , описывает ошибку и ее причину. |
| HY001 | Ошибка выделения памяти | Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции. |
| HY010 | Ошибка последовательности функций | Асинхронно выполняющаяся функция, связанная с оператором, была вызвана для одного из дескрипторов инструкций, связанных с дескриптором, и Для HandleType было задано значение SQL_HANDLE_DBC. Асинхронная функция по-прежнему выполнялась при вызове SQLCancelHandle . (DM) Аргумент HandleType был SQL_HANDLE_STMT; асинхронно выполняющаяся функция была вызвана на связанном дескрипторе подключения, и функция по-прежнему выполняется при вызове этой функции. (DM) SQLExecute, SQLExecDirect или SQLMoreResults был вызван для одного из дескрипторов инструкций, связанных с handle and HandleType, был установлен на SQL_HANDLE_DBC и возвращен SQL_PARAM_DATA_AVAILABLE. Эта функция была вызвана до получения данных для всех потоковых параметров. SQLBrowseConnect был вызван для ConnectionHandle и возвращен SQL_NEED_DATA. Эта функция была вызвана до завершения процесса просмотра. |
| HY013 | Ошибка управления памятью | Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти. |
| HY092 | Недопустимый идентификатор атрибута или параметра | Для HandleType задано значение SQL_HANDLE_ENV или SQL_HANDLE_DESC. |
| HY117 | Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения. | (DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function. |
| HYT01 | Время ожидания для подключения истекло | Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Драйвер не поддерживает эту функцию | (DM) Драйвер, связанный с дескриптором, не поддерживает функцию. |
Если SQLCancelHandle вызывается с параметром HandleType с значением SQL_HANDLE_STMT, он может возвращать любой SQLSTATE, который может быть возвращен функцией SQLCancel.
Комментарии
Эта функция похожа на SQLCancel , но может принимать соединение или дескриптор инструкции в качестве параметра, а не только дескриптор инструкции. Диспетчер драйверов сопоставляет вызов SQLCancelHandle с вызовом SQLCancel, когда HandleType SQL_HANDLE_STMT. Это позволяет приложениям использовать SQLCancelHandle для отмены операций инструкций, даже если драйвер не реализует SQLCancelHandle.
Дополнительные сведения об отмене операции инструкции см. в статье SQLCancel Function.
Если операции не выполняются при вызовеSQLCancelHandle , не действует.
SQLCancelHandle в дескрипторе подключения может отменить следующие типы обработки:
Функция, выполняющаяся асинхронно в соединении.
Функция, запущенная в дескрипторе подключения в другом потоке.
При вызове SQLCancelHandle для отмены функции, выполняемой асинхронно в соединении, записи диагностики, опубликованные SQLCancelHandle, добавляются к тем, которые возвращаются операцией отмены; SQLCancelHandle не возвращает диагностические записи, однако при отмене функции, работающей на соединении в другом потоке.
Использование SQLCancelHandle для отмены SQLEndTran может поместить подключение в приостановленное состояние. Дополнительные сведения о приостановленном состоянии см. в разделе "Функция SQLEndTran".
Заметка
Сведения об использовании SQLCancelHandle в приложении, которое будет развернуто в операционной системе Windows старше Windows 7, см. в таблице совместимости.
Отмена асинхронной обработки, связанной с подключением
Если функция возвращает SQL_STILL_EXECUTING, приложение может вызвать SQLCancelHandle , чтобы отменить операцию. Если запрос отмены выполнен успешно, SQLCancelHandle возвращает SQL_SUCCESS. Это не означает, что исходная функция была отменена; указывает, что запрос на отмену был обработан. Драйвер и источник данных определяют, когда или если операция отменена. Приложение должно продолжать вызывать исходную функцию, пока возвращаемый код не SQL_STILL_EXECUTING. Если исходная функция отменена, возвращаемый код SQL_ERROR и SQLSTATE HY008 (операция отменена). Если исходная функция завершила обычную обработку (не была отменена), код возврата SQL_SUCCESS или SQL_SUCCESS_WITH_INFO или SQL_ERROR и SQLSTATE, отличный от HY008 (операция отменена), если исходная функция завершилась ошибкой.
Отмена выполнения функций в другом потоке
В многопоточных приложениях приложение может отменить операцию, которая выполняется в другом потоке. Чтобы отменить операцию, приложение вызывает SQLCancelHandle с дескриптором, используемым функцией, но в другом потоке. Драйвер и операционная система определяют способ отмены операции. Код возврата SQLCancelHandle указывает, обрабатывает ли драйвер запрос, возвращая SQL_SUCCESS или SQL_ERROR (диагностические сведения не возвращаются). Если обработка исходной функции отменена, исходная функция возвращает SQL_ERROR и SQLSTATE HY008 (операция отменена).
Если функция выполняется при вызове SQLCancelHandle в другом потоке, чтобы отменить функцию, можно успешно выполнить функцию и вернуть SQL_SUCCESS до того, как отмена может вступить в силу. Вызов SQLCancelHandle не действует, если операция завершена до того, как SQLCancelHandle смог отменить операцию.
Связанные функции
| Сведения | Раздел |
|---|---|
| Отмена функции, выполняемой асинхронно в дескрипторе инструкции, отмене функции в инструкции, требующей данных, или отмене функции, выполняемой в инструкции в другом потоке. | Функция SQLCancel |
См. также
Справочник по API ODBC
Файлы заголовков ODBC
Асинхронное выполнение (метод опроса)