Exemplo de navegação do SQL Server

O exemplo a seguir mostra como SQLBrowseConnect pode ser usado para procurar as 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 por SQLDrivers:

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

Como essa é a primeira chamada a 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, deverá especificar informações de ID de usuário e senha na cadeia de conexão.

O driver determina que essa é a primeira chamada a 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 server, ele retorna uma lista de nomes de servidores válidos. O código de retorno de SQLBrowseConnect é SQL_NEED_DATA. Aqui está a cadeia de caracteres de resultados da procura:

"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 da procura é 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 com um asterisco, o que significa que são opcionais. As palavras-chave SERVER, UID e PWD não são prefixadas com um asterisco; os valores devem ser fornecidos para elas na próxima cadeia de caracteres de solicitação de procura. 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 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 valores-chave ausente, SQLBrowseConnect retornará SQL_NEED_DATA e permanecerá no mesmo estado em que estava 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 a cadeia de caracteres de resultados da procura:

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

Como os atributos nessa cadeia de caracteres são opcionais, o aplicativo pode omiti-los. No entanto, o aplicativo deverá chamar SQLBrowseConnect novamente. Se o aplicativo optar por omitir o nome e o idioma do banco de dados, ele especificará uma cadeia de caracteres de solicitação de procura vazia. Neste exemplo, o aplicativo escolhe o banco de dados 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 é 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 resultados da procura:

"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 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 (após a desconexão) ou para se conectar à 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);