SQLBrowseConnect-Funktion

Konformität
Version eingeführt: ODBC 1.0-Standardscompliance: ODBC

Zusammenfassung
SQLBrowseConnect unterstützt eine iterative Methode zum Ermitteln und Aufzählen der Attribute und Attributwerte, die zum Herstellen einer Verbindung mit einer Datenquelle erforderlich sind. Jeder Aufruf von SQLBrowseConnect gibt aufeinanderfolgende Ebenen von Attributen und Attributwerten zurück. Wenn alle Ebenen aufgezählt wurden, wird eine Verbindung mit der Datenquelle abgeschlossen, und eine vollständige Verbindungszeichenfolge wird von SQLBrowseConnect zurückgegeben. Ein Rückgabecode von SQL_SUCCESS oder SQL_SUCCESS_WITH_INFO gibt an, dass alle Verbindungsinformationen angegeben wurden und die Anwendung jetzt mit der Datenquelle verbunden ist.

Syntax

  
SQLRETURN SQLBrowseConnect(  
     SQLHDBC         ConnectionHandle,  
     SQLCHAR *       InConnectionString,  
     SQLSMALLINT     StringLength1,  
     SQLCHAR *       OutConnectionString,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   StringLength2Ptr);  

Argumente

ConnectionHandle
[Eingabe] Verbindungshandle.

InConnectionString
[Eingabe] Suchanforderung Verbindungszeichenfolge (siehe "InConnectionString-Argument" in "Kommentare").

StringLength1
[Eingabe] Länge von *InConnectionString in Zeichen.

OutConnectionString
[Ausgabe] Zeigen Sie auf einen Zeichenpuffer, in dem das Suchergebnis Verbindungszeichenfolge zurückgegeben werden soll (siehe "OutConnectionString-Argument" in "Kommentare").

Wenn OutConnectionString NULL ist, gibt StringLength2Ptr weiterhin die Gesamtanzahl der Zeichen zurück (mit Ausnahme des Nullendpunkts für Zeichendaten), die für die Rückgabe im Puffer verfügbar sind, auf den outConnectionString verweist.

BufferLength
[Eingabe] Länge des *OutConnectionString-Puffers in Zeichen.

StringLength2Ptr
[Ausgabe] Die Gesamtanzahl der Zeichen (mit Ausnahme von NULL-Beendigung), die in *OutConnectionString zurückgegeben werden können. Wenn die Anzahl der zurückzugebenden Zeichen größer oder gleich "BufferLength" ist, wird die Verbindungszeichenfolge in "*OutConnectionString" auf "BufferLength" abgeschnitten, abzüglich der Länge eines Null-Beendigungszeichens.

Gibt zurück

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_ERROR, SQL_INVALID_HANDLE oder SQL_STILL_EXECUTING.

Diagnostik

Wenn SQLBrowseConnect SQL_ERROR, SQL_SUCCESS_WITH_INFO oder SQL_NEED_DATA zurückgibt, kann ein zugeordneter SQLSTATE-Wert durch Aufrufen von SQLGetDiagRec mit einem HandleType von SQL_HANDLE_STMT und einem Handle of ConnectionHandle abgerufen werden. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die häufig von SQLBrowseConnect zurückgegeben werden und die einzelnen Werte im Kontext dieser Funktion erläutert. Die Notation "(DM)" steht vor den Beschreibungen von SQLSTATEs, die vom Treiber-Manager zurückgegeben werden. Der rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.

InConnectionString-Argument

Eine Suchanforderung Verbindungszeichenfolge weist die folgende Syntax auf:

connection-string ::= attribute[;] | Attributverbindungszeichenfolge;;
attribut ::= attribut-keyword= attribute-value | DRIVER=[{]attribute-value[]}
attribut-keyword ::= DSNPWD | UID | | driver-defined-attribute-keyword
attribut-value ::= character-string
driver-defined-attribute-keyword ::= identifier

wobei die Zeichenzeichenfolge null oder mehr Zeichen enthält; Der Bezeichner weist mindestens ein Zeichen auf; Bei Attributschlüsselwort wird die Groß-/Kleinschreibung nicht beachtet; Bei Attributwert kann die Groß-/Kleinschreibung beachtet werden, und der Wert des DSN-Schlüsselworts besteht nicht ausschließlich aus Leerzeichen. Aufgrund von Verbindungszeichenfolge- und Initialisierungsdateigrammatik, Schlüsselwörtern und Attributwerten, die die Zeichen []{}(),;? *=!@ sollte vermieden werden. Aufgrund der Grammatik in den Systeminformationen können Schlüsselwörter und Datenquellennamen nicht das umgekehrte Schrägstrichzeichen (\) enthalten. Für ein ODBC 2.x-Treiber , geschweifte Klammern sind um den Attributwert für das DRIVER-Schlüsselwort erforderlich.

Wenn Schlüsselwörter in der Suchanforderung Verbindungszeichenfolge wiederholt werden, verwendet der Treiber den Wert, der dem ersten Vorkommen des Schlüsselworts zugeordnet ist. Wenn die Schlüsselwörter DSN und DRIVER in derselben Suchanforderung Verbindungszeichenfolge enthalten sind, wird zuerst das Schlüsselwort "Treiber-Manager" und "Treiber" verwendet.

Informationen dazu, wie eine Anwendung eine Datenquelle oder einen Treiber auswählt, finden Sie unter Auswählen einer Datenquelle oder eines Treibers.

OutConnectionString-Argument

Das Suchergebnis Verbindungszeichenfolge ist eine Liste von Verbindungsattributen. Ein Verbindungsattribute besteht aus einem Attributschlüsselwort und einem entsprechenden Attributwert. Das Suchergebnis Verbindungszeichenfolge weist die folgende Syntax auf:

connection-string ::= attribute[;] | Attributverbindungszeichenfolge ;
attribut ::= [*]attribut-keyword=attribute-value
attribut-keyword ::= ODBC-attribute-keyword | driver-defined-attribute-keyword
ODBC-attribut-keyword = {UID | PWD}[:localized-identifier] driver-defined-attribute-keyword ::= identifier[:localized-identifier] attribute-value ::= { attribute-value-list } | ? (Die geschweiften Klammern sind literal; sie werden vom Treiber zurückgegeben.)
attribut-value-list ::= character-string [:localized-character string] | character-string [:localized-character string] , attribute-value-list

wobei zeichenzeichenfolgen und lokalisierte Zeichenfolge null oder mehr Zeichen enthalten; Der Bezeichner und der lokalisierte Bezeichner weisen mindestens ein Zeichen auf; bei Attribut-Schlüsselwort wird die Groß-/Kleinschreibung nicht beachtet. Bei Attributwert wird die Groß-/Kleinschreibung möglicherweise beachtet. Aufgrund von Verbindungszeichenfolge- und Initialisierungsdateigrammatik, Schlüsselwörtern, lokalisierten Bezeichnern und Attributwerten, die die Zeichen []{}(),;? *=!@ sollte vermieden werden. Aufgrund der Grammatik in den Systeminformationen können Schlüsselwörter und Datenquellennamen nicht das umgekehrte Schrägstrichzeichen (\) enthalten.

Das Suchergebnis Verbindungszeichenfolge Syntax wird gemäß den folgenden semantischen Regeln verwendet:

• Wenn ein Sternchen (*) vor einem Attributschlüsselwort steht, ist das Attribut optional und kann im nächsten Aufruf von SQLBrowseConnect weggelassen werden.

• Die Attributstichwörter UID und PWD haben die gleiche Bedeutung wie in SQLDriverConnect definiert.

• Ein Driver-defined-attribute-keyword benennt die Art des Attributs, für das ein Attributwert angegeben werden kann. Beispielsweise kann es sich um SERVER, DATENBANK, HOST oder DBMS handeln.

• ODBC-attribut-keywords und driver-defined-attribute-keywords include a localized or user-friendly version of the keyword. Dies kann von Anwendungen als Bezeichnung in einem Dialogfeld verwendet werden. Die UID, PWD oder der Bezeichner müssen jedoch nur verwendet werden, wenn eine Suchanforderungszeichenfolge an den Treiber übergeben wird.

• Die {attribute-value-list} ist eine Aufzählung der tatsächlichen Werte, die für das entsprechende Attribut-Schlüsselwort gültig sind. Beachten Sie, dass die geschweiften Klammern ({}) keine Liste mit Auswahlmöglichkeiten angeben; sie werden vom Treiber zurückgegeben. Beispielsweise kann es sich um eine Liste von Servernamen oder eine Liste mit Datenbanknamen handeln.

• Wenn der Attributwert ein einzelnes Fragezeichen (?) ist, entspricht ein einzelner Wert dem Attribut-Schlüsselwort. Beispiel: UID=JohnS; PWD=Sesam.

• Jeder Aufruf von SQLBrowseConnect gibt nur die Informationen zurück, die erforderlich sind, um die nächste Ebene des Verbindungsprozesses zu erfüllen. Der Treiber ordnet Statusinformationen dem Verbindungshandle zu, sodass der Kontext für jeden Anruf immer bestimmt werden kann.

Verwenden von SQLBrowseConnect

SQLBrowseConnect erfordert eine zugeordnete Verbindung. Der Treiber-Manager lädt den Treiber, der angegeben wurde oder dem in der ursprünglichen Suchanforderung angegebenen Datenquellennamen entspricht, Verbindungszeichenfolge. Informationen dazu, wann dies geschieht, finden Sie im Abschnitt "Kommentare" in der SQLConnect-Funktion. Der Treiber kann während des Browservorgangs eine Verbindung mit der Datenquelle herstellen. Wenn SQLBrowseConnect SQL_ERROR zurückgibt, werden ausstehende Verbindungen beendet, und die Verbindung wird in einen nicht verbundenen Zustand zurückgegeben.

Wenn SQLBrowseConnect zum ersten Mal für eine Verbindung aufgerufen wird, muss die Suchanforderung Verbindungszeichenfolge das DSN-Schlüsselwort oder das DRIVER-Schlüsselwort enthalten. Wenn die Suchanforderung Verbindungszeichenfolge das DSN-Schlüsselwort enthält, sucht der Treiber-Manager eine entsprechende Datenquellenspezifikation in den Systeminformationen:

• Wenn der Treiber-Manager die entsprechende Datenquellenspezifikation findet, lädt er die zugeordnete Treiber-DLL; Der Treiber kann Informationen zur Datenquelle aus den Systeminformationen abrufen.

• Wenn der Treiber-Manager die entsprechende Datenquellenspezifikation nicht finden kann, sucht er die Standarddatenquellenspezifikation und lädt die zugeordnete Treiber-DLL. Der Treiber kann Informationen zur Standarddatenquelle aus den Systeminformationen abrufen. "DEFAULT" wird an den Treiber für den DSN übergeben.

• Wenn der Treiber-Manager die entsprechende Datenquellenspezifikation nicht finden kann und keine Standarddatenquellenspezifikation vorhanden ist, wird SQL_ERROR mit SQLSTATE IM002 zurückgegeben (Datenquelle nicht gefunden und kein Standardtreiber angegeben).

Wenn die Suchanforderung Verbindungszeichenfolge das SCHLÜSSELwort DRIVER enthält, lädt der Treiber-Manager den angegebenen Treiber. Es wird nicht versucht, eine Datenquelle in den Systeminformationen zu suchen. Da das DRIVER-Schlüsselwort keine Informationen aus den Systeminformationen verwendet, muss der Treiber genügend Schlüsselwörter definieren, damit ein Treiber eine Verbindung mit einer Datenquelle herstellen kann, indem nur die Informationen in der Suchanforderung Verbindungszeichenfolge s verwendet werden.

Bei jedem Aufruf von SQLBrowseConnect gibt die Anwendung die Verbindungsattributwerte in der Suchanforderung Verbindungszeichenfolge an. Der Treiber gibt nachfolgende Ebenen von Attributen und Attributwerten im Suchergebnis Verbindungszeichenfolge zurück. Er gibt SQL_NEED_DATA zurück, solange verbindungsattribute vorhanden sind, die in der Suchanforderung noch nicht aufgelistet wurden Verbindungszeichenfolge. Die Anwendung verwendet den Inhalt des Suchergebnisses Verbindungszeichenfolge, um die Suchanforderung Verbindungszeichenfolge für den nächsten Aufruf von SQLBrowseConnect zu erstellen. Alle obligatorischen Attribute (denen im Argument OutConnectionString kein Sternchen vorangestellt ist) müssen im nächsten Aufruf von SQLBrowseConnect enthalten sein. Beachten Sie, dass die Anwendung den Inhalt des vorherigen Suchergebniss nicht Verbindungszeichenfolge beim Erstellen der aktuellen Suchanforderung Verbindungszeichenfolge verwenden kann. Das heißt, sie kann keine anderen Werte für Attribute angeben, die in vorherigen Ebenen festgelegt wurden.

Wenn alle Verbindungsebenen und die zugehörigen Attribute aufgezählt wurden, gibt der Treiber SQL_SUCCESS zurück, die Verbindung mit der Datenquelle ist abgeschlossen, und eine vollständige Verbindungszeichenfolge wird an die Anwendung zurückgegeben. Die Verbindungszeichenfolge eignet sich für die Verwendung in Verbindung mit SQLDriverConnect mit der Option SQL_DRIVER_NOPROMPT, eine weitere Verbindung herzustellen. Die vollständige Verbindungszeichenfolge kann nicht in einem anderen Aufruf von SQLBrowseConnect verwendet werden. Wenn SQLBrowseConnect erneut aufgerufen wurde, müsste die gesamte Abfolge der Aufrufe wiederholt werden.

SQLBrowseConnect gibt auch SQL_NEED_DATA zurück, wenn während des Suchvorgangs wiederherstellbare, nichtfatale Fehler auftreten, z. B. ein ungültiges Kennwort oder attributschlüsselwort, das von der Anwendung bereitgestellt wird. Wenn SQL_NEED_DATA zurückgegeben wird und das Suchergebnis Verbindungszeichenfolge unverändert ist, ist ein Fehler aufgetreten, und die Anwendung kann SQLGetDiagRec aufrufen, um sqlSTATE für Suchzeitfehler zurückzugeben. Dadurch kann die Anwendung das Attribut korrigieren und die Suche fortsetzen.

Eine Anwendung kann den Suchvorgang jederzeit beenden, indem SQLDisconnect aufgerufen wird. Der Treiber beendet alle ausstehenden Verbindungen und gibt die Verbindung in einen nicht verbundenen Zustand zurück.

Wenn asynchrone Vorgänge für das Verbindungshandle aktiviert sind, gibt SQLBrowseConnect möglicherweise auch SQL_STILL_EXECUTING zurück. Wenn sie SQL_NEED_DATA zurückgibt, muss eine Anwendung SQLDisconnect verwenden, um den Suchvorgang abzubrechen. Wenn SQLBrowseConnect SQL_STILL_EXECUTING zurückgibt, sollte eine Anwendung SQLCancelHandle verwenden, um den Vorgang abzubrechen. Das Aufrufen von SQLCancelHandle nach dem Zurückgeben der Funktion SQL_NEED_DATA hat keine Auswirkung.

Weitere Informationen finden Sie unter Herstellen einer Verbindung mit SQLBrowseConnect.

Wenn ein Treiber SQLBrowseConnect unterstützt, muss der Schlüsselwortabschnitt des Treibers in den Systeminformationen für den Treiber das Schlüsselwort ConnectFunctions enthalten, wobei das dritte Zeichen auf "Y" festgelegt ist.

Codebeispiel

Im folgenden Beispiel ruft eine Anwendung SQLBrowseConnect wiederholt auf. Jedes Mal, wenn SQLBrowseConnect SQL_NEED_DATA zurückgibt, übergibt es Informationen zu den in *OutConnectionString benötigten Daten. Die Anwendung übergibt OutConnectionString an die Routine "GetUserInput " (nicht angezeigt). GetUserInput analysiert die Informationen, erstellt und zeigt ein Dialogfeld an und gibt die vom Benutzer in *InConnectionString eingegebenen Informationen zurück. Die Anwendung übergibt die Informationen des Benutzers an den Treiber im nächsten Aufruf von SQLBrowseConnect. Nachdem die Anwendung alle erforderlichen Informationen für den Treiber bereitgestellt hat, um eine Verbindung mit der Datenquelle herzustellen, gibt SQLBrowseConnect SQL_SUCCESS zurück, und die Anwendung wird fortgesetzt.

Ein ausführlicheres Beispiel für die Verbindung mit einem SQL Server-Treiber durch Aufrufen von SQLBrowseConnect finden Sie unter SQL Server Browsing Example.

Um beispielsweise eine Verbindung mit der Datenquelle "Vertrieb" herzustellen, können die folgenden Aktionen auftreten. Zunächst übergibt die Anwendung die folgende Zeichenfolge an SQLBrowseConnect:

"DSN=Sales"  

Der Treiber-Manager lädt den Treiber, der der Datenquelle "Vertrieb" zugeordnet ist. Anschließend wird die SQLBrowseConnect-Funktion des Treibers mit denselben Argumenten aufgerufen, die sie von der Anwendung erhalten haben. Der Treiber gibt die folgende Zeichenfolge in *OutConnectionString zurück:

"HOST:Server={red,blue,green};UID:ID=?;PWD:Password=?"  

Die Anwendung übergibt diese Zeichenfolge an die GetUserInput-Routine , die ein Dialogfeld erstellt, in dem der Benutzer aufgefordert wird, den roten, blauen oder grünen Server auszuwählen und eine Benutzer-ID und ein Kennwort einzugeben. Die Routine übergibt die folgenden vom Benutzer angegebenen Informationen zurück in *InConnectionString, die die Anwendung an SQLBrowseConnect übergibt:

"HOST=red;UID=Smith;PWD=Sesame"  

SQLBrowseConnect verwendet diese Informationen, um eine Verbindung mit dem roten Server als Smith mit dem Kennwort Silke herzustellen, und gibt dann die folgende Zeichenfolge in *OutConnectionString zurück:

"*DATABASE:Database={SalesEmployees,SalesGoals,SalesOrders}"  

Die Anwendung übergibt diese Zeichenfolge an die GetUserInput-Routine , die ein Dialogfeld erstellt, in dem der Benutzer aufgefordert wird, eine Datenbank auszuwählen. Der Benutzer wählt empdata aus, und die Anwendung ruft SQLBrowseConnect ein letztes Mal mit dieser Zeichenfolge auf:

"DATABASE=SalesOrders"  

Dies ist die letzte Information, die der Treiber benötigt, um eine Verbindung mit der Datenquelle herzustellen; SQLBrowseConnect gibt SQL_SUCCESS zurück, und *OutConnectionString enthält die abgeschlossenen Verbindungszeichenfolge:

// SQLBrowseConnect_Function.cpp  
// compile with: odbc32.lib  
#include <windows.h>  
#include <sqltypes.h>  
#include <sqlext.h>  
  
#define BRWS_LEN 100  
SQLHENV henv;  
SQLHDBC hdbc;  
SQLHSTMT hstmt;  
SQLRETURN retcode;  
SQLCHAR szConnStrIn[BRWS_LEN], szConnStrOut[BRWS_LEN];  
SQLSMALLINT cbConnStrOut;  
  
void GetUserInput(SQLCHAR * szConnStrOut, SQLCHAR * szConnStrIn) {}  
  
int main() {  
   // Allocate the environment handle.  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);        
   if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
  
      // Set the version environment attribute.  
      retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);  
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
  
         // Allocate the connection handle.  
         retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  
         if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
            // Call SQLBrowseConnect until it returns a value other than SQL_NEED_DATA   
            // (pass data source name the first time).  If SQL_NEED_DATA is returned, call GetUserInput   
            // (not shown) to build a dialog from the values in szConnStrOut.  The user-supplied values   
            // are returned in szConnStrIn, which is passed in the next call to SQLBrowseConnect.  
  
            strcpy_s((char*)szConnStrIn, _countof(szConnStrIn), "DSN=Sales");  
            do {  
               retcode = SQLBrowseConnect(hdbc, szConnStrIn, SQL_NTS,  
                  szConnStrOut, BRWS_LEN, &cbConnStrOut);  
               if (retcode == SQL_NEED_DATA)  
                  GetUserInput(szConnStrOut, szConnStrIn);  
            } while (retcode == SQL_NEED_DATA);  
  
            if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO){  
  
               // Allocate the statement handle.  
               retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
               if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO)  
                  // Process data after successful connection  
                  SQLFreeHandle(SQL_HANDLE_STMT, hstmt);  
               SQLDisconnect(hdbc);  
            }  
         }  
         SQLFreeHandle(SQL_HANDLE_DBC, hdbc);  
      }  
   }  
   SQLFreeHandle(SQL_HANDLE_ENV, henv);  
}  

Verwandte Funktionen

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien