Функция SQLEndTran

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

Сводка
SQLEndTran запрашивает операцию фиксации или отката для всех активных операций со всеми операторами, связанными с подключением. SQLEndTran также может запросить выполнение операции фиксации или отката для всех подключений, связанных с средой.

Синтаксис

  
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, если не указано иное.

Комментарии

Для ODBC 3.x driver, если HandleType SQL_HANDLE_ENV и Handle является допустимым дескриптором среды, диспетчер драйверов вызовет SQLEndTran в каждом драйвере, связанном с средой. Аргумент handle для вызова драйвера будет дескриптором среды драйвера. Для ODBC 2.X Driver, если HandleType SQL_HANDLE_ENV и Handle является допустимым дескриптором среды, и в этой среде существует несколько подключений, диспетчер драйверов будет вызывать SQLTransact в драйвере один раз для каждого подключения в подключенном состоянии в этой среде. Аргумент Handle в каждом вызове будет дескриптором соединения. В любом случае драйвер попытается зафиксировать или откатить транзакции в зависимости от значения CompletionType во всех подключениях, которые находятся в подключенном состоянии в этой среде. Подключения, которые не являются активными, не влияют на транзакцию.

Диспетчер драйверов возвращает 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 в приостановленном подключении подключение можно использовать для повторного подключения к другому источнику данных или тому же источнику данных.

Связанные функции

См. также

Справочник по API ODBC
Файлы заголовков ODBC
Асинхронное выполнение (метод опроса)