Função SQLEndTran
Compatibilidade
Versão introduzida: ODBC 3.0 Conformidade com os padrões: ISO 92
Resumo
SQLEndTran solicita uma operação de confirmação ou reversão para todas as operações ativas em todas as instruções associadas a uma conexão. O SQLEndTran também pode solicitar que uma operação de confirmação ou reversão seja executada para todas as conexões associadas a um ambiente.
Observação
Para obter mais informações sobre o que o Gerenciador de Driver mapeia essa função quando um ODBC 3.x está funcionando com um ODBC 2.x , consulte Mapeando funções de substituição para compatibilidade com versões anteriores de aplicativos.
Sintaxe
SQLRETURN SQLEndTran(
SQLSMALLINT HandleType,
SQLHANDLE Handle,
SQLSMALLINT CompletionType);
Argumentos
Tipo de Identificador
[Entrada] Identificador de tipo de identificador. Contém SQL_HANDLE_ENV (se Handle for um identificador de ambiente) ou SQL_HANDLE_DBC (se Handle for um identificador de conexão).
Handle
[Entrada] O identificador, do tipo indicado por HandleType, indicando o escopo da transação. Consulte "Comentários" para obter mais informações.
Tipo de conclusão
[Entrada] Um dos dois valores a seguir:
SQL_COMMIT SQL_ROLLBACK
Devoluções
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE ou SQL_STILL_EXECUTING.
Diagnósticos
Quando SQLEndTran retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido chamando SQLGetDiagRec com o HandleType e o Handle apropriados. A tabela a seguir lista os valores SQLSTATE comumente retornados por SQLEndTran e explica cada um no contexto dessa função; a notação "(DM)" precede as descrições de SQLSTATEs retornadas pelo Gerenciador de Driver. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, a menos que indicado de outra forma.
| SQLSTATE | Erro | Descrição |
|---|---|---|
| 01000 | Aviso geral | Mensagem informativa específica do driver. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 08003 | Conexão não aberta | (DM) O HandleType foi SQL_HANDLE_DBC e o Handle não estava em um estado conectado. |
| 08007 | Falha de conexão durante a transação | O HandleType foi SQL_HANDLE_DBC e a conexão associada ao Handle falhou durante a execução da função, e não pode ser determinado se o COMMIT ou ROLLBACK solicitado ocorreu antes da falha. |
| 25S01 | Estado da transação desconhecido | Uma ou mais das conexões em Handle falharam ao concluir a transação com o resultado especificado e o resultado é desconhecido. |
| 25S02 | A transação ainda está ativa | O driver não foi capaz de garantir que todo o trabalho na transação global pudesse ser concluído atomicamente e a transação ainda está ativa. |
| 25S03 | A transação é revertida | O driver não foi capaz de garantir que todo o trabalho na transação global pudesse ser concluído atomicamente e todo o trabalho na transação ativa no Handle foi revertido. |
| 40001 | Falha de serialização | A transação foi revertida devido a um deadlock de recursos com outra transação. |
| 40002 | Violação de restrição de integridade | O CompletionType foi SQL_COMMIT e o compromisso de alterações causou violação de restrição de integridade. Como resultado, a transação foi revertida. |
| HY000 | Erro geral | Ocorreu um erro para o qual não havia SQLSTATE específico e para o qual nenhum SQLSTATE específico da implementação foi definido. A mensagem de erro retornada por SQLGetDiagRec no buffer *szMessageText descreve o erro e sua causa. |
| HY001 | Erro de alocação de memória | O driver não pôde alocar a memória necessária para dar suporte à execução ou conclusão da função. |
| HY008 | Operação cancelada | O processamento assíncrono foi habilitado para o ConnectionHandle. A função foi chamada e, antes de terminar de executar SQLCancelHandle, Function foi chamada no ConnectionHandle. Em seguida, a função foi chamada novamente no ConnectionHandle. A função foi chamada e, antes de terminar de executar SQLCancelHandle , foi chamada no ConnectionHandle de um thread diferente em um aplicativo multithread. |
| HY010 | Erro de sequência de função | (DM) Uma função de execução assíncrona foi chamada para um identificador de instrução associado ao ConnectionHandle e ainda estava em execução quando SQLEndTran foi chamado. (DM) Uma função de execução assíncrona (não esta) foi chamada para o ConnectionHandle e ainda estava em execução quando essa função foi chamada. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos foi chamado para um identificador de instrução associado ao ConnectionHandle e retornou SQL_NEED_DATA. Essa função foi chamada antes que os dados fossem enviados para todos os parâmetros ou colunas de dados em execução. (DM) Uma função de execução assíncrona (não esta) foi chamada para o Handle com HandleType definido como SQL_HANDLE_DBC e ainda estava em execução quando essa função foi chamada. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para um dos identificadores de instrução associados a Handle e retornado SQL_PARAM_DATA_AVAILABLE. Essa função foi chamada antes que os dados fossem recuperados para todos os parâmetros transmitidos. |
| HY012 | Código de operação de transação inválido | (DM) O valor especificado para o argumento CompletionType não era SQL_COMMIT nem SQL_ROLLBACK. |
| HY013 | Erro de gerenciamento de memória | A chamada de função não pôde ser processada porque os objetos de memória subjacentes não puderam ser acessados, possivelmente devido a condições de memória baixa. |
| HY092 | Identificador de atributo/opção inválido | (DM) O valor especificado para o argumento HandleType não foi SQL_HANDLE_ENV nem SQL_HANDLE_DBC. |
| HY115 | SQLEndTran não é permitido para um ambiente que contém uma conexão com execução de função assíncrona habilitada | (DM) HandleType não pode ser definido como SQL_HANDLE_ENV se a execução assíncrona de funções de conexão estiver habilitada para uma conexão no ambiente. |
| HY117 | A conexão está suspensa devido ao estado desconhecido da transação. Somente funções de desconexão e somente leitura são permitidas. | (DM) Para obter mais informações sobre o estado suspenso, consulte a seção Comentários deste tópico. |
| HYC00 | Recurso opcional não implementado | O driver ou a fonte de dados não dá suporte à operação ROLLBACK . |
| HYT01 | O tempo limite da conexão expirou | O período de tempo limite da conexão expirou antes que a fonte de dados respondesse à solicitação. O período de tempo limite da conexão é definido por meio de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | O driver não suporta esta função | (DM) O driver associado ao ConnectionHandle não dá suporte à função. |
| IM017 | A sondagem está desabilitada no modo de notificação assíncrona | Sempre que o modelo de notificação é usado, a sondagem é desabilitada. |
| IM018 | SQLCompleteAsync não foi chamado para concluir a operação assíncrona anterior nesse identificador. | Se a chamada de função anterior no identificador retornar SQL_STILL_EXECUTING e se o modo de notificação estiver habilitado, SQLCompleteAsync deverá ser chamado no identificador para fazer o pós-processamento e concluir a operação. |
Comentários
Para um ODBC 3.x , se HandleType for SQL_HANDLE_ENV e Handle for um identificador de ambiente válido, o Gerenciador de Driver chamará SQLEndTran em cada driver associado ao ambiente. O argumento Handle para a chamada para um driver será o identificador de ambiente do driver. Para um ODBC 2.x , se HandleType for SQL_HANDLE_ENV e Handle for um identificador de ambiente válido e houver várias conexões em um estado conectado nesse ambiente, o Gerenciador de Driver chamará SQLTransact no driver uma vez para cada conexão em um estado conectado nesse ambiente. O argumento Handle em cada chamada será o identificador da conexão. Em ambos os casos, o driver tentará confirmar ou reverter transações, dependendo do valor de CompletionType, em todas as conexões que estão em um estado conectado nesse ambiente. As conexões que não estão ativas não afetam a transação.
Observação
SQLEndTran não pode ser usado para confirmar ou reverter transações em um ambiente compartilhado. SQLSTATE HY092 (identificador de atributo/opção inválido) será retornado se SQLEndTran for chamado com Handle definido como o identificador de um ambiente compartilhado ou o identificador de uma conexão em um ambiente compartilhado.
O Gerenciador de Driver retornará SQL_SUCCESS somente se receber SQL_SUCCESS para cada conexão. Se o Gerenciador de Driver receber SQL_ERROR em uma ou mais conexões, ele retornará SQL_ERROR ao aplicativo e as informações de diagnóstico serão colocadas na estrutura de dados de diagnóstico do ambiente. Para determinar qual conexão ou conexões falharam durante a operação de confirmação ou reversão, o aplicativo pode chamar SQLGetDiagRec para cada conexão.
Observação
O Gerenciador de Driver não simula uma transação global em todas as conexões e, portanto, não usa protocolos de confirmação de duas fases.
Se CompletionType for SQL_COMMIT, SQLEndTran emitirá uma solicitação de confirmação para todas as operações ativas em qualquer instrução associada a uma conexão afetada. Se CompletionType for SQL_ROLLBACK, SQLEndTran emitirá uma solicitação de reversão para todas as operações ativas em qualquer instrução associada a uma conexão afetada. Se nenhuma transação estiver ativa, SQLEndTran retornará SQL_SUCCESS sem efeito em nenhuma fonte de dados. Para obter mais informações, consulte Confirmando e revertendo transações.
Se o driver estiver no modo de confirmação manual (chamando SQLSetConnectAttr com o atributo SQL_ATTR_AUTOCOMMIT definido como SQL_AUTOCOMMIT_OFF), uma nova transação será iniciada implicitamente quando uma instrução SQL que pode estar contida em uma transação for executada na fonte de dados atual. Para obter mais informações, consulte Modo de confirmação.
Para determinar como as operações de transação afetam os cursores, um aplicativo chama SQLGetInfo com as opções SQL_CURSOR_ROLLBACK_BEHAVIOR e SQL_CURSOR_COMMIT_BEHAVIOR. Para obter mais informações, consulte os parágrafos a seguir e também consulte Efeito de transações em cursores e instruções preparadas.
Se o valor SQL_CURSOR_ROLLBACK_BEHAVIOR ou SQL_CURSOR_COMMIT_BEHAVIOR for igual a SQL_CB_DELETE, SQLEndTran fechará e excluirá todos os cursores abertos em todas as instruções associadas à conexão e descartará todos os resultados pendentes. SQLEndTran deixa qualquer instrução presente em um estado alocado (despreparado); o aplicativo pode reutilizá-los para solicitações SQL subsequentes ou pode chamar SQLFreeStmt ou SQLFreeHandle com um HandleType de SQL_HANDLE_STMT para desalocá-los.
Se o valor SQL_CURSOR_ROLLBACK_BEHAVIOR ou SQL_CURSOR_COMMIT_BEHAVIOR for igual a SQL_CB_CLOSE, SQLEndTran fechará todos os cursores abertos em todas as instruções associadas à conexão. SQLEndTran deixa qualquer instrução presente em um estado preparado; o aplicativo pode chamar SQLExecute para uma instrução associada à conexão sem primeiro chamar SQLPrepare.
Se o valor SQL_CURSOR_ROLLBACK_BEHAVIOR ou SQL_CURSOR_COMMIT_BEHAVIOR for igual a SQL_CB_PRESERVE, SQLEndTran não afetará os cursores abertos associados à conexão. Os cursores permanecem na linha para a qual apontaram antes da chamada para SQLEndTran.
Para drivers e fontes de dados que dão suporte a transações, chamar SQLEndTran com SQL_COMMIT ou SQL_ROLLBACK quando nenhuma transação está ativa retorna SQL_SUCCESS (indicando que não há trabalho a ser confirmado ou revertido) e não tem efeito na fonte de dados.
Quando um driver está no modo de confirmação automática, o Gerenciador de Driver não chama SQLEndTran no driver. SQLEndTran sempre retorna SQL_SUCCESS independentemente de ser chamado com um CompletionType de SQL_COMMIT ou SQL_ROLLBACK.
Drivers ou fontes de dados que não dão suporte a transações (a opção SQLGetInfo SQL_TXN_CAPABLE é SQL_TC_NONE) estão efetivamente sempre no modo de confirmação automática e, portanto, sempre retornam SQL_SUCCESS para SQLEndTran, independentemente de serem chamados ou não com um CompletionType de SQL_COMMIT ou SQL_ROLLBACK. Esses drivers e fontes de dados não revertem transações quando solicitados a fazê-lo.
Estado Suspenso
Nos Gerenciadores de Driver lançados antes do Windows 7, uma transação estava ativa se o SQLEndTran retornasse SQL_ERROR do driver. No entanto, era possível que a transação tivesse sido confirmada com êxito no servidor, mas o driver no cliente não tivesse sido notificado (por exemplo, porque ocorreu um erro de rede). Isso deixaria a conexão em um estado ruim. A partir do Windows 7, quando SQLEndTran retorna SQL_ERROR, a conexão pode estar em um estado suspenso. Em um estado suspenso, é possível chamar funções somente leitura. Eventualmente, o aplicativo deve chamar SQLDisconnect em uma conexão suspensa para liberar recursos.
Se todas as condições a seguir forem verdadeiras, a conexão será colocada em um estado suspenso:
O driver retorna SQL_ERROR de SQLEndTran.
O driver é ODBC versão 3.8 ou posterior.
A versão do aplicativo é 3.8 ou posterior; ou o aplicativo ODBC 2.x ou 3.x recompilado cancela com êxito a função SQLEndTran por meio de SQLCancelHandle.
O driver não retornou uma das seguintes mensagens, que confirmam que a transação não foi concluída:
25S03: A transação é revertida
40001: Falha de serialização
40002: Restrição de integridade
HYC00: Recurso opcional não implementado
Se SQLEndTran foi chamado em um identificador de ambiente e uma de suas conexões atendeu às condições acima, todas as conexões conectadas ao mesmo driver serão colocadas no estado suspenso.
Depois que um aplicativo chama SQLDisconnect em uma conexão suspensa, a conexão pode ser usada para se reconectar a outra fonte de dados ou à mesma fonte de dados.
Funções relacionadas
| Para obter informações sobre | Consulte |
|---|---|
| Cancelar uma função em execução assíncrona em um identificador de conexão. | Função SQLCancelHandle |
| Retornando informações sobre um driver ou fonte de dados | Função SQLGetInfo |
| Liberando uma alça | Função SQLFreeHandle |
| Liberando um identificador de instrução | Função SQLFreeStmt |
Confira também
Referência de API do ODBC
Arquivos de cabeçalho ODBC
Execução assíncrona (método de sondagem)