Função SQLEndTran

  • Artigo

Conformidade
Versão introduzida: ODBC 3.0 Standards Compliance: 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 para quando um ODBC 3. o aplicativo x está trabalhando com um ODBC 2. x driver, 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

Handletype
[Entrada] Identificador de tipo de identificador 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.

CompletionType
[Entrada] Um dos dois valores a seguir:

SQL_COMMIT SQL_ROLLBACK

Retornos

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 Handle apropriados. A tabela a seguir lista os valores SQLSTATE normalmente retornados por SQLEndTran e explica cada um deles 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 Identificador 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 Identificador falhou durante a execução da função e não é possível determinar se o COMMIT ou ROLLBACK solicitado ocorreu antes da falha.
25S01 Estado da transação desconhecido Uma ou mais das conexões no 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 conseguiu garantir que todo o trabalho na transação global pudesse ser concluído atomicamente e que a transação ainda está ativa.
25S03 A transação é revertida O driver não conseguiu 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 na serialização A transação foi revertida devido a um deadlock de recursos com outra transação.
40002 Violação da restrição de integridade O CompletionType foi SQL_COMMIT e o compromisso de alterações causou violação da restrição de integridade. Como resultado, a transação foi revertida.
HY000 Erro geral Ocorreu um erro para o qual não havia nenhum 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 a Função SQLCancelHandle 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 o SQLCancelHandle , foi chamada no ConnectionHandle de um thread diferente em um aplicativo multithread.
HY010 Erro de sequência de funções (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 retornado SQL_NEED_DATA. Essa função foi chamada antes de os dados serem 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 Identificador 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 ao Handle e retornados SQL_PARAM_DATA_AVAILABLE. Essa função foi 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 foi 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 era SQL_HANDLE_ENV nem SQL_HANDLE_DBC.
HY115 SQLEndTran não é permitido para um ambiente que contém uma conexão com a execução de função assíncrona habilitada (DM) HandleType não poderá 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 é suspensa devido ao estado de transação desconhecido. 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 da fonte de dados responder à 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 dá suporte a essa 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 driver, 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 a um driver será o identificador de ambiente do driver. Para um ODBC 2. x driver, 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

O SQLEndTran não pode ser usado para confirmar ou reverter transações em um ambiente compartilhado. SQLSTATE HY092 (identificador de opção/atributo 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 em 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 ser 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 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á-las.

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á cursores abertos associados à conexão. Os cursores permanecem na linha que 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 estiver ativa retorna SQL_SUCCESS (indicando que não há trabalho a ser confirmado ou revertido) e não tem nenhum efeito sobre a 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çãoSQLGetInfo SQL_TXN_CAPABLE é SQL_TC_NONE) estão sempre no modo de confirmação automática e, portanto, sempre retornam SQL_SUCCESS para SQLEndTran se são 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

Em Gerenciadores de Driver que foram lançados antes do Windows 7, uma transação estava ativa se 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 havia sido notificado (por exemplo, porque ocorreu um erro de rede). Isso deixaria a conexão em um estado inválido. 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 seguintes condições forem verdadeiras, a conexão será colocada em um estado suspenso:

  • O driver retorna SQL_ERROR do SQLEndTran.

  • O driver é o 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 na serialização

    • 40002: restrição de integridade

    • HYC00: recurso opcional não implementado

Se SQLEndTran tiver sido chamado em um identificador de ambiente e uma de suas conexões atender às condições acima, todas as conexões que se conectam 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.

Para obter informações sobre Consulte
Cancelando uma função em execução de forma 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 um identificador Função SQLFreeHandle
Liberando um identificador de instrução Função SQLFreeStmt

Consulte Também

Referência de API do ODBC
Arquivos de cabeçalho ODBC
Execução assíncrona (método polling)