SQL Server-Browserbeispiel

Das folgende Beispiel zeigt, wie SQLBrowseConnect verwendet werden kann, um die verbindungen zu durchsuchen, die mit einem Treiber für SQL Server verfügbar sind. Zuerst fordert die Anwendung ein Verbindungshandle an:

SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  

Als Nächstes ruft die Anwendung SQLBrowseConnect auf und gibt den SQL Server-Treiber mithilfe der von SQLDrivers zurückgegebenen Treiberbeschreibung an:

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

Da dies der erste Aufruf von SQLBrowseConnect ist, lädt der Treiber-Manager den SQL Server-Treiber und ruft die SQLBrowseConnect-Funktion des Treibers mit denselben Argumenten auf, die sie von der Anwendung erhalten haben.

Hinweis

Wenn Sie eine Verbindung mit einem Datenquellenanbieter herstellen, der die Windows-Authentifizierung unterstützt, sollten Sie anstelle von Benutzer-ID- und Kennwortinformationen in der Verbindungszeichenfolge angeben Trusted_Connection=yes .

Der Treiber bestimmt, dass dies der erste Aufruf von SQLBrowseConnect ist und die zweite Ebene der Verbindungsattribute zurückgibt: Server, Benutzername, Kennwort, Anwendungsname und Arbeitsstations-ID. Für das Server-Attribut wird eine Liste gültiger Servernamen zurückgegeben. Der Rückgabecode von SQLBrowseConnect ist SQL_NEED_DATA. Hier ist die Suchergebniszeichenfolge:

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

Auf jedes Schlüsselwort in der Suchergebniszeichenfolge folgt ein Doppelpunkt und ein oder mehrere Wörter vor dem Gleichheitszeichen. Bei diesen Wörtern handelt es sich um den benutzerfreundlichen Namen, den eine Anwendung zum Erstellen eines Dialogfelds verwenden kann. Die Schlüsselwörter APP und WSID werden einem Sternchen vorangestellt, was bedeutet, dass sie optional sind. Die Schlüsselwörter SERVER, UID und PWD werden nicht durch ein Sternchen vorangestellt; werte müssen für sie in der nächsten Durchstöberanforderungszeichenfolge angegeben werden. Der Wert für das SERVER-Schlüsselwort kann einer der Server sein, die von SQLBrowseConnect oder einem vom Benutzer angegebenen Namen zurückgegeben werden.

Die Anwendung ruft SQLBrowseConnect erneut auf, wobei der grüne Server angegeben und die Schlüsselwörter APP und WSID und die benutzerfreundlichen Namen nach jedem Schlüsselwort weggelassen werden:

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

Der Treiber versucht, eine Verbindung mit dem grünen Server herzustellen. Wenn es nichtfatale Fehler gibt, z. B. ein fehlendes Schlüsselwort-Wert-Paar, gibt SQLBrowseConnect SQL_NEED_DATA zurück und verbleibt im gleichen Zustand wie vor dem Fehler. Die Anwendung kann SQLGetDiagField oder SQLGetDiagRec aufrufen, um den Fehler zu ermitteln. Wenn die Verbindung erfolgreich ist, gibt der Treiber SQL_NEED_DATA zurück und gibt die Suchergebniszeichenfolge zurück:

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

Da die Attribute in dieser Zeichenfolge optional sind, kann sie von der Anwendung weggelassen werden. Die Anwendung muss sqlBrowseConnect jedoch erneut aufrufen. Wenn die Anwendung den Datenbanknamen und die Sprache auslassen möchte, gibt sie eine leere Suchanforderungszeichenfolge an. In diesem Beispiel wählt die Anwendung die Pubs-Datenbank aus und ruft SQLBrowseConnect ein letztes Mal auf, wobei das SCHLÜSSELwort LANGUAGE und das Sternchen vor dem DATABASE-Schlüsselwort weggelassen werden:

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

Da das DATABASE-Attribut das endgültige Verbindungsattribute ist, das vom Treiber benötigt wird, ist der Browservorgang abgeschlossen, die Anwendung ist mit der Datenquelle verbunden, und SQLBrowseConnect gibt SQL_SUCCESS zurück. SQLBrowseConnect gibt auch die vollständige Verbindungszeichenfolge als Suchergebniszeichenfolge zurück:

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

Die letzte verbindungszeichenfolge, die vom Treiber zurückgegeben wird, enthält weder die benutzerfreundlichen Namen nach jedem Schlüsselwort noch optionale Schlüsselwörter, die von der Anwendung nicht angegeben werden. Die Anwendung kann diese Zeichenfolge mit SQLDriverConnect verwenden, um eine erneute Verbindung mit der Datenquelle im aktuellen Verbindungshandle (nach dem Trennen) oder zum Herstellen einer Verbindung mit der Datenquelle für ein anderes Verbindungshandle herzustellen. Beispiel:

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