Exemplo de navegação no SQL Server

O exemplo seguinte mostra como o SQLBrowseConnect pode ser usado para navegar pelas ligações disponíveis com um driver para SQL Server. Primeiro, a aplicação solicita um handle de ligação:

SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  

De seguida, a aplicação chama SQLBrowseConnect e especifica o driver do SQL Server, usando a descrição do driver devolvida pelo SQLDrivers:

SQLBrowseConnect(hdbc, "DRIVER={SQL Server};", SQL_NTS, BrowseResult,  
                  sizeof(BrowseResult), &BrowseResultLen);  

Como esta é a primeira chamada ao SQLBrowseConnect, o Gestor de Drivers carrega o driver do SQL Server e chama a função SQLBrowseConnect do driver com os mesmos argumentos que recebeu da aplicação.

Observação

Se estiver a ligar-se a um fornecedor de fonte de dados que suporta autenticação Windows, deve especificar Trusted_Connection=yes em vez de informações de ID de utilizador e palavra-passe na cadeia de ligação.

O driver determina que esta é a primeira chamada ao SQLBrowseConnect e devolve o segundo nível de atributos de ligação: servidor, nome de utilizador, palavra-passe, nome da aplicação e ID da estação de trabalho. Para o atributo servidor, devolve uma lista de nomes válidos de servidores. O código de retorno do SQLBrowseConnect é SQL_NEED_DATA. Aqui está a cadeia de resultados de navegação:

"SERVER:Server={red,blue,green,yellow};UID:Login ID=?;PWD:Password=?;  
   *APP:AppName=?;*WSID:WorkStation ID=?;"  

Cada palavra-chave na cadeia de caracteres de resultados de navegação é seguida por dois pontos e por uma ou mais palavras antes do sinal de igual. Estas palavras são o nome fácil de usar que uma aplicação pode usar para criar uma caixa de diálogo. As palavras-chave APP e WSID são prefixadas por um asterisco, o que significa que são opcionais. As palavras-chave SERVER, UID e PWD não são precedidas por um asterisco; os valores devem ser fornecidos para eles na próxima cadeia de pedido de navegação. O valor da palavra-chave SERVIDOR pode ser um dos servidores devolvidos pelo SQLBrowseConnect ou um nome fornecido pelo utilizador.

A aplicação chama novamente SQLBrowseConnect , especificando o servidor verde e omitindo as palavras-chave APP e WSID e os nomes amigáveis após cada palavra-chave:

SQLBrowseConnect(hdbc, "SERVER=green;UID=Smith;PWD=Sesame;", SQL_NTS,  
                  BrowseResult, sizeof(BrowseResult), &BrowseResultLen);  

O driver tenta ligar-se ao servidor verde. Se existirem erros não fatais, como falta de um par palavra-chave, o SQLBrowseConnect devolve SQL_NEED_DATA e mantém-se no mesmo estado em que estava antes do erro. A aplicação pode chamar SQLGetDiagField ou SQLGetDiagRec para determinar o erro. Se a ligação for bem-sucedida, o driver devolve SQL_NEED_DATA e devolve a cadeia de resultados de navegação:

"*DATABASE:Database={master,model,pubs,tempdb};  
   *LANGUAGE:Language={us_english,Franais};"  

Como os atributos nesta cadeia são opcionais, a aplicação pode omitê-los. No entanto, a aplicação tem de chamar novamente o SQLBrowseConnect . Se a aplicação optar por omitir o nome da base de dados e a linguagem, especifica uma cadeia de pedidos de navegação vazia. Neste exemplo, a aplicação escolhe a base de dados pubs e chama o SQLBrowseConnect uma última vez, omitindo a palavra-chave LANGUAGE e o asterisco antes da palavra-chave DATABASE :

SQLBrowseConnect(hdbc, "DATABASE=pubs;", SQL_NTS, BrowseResult,  
                  sizeof(BrowseResult), &BrowseResultLen);  

Como o atributo DATABASE é o atributo final de ligação exigido pelo driver, o processo de navegação está completo, a aplicação está ligada à fonte de dados e o SQLBrowseConnect devolve SQL_SUCCESS. O SQLBrowseConnect também devolve a cadeia de ligação completa como a cadeia de resultados de navegação:

"DSN=MySQLServer;SERVER=green;UID=Smith;PWD=Sesame;DATABASE=pubs;"  

A cadeia final de ligação devolvida pelo driver não contém os nomes fáceis de usar após cada palavra-chave, nem contém palavras-chave opcionais não especificadas pela aplicação. A aplicação pode usar esta cadeia com o SQLDriverConnect para se reconectar à fonte de dados no handle de ligação atual (após a desligação) ou para se ligar à fonte de dados num handle de ligação diferente. Por exemplo:

SQLDriverConnect(hdbc, hwnd, BrowseResult, SQL_NTS, ConnStrOut,  
                  sizeof(ConnStrOut), &ConnStrOutLen, SQL_DRIVER_NOPROMPT);