Exemplo de navegação do SQL Server

O exemplo a seguir mostra como o SQLBrowseConnect pode ser usado para navegar pelas conexões disponíveis com um driver para SQL Server. Primeiro, o aplicativo solicita um identificador de conexão:

SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  

Em seguida, o aplicativo chama SQLBrowseConnect e especifica o driver do SQL Server usando a descrição do driver retornada pelo SQLDrivers:

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

Como essa é a primeira chamada para SQLBrowseConnect, o Gerenciador de Driver carrega o driver do SQL Server e chama a função SQLBrowseConnect do driver com os mesmos argumentos recebidos do aplicativo.

Observação

Se você estiver se conectando a um provedor de fonte de dados que dê suporte à autenticação do Windows, especifique Trusted_Connection=yes em vez de informações de ID de usuário e senha na cadeia de conexão.

O driver determina que essa é a primeira chamada para SQLBrowseConnect e retorna o segundo nível de atributos de conexão: servidor, nome de usuário, senha, nome do aplicativo e ID da estação de trabalho. Para o atributo de servidor, ele retorna uma lista de nomes de servidor válidos. O código de retorno do SQLBrowseConnect é SQL_NEED_DATA. Aqui está a cadeia de caracteres de resultado de navegação:

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

Cada palavra-chave na sequência de resultado de navegação é seguida por dois pontos e uma ou mais palavras antes do sinal de igual. Essas palavras são o nome amigável que um aplicativo 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 elas são opcionais. As palavras-chave SERVER, UID e PWD não são prefixadas por um asterisco; os valores devem ser fornecidos para eles na próxima cadeia de caracteres de solicitação de navegação. O valor da palavra-chave SERVER pode ser um dos servidores retornados por SQLBrowseConnect ou um nome fornecido pelo usuário.

O aplicativo chama SQLBrowseConnect novamente, especificando o servidor verde e omitindo as palavras-chave APP e WSID e os nomes amigáveis do usuário após cada palavra-chave:

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

O driver tenta se conectar ao servidor verde. Se houver erros não fatais, como um par de palavra-chave-valor ausente, SQLBrowseConnect retornará SQL_NEED_DATA e permanecerá no mesmo estado que era antes do erro. O aplicativo pode chamar SQLGetDiagField ou SQLGetDiagRec para determinar o erro. Se a conexão for bem-sucedida, o driver retornará SQL_NEED_DATA e retornará a cadeia de caracteres de resultado de navegação:

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

Como os atributos nessa cadeia de caracteres são opcionais, o aplicativo pode omitê-los. No entanto, o aplicativo deve chamar SQLBrowseConnect novamente. Se o aplicativo optar por omitir o nome e o idioma do banco de dados, ele especifica uma cadeia de caracteres de solicitação de navegação vazia. Neste exemplo, o aplicativo escolhe o banco de dados de pubs e chama 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 de conexão final exigido pelo driver, o processo de navegação é concluído, o aplicativo está conectado à fonte de dados e SQLBrowseConnect retorna SQL_SUCCESS. SQLBrowseConnect também retorna a cadeia de conexão completa como a cadeia de caracteres de resultado de navegação:

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

A cadeia de conexão final retornada pelo driver não contém os nomes amigáveis do usuário após cada palavra-chave, nem contém palavras-chave opcionais não especificadas pelo aplicativo. O aplicativo pode usar essa cadeia de caracteres com SQLDriverConnect para se reconectar à fonte de dados no identificador de conexão atual (depois de desconectar) ou conectar-se à fonte de dados em um identificador de conexão diferente. Por exemplo:

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