Esempio di esplorazione di SQL Server

Nell'esempio seguente viene illustrato come usare SQLBrowseConnect per esplorare le connessioni disponibili con un driver per SQL Server. Per prima cosa, l'applicazione richiede un handle di connessione:

SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  

Successivamente, l'applicazione chiama SQLBrowseConnect e specifica il driver di SQL Server usando la descrizione del driver restituita da SQLDrivers:

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

Poiché si tratta della prima chiamata a SQLBrowseConnect, Gestione driver carica il driver di SQL Server e chiama la funzione SQLBrowseConnect del driver con gli stessi argomenti ricevuti dall'applicazione.

Il driver stabilisce che si tratta della prima chiamata a SQLBrowseConnect e restituisce il secondo livello di attributi di connessione: server, nome utente, password, nome dell’applicazione e ID workstation. Per l'attributo server, restituisce un elenco di nomi del server validi. Il codice restituito da SQLBrowseConnect è SQL_NEED_DATA. Ecco la stringa dei risultati di esplorazione:

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

Ogni parola chiave nella stringa dei risultati di esplorazione è seguita da due punti e da una o più parole prima del segno di uguale. Queste parole sono il nome descrittivo che un'applicazione può usare per compilare una finestra di dialogo. Le parole chiave APP e WSID sono precedute da un asterisco, che indica che sono facoltative. Le parole chiave SERVER, UID e PWD non sono precedute da un asterisco; i loro valori devono essere specificati nella stringa di richiesta di esplorazione successiva. Il valore della parola chiave SERVER può essere uno dei server restituiti da SQLBrowseConnect o un nome fornito dall'utente.

L'applicazione chiamadi nuovo SQLBrowseConnect, specificando il server verde e omettendo le parole chiave APP e WSID e i nomi descrittivi dopo ogni parola chiave:

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

Il driver tenta di effettuare la connessione al server verde. Se sono presenti errori non irreversibili, ad esempio una coppia di parola chiave-valore mancante, SQLBrowseConnect restituisce SQL_NEED_DATA e rimane nello stesso stato in cui si trovava precedentemente all'errore. L'applicazione può chiamare SQLGetDiagField o SQLGetDiagRec per determinare l'errore. Se la connessione ha esito positivo, il driver restituisce SQL_NEED_DATA e restituisce la stringa dei risultati di esplorazione:

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

Poiché gli attributi in questa stringa sono facoltativi, l'applicazione può ometterli. Tuttavia, l'applicazione deve chiamare di nuovo SQLBrowseConnect. Se l'applicazione sceglie di omettere il nome e la lingua del database, specifica una stringa di richiesta di esplorazione vuota. In questo esempio l'applicazione sceglie il database Pubs e chiama SQLBrowseConnect per un’ultima volta, omettendo la parola chiave LANGUAGE e l'asterisco prima dellaparola chiave DATABASE:

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

Poiché l'attributo DATABASE è l'attributo di connessione finale richiesto dal driver, il processo di esplorazione è completo, l'applicazione è connessa all'origine dati e SQLBrowseConnect restituisce SQL_SUCCESS. SQLBrowseConnect restituisce anche la stringa di connessione completa come stringa dei risultati di esplorazione:

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

La stringa di connessione finale restituita dal driver non contiene i nomi descrittivi dopo ogni parola chiave, né le parole chiave facoltative non specificate dall'applicazione. L'applicazione può usare questa stringa con SQLDriverConnect per riconnettersi all'origine dati nell'handle di connessione corrente (dopo la disconnessione) o per connettersi all'origine dati in un handle di connessione diverso. Ad esempio:

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