Функция SQLCancel

  • Статья

Соответствия
Представлена версия: соответствие стандартам ODBC 1.0: ISO 92

Сводка
SQLCancel отменяет обработку инструкции.

Чтобы отменить обработку подключения или инструкции, используйте функцию SQLCancelHandle.

Синтаксис

  
SQLRETURN SQLCancel(  
     SQLHSTMT     StatementHandle);

Аргументы

ОператорHandle
[Входные данные] Дескриптор инструкции.

Возвраты

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR или SQL_INVALID_HANDLE.

Диагностика

Когда SQLCancel возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить путем вызова SQLGetDiagRec с помощью HandleType SQL_HANDLE_STMT и handle of StatementHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLCancel и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемым диспетчером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.

SQLSTATE Error Description
01000 Общее предупреждение Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
HY000 Общая ошибка Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере аргумента *MessageText , описывает ошибку и ее причину.
HY001 Ошибка выделения памяти Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции.
HY010 Ошибка последовательности функций (DM) Асинхронно выполняющаяся функция была вызвана для дескриптора соединения, связанного с ОператоромHandle. Эта асинхронная функция по-прежнему выполнялась при вызове функции SQLCancel .

Сбой операции отмены (DM) из-за того, что асинхронная операция выполняется в дескрипторе подключения, связанном с ОператоромHandle.
HY013 Ошибка управления памятью Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти.
HY018 Отклоненный запрос на отмену сервера Сервер отказался от запроса на отмену.
HY117 Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения. (DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function.
HYT01 Время ожидания для подключения истекло Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Драйвер не поддерживает эту функцию (DM) Драйвер, связанный с StatementHandle , не поддерживает функцию.

Комментарии

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

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

  • Функция в инструкции, которая нуждается в данных.

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

В ODBC 2.x, если приложение вызывает SQLCancel, если обработка не выполняется в инструкции, SQLCancel имеет тот же эффект, что и SQLFreeStmt с параметром SQL_CLOSE; это поведение определяется только для полноты, и приложения должны вызывать SQLFreeStmt или SQLCloseCursor для закрытия курсоров.

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

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

После асинхронного вызова функции функция вызывает функцию многократно, чтобы определить, завершена ли обработка. Если функция по-прежнему обрабатывается, она возвращает SQL_STILL_EXECUTING. Если функция завершила обработку, она возвращает другой код.

После любого вызова функции, возвращающей SQL_STILL_EXECUTING, приложение может вызвать SQLCancel , чтобы отменить функцию. Если запрос отмены выполнен успешно, драйвер возвращает SQL_SUCCESS. Это сообщение не указывает, что функция была фактически отменена; указывает, что запрос на отмену был обработан. Если функция фактически отменена, зависит от драйвера и зависит от источника данных. Приложение должно продолжать вызывать исходную функцию, пока возвращаемый код не SQL_STILL_EXECUTING. Если функция была успешно отменена, возвращаемый код SQL_ERROR и SQLSTATE HY008 (операция отменена). Если функция завершила обычную обработку, возвращаемый код SQL_SUCCESS или SQL_SUCCESS_WITH_INFO, если функция завершилась успешно или SQL_ERROR и SQLSTATE, отличной от HY008 (операция отменена), если функция завершилась ошибкой.

Заметка

В ODBC 3.5 вызов SQLCancel , если обработка не выполняется в инструкции, не рассматривается как SQLFreeStmt с параметром SQL_CLOSE, но не действует вообще. Чтобы закрыть курсор, приложение должно вызывать SQLCloseCursor, а не SQLCancel.

Дополнительные сведения об асинхронной обработке см. в разделе "Асинхронное выполнение".

Отмена функций, требующих данных

После возвращения sqlExecute или SQLExecDirect SQL_NEED_DATA и перед отправкой данных для всех параметров выполнения приложение может вызвать SQLCancel , чтобы отменить выполнение инструкции. После отмены инструкции приложение может снова вызвать SQLExecute или SQLExecDirect . Дополнительные сведения см. в разделе SQLBindParameter.

После возврата sqlBulkOperations или SQLSetPos SQL_NEED_DATA и перед отправкой данных для всех столбцов выполнения приложение может вызвать SQLCancel , чтобы отменить операцию. После отмены операции приложение может снова вызвать SQLBulkOperations или SQLSetPos . Отмена не влияет на состояние курсора или текущее положение курсора. Дополнительные сведения см. в статье SQLBulkOperations или SQLSetPos.

Отмена выполнения функций в другом потоке

В мультипотоковом приложении приложение может отменить функцию, которая выполняется в другом потоке. Чтобы отменить функцию, приложение вызывает SQLCancel с тем же дескриптором инструкции, что и целевая функция, но в другом потоке. Как функция отменена, зависит от драйвера и операционной системы. Как и при отмене функции, выполняемой асинхронно, возвращаемый код SQLCancel указывает, успешно ли драйвер обработал запрос. Можно вернуть только SQL_SUCCESS или SQL_ERROR; диагностические сведения не возвращаются. Если исходная функция отменена, она возвращает SQL_ERROR и SQLSTATE HY008 (операция отменена).

Если инструкция SQL выполняется при вызове SQLCancel в другом потоке, чтобы отменить выполнение инструкции, можно выполнить успешно и вернуть SQL_SUCCESS в то время как отмена также выполнена успешно. В этом случае диспетчер драйверов предполагает, что курсор, открытый выполнением инструкции, закрывается отменой, поэтому приложение не сможет использовать курсор.

Дополнительные сведения о потоке см. в разделе "Многопоточность".

Сведения Раздел
Привязка буфера к параметру Функция SQLBindParameter
Выполнение операций массового вставки или обновления Функция SQLBulkOperations
Отменяет функцию, выполняемую асинхронно на дескрипторе подключения, помимо функциональности SQLCancel. Функция SQLCancelHandle
Выполнение инструкции SQL Функция SQLExecDirect
Выполнение подготовленной инструкции SQL Функция SQLExecute
Освобождение дескриптора инструкций SQLFreeStmt
Получение поля диагностической записи или поля заголовка диагностики Функция SQLGetDiagField
Получение нескольких полей структуры диагностических данных Функция SQLGetDiagRec
Возврат следующего параметра для отправки данных Функция SQLParamData
Отправка данных параметров во время выполнения Функция SQLPutData
Размещение курсора в наборе строк, обновление данных в наборе строк или обновление или удаление данных в результирующем наборе Функция SQLSetPos

См. также

Справочник по API ODBC
Файлы заголовков ODBC