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 |