Функция SQLCancelHandle

соответствие
Представлена версия: соответствие стандартам ODBC 3.8: нет

Ожидается, что большинство драйверов ODBC 3.8 (и более поздних версий) реализуют эту функцию. Если драйвер не имеет, вызов SQLCancelHandle с дескриптором подключения в параметре Handle возвращает SQL_ERROR с sqlSTATE IM001 и сообщение "Драйвер не поддерживает эту функцию" Вызов A Значение , чтобы SQLCancelHandle с дескриптором инструкции, так как параметр обработчика будет сопоставлен с вызовом SQLCancel диспетчером драйверов и может обрабатываться, если драйвер реализует SQLCancel. Приложение может использовать SQLGetFunctions, чтобы определить, поддерживает ли драйвер SQLCancelHandle.

Сводка
SQLCancelHandle отменяет обработку подключения или инструкции. Диспетчер драйверов сопоставляет вызов SQLCancelHandle с вызовом SQLCancel при SQL_HANDLE_STMT HandleType.

Синтаксис

  
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 с HandleType SQL_HANDLE_STMT и дескриптором инструкции Handle или HandleType SQL_HANDLE_DBC и обработчиком соединения Handle.

В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLCancelHandle и объясняются каждый из них в контексте этой функции; Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемым диспетчером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.

Если SQLCancelHandle вызывается с HandleType для SQL_HANDLE_STMT, он может возвращать любой SQLSTATE, который может быть возвращен функцией SQLCancel.

Комментарии

Эта функция аналогична SQLCancel, но может принимать либо соединение, либо дескриптор инструкции в качестве параметра, а не только дескриптор инструкции. Диспетчер драйверов сопоставляет вызов SQLCancelHandle с вызовом SQLCancel при SQL_HANDLE_STMT HandleType. Это позволяет приложениям использовать SQLCancelHandle для отмены операций инструкций, даже если драйвер не реализует SQLCancelHandle.

Дополнительные сведения об отмене операции инструкции см. в функции SQLCancel.

Если нет операций в Handle вызов SQLCancelHandle не действует.

SQLCancelHandle в дескрипторе подключения может отменить следующие типы обработки:

• Функция, выполняющаяся асинхронно в соединении.

• Функция, запущенная в дескрипторе подключения в другом потоке.

Когда SQLCancelHandle вызывается для отмены функции, выполняемой асинхронно в соединении, записи диагностики, опубликованные SQLCancelHandle добавляются к тем, которые возвращаются операцией отмены; SQLCancelHandle не возвращает диагностические записи, однако при отмене функции, работающей в соединении на другом потоке.

Использование SQLCancelHandle для отмены SQLEndTran может поместить подключение в приостановленное состояние. Дополнительные сведения о приостановленном состоянии см. в функции SQLEndTran.

Отмена асинхронной обработки Connection-Related

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