Поделиться через


Функция 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
Асинхронное выполнение (метод опроса)