Função SQLConnect
Conformidade
Versão introduzida: ODBC 1.0 Standards Compliance: ISO 92
Resumo
O SQLConnect estabelece conexões com um driver e uma fonte de dados. O identificador de conexão faz referência ao armazenamento de todas as informações sobre a conexão com a fonte de dados, incluindo status, estado da transação e informações de erro.
Sintaxe
SQLRETURN SQLConnect(
SQLHDBC ConnectionHandle,
SQLCHAR * ServerName,
SQLSMALLINT NameLength1,
SQLCHAR * UserName,
SQLSMALLINT NameLength2,
SQLCHAR * Authentication,
SQLSMALLINT NameLength3);
Argumentos
ConnectionHandle
[Entrada] Identificador de conexão.
ServerName
[Entrada] Nome da fonte de dados. Os dados podem estar localizados no mesmo computador que o programa ou em outro computador em algum lugar em uma rede. Para obter informações sobre como um aplicativo escolhe uma fonte de dados, consulte Escolhendo uma fonte de dados ou driver.
NameLength1
[Entrada] Comprimento de *ServerName em caracteres.
UserName
[Entrada] Identificador de usuário.
NameLength2
[Entrada] Comprimento de *UserName em caracteres.
Autenticação
[Entrada] Cadeia de caracteres de autenticação (normalmente a senha).
NameLength3
[Entrada] Comprimento de *Autenticação em caracteres.
Retornos
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE ou SQL_STILL_EXECUTING.
Diagnósticos
Quando SQLConnect 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 SQLConnect 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.) |
| 01S02 | Valor da opção alterado | O driver não deu suporte ao valor especificado do argumento ValuePtr em SQLSetConnectAttr e substituiu um valor semelhante. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 08001 | O cliente não consegue estabelecer a conexão | O driver não pôde estabelecer uma conexão com a fonte de dados. |
| 08002 | Nome da conexão em uso | (DM) O ConnectionHandle especificado já havia sido usado para estabelecer uma conexão com uma fonte de dados e a conexão ainda estava aberta ou o usuário estava procurando uma conexão. |
| 08004 | O servidor rejeitou a conexão | A fonte de dados rejeitou o estabelecimento da conexão por motivos definidos pela implementação. |
| 08S01 | Falha no link de comunicação | O link de comunicação entre o driver e a fonte de dados à qual o driver estava tentando se conectar falhou antes da função concluir o processamento. |
| 28000 | Especificação de autorização inválida | O valor especificado para o argumento UserName ou o valor especificado para o argumento Autenticação violou restrições definidas pela fonte de dados. |
| 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 | (DM) O Gerenciador de Driver não pôde alocar 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 SQLConnect foi chamada e, antes de concluir a execução, a função SQLCancelHandle foi chamada no ConnectionHandle e, em seguida, a função SQLConnect foi chamada novamente no ConnectionHandle. Ou, a função SQLConnect foi chamada e, antes de concluir a execução, SQLCancelHandle foi chamado 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 (não esta) foi chamada para o ConnectionHandle e ainda estava em execução quando essa função foi chamada. |
| 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. |
| HY090 | Comprimento de buffer ou cadeia de caracteres inválida | (DM) O valor especificado para o argumento NameLength1, NameLength2 ou NameLength3 era menor que 0, mas não igual a SQL_NTS. (DM) O valor especificado para o argumento NameLength1 excedeu o comprimento máximo de um nome de fonte de dados. |
| HYT00 | Tempo limite esgotado | O período de tempo limite da consulta expirou antes da conexão com a fonte de dados ser concluída. O período de tempo limite é definido por meio de SQLSetConnectAttr, SQL_ATTR_LOGIN_TIMEOUT. |
| HY114 | O driver não dá suporte à execução de função assíncrona no nível de conexão | (DM) O aplicativo habilitou a operação assíncrona no identificador de conexão antes de fazer a conexão. No entanto, o driver não dá suporte a operações assíncronas no identificador de conexão. |
| 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 especificado pelo nome da fonte de dados não dá suporte à função. |
| IM002 | Fonte de dados não encontrada e nenhum driver padrão especificado | (DM) O nome da fonte de dados especificado no argumento ServerName não foi encontrado nas informações do sistema, nem havia uma especificação de driver padrão. |
| IM003 | O driver especificado não pôde ser conectado a | (DM) O driver listado na especificação da fonte de dados nas informações do sistema não foi encontrado ou não pôde ser conectado por algum outro motivo. |
| IM004 | Falha no SQLAllocHandle do driver no SQL_HANDLE_ENV | (DM) Durante o SQLConnect, o Gerenciador de Driver chamou a função SQLAllocHandle do driver com um HandleType de SQL_HANDLE_ENV e o driver retornou um erro. |
| IM005 | Falha no SQLAllocHandle do driver no SQL_HANDLE_DBC | (DM) Durante o SQLConnect, o Gerenciador de Driver chamou a função SQLAllocHandle do driver com um HandleType de SQL_HANDLE_DBC e o driver retornou um erro. |
| IM006 | Falha no SQLSetConnectAttr do driver | Durante o SQLConnect, o Gerenciador de Driver chamou a função SQLSetConnectAttr do driver e o driver retornou um erro. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| IM009 | Não é possível se conectar à DLL de tradução | O driver não pôde se conectar à DLL de tradução especificada para a fonte de dados. |
| IM010 | Nome da fonte de dados muito longo | (DM) *ServerName era maior que SQL_MAX_DSN_LENGTH caracteres. |
| IM014 | O DSN especificado contém uma incompatibilidade de arquitetura entre o Driver e o Aplicativo | O aplicativo (DM) de 32 bits usa um DSN que se conecta a um driver de 64 bits; ou vice-versa. |
| IM015 | Falha no SQLConnect do driver no SQL_HANDLE_DBC_INFO_HANDLE | Se um driver retornar SQL_ERROR, o Gerenciador de Driver retornará SQL_ERROR ao aplicativo e a conexão falhará. Para obter mais informações sobre SQL_HANDLE_DBC_INFO_TOKEN, consulte Desenvolvendo Connection-Pool reconhecimento em um driver ODBC. |
| 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. |
| S1118 | O driver não dá suporte à notificação assíncrona | Quando o driver não dá suporte à notificação assíncrona, você não pode definir SQL_ATTR_ASYNC_DBC_EVENT ou SQL_ATTR_ASYNC_DBC_RETCODE_PTR. |
Comentários
Para obter informações sobre por que um aplicativo usa SQLConnect, consulte Conectando-se com SQLConnect.
O Gerenciador de Driver não se conecta a um driver até que o aplicativo chame uma função (SQLConnect, SQLDriverConnect ou SQLBrowseConnect) para se conectar ao driver. Até esse ponto, o Gerenciador de Driver trabalha com seus próprios identificadores e gerencia as informações de conexão. Quando o aplicativo chama uma função de conexão, o Gerenciador de Driver verifica se um driver está conectado no momento para o ConnectionHandle especificado:
Se um driver não estiver conectado, o Gerenciador de Driver se conectará ao driver e chamará SQLAllocHandle com um HandleType de SQL_HANDLE_ENV, SQLAllocHandle com um HandleType de SQL_HANDLE_DBC, SQLSetConnectAttr (se o aplicativo especificar atributos de conexão) e a função de conexão no driver. O Gerenciador de Driver retorna SQLSTATE IM006 ( falha de SQLSetConnectOption do Driver) e SQL_SUCCESS_WITH_INFO para a função de conexão se o driver retornasse um erro para SQLSetConnectAttr. Para obter mais informações, consulte Conectando-se a uma fonte de dados ou driver.
Se o driver especificado já estiver conectado no ConnectionHandle, o Gerenciador de Driver chamará apenas a função de conexão no driver. Nesse caso, o driver deve garantir que todos os atributos de conexão do ConnectionHandle mantenham suas configurações atuais.
Se um driver diferente estiver conectado, o Gerenciador de Driver chamará SQLFreeHandle com um HandleType de SQL_HANDLE_DBC e, se nenhum outro driver estiver conectado a esse ambiente, ele chamará SQLFreeHandle com um HandleType de SQL_HANDLE_ENV no driver conectado e desconectará esse driver. Em seguida, ele executa as mesmas operações que quando um driver não está conectado.
Em seguida, o driver aloca identificadores e se inicializa.
Quando o aplicativo chama SQLDisconnect, o Gerenciador de Driver chama SQLDisconnect no driver. No entanto, ele não desconecta o driver. Isso mantém o driver na memória para aplicativos que se conectam repetidamente e se desconectam de uma fonte de dados. Quando o aplicativo chama SQLFreeHandle com um HandleType de SQL_HANDLE_DBC, o Gerenciador de Driver chama SQLFreeHandle com um HandleType de SQL_HANDLE_DBC e, em seguida, SQLFreeHandle com um HandleType de SQL_HANDLE_ENV no driver e desconecta o driver.
Um aplicativo ODBC pode estabelecer mais de uma conexão.
Diretrizes do Gerenciador de Driver
O conteúdo de *ServerName afeta como o Gerenciador de Driver e um driver trabalham juntos para estabelecer uma conexão com uma fonte de dados.
Se *ServerName contiver um nome de fonte de dados válido, o Gerenciador de Driver localizará a especificação de fonte de dados correspondente nas informações do sistema e se conectará ao driver associado. O Gerenciador de Driver passa cada argumento SQLConnect para o driver.
Se o nome da fonte de dados não puder ser encontrado ou ServerName for um ponteiro nulo, o Gerenciador de Driver localizará a especificação de fonte de dados padrão e se conectará ao driver associado. O Gerenciador de Driver passa para o driver os argumentos UserName e Authentication não modificados e "DEFAULT" para o argumento ServerName .
Se o argumento ServerName for "DEFAULT", o Gerenciador de Driver localizará a especificação de fonte de dados padrão e se conectará ao driver associado. O Gerenciador de Driver passa cada argumento SQLConnect para o driver.
Se o nome da fonte de dados não puder ser encontrado ou ServerName for um ponteiro nulo e a especificação de fonte de dados padrão não existir, o Gerenciador de Driver retornará SQL_ERROR com SQLSTATE IM002 (nome da fonte de dados não encontrado e nenhum driver padrão especificado).
Depois de conectado pelo Gerenciador de Driver, um driver pode localizar sua especificação de fonte de dados correspondente nas informações do sistema e usar informações específicas do driver da especificação para concluir o conjunto de informações de conexão necessárias.
Se uma biblioteca de tradução padrão for especificada nas informações do sistema para a fonte de dados, o driver se conectará a ela. Uma biblioteca de tradução diferente pode ser conectada chamando SQLSetConnectAttr com o atributo SQL_ATTR_TRANSLATE_LIB. Uma opção de tradução pode ser especificada chamando SQLSetConnectAttr com o atributo SQL_ATTR_TRANSLATE_OPTION.
Se um driver der suporte ao SQLConnect, a seção de palavra-chave driver das informações do sistema para o driver deverá conter a palavra-chave ConnectFunctions com o primeiro caractere definido como "Y".
Pool de conexões
O pool de conexões permite que um aplicativo reutilize uma conexão que já foi criada. Quando o pool de conexões está habilitado e o SQLConnect é chamado, o Gerenciador de Driver tenta fazer a conexão usando uma conexão que faz parte de um pool de conexões em um ambiente designado para pool de conexões. Esse ambiente é um ambiente compartilhado que é usado por todos os aplicativos que usam as conexões no pool.
O pool de conexões é habilitado antes que o ambiente seja alocado chamando SQLSetEnvAttr para definir SQL_ATTR_CONNECTION_POOLING como SQL_CP_ONE_PER_DRIVER (que especifica um máximo de um pool por driver) ou SQL_CP_ONE_PER_HENV (que especifica um máximo de um pool por ambiente). SQLSetEnvAttr nesse caso é chamado com EnvironmentHandle definido como nulo, o que torna o atributo um atributo de nível de processo. Se SQL_ATTR_CONNECTION_POOLING estiver definido como SQL_CP_OFF, o pool de conexões será desabilitado.
Após a habilitação do pool de conexões, SQLAllocHandle com um HandleType de SQL_HANDLE_ENV é chamado para alocar um ambiente. O ambiente alocado por essa chamada é um ambiente compartilhado porque o pool de conexões foi habilitado. No entanto, o ambiente que será usado não será determinado até que SQLAllocHandle com um HandleType de SQL_HANDLE_DBC seja chamado.
SQLAllocHandle com um HandleType de SQL_HANDLE_DBC é chamado para alocar uma conexão. O Gerenciador de Driver tenta encontrar um ambiente compartilhado existente que corresponda aos atributos de ambiente definidos pelo aplicativo. Se esse ambiente não existir, um será criado como um ambiente compartilhado implícito. Se um ambiente compartilhado correspondente for encontrado, o identificador de ambiente será retornado ao aplicativo e sua contagem de referência será incrementada.
No entanto, a conexão que será usada não será determinada até que SQLConnect seja chamado. Nesse ponto, o Gerenciador de Driver tenta encontrar uma conexão existente no pool de conexões que corresponda aos critérios solicitados pelo aplicativo. Esses critérios incluem as opções de conexão solicitadas na chamada para SQLConnect (os valores das palavras-chave ServerName, UserName e Authentication ) e quaisquer atributos de conexão definidos desde que SQLAllocHandle com um HandleType de SQL_HANDLE_DBC foi chamado. O Gerenciador de Driver verifica esses critérios em relação às palavras-chave e atributos de conexão correspondentes em conexões no pool. Se uma correspondência for encontrada, a conexão no pool será usada. Se nenhuma correspondência for encontrada, uma nova conexão será criada.
Se o atributo de ambiente SQL_ATTR_CP_MATCH estiver definido como SQL_CP_STRICT_MATCH, a correspondência deverá ser exata para que uma conexão no pool seja usada. Se o atributo de ambiente SQL_ATTR_CP_MATCH estiver definido como SQL_CP_RELAXED_MATCH, as opções de conexão na chamada para SQLConnect deverão corresponder, mas nem todos os atributos de conexão devem corresponder.
As regras a seguir são aplicadas quando um atributo de conexão, conforme definido pelo aplicativo antes de SQLConnect ser chamado, não corresponde ao atributo de conexão da conexão no pool:
Se o atributo de conexão precisar ser definido antes da conexão ser feita:
Se SQL_ATTR_CP_MATCH for SQL_CP_STRICT_MATCH, SQL_ATTR_PACKET_SIZE na conexão em pool deverão ser idênticas ao atributo definido pelo aplicativo. Se SQL_CP_RELAXED_MATCH, os valores de SQL_ATTR_PACKET_SIZE poderão ser diferentes.
O valor de SQL_ATTR_LOGIN_VALUE não afeta a correspondência.
Se o atributo de conexão puder ser definido antes ou depois que a conexão for feita:
Se o atributo de conexão não tiver sido definido pelo aplicativo, mas tiver sido definido na conexão no pool e houver um padrão, o atributo de conexão na conexão em pool será definido de volta para o padrão e uma correspondência será declarada. Se não houver nenhum padrão, a conexão em pool não será considerada uma correspondência.
Se o atributo de conexão tiver sido definido pelo aplicativo, mas não tiver sido definido na conexão no pool, o atributo de conexão no pool será alterado para aquele definido pelo aplicativo e uma correspondência será declarada.
Se o atributo de conexão tiver sido definido pelo aplicativo e também tiver sido definido na conexão no pool, mas os valores forem diferentes, o valor do atributo de conexão do aplicativo será usado e uma correspondência será declarada.
Se os valores de atributos de conexão específicos do driver não forem idênticos e SQL_ATTR_CP_MATCH estiver definido como SQL_CP_STRICT_MATCH, a conexão no pool não será usada.
Quando o aplicativo chama SQLDisconnect para desconectar, a conexão é retornada para o pool de conexões e está disponível para reutilização.
Otimizando o desempenho do pool de conexões
Quando as transações distribuídas estão envolvidas, é possível otimizar o desempenho do pool de conexões usando SQL_DTC_TRANSITION_COST, que é uma máscara de bits SQLUINTEGER. As transições mencionadas são as transições do atributo de conexão SQL_ATTR_ENLIST_IN_DTC indo do valor 0 para diferente de zero e vice-versa. Essa é uma conexão que vai de não inscrito em uma transação distribuída para inscrito em uma transação distribuída e vice-versa. Dependendo de como o driver implementou a inscrição (configurando o atributo de conexão SQL_ATTR_ENLIST_IN_DTC), essas transições podem ser caras e, portanto, devem ser evitadas para melhor desempenho.
O valor retornado pelo driver contém qualquer combinação dos seguintes bits:
SQL_DTC_ENLIST_EXPENSIVE, quando definido, implica que a transição de zero a diferente de zero é significativamente mais cara do que uma transição de diferente de zero para outro valor diferente de zero (inscrevendo uma conexão inscrita anteriormente em sua próxima transação).
SQL_DTC_UNENLIST_EXPENSIVE, quando definido, implica que a transição diferente de zero é significativamente mais cara do que usar uma conexão cujo atributo SQL_ATTR_ENLIST_IN_DTC já está definido como zero.
Há uma compensação de desempenho versus uso de conexão. Se um driver indicar que uma ou mais dessas transições são caras, o pooler de conexões do gerenciador de driver responderá a isso mantendo mais conexões no pool. Algumas das conexões no pool são preferenciais para uso não transacional e outras são preferenciais para uso transacional. No entanto, se o driver indicar que essas transições não são caras, menos conexões poderão ser usadas, talvez alternando entre o uso não transacional e transacional.
Drivers que não dão suporte a SQL_ATTR_ENLIST_IN_DTC não precisam dar suporte a SQL_DTC_TRANSITION_COST. Para drivers que dão suporte a SQL_ATTR_ENLIST_IN_DTC mas não SQL_DTC_TRANSITION_COST, supõe-se que as transições não sejam caras, como se o driver retornasse 0 (nenhum bit definido) para esse valor.
Embora SQL_DTC_TRANSITION_COST tenha sido introduzido no ODBC 3.5, um ODBC 2. O driver x também pode dar suporte a ele porque o gerenciador de driver consultará essas informações independentemente da versão do driver.
Exemplo de código
No exemplo a seguir, um aplicativo aloca identificadores de conexão e ambiente. Em seguida, ele se conecta à fonte de dados SalesOrders com a ID de usuário JohnS e a senha Costura e processa dados. Quando terminar de processar dados, ele se desconectará da fonte de dados e liberará os identificadores.
// SQLConnect_ref.cpp
// compile with: odbc32.lib
#include <windows.h>
#include <sqlext.h>
int main() {
SQLHENV henv;
SQLHDBC hdbc;
SQLHSTMT hstmt;
SQLRETURN retcode;
SQLCHAR * OutConnStr = (SQLCHAR * )malloc(255);
SQLSMALLINT * OutConnStrLen = (SQLSMALLINT *)malloc(255);
// Allocate environment handle
retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
// Set the ODBC version environment attribute
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (void*)SQL_OV_ODBC3, 0);
// Allocate connection handle
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);
// Set login timeout to 5 seconds
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);
// Connect to data source
retcode = SQLConnect(hdbc, (SQLCHAR*) "NorthWind", SQL_NTS, (SQLCHAR*) NULL, 0, NULL, 0);
// Allocate statement handle
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
// Process data
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
SQLFreeHandle(SQL_HANDLE_STMT, hstmt);
}
SQLDisconnect(hdbc);
}
SQLFreeHandle(SQL_HANDLE_DBC, hdbc);
}
}
SQLFreeHandle(SQL_HANDLE_ENV, henv);
}
}
Funções relacionadas
| Para obter informações sobre | Consulte |
|---|---|
| Alocando um identificador | Função SQLAllocHandle |
| Descobrir e enumerar valores necessários para se conectar a uma fonte de dados | Função SQLBrowseConnect |
| Desconectando de uma fonte de dados | Função SQLDisconnect |
| Conectando-se a uma fonte de dados usando uma cadeia de conexão ou caixa de diálogo | Função SQLDriverConnect |
| Retornando a configuração de um atributo de conexão | Função SQLGetConnectAttr |
| Definindo um atributo de conexão | Função SQLSetConnectAttr |