Функция 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, если не указано иное.

Если 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".

Отмена асинхронной обработки, связанной с подключением

Если функция возвращает 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 смог отменить операцию.

Связанные функции

См. также

Справочник по API ODBC
Файлы заголовков ODBC
Асинхронное выполнение (метод опроса)