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