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.
Nota
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);