Conectando-se a uma fonte de dados (ODBC)
Depois de alocar os identificadores de ambiente e conexão e definir quaisquer atributos de conexão, o aplicativo se conectará à fonte de dados ou driver. Há três funções que você pode usar para se conectar:
SQLConnect
SQLDriverConnect
SQLBrowseConnect
Para obter mais informações sobre como estabelecer conexões com uma fonte de dados, incluindo as várias opções de cadeia de conexão disponíveis, consulte Usando palavras-chave da cadeia de conexão com o SQL Server Native Client.
SQLConnect
SQLConnect é a função de conexão mais simples. Ela aceita três parâmetros: um nome da fonte de dados, uma ID de usuário e uma senha. Use SQLConnect quando esses três parâmetros contiverem todas as informações necessárias para conexão ao banco de dados. Para fazer isso, crie uma lista de fontes de dados usando SQLDataSources; solicite ao usuário uma fonte de dados, ID de usuário e senha; e chame SQLConnect.
SQLConnect pressupõe que um nome da fonte de dados, uma ID de usuário e uma senha sejam suficientes para conexão a uma fonte de dados e que a fonte de dados ODBC contenha todas as outras informações necessárias ao driver ODBC para estabelecer a conexão. Diferentemente de SQLDriverConnect e SQLBrowseConnect, SQLConnect não usa uma cadeia de conexão.
SQLDriverConnect
SQLDriverConnect é usado quando são necessárias mais informações do que o nome da fonte de dados, o ID de usuário e a senha. Um dos parâmetros para SQLDriverConnect é uma cadeia de conexão que contenha informações específicas de driver. Você pode usar SQLDriverConnect, em vez de SQLConnect pelos motivos a seguir:
Para especificar informações específicas de driver no tempo de conexão.
Para solicitar que o driver instrua o usuário a fornecer informações de conexão.
Para se conectar sem usar uma fonte de dados ODBC.
A cadeia de conexão SQLDriverConnect contém uma série de pares de valor de palavra-chave que especificam todas as informações de conexão suportadas em um driver ODBC. Cada driver suporta as palavras-chave ODBC padrão (DSN, FILEDSN, DRIVER, UID, PWD e SAVEFILE), além das palavras-chave específicas de driver para todas as informações de conexão suportadas pelo driver. SQLDriverConnect pode ser usado para se conectar sem uma fonte de dados. Por exemplo, um aplicativo que foi projetado para estabelecer uma conexão "sem DSN" com uma instância do SQL Server pode chamar SQLDriverConnect com uma cadeia de conexão que define o ID de logon, a senha, a biblioteca de rede, o nome de servidor com o qual será feita a conexão e o banco de dados padrão que será usado.
Ao usar SQLDriverConnect, há duas opções para solicitar o usuário a fornecer quaisquer informações de conexão necessárias:
Caixa de diálogo de aplicativo
Você pode criar uma caixa de diálogo de aplicativo que solicita informações de conexão e chama SQLDriverConnect com um identificador de janela NULL e DriverCompletion definido como SQL_DRIVER_NOPROMPT. Essas configurações de parâmetro impedem que o driver ODBC abra sua própria caixa de diálogo. Esse método é usado quando é importante controlar a interface do usuário do aplicativo.
Caixa de diálogo de driver
Você pode codificar o aplicativo para passar um identificador de janela válido para SQLDriverConnect e definir o parâmetro DriverCompletion como SQL_DRIVER_COMPLETE, SQL_DRIVER_PROMPT ou SQL_DRIVER_COMPLETE_REQUIRED. O driver gera uma caixa de diálogo para solicitar o usuário a fornecer as informações de conexão. Esse método simplifica o código do aplicativo.
SQLBrowseConnect
SQLBrowseConnect, como SQLDriverConnect, usa uma cadeia de conexão. Entretanto, usando SQLBrowseConnect, um aplicativo pode construir uma cadeia de conexão completa iterativamente com a fonte de dados em tempo de execução. Isso permite que o aplicativo faça duas tarefas:
Crie as próprias caixas de diálogo para solicitar essas informações, assim mantendo o controle da interface do usuário.
Procure no sistema por fontes de dados que possam ser usadas por um driver específico, possivelmente em várias etapas.
Por exemplo, primeiro o usuário pode procurar servidores na rede e, depois de escolher um, procurar no servidor pelos bancos de dados acessíveis pelo driver.
Quando SQLBrowseConnect conclui uma conexão com êxito, retorna uma cadeia de conexão que pode ser usada em chamadas subseqüentes a SQLDriverConnect.
O driver ODBC do SQL Server Native Client sempre retorna SQL_SUCCESS_WITH_INFO em um SQLConnect, SQLDriverConnect ou SQLBrowseConnect bem-sucedido. Quando um aplicativo ODBC chama SQLGetDiagRec depois de obter SQL_SUCCESS_WITH_INFO, ele pode receber as mensagens a seguir:
5701
Indica que o SQL Server colocou o contexto do usuário no banco de dados padrão definido na fonte de dados, ou no banco de dados padrão definido para o ID de logon usado na conexão se a fonte de dados não tinha um banco de dados padrão.5703
Indica o idioma usado no servidor.
O exemplo a seguir mostra a mensagem retornada em uma conexão bem-sucedida pelo administrador do sistema:
szSqlState = "01000", *pfNativeError = 5701,
szErrorMsg="[Microsoft][SQL Server Native Client][SQL Server]
Changed database context to 'pubs'."
szSqlState = "01000", *pfNativeError = 5703,
szErrorMsg="[Microsoft][SQL Server Native Client][SQL Server]
Changed language setting to 'us_english'."
Você pode ignorar as mensagens 5701 e 5703; elas são meramente informativas. Entretanto, você não deve ignorar um código de retorno de SQL_SUCCESS_WITH_INFO porque podem ser retornadas mensagens diferentes de 5701 ou 5703. Por exemplo, se um driver se conectar a um servidor que executa uma instância do SQL Server com procedimentos armazenados de catálogo obsoletos, um dos erros retornados pelo SQLGetDiagRec após um SQL_SUCCESS_WITH_INFO será:
SqlState: 01000
pfNative: 0
szErrorMsg: "[Microsoft][SQL Server Native Client]The ODBC
catalog stored procedures installed on server
my65server are version 06.50.0193; version 07.00.0205
or later is required to ensure proper operation.
Please contact your system administrator."
A função de tratamento de erros de um aplicativo para conexões do SQL Server deve chamar SQLGetDiagRec até que retorne SQL_NO_DATA. Ela deve então processar quaisquer mensagens diferentes daquelas com um código de pfNative 5701 ou 5703.
Verificando o estado da conexão
O comportamento de SQL_ATTR_CONNECTION_DEAD e SQL_COPT_SS_CONNECTION_DEAD no SQL Server 2000 e superior é diferente do comportamento de versões anteriores. No SQL Server 2000 e superior, SQL_ATTR_CONNECTION_DEAD retorna o estado mais recente da conexão, que pode não ser o estado de conexão atual. Entretanto, SQL_COPT_SS_CONNECTION_DEAD sempre consulta na Biblioteca de Rede o estado atual da conexão.
Para diferenciar entre esses comportamentos, SQL_COPT_SS_CONNECTION_DEAD recebe um valor novo no SQL Server 2000 e depois inclui arquivos. Os aplicativos que usam esse atributo criados usando os cabeçalhos do SQL Server 2000 e superior retornarão um erro de identificador de opção/atributo inválido (HY092) se forem executados usando um driver do SQL Server versão 7.0. Recomendamos que o aplicativo verifique a versão do driver em uso antes de chamar SQLGetConnectAttr e use SQL_ATTR_CONNECTION_DEAD no lugar de SQL_COPT_SS_CONNECTION_DEAD se o aplicativo estiver sendo executado em um driver do SQL Server 7.0.