Ligação a uma Fonte de Dados (ODBC)

Aplica-se a: SQL ServerBase de Dados SQL do AzureAzure SQL Managed InstanceAzure Synapse AnalyticsSistema de Plataforma de Análise (PDW)

Depois de alocar os controlos do ambiente e da ligação e definir quaisquer atributos de ligação, a aplicação liga-se à fonte de dados ou ao driver. Existem três funções que pode usar para se ligar:

• SQLConnect

• SQLDriverConnect

• SQLBrowseConnect

Para mais informações sobre como fazer ligações a uma fonte de dados, incluindo as várias opções de cadeia de ligação disponíveis, consulte Using Connection String Keywords with SQL Server Native Client.

SQLConnect

O SQLConnect é a função de ligação mais simples. Aceita três parâmetros: um nome da fonte de dados, um ID de utilizador e uma palavra-passe. Use o SQLConnect quando estes três parâmetros contêm toda a informação necessária para se ligar à base de dados. Para isso, constrói uma lista de fontes de dados usando SQLDataSources; pedir ao utilizador uma fonte de dados, ID de utilizador e palavra-passe; e depois chamar SQLConnect.

O SQLConnect assume que um nome da fonte de dados, ID de utilizador e palavra-passe são suficientes para se ligar a uma fonte de dados e que a fonte de dados ODBC contém toda a outra informação que o driver ODBC necessita para fazer a ligação. Ao contrário do SQLDriverConnect e SQLBrowseConnect, o SQLConnect não utiliza uma cadeia de ligação.

SQLDriverConnect

O SQLDriverConnect é utilizado quando é necessária mais informação do que o nome da fonte de dados, ID de utilizador e palavra-passe. Um dos parâmetros do SQLDriverConnect é uma cadeia de ligação que contém informação específica do driver. Pode usar SQLDriverConnect em vez de SQLConnect pelas seguintes razões:

• Para especificar informações específicas do condutor no momento da ligação.

• Pedir ao driver que solicite ao utilizador informações de ligação.

• Para se ligar sem usar uma fonte de dados ODBC.

A cadeia de ligação SQLDriverConnect contém uma série de pares palavra-chave que especificam toda a informação de ligação suportada por um driver ODBC. Cada driver suporta as palavras-chave padrão ODBC (DSN, FILEDSN, DRIVER, UID, PWD e SAVEFILE), além de palavras-chave específicas do driver para toda a informação de ligação suportada pelo driver. O SQLDriverConnect pode ser usado para se ligar sem uma fonte de dados. Por exemplo, uma aplicação concebida para criar uma ligação "sem DSN" a uma instância do SQL Server pode chamar o SQLDriverConnect com uma cadeia de ligação que define o ID de login, palavra-passe, biblioteca de rede, nome do servidor a que se ligar e base de dados padrão a utilizar.

Ao usar o SQLDriverConnect, existem duas opções para pedir ao utilizador qualquer informação de ligação necessária:

• Caixa de diálogo de aplicação

  Podes criar uma caixa de diálogo de aplicação que pede informações de ligação e depois chama o SQLDriverConnect com um handle de janela NULL e o DriverCompletion definido para SQL_DRIVER_NOPROMPT. Estas definições de parâmetros impedem o driver ODBC de abrir a sua própria caixa de diálogo. Este método é utilizado quando é importante controlar a interface de utilizador da aplicação.

• Caixa de diálogo do condutor

  Podes programar a aplicação para passar um handle de janela válido ao SQLDriverConnect e definir o parâmetro DriverCompletion para SQL_DRIVER_COMPLETE, SQL_DRIVER_PROMPT ou SQL_DRIVER_COMPLETE_REQUIRED. O driver gera então uma caixa de diálogo para pedir ao utilizador informações de ligação. Este método simplifica o código da aplicação.

SQLBrowseConnect

O SQLBrowseConnect, tal como o SQLDriverConnect, usa uma cadeia de ligação. No entanto, ao usar SQLBrowseConnect, uma aplicação pode construir iterativamente uma cadeia de ligação completa com a fonte de dados em tempo de execução. Isto permite que a aplicação faça duas funções:

• Construir as suas próprias caixas de diálogo para pedir esta informação, mantendo assim o controlo sobre a interface de utilizador.

• Navegue pelo sistema à procura de fontes de dados que possam ser usadas por um determinado condutor, possivelmente em vários passos.

  Por exemplo, o utilizador pode primeiro navegar na rede à procura de servidores e, depois de escolher um servidor, navegar pelo servidor à procura de bases de dados acessíveis pelo driver.

Quando o SQLBrowseConnect conclui uma ligação bem-sucedida, devolve uma cadeia de ligação que pode ser usada em chamadas subsequentes ao SQLDriverConnect.

O driver ODBC SQL Server Native Client retorna sempre SQL_SUCCESS_WITH_INFO num SQLConnect, SQLDriverConnect ou SQLBrowseConnect bem-sucedido. Quando uma aplicação ODBC chama SQLGetDiagRec após receber SQL_SUCCESS_WITH_INFO, pode receber as seguintes mensagens:

5701
Indica que o SQL Server colocou o contexto do utilizador na base de dados padrão definida na fonte de dados, ou na base de dados padrão definida para o ID de login usado na ligação caso a fonte de dados não tivesse uma base de dados predefinida.

5703
Indica a linguagem usada no servidor.

O exemplo seguinte mostra a mensagem devolvida numa ligaçã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'."  

Pode ignorar as mensagens 5701 e 5703; São apenas informativos. No entanto, não deve ignorar um código de retorno SQL_SUCCESS_WITH_INFO porque mensagens que não sejam 5701 ou 5703 podem ser devolvidas. Por exemplo, se um driver se liga a um servidor a correr uma instância de SQL Server com procedimentos armazenados de catálogo desatualizados, um dos erros devolvidos através do SQLGetDiagRec após um SQL_SUCCESS_WITH_INFO é:

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 gestão de erros de uma aplicação para ligações SQL Server deve chamar SQLGetDiagRec até que este retorne SQL_NO_DATA. Deverá então agir sobre quaisquer mensagens que não sejam aquelas com código pfNative 5701 ou 5703.

Conteúdo relacionado

• Comunicação com o SQL Server (ODBC)