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.

SQLSTATE	Error	Beschreibung
01000	Allgemeiner Warnhinweis	Treiberspezifische Informationsmeldung. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.)
01004	Zeichenfolgendaten, rechts abgeschnitten	Der Puffer *OutConnectionString war nicht groß genug, um das gesamte Suchergebnis Verbindungszeichenfolge zurückzugeben, sodass die Zeichenfolge abgeschnitten wurde. Der Puffer *StringLength2Ptr enthält die Länge des untruncated browse result Verbindungszeichenfolge. (Funktion gibt SQL_NEED_DATA zurück.)
01S00	Ungültiges Verbindungszeichenfolge-Attribut	In der Suchanforderung Verbindungszeichenfolge (InConnectionString) wurde ein ungültiges Attributschlüsselwort angegeben. (Funktion gibt SQL_NEED_DATA zurück.) Ein Attributschlüsselwort wurde in der Suchanforderung Verbindungszeichenfolge (InConnectionString) angegeben, das nicht auf die aktuelle Verbindungsebene angewendet wird. (Funktion gibt SQL_NEED_DATA zurück.)
01S02	Wert geändert	Der Treiber hat den angegebenen Wert des ValuePtr-Arguments in SQLSetConnectAttr nicht unterstützt und einen ähnlichen Wert ersetzt. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.)
08001	Client kann keine Verbindung herstellen	Der Treiber konnte keine Verbindung mit der Datenquelle herstellen.
08002	Verwendeter Verbindungsname	(DM) Die angegebene Verbindung wurde bereits verwendet, um eine Verbindung mit einer Datenquelle herzustellen, und die Verbindung war geöffnet.
08004	Der Server hat die Verbindung abgelehnt.	Die Datenquelle lehnte die Einrichtung der Verbindung aus implementierungsdefinierten Gründen ab.
08S01	Kommunikationslinkfehler	Die Kommunikationsverbindung zwischen dem Treiber und der Datenquelle, mit der der Treiber versucht hat, eine Verbindung herzustellen, ist fehlgeschlagen, bevor die Verarbeitung der Funktion abgeschlossen wurde.
28000	Ungültige Autorisierungsspezifikation	Entweder der Benutzerbezeichner oder die Autorisierungszeichenfolge oder beides, wie in der Suchanforderung angegeben, Verbindungszeichenfolge (InConnectionString) verletzte Einschränkungen, die von der Datenquelle definiert wurden.
HY000	Allgemeiner Fehler	Es ist ein Fehler aufgetreten, für den kein spezifischer SQLSTATE-Wert vorhanden war und für den keine implementierungsspezifische SQLSTATE definiert wurde. Die von SQLGetDiagRec im *MessageText-Puffer zurückgegebene Fehlermeldung beschreibt den Fehler und dessen Ursache.
HY001	Speicherzuweisungsfehler	(DM) Der Treiber-Manager konnte speicher nicht zuordnen, der erforderlich ist, um die Ausführung oder den Abschluss der Funktion zu unterstützen. Der Treiber konnte speicher nicht zuordnen, der erforderlich ist, um die Ausführung oder den Abschluss der Funktion zu unterstützen.
HY008	Vorgang abgebrochen	Ein asynchroner Vorgang wurde durch Aufrufen der SQLCancelHandle-Funktion abgebrochen. Anschließend wurde die ursprüngliche Funktion erneut für das ConnectionHandle aufgerufen. Ein Vorgang wurde abgebrochen, indem SQLCancelHandle für das ConnectionHandle-Element aus einem anderen Thread in einer Multithreadanwendung aufgerufen wurde.
HY010	Funktionssequenzfehler	(DM) Eine asynchron ausgeführte Funktion (nicht diese) wurde für das ConnectionHandle aufgerufen und wurde weiterhin ausgeführt, als diese Funktion aufgerufen wurde.
HY013	Speicherverwaltungsfehler	Der Funktionsaufruf konnte nicht verarbeitet werden, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund geringer Arbeitsspeicherbedingungen.
HY090	Ungültige Zeichenfolgen- oder Pufferlänge	(DM) Der für argument "StringLength1 " angegebene Wert war kleiner als 0 und war nicht gleich SQL_NTS. (DM) Der für argument "BufferLength " angegebene Wert war kleiner als 0.
HY114	Treiber unterstützt keine asynchrone Funktionsausführung auf Verbindungsebene	(DM) Die Anwendung hat den asynchronen Vorgang auf dem Verbindungshandle aktiviert, bevor die Verbindung hergestellt wird. Der Treiber unterstützt jedoch keinen asynchronen Vorgang beim Verbindungshandle.
HYT00	Timeout überschritten	Der Anmeldetimeoutzeitraum ist abgelaufen, bevor die Verbindung mit der Datenquelle abgeschlossen wurde. Der Timeoutzeitraum wird über SQLSetConnectAttr SQL_ATTR_LOGIN_TIMEOUT festgelegt.
HYT01	Verbindungstimeout abgelaufen	Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung geantwortet hat. Der Verbindungstimeoutzeitraum wird über SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT festgelegt.
IM001	Dieser Treiber unterstützt diese Funktion nicht.	(DM) Der Treiber, der dem angegebenen Datenquellennamen entspricht, unterstützt die Funktion nicht.
IM002	Datenquelle nicht gefunden und kein Standardtreiber angegeben	(DM) Der in der Suchanforderung angegebene Datenquellenname Verbindungszeichenfolge (InConnectionString) wurde in den Systeminformationen nicht gefunden, noch gab es eine Standardtreiberspezifikation. (DM) ODBC-Datenquellen- und Standardtreiberinformationen wurden in den Systeminformationen nicht gefunden.
IM003	Der angegebene Treiber konnte nicht geladen werden.	(DM) Der in der Datenquellenspezifikation in den Systeminformationen oder durch das DRIVER-Schlüsselwort angegebene Treiber wurde aus einem anderen Grund nicht gefunden oder konnte nicht geladen werden.
IM004	Fehler des SQLAllocHandle-Treibers für SQL_HANDLE _ENV	(DM) Während SQLBrowseConnect hat der Treiber-Manager die SQLAllocHandle-Funktion des Treibers mit einem HandleType von SQL_HANDLE_ENV aufgerufen und der Treiber hat einen Fehler zurückgegeben.
IM005	Fehler beim SQLAllocHandle des Treibers bei SQL_HANDLE_DBC	(DM) Während SQLBrowseConnect hat der Treiber-Manager die SQLAllocHandle-Funktion des Treibers mit einem HandleType von SQL_HANDLE_DBC aufgerufen, und der Treiber hat einen Fehler zurückgegeben.
IM006	Fehler beim SqlSetConnectAttr des Treibers.	(DM) Während SQLBrowseConnect hat der Treiber-Manager die SQLSetConnectAttr-Funktion des Treibers aufgerufen, und der Treiber hat einen Fehler zurückgegeben.
IM009	Die Übersetzungs-DLL kann nicht geladen werden.	Der Treiber konnte die Übersetzungs-DLL, die für die Datenquelle oder für die Verbindung angegeben wurde, nicht laden.
IM010	Name der Datenquelle zu lang	(DM) Der Attributwert für das DSN-Schlüsselwort war länger als SQL_MAX_DSN_LENGTH Zeichen.
IM011	Treibername zu lang	(DM) Der Attributwert für das DRIVER-Schlüsselwort war länger als 255 Zeichen.
IM012	DRIVER-Schlüsselwortsyntaxfehler	(DM) Das Schlüsselwort-Wert-Paar für das DRIVER-Schlüsselwort enthielt einen Syntaxfehler.
IM014	Der angegebene DSN enthält einen Architekturkonflikt zwischen Treiber und Anwendung.	(DM) 32-Bit-Anwendung verwendet einen DSN, der eine Verbindung mit einem 64-Bit-Treiber herstellt; oder umgekehrt.
IM017	Die Abrufung ist im asynchronen Benachrichtigungsmodus deaktiviert.	Immer wenn das Benachrichtigungsmodell verwendet wird, ist die Abrufung deaktiviert.
IM018	SQLCompleteAsync wurde nicht aufgerufen, um den vorherigen asynchronen Vorgang für dieses Handle abzuschließen.	Wenn der vorherige Funktionsaufruf für das Handle SQL_STILL_EXECUTING zurückgibt und der Benachrichtigungsmodus aktiviert ist, muss SQLCompleteAsync für das Handle aufgerufen werden, um die Nachbearbeitung durchzuführen und den Vorgang abzuschließen.
S1118	Der Treiber unterstützt keine asynchrone Benachrichtigung.	Wenn der Treiber keine asynchrone Benachrichtigung unterstützt, können Sie SQL_ATTR_ASYNC_DBC_EVENT oder SQL_ATTR_ASYNC_DBC_RETCODE_PTR nicht festlegen.

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.

Hinweis

SQLBrowseConnect unterstützt keine Verbindungspooling. Wenn SQLBrowseConnect aufgerufen wird, während die Verbindungspooling aktiviert ist, wird SQLSTATE HY000 (Allgemeiner Fehler) 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

Hinweis

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

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 zu	Siehe
Zuordnen eines Verbindungsziehpunkts	SQLAllocHandle-Funktion
Aufbauen der Verbindung zu einer Datenquelle	SQLConnect-Funktion
Trennen der Verbindung mit einer Datenquelle	SQLDisconnect-Funktion
Herstellen einer Verbindung mit einer Datenquelle mithilfe eines Verbindungszeichenfolge oder Dialogfelds	SQLDriverConnect-Funktion
Zurückgeben von Treiberbeschreibungen und Attributen	SQLDrivers-Funktion
Freigeben eines Verbindungsziehpunkts	SQLFreeHandle-Funktion

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien