Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Conformidade
Versão Introduzida: Normas ODBC 3.0 Conformidade: ISO 92
Summary
O SQLEndTran solicita uma operação de commit ou rollback para todas as operações ativas em todas as instruções associadas a uma ligação.
O SQLEndTran pode também solicitar que seja realizada uma operação de commit ou rollback para todas as ligações associadas a um ambiente.
Note
Para mais informações sobre o que o Driver Manager mapeia esta função quando um ODBC 3. A aplicação x está a funcionar com um ODBC 2. x , veja Mapear Funções de Substituição para Compatibilidade Retrocedora de Aplicações.
Syntax
SQLRETURN SQLEndTran(
SQLSMALLINT HandleType,
SQLHANDLE Handle,
SQLSMALLINT CompletionType);
Arguments
HandleType
[Entrada] Identificador de tipo de alça. Contém ou SQL_HANDLE_ENV (se o Handle for um handle de ambiente) ou SQL_HANDLE_DBC (se o Handle for um handle de ligação).
Manípulo
[Entrada] O handle, do tipo indicado por HandleType, indica o âmbito da transação. Consulte "Comentários" para mais informações.
CompletionType
[Entrada] Um dos seguintes dois valores:
SQL_COMMIT SQL_ROLLBACK
Devoluções
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE ou SQL_STILL_EXECUTING.
Diagnósticos
Quando o SQLEndTran devolve SQL_ERROR ou SQL_SUCCESS_WITH_INFO, pode ser obtido um valor SQLSTATE associado chamando SQLGetDiagRec com o HandleType e o Handle apropriados. A tabela seguinte lista os valores SQLSTATE normalmente devolvidos pelo SQLEndTran e explica cada um no contexto desta função; a notação "(DM)" precede as descrições dos SQLSTATEs devolvidas pelo Gestor de Drivers. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, salvo indicação em contrário.
| SQLSTATE | Erro | Description |
|---|---|---|
| 01000 | Aviso geral | Mensagem informativa específica para o condutor. (Função devolve SQL_SUCCESS_WITH_INFO.) |
| 08003 | Ligação não aberta | (DM) O HandleType estava SQL_HANDLE_DBC, e o Handle não estava num estado de conexão. |
| 08007 | Falha de ligação durante a transação | O HandleType estava SQL_HANDLE_DBC, e a ligação associada ao Handle falhou durante a execução da função, não podendo ser determinado se o COMMIT ou ROLLBACK solicitado ocorreu antes da falha. |
| 25S01 | Estado da transação desconhecido | Uma ou mais das ligações no Handle falharam em concluir a transação com o resultado especificado, e o resultado é desconhecido. |
| 25S02 | A transação continua ativa | O driver não conseguiu garantir que todo o trabalho na transação global pudesse ser concluído atómicamente, e a transação continuava ativa. |
| 25S03 | A transação é revertida | O driver não conseguia garantir que todo o trabalho na transação global pudesse ser concluído atomicamente, e todo o trabalho na transação ativo em Handle foi revertido. |
| 40001 | Falha de serialização | A transação foi revertida devido a um bloqueio de recursos com outra transação. |
| 40002 | Violação de restrições de integridade | O CompletionType era SQL_COMMIT, e o compromisso de alterações causava violação de restrições de integridade. Como resultado, a transação foi revertida. |
| HY000 | Erro geral | Ocorreu um erro para o qual não existia um SQLSTATE específico e para o qual não estava definido nenhum SQLSTATE específico da implementação. A mensagem de erro devolvida pelo SQLGetDiagRec no buffer *szMessageText descreve o erro e a sua causa. |
| HY001 | Erro de alocação de memória | O driver não conseguia alocar a memória necessária para suportar a execução ou conclusão da função. |
| HY008 | Operação cancelada | O processamento assíncrono foi ativado para o ConnectionHandle. A função foi chamada e, antes de terminar de executar , a Função SQLCancelHandle foi chamada no ConnectionHandle. Depois, a função era chamada novamente no ConnectionHandle. A função era chamada e, antes de terminar de executar, o SQLCancelHandle era chamado no ConnectionHandle a partir de outro thread numa aplicação multithread. |
| HY010 | Erro de sequência de funções | (DM) Uma função de execução assíncrona era chamada para um handle de instrução associado ao ConnectionHandle e ainda estava a correr quando o SQLEndTran era chamado. (DM) Uma função de execução assíncrona (não esta) era chamada para o ConnectionHandle e continuava a ser executada quando esta função era chamada. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos era chamado para um handle de instrução associado ao ConnectionHandle e devolvido SQL_NEED_DATA. Esta função era chamada antes de os dados serem enviados para todos os parâmetros ou colunas de dados na execução. (DM) Uma função de execução assíncrona (não esta) era chamada para o Handle com o HandleType definido para SQL_HANDLE_DBC e continuava a ser executada quando esta função era chamada. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para um dos handles de instruções associados ao Handle e devolvido SQL_PARAM_DATA_AVAILABLE. Esta função era chamada antes de os dados serem 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 nem SQL_COMMIT nem SQL_ROLLBACK. |
| HY013 | Erro de gestão de memória | A chamada de função não podia ser processada porque os objetos de memória subjacentes não podiam ser acedidos, possivelmente devido a condições de baixa memória. |
| HY092 | Identificador de atributo/opção inválido | (DM) O valor especificado para o argumento HandleType não era nem SQL_HANDLE_ENV nem SQL_HANDLE_DBC. |
| HY115 | O SQLEndTran não é permitido para um ambiente que contenha uma ligação com execução de funções assíncronas ativada | (DM) O HandleType não pode ser definido para SQL_HANDLE_ENV se a execução assíncrona das funções de ligação estiver ativada para uma ligação no ambiente. |
| HY117 | A ligação é suspensa devido ao estado desconhecido da transação. Apenas funções de desconexão e de leitura são permitidas. | (DM) Para mais informações sobre o estado suspenso, consulte a secção de Comentários deste tópico. |
| HYC00 | Funcionalidade opcional não implementada | O driver ou fonte de dados não suporta a operação ROLLBACK . |
| HYT01 | Expirou o tempo limite de ligação | O período de timeout da ligação expirou antes de a fonte de dados responder ao pedido. O período de tempo de expiração da ligação é definido através do SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | O driver não suporta esta função | (DM) O driver associado ao ConnectionHandle não suporta esta função. |
| IM017 | A sondagem está desativada no modo de notificação assíncrona | Sempre que o modelo de notificação é utilizado, o sonding é desativado. |
| IM018 | O SQLCompleteAsync não foi chamado para completar a operação assíncrona anterior neste handle. | Se a chamada de função anterior no handle devolver SQL_STILL_EXECUTING e se o modo de notificação estiver ativado, o SQLCompleteAsync deve ser chamado no handle para fazer o pós-processamento e completar a operação. |
Comments
Para um ODBC 3. x , se HandleType for SQL_HANDLE_ENV e Handle for um handle de ambiente válido, então o Gestor de Drivers chamará SQLEndTran em cada driver associado ao ambiente. O argumento da alavanca para a chamada a um condutor será a alavanca do ambiente do condutor. Para um ODBC 2. x , se o HandleType for SQL_HANDLE_ENV e o Handle for um handle válido no ambiente, e houver múltiplas ligações num estado ligado nesse ambiente, então o Gestor de Drivers chamará SQLTransact no driver uma vez por cada ligação num estado ligado nesse ambiente. O argumento Handle em cada chamada será o handle da ligação. Em qualquer dos casos, o driver tentará comprometer ou reverter transações, dependendo do valor do CompletionType, em todas as ligações que estejam num estado de ligação nesse ambiente. Ligações que não estão ativas não afetam a transação.
Note
O SQLEndTran não pode ser usado para comprometer ou reverter transações num ambiente partilhado. SQLSTATE HY092 (Identificador de atributo/opção inválido) será devolvido se o SQLEndTran for chamado com o Handle definido para o handle de um ambiente partilhado ou para o handle de uma ligação num ambiente partilhado.
O Driver Manager só devolve SQL_SUCCESS se receber SQL_SUCCESS para cada ligação. Se o Gestor de Drivers receber SQL_ERROR numa ou mais ligações, devolve SQL_ERROR à aplicação, e a informação de diagnóstico é colocada na estrutura de dados de diagnóstico do ambiente. Para determinar que ligação(s) falharam durante a operação de commit ou rollback, a aplicação pode chamar SQLGetDiagRec para cada ligação.
Note
O Driver Manager não simula uma transação global em todas as ligações e, por isso, não utiliza protocolos de commit em duas fases.
Se o CompletionType estiver SQL_COMMIT, o SQLEndTran emite um pedido de commit para todas as operações ativas em qualquer instrução associada a uma ligação afetada. Se o CompletionType estiver SQL_ROLLBACK, o SQLEndTran emite um pedido de rollback para todas as operações ativas em qualquer instrução associada a uma ligação afetada. Se não houver transações ativas, o SQLEndTran devolve SQL_SUCCESS sem afetar quaisquer fontes de dados. Para mais informações, consulte Transações de Comprometimento e Reversão de Transações.
Se o driver estiver em modo de commit manual (chamando SQLSetConnectAttr com o atributo SQL_ATTR_AUTOCOMMIT definido para SQL_AUTOCOMMIT_OFF), uma nova transação é implicitamente iniciada quando uma instrução SQL que pode estar contida numa transação é executada contra a fonte de dados atual. Para mais informações, consulte Modo de Compromisso.
Para determinar como as operações de transação afetam os cursores, uma aplicação chama SQLGetInfo com as opções SQL_CURSOR_ROLLBACK_BEHAVIOR e SQL_CURSOR_COMMIT_BEHAVIOR. Para mais informações, consulte os parágrafos seguintes e veja também Efeito das Transações nos Cursores e Declarações Preparadas.
Se o valor SQL_CURSOR_ROLLBACK_BEHAVIOR ou SQL_CURSOR_COMMIT_BEHAVIOR for igual a SQL_CB_DELETE, o SQLEndTran fecha e apaga todos os cursores abertos em todas as instruções associadas à ligação e descarta todos os resultados pendentes. O SQLEndTran deixa qualquer instrução presente num estado alocado (não preparado); a aplicação pode reutilizá-los para pedidos SQL subsequentes ou pode chamar SQLFreeStmt ou SQLFreeHandle com um HandleType de SQL_HANDLE_STMT para os desalocar.
Se o valor SQL_CURSOR_ROLLBACK_BEHAVIOR ou SQL_CURSOR_COMMIT_BEHAVIOR for igual a SQL_CB_CLOSE, o SQLEndTran fecha todos os cursores abertos em todas as instruções associadas à ligação. O SQLEndTran mantém qualquer instrução presente num estado preparado; a aplicação pode chamar SQLExecute para uma instrução associada à ligação sem antes chamar SQLPrepare.
Se o valor SQL_CURSOR_ROLLBACK_BEHAVIOR ou SQL_CURSOR_COMMIT_BEHAVIOR for igual a SQL_CB_PRESERVE, o SQLEndTran não afeta os cursores abertos associados à ligação. Os cursores permanecem na linha para a qual apontaram antes da chamada ao SQLEndTran.
Para drivers e fontes de dados que suportam 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 comprometer ou reverter) e não tem efeito na fonte de dados.
Quando um driver está em modo de autocommit, o Gestor de Drivers não chama SQLEndTran no driver. O SQLEndTran devolve sempre SQL_SUCCESS independentemente de ser chamado com um CompletionType de SQL_COMMIT ou SQL_ROLLBACK.
Drivers ou fontes de dados que não suportam transações (opçãoSQLGetInfo SQL_TXN_CAPABLE é SQL_TC_NONE) estão efetivamente sempre em modo de autocommit e, por isso, retornam sempre SQL_SUCCESS para SQLEndTran, quer sejam chamados com um CompletionType de SQL_COMMIT ou SQL_ROLLBACK. Tais condutores e fontes de dados não revertem realmente transações quando solicitados.
Estado Suspenso
Nos Gestores de Drivers lançados antes de Windows 7, uma transação estava ativa se o SQLEndTran devolvesse SQL_ERROR do driver. No entanto, era possível que a transação tivesse sido confirmada com sucesso no servidor, mas o driver no cliente não tivesse sido notificado (por exemplo, porque ocorreu um erro de rede). Isto deixaria a ligação num mau estado. A partir de Windows 7, quando o SQLEndTran devolve SQL_ERROR, a ligação pode estar num estado suspenso. Num estado suspenso, é possível chamar funções apenas de leitura. Eventualmente, a aplicação deve chamar SQLDisconnect numa ligação suspensa para libertar recursos.
Se todas as seguintes condições forem verdadeiras, a ligação será colocada num estado suspenso:
O driver devolve SQL_ERROR do SQLEndTran.
O driver é ODBC versão 3.8, ou posterior.
A versão da aplicação é a 3.8 ou posterior; ou a aplicação ODBC 2.x ou 3.x recompilada cancela com sucesso a função SQLEndTran através do SQLCancelHandle.
O motorista não respondeu a uma das seguintes mensagens, que confirmam que a transação não foi concluída:
25S03: A transação é revertida
40001: Falha na serialização
40002: Restrição de integridade
HYC00: Funcionalidade opcional não implementada
Se o SQLEndTran foi chamado num handle de ambiente e uma das suas ligações cumpriu as condições acima, todas as ligações ligadas ao mesmo driver serão colocadas em estado suspenso.
Depois de uma aplicação chamar SQLDisconnect numa ligação suspensa, a ligaçã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 | Veja |
|---|---|
| Cancelar uma função a correr assíncrona numa alavanca de ligação. | Função SQLCancelHandle |
| Retorno de informação sobre um driver ou fonte de dados | Função SQLGetInfo |
| Libertar uma pega | Função SQLFreeHandle |
| Libertação de um handle de instrução | Função SQLFreeStmt |