Функция 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 | Ошибка | Описание |
|---|---|---|
| 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 |