Função SQLDisconnect
Conformidade
Versão introduzida: Conformidade de padrões do ODBC 1.0: ISO 92
Resumo
SQLDisconnect fecha a conexão associada a um identificador de conexão específico.
Sintaxe
SQLRETURN SQLDisconnect(
SQLHDBC ConnectionHandle);
Argumentos
ConnectionHandle
[Entrada] Identificador de conexão.
Retornos
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE ou SQL_STILL_EXECUTING.
Diagnósticos
Quando SQLDisconnect retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_DBC e um Identificador de ConnectionHandle. A tabela a seguir lista os valores SQLSTATE normalmente retornados por SQLDisconnect 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 o contrário.
| SQLSTATE | Erro | Descrição |
|---|---|---|
| 01000 | Aviso geral | Mensagem informativa específica do driver. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 01002 | Erro de desconexão | Ocorreu um erro durante a desconexão. No entanto, a desconexão foi bem-sucedida. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 08003 | Conexão não aberta | (DM) A conexão especificada no argumento ConnectionHandle não estava aberta. |
| 25000 | Estado de transação inválido | Havia uma transação em processo na conexão especificada pelo argumento ConnectionHandle. A transação permanece ativa. |
| 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 *MessageText 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 ConnectionHandle. A função foi chamada e antes de ser finshed executando 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 concluir a execução de 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 StatementHandle associado ao ConnectionHandle e ainda estava em execução quando SQLDisconnect foi chamado. (DM) Uma função de execução assíncrona (não esta) foi chamada para ConnectionHandle e ainda estava em execução quando essa função foi chamada. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos foi chamado para um StatementHandle 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. |
| 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. |
| HY117 | A conexão está suspensa devido ao estado de transação desconhecido. Somente funções desconectar e somente leitura são permitidas. | (DM) Para obter mais informações sobre o estado suspenso, consulte Função SQLEndTran. |
| 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 e a conexão ainda está ativa. 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
Se um aplicativo chamar SQLDisconnect depois que SQLBrowseConnect retornar SQL_NEED_DATA e antes de retornar um código de retorno diferente, o driver cancelará o processo de navegação de conexão e retornará a conexão a um estado não conectado.
Se um aplicativo chamar SQLDisconnect enquanto houver uma transação incompleta associada ao identificador de conexão, o driver retornará SQLSTATE 25000 (estado de transação inválido), indicando que a transação está inalterada e a conexão está aberta. Uma transação incompleta é aquela que não foi confirmada ou revertida com SQLEndTran.
Se um aplicativo chamar SQLDisconnect antes de liberar todas as instruções associadas à conexão, o driver, depois de se desconectar com êxito da fonte de dados, liberará essas instruções e todos os descritores que foram explicitamente alocados na conexão. No entanto, se uma ou mais das instruções associadas à conexão ainda estiverem em execução de forma assíncrona, SQLDisconnect retornará SQL_ERROR com um valor SQLSTATE de HY010 (erro de sequência de funções). Além disso, o SQLDisconnect liberará todas as instruções associadas e todos os descritores que foram explicitamente alocados na conexão, se a conexão estiver em um estado suspenso ou se SQLDisconnect tiver sido cancelado com êxito pelo SQLCancelHandle.
Para obter informações sobre como um aplicativo usa SQLDisconnect, consulte Desconectando de uma fonte de dados ou driver.
Desconectando de uma conexão em pool
Se o pool de conexões estiver habilitado para um ambiente compartilhado e um aplicativo chamar SQLDisconnect em uma conexão nesse ambiente, a conexão será retornada ao pool de conexões e ainda estará disponível para outros componentes usando o mesmo ambiente compartilhado.
Exemplo de código
Consulte Programa ODBC de exemplo, Função SQLBrowseConnect e Função SQLConnect.
Funções relacionadas
| Para obter informações sobre | Consulte |
|---|---|
| Alocando um identificador | Função SQLAllocHandle |
| Conectando-se a uma fonte de dados | Função SQLConnect |
| Conectando-se a uma fonte de dados usando uma cadeia de conexão ou caixa de diálogo | Função SQLDriverConnect |
| Executando uma operação de confirmação ou reversão | Função SQLEndTran |
| Liberando um identificador de conexão | Função SQLFreeConnect |