Функция SQLEndTran
Соответствие
Представлена версия: соответствие стандартам ODBC 3.0: ISO 92
Сводка
SQLEndTran запрашивает операцию фиксации или отката для всех активных операций со всеми операторами, связанными с подключением. SQLEndTran также может запросить выполнение операции фиксации или отката для всех подключений, связанных с средой.
Примечание.
Дополнительные сведения о том, с чем диспетчер драйверов сопоставляет эту функцию при использовании ODBC 3.Приложение x работает с ODBC 2.Драйвер x см. в разделе "Функции замены сопоставления" для обеспечения обратной совместимости приложений.
Синтаксис
SQLRETURN SQLEndTran(
SQLSMALLINT HandleType,
SQLHANDLE Handle,
SQLSMALLINT CompletionType);
Аргументы
HandleType
[Входные данные] Обработка идентификатора типа. Содержит либо SQL_HANDLE_ENV (если дескриптор является дескриптором среды) или SQL_HANDLE_DBC (если дескриптор является дескриптором соединения).
Дескриптор
[Входные данные] Дескриптор типа, указанного HandleType, указывающий область транзакции. Дополнительные сведения см. в разделе "Комментарии".
Тип завершения
[Входные данные] Одно из следующих двух значений:
SQL_COMMIT SQL_ROLLBACK
Возвраты
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE или SQL_STILL_EXECUTING.
Диагностика
Когда SQLEndTran возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE может быть получено путем вызова SQLGetDiagRec с соответствующим HandleType и Handle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLEndTran и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемым диспетчером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.
| SQLSTATE | Ошибка | Описание |
|---|---|---|
| 01000 | Общее предупреждение | Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 08003 | Подключение не открыто | (DM) HandleType был SQL_HANDLE_DBC, и дескриптор не был в подключенном состоянии. |
| 08007 | Сбой подключения во время транзакции | HandleType был SQL_HANDLE_DBC, и соединение, связанное с дескриптором, завершилось сбоем во время выполнения функции, и его невозможно определить, произошло ли запрошенное ФИКСАЦИЯ или ROLLBACK до сбоя. |
| 25S01 | Состояние транзакции неизвестно | Одно или несколько подключений в Handle не удалось завершить транзакцию с указанным результатом, и результат неизвестен. |
| 25S02 | Транзакция по-прежнему активна | Драйвер не смог гарантировать, что все работы в глобальной транзакции могут быть завершены атомарно, и транзакция по-прежнему активна. |
| 25S03 | Откат транзакции | Драйвер не смог гарантировать, что все работы в глобальной транзакции могут быть завершены атомарно, и все действия в транзакции, активной в Handle , были откатированы. |
| 40001 | Сбой сериализации | Транзакция была откатена из-за взаимоблокировки ресурсов с другой транзакцией. |
| 40002 | Нарушение ограничений целостности | Тип завершения был SQL_COMMIT, и обязательство изменений вызвало нарушение ограничений целостности. В результате транзакция была откатена. |
| HY000 | Общая ошибка | Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *szMessageText , описывает ошибку и ее причину. |
| HY001 | Ошибка выделения памяти | Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции. |
| HY008 | Операция отменена | Асинхронная обработка была включена для ConnectionHandle. Функция была вызвана и до завершения выполнения функции SQLCancelHandle была вызвана в ConnectionHandle. Затем функция была вызвана снова в ConnectionHandle. Функция была вызвана и до завершения выполнения SQLCancelHandle была вызвана в ConnectionHandle из другого потока в многопотоковом приложении. |
| HY010 | Ошибка последовательности функций | (DM) Асинхронно выполняющаяся функция была вызвана для дескриптора инструкции, связанного с ConnectionHandle , и по-прежнему выполнялась при вызове SQLEndTran . (DM) асинхронно выполняющаяся функция (не эта) была вызвана для ConnectionHandle и по-прежнему выполнялась при вызове этой функции. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos были вызваны для дескриптора инструкции, связанного с ConnectionHandle и возвращенных SQL_NEED_DATA. Эта функция была вызвана до отправки данных для всех параметров выполнения или столбцов. (DM) асинхронно выполняющаяся функция (не эта) была вызвана для дескриптора с параметром HandleType, заданного для SQL_HANDLE_DBC и по-прежнему выполнялась при вызове этой функции. (DM) SQLExecute, SQLExecDirect или SQLMoreResults был вызван для одного из дескрипторов инструкций, связанных с Дескриптором и возвращенным SQL_PARAM_DATA_AVAILABLE. Эта функция была вызвана до получения данных для всех потоковых параметров. |
| HY012 | Недопустимый код операции транзакции | (DM) Значение, указанное для аргумента CompletionType , не было SQL_COMMIT или SQL_ROLLBACK. |
| HY013 | Ошибка управления памятью | Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти. |
| HY092 | Недопустимый идентификатор атрибута или параметра | (DM) Значение, указанное для аргумента HandleType , не было ни SQL_HANDLE_ENV, ни SQL_HANDLE_DBC. |
| HY115 | SQLEndTran не допускается для среды, содержащей подключение с включенным асинхронным выполнением функции | (DM) HandleType не может быть задан SQL_HANDLE_ENV если асинхронное выполнение функций подключения включено для подключения в среде. |
| HY117 | Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения. | Дополнительные сведения о приостановленном состоянии см. в разделе "Комментарии" этой статьи. |
| HYC00 | Необязательный компонент не реализован | Драйвер или источник данных не поддерживает операцию ROLLBACK . |
| HYT01 | Время ожидания для подключения истекло | Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Драйвер не поддерживает эту функцию | (DM) Драйвер, связанный с ConnectionHandle , не поддерживает функцию. |
| IM017 | Опрос отключен в асинхронном режиме уведомлений | При использовании модели уведомлений опрос отключается. |
| IM018 | SQLCompleteAsync не был вызван для выполнения предыдущей асинхронной операции с этим дескриптором. | Если предыдущий вызов функции дескриптора возвращает SQL_STILL_EXECUTING и если включен режим уведомлений, sqlCompleteAsync должен вызываться на дескрипторе для выполнения последующей обработки и завершения операции. |
Комментарии
Для ODBC 3.x driver, если HandleType SQL_HANDLE_ENV и Handle является допустимым дескриптором среды, диспетчер драйверов вызовет SQLEndTran в каждом драйвере, связанном с средой. Аргумент handle для вызова драйвера будет дескриптором среды драйвера. Для ODBC 2.X Driver, если HandleType SQL_HANDLE_ENV и Handle является допустимым дескриптором среды, и в этой среде существует несколько подключений, диспетчер драйверов будет вызывать SQLTransact в драйвере один раз для каждого подключения в подключенном состоянии в этой среде. Аргумент Handle в каждом вызове будет дескриптором соединения. В любом случае драйвер попытается зафиксировать или откатить транзакции в зависимости от значения CompletionType во всех подключениях, которые находятся в подключенном состоянии в этой среде. Подключения, которые не являются активными, не влияют на транзакцию.
Примечание.
SQLEndTran нельзя использовать для фиксации или отката транзакций в общей среде. Функция SQLSTATE HY092 (недопустимый идентификатор атрибута или параметра) возвращается, если sqlEndTran вызывается с помощью handle set to the handle of a shared environment or handle of a shared environment or handle of a connection on a shared environment.
Диспетчер драйверов возвращает SQL_SUCCESS только в том случае, если он получает SQL_SUCCESS для каждого подключения. Если диспетчер драйверов получает SQL_ERROR на одном или нескольких подключениях, он возвращает SQL_ERROR приложению, а диагностические сведения помещаются в структуру диагностических данных среды. Чтобы определить, какое соединение или подключения завершилось сбоем во время операции фиксации или отката, приложение может вызывать SQLGetDiagRec для каждого подключения.
Примечание.
Диспетчер драйверов не имитирует глобальную транзакцию во всех подключениях и поэтому не использует протоколы фиксации двухэтапной фиксации.
Если значение CompletionType SQL_COMMIT, SQLEndTran выдает запрос фиксации для всех активных операций с любой инструкцией, связанной с затронутым подключением. Если значение CompletionType SQL_ROLLBACK, SQLEndTran выдает запрос отката для всех активных операций с любой инструкцией, связанной с затронутым подключением. Если транзакции не активны, SQLEndTran возвращает SQL_SUCCESS без влияния на источники данных. Дополнительные сведения см. в разделе "Фиксация и откат транзакций".
Если драйвер находится в режиме ручной фиксации (вызывая SQLSetConnectAttr с атрибутом SQL_ATTR_AUTOCOMMIT, заданным для SQL_AUTOCOMMIT_OFF), новая транзакция неявно запускается при выполнении инструкции SQL, которая может содержаться в транзакции в текущем источнике данных. Дополнительные сведения см. в разделе "Режим фиксации".
Чтобы определить, как операции транзакций влияют на курсоры, приложение вызывает SQLGetInfo с параметрами SQL_CURSOR_ROLLBACK_BEHAVIOR и SQL_CURSOR_COMMIT_BEHAVIOR. Дополнительные сведения см. в следующих абзацах, а также сведения о влиянии транзакций на курсоры и подготовленные инструкции.
Если значение SQL_CURSOR_ROLLBACK_BEHAVIOR или SQL_CURSOR_COMMIT_BEHAVIOR равно SQL_CB_DELETE, SQLEndTran закрывает и удаляет все открытые курсоры для всех инструкций, связанных с подключением, и удаляет все ожидающие результаты. SQLEndTran оставляет любую инструкцию в выделенном (нерекомендуемом) состоянии; приложение может повторно использовать их для последующих запросов SQL или может вызывать SQLFreeStmt или SQLFreeHandle с помощью HandleType SQL_HANDLE_STMT для их освобождения.
Если значение SQL_CURSOR_ROLLBACK_BEHAVIOR или SQL_CURSOR_COMMIT_BEHAVIOR равно SQL_CB_CLOSE, SQLEndTran закрывает все открытые курсоры для всех инструкций, связанных с подключением. SQLEndTran оставляет любую инструкцию в состоянии подготовки; приложение может вызывать SQLExecute для инструкции, связанной с подключением без первого вызова SQLPrepare.
Если значение SQL_CURSOR_ROLLBACK_BEHAVIOR или SQL_CURSOR_COMMIT_BEHAVIOR равно SQL_CB_PRESERVE, SQLEndTran не влияет на открытые курсоры, связанные с подключением. Курсоры остаются в строке, на которую они указали до вызова SQLEndTran.
Для драйверов и источников данных, поддерживающих транзакции, вызов SQLEndTran либо с SQL_COMMIT или SQL_ROLLBACK, если транзакция не активна, возвращает SQL_SUCCESS (указывая, что не требуется фиксация или откат) и не влияет на источник данных.
Если драйвер находится в режиме автокоммитирования, диспетчер драйверов не вызывает SQLEndTran в драйвере. SQLEndTran всегда возвращает SQL_SUCCESS независимо от того, вызывается ли он с помощью типа завершения SQL_COMMIT или SQL_ROLLBACK.
Драйверы или источники данных, которые не поддерживают транзакции (параметр SQLGetInfo SQL_TXN_CAPABLE SQL_TC_NONE) фактически всегда находятся в режиме автозаключения и поэтому всегда возвращают SQL_SUCCESS для SQLEndTran независимо от того, вызываются ли они с помощью типа завершения SQL_COMMIT или SQL_ROLLBACK. Такие драйверы и источники данных фактически не откатывают транзакции при запросе на это.
Приостановленное состояние
В диспетчерах драйверов, выпущенных до Windows 7, транзакция активна, если SQLEndTran вернул SQL_ERROR из драйвера. Однако возможно, что транзакция была успешно зафиксирована на сервере, но драйвер на клиенте не был уведомлен (например, из-за ошибки сети). Это позволит оставить подключение в плохом состоянии. Начиная с Windows 7, когда SQLEndTran возвращает SQL_ERROR, подключение может находиться в приостановленном состоянии. В приостановленном состоянии можно вызывать функции только для чтения. В конечном итоге приложение должно вызывать SQLDisconnect в приостановленном подключении к ресурсам выпуска.
Если все следующие условия верны, подключение будет помещено в приостановленное состояние:
Драйвер возвращает SQL_ERROR из SQLEndTran.
Драйвер — ODBC версии 3.8 или более поздней.
Версия приложения — 3.8 или более поздняя; или повторно скомпилированного приложения ODBC 2.x или 3.x успешно отменяет функцию SQLEndTran через SQLCancelHandle.
Драйвер не вернул одно из следующих сообщений, которые подтверждают, что транзакция не завершена:
25S03: откат транзакции выполняется
40001: сбой сериализации
40002: ограничение целостности
HYC00: необязательная функция не реализована
Если SQLEndTran был вызван дескриптором среды, а одно из его подключений соответствует приведенным выше условиям, все подключения, подключающиеся к одному драйверу, будут помещены в приостановленное состояние.
После вызова SQLDisconnect в приостановленном подключении подключение можно использовать для повторного подключения к другому источнику данных или тому же источнику данных.
Связанные функции
| Сведения | Смотрите |
|---|---|
| Отмена функции, выполняемой асинхронно на дескрипторе подключения. | Функция SQLCancelHandle |
| Возврат сведений о драйвере или источнике данных | Функция SQLGetInfo |
| Освобождение дескриптора | Функция SQLFreeHandle |
| Освобождение дескриптора инструкций | Функция SQLFreeStmt |
См. также
Справочник по API ODBC
Файлы заголовков ODBC
Асинхронное выполнение (метод опроса)