SQLBrowseConnect-Funktion
Konformität
Version eingeführt: ODBC 1.0-Standardkonformität: 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 aufgelistet wurden, wird eine Verbindung mit der Datenquelle hergestellt, 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] Durchsuchen sie die Verbindungszeichenfolge der Anforderung (siehe "InConnectionString-Argument " in "Kommentare").
StringLength1
[Eingabe] Länge von *InConnectionString in Zeichen.
OutConnectionString
[Ausgabe] Zeiger auf einen Zeichenpuffer, in dem die Verbindungszeichenfolge für das Durchsuchen des Ergebnisses zurückgegeben werden soll (siehe "OutConnectionString-Argument " in "Kommentare").
Wenn OutConnectionString NULL ist, gibt StringLength2Ptr weiterhin die Gesamtanzahl der Zeichen (mit Ausnahme des NULL-Terminierungszeichens für Zeichendaten) zurück, die im Puffer zurückgegeben werden können, auf den von OutConnectionString verwiesen wird.
BufferLength
[Eingabe] Länge des *OutConnectionString-Puffers in Zeichen.
StringLength2Ptr
[Ausgabe] Die Gesamtzahl der Zeichen (ohne NULL-Terminierung), 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 in BufferLength abzüglich der Länge eines NULL-Terminierungszeichens abgeschnitten.
Gibt zurück
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_ERROR, SQL_INVALID_HANDLE oder SQL_STILL_EXECUTING.
Diagnose
Wenn SQLBrowseConnect SQL_ERROR, SQL_SUCCESS_WITH_INFO oder SQL_NEED_DATA zurückgibt, kann ein zugeordneter SQLSTATE-Wert abgerufen werden, indem SQLGetDiagRec mit einem HandleType von SQL_HANDLE_STMT und einem Handle von ConnectionHandle aufgerufen wird. 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 werden 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 | Fehler | BESCHREIBUNG |
|---|---|---|
| 01000 | Allgemeine Warnung | Treiberspezifische Informationsmeldung. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 01004 | Zeichenfolgendaten, rechts abgeschnitten | Der Puffer *OutConnectionString war nicht groß genug, um die gesamte Suchergebnisverbindungszeichenfolge zurückzugeben, sodass die Zeichenfolge abgeschnitten wurde. Der Puffer *StringLength2Ptr enthält die Länge der unwahren Suchergebnis-Verbindungszeichenfolge. (Die Funktion gibt SQL_NEED_DATA zurück.) |
| 01S00 | Ungültiges Verbindungszeichenfolgen-Attribut | In der Verbindungszeichenfolge für die Durchsuchenanforderung (InConnectionString) wurde ein ungültiges Attributschlüsselwort angegeben. (Die Funktion gibt SQL_NEED_DATA zurück.) In der Verbindungszeichenfolge für die Durchsuchenanforderung (InConnectionString) wurde ein Attributschlüsselwort angegeben, das nicht für die aktuelle Verbindungsebene gilt. (Die 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 das Herstellen 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 beide, wie in der Verbindungszeichenfolge für die Durchsuchenanforderung (InConnectionString) angegeben, verstoßen gegen die von der Datenquelle definierten Einschränkungen. |
| 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 seine Ursache. |
| HY001 | Fehler bei der Speicherbelegung | (DM) Der Treiber-Manager konnte keinen Arbeitsspeicher zuordnen, der zur Unterstützung der Ausführung oder Fertigstellung der Funktion erforderlich ist. Der Treiber konnte keinen Arbeitsspeicher zuordnen, der für die Unterstützung der Ausführung oder Fertigstellung der Funktion erforderlich ist. |
| HY008 | Vorgang abgebrochen | Ein asynchroner Vorgang wurde durch Aufrufen der SQLCancelHandle-Funktion abgebrochen. Anschließend wurde die ursprüngliche Funktion für connectionHandle erneut aufgerufen. Ein Vorgang wurde abgebrochen, indem SQLCancelHandle für ConnectionHandle aus einem anderen Thread in einer Multithreadanwendung aufgerufen wurde. |
| HY010 | Funktionssequenzfehler | (DM) Eine asynchron ausgeführte Funktion (nicht diese) wurde für connectionHandle aufgerufen und wurde noch ausgeführt, als diese Funktion aufgerufen wurde. |
| HY013 | Fehler bei der Speicherverwaltung | Der Funktionsaufruf konnte nicht verarbeitet werden, weil auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund von geringen Arbeitsspeicherbedingungen. |
| HY090 | Ungültige Zeichenfolgen- oder Pufferlänge | (DM) Der für das Argument StringLength1 angegebene Wert war kleiner als 0 und war nicht gleich SQL_NTS. (DM) Der für das Argument BufferLength angegebene Wert war kleiner als 0. |
| HY114 | Der Treiber unterstützt keine asynchrone Funktionsausführung auf Verbindungsebene. | (DM) Die Anwendung hat den asynchronen Vorgang für das Verbindungshandle aktiviert, bevor die Verbindung hergestellt wird. Der Treiber unterstützt jedoch keinen asynchronen Vorgang für das Verbindungshandle. |
| HYT00 | Timeout abgelaufen | Der Anmeldetimeoutzeitraum ist abgelaufen, bevor die Verbindung mit der Datenquelle hergestellt wurde. Der Timeoutzeitraum wird über SQLSetConnectAttr festgelegt, SQL_ATTR_LOGIN_TIMEOUT. |
| HYT01 | Verbindungstimeout abgelaufen | Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung geantwortet hat. Der Verbindungstimeoutzeitraum wird über SQLSetConnectAttr festgelegt, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | 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 Verbindungszeichenfolge für die Durchsuchenanforderung angegebene Datenquellenname (InConnectionString) wurde weder in den Systeminformationen gefunden, noch gab es eine Standardtreiberspezifikation. (DM) ODBC-Datenquellen und Standardtreiberinformationen konnten in den Systeminformationen nicht gefunden werden. |
| IM003 | Der angegebene Treiber konnte nicht geladen werden. | (DM) Der in der Datenquellenspezifikation in den Systeminformationen aufgeführte oder durch das DRIVER-Schlüsselwort angegebene Treiber wurde nicht gefunden oder konnte aus einem anderen Grund nicht geladen werden. |
| IM004 | SqlAllocHandle des Treibers auf SQL_HANDLE _ENV fehlgeschlagen | (DM) Während SQLBrowseConnect hat der Treiber-Manager die SQLAllocHandle-Funktion des Treibers mit einem HandleType-Wert von SQL_HANDLE_ENV aufgerufen, und der Treiber hat einen Fehler zurückgegeben. |
| IM005 | SqlAllocHandle des Treibers auf SQL_HANDLE_DBC fehlgeschlagen | (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 bei SQLSetConnectAttr des Treibers | (DM) Während SQLBrowseConnect hat der Treiber-Manager die FUNKTION SQLSetConnectAttr des Treibers aufgerufen, und der Treiber hat einen Fehler zurückgegeben. |
| IM009 | Übersetzungs-DLL kann nicht geladen werden | Der Treiber konnte die Für die Datenquelle oder für die Verbindung angegebene Übersetzungs-DLL nicht laden. |
| IM010 | Datenquellenname 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) Die 32-Bit-Anwendung verwendet einen DSN, der eine Verbindung mit einem 64-Bit-Treiber herstellt. oder umgekehrt. |
| IM017 | Abruf ist im asynchronen Benachrichtigungsmodus deaktiviert. | Wenn das Benachrichtigungsmodell verwendet wird, wird die Abfrage 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 Nachverarbeitung 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 Suchanforderungs-Verbindungszeichenfolge weist die folgende Syntax auf:
connection-string ::= attribute[;] | Attribut;Verbindungszeichenfolge;
attribut ::= attribute-keyword=attribute-value | DRIVER=[{]attribute-value[}]
attribute-keyword ::= DSNPWDUID | | | driver-defined-attribute-keyword
attribute-value ::= zeichenzeichenfolge
driver-defined-attribute-keyword ::= identifier
wobei Zeichenfolgen null oder mehr Zeichen enthalten; der Bezeichner verfügt über ein oder mehrere Zeichen; attribute-keyword unterscheidet nicht die Groß-/Kleinschreibung. beim Attributwert kann die Groß-/Kleinschreibung beachtet werden. und der Wert des DSN-Schlüsselworts besteht nicht ausschließlich aus Leerzeichen. Aufgrund der Grammatik von Verbindungszeichenfolgen und Initialisierungsdatei, Schlüsselwörtern und Attributwerten, die die Zeichen []{}(),;? *=!@ sollte vermieden werden. Aufgrund der Grammatik in den Systeminformationen können Schlüsselwörter und Datenquellennamen den umgekehrten Schrägstrich (\) nicht enthalten. Für odbc 2. x-Treiber , Klammern sind um den Attributwert für das DRIVER-Schlüsselwort erforderlich.
Wenn Schlüsselwörter in der Verbindungszeichenfolge der Suchanforderung 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 Verbindungszeichenfolge für die Suchanforderung enthalten sind, verwenden Treiber-Manager und Treiber das schlüsselwort, das zuerst angezeigt wird.
Informationen dazu, wie eine Anwendung eine Datenquelle oder einen Treiber auswählt, finden Sie unter Auswählen einer Datenquelle oder eines Treibers.
OutConnectionString-Argument
Die Verbindungszeichenfolge des Suchergebniss ist eine Liste von Verbindungsattributen. Ein Verbindungsattribute besteht aus einem Attributschlüsselwort und einem entsprechenden Attributwert. Die Verbindungszeichenfolge für das Durchsuchen des Ergebnisses weist die folgende Syntax auf:
connection-string ::= attribute[;] | Attribut;Verbindungszeichenfolge
attribut ::= [*]attribut-keyword=attribute-value
attribute-keyword ::= ODBC-attribute-keyword | driver-defined-attribute-keyword
ODBC-attribute-keyword = {UIDPWD | }[: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.)
attribute-value-list ::= character-string [:localized-character string] | Zeichenfolge [:lokalisierte Zeichenfolge] ,attribute-value-list
Wobei Zeichenfolge und lokalisierte Zeichenfolge null oder mehr Zeichen haben; identifier und localized-identifier haben ein oder mehrere Zeichen; attribute-keyword unterscheidet nicht die Groß-/Kleinschreibung. und attributwert kann zwischen Groß-/Kleinschreibung unterschieden werden. Aufgrund der Grammatik von Verbindungszeichenfolgen und Initialisierungsdatei, Schlüsselwörtern, lokalisierten Bezeichnern und Attributwerten, die die Zeichen []{}(),;? enthalten *=!@ sollte vermieden werden. Aufgrund der Grammatik in den Systeminformationen können Schlüsselwörter und Datenquellennamen den umgekehrten Schrägstrich (\) nicht enthalten.
Die Syntax der Suchergebnis-Verbindungszeichenfolge wird gemäß den folgenden semantischen Regeln verwendet:
Wenn einem Attributschlüsselwort ein Sternchen (*) vorangestellt ist, ist das Attribut optional und kann beim nächsten Aufruf von SQLBrowseConnect weggelassen werden.
Die Attributschlüsselwörter UID und PWD haben dieselbe Bedeutung wie in SQLDriverConnect definiert.
Ein driver-defined-attribute-keyword benennt die Art des Attributs, für das ein Attributwert angegeben werden kann. Dies kann z. B. SERVER, DATENBANK, HOST oder DBMS sein.
ODBC-attribute-keywords und driver-defined-attribute-keywords enthalten eine lokalisierte oder benutzerfreundliche Version des Schlüsselworts. Dies kann von Anwendungen als Bezeichnung in einem Dialogfeld verwendet werden. Allerdings müssen UID, PWD oder der Bezeichner allein verwendet werden, wenn eine Browseanforderungszeichenfolge an den Treiber übergeben wird.
Die {attribute-value-list} ist eine Enumeration der tatsächlichen Werte, die für das entsprechende Attributschlüsselwort gültig sind. Beachten Sie, dass die geschweiften Klammern ({}) keine Liste von Auswahlmöglichkeiten angeben. Sie werden vom Treiber zurückgegeben. Dies kann z. B. eine Liste von Servernamen oder eine Liste von Datenbanknamen sein.
Wenn der Attributwert ein einzelnes Fragezeichen (?) ist, entspricht ein einzelner Wert dem Attributschlüsselwort. Beispiel: UID=JohnS; PWD=Sesame.
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 dem Verbindungshandle Zustandsinformationen zu, sodass der Kontext bei jedem Aufruf immer bestimmt werden kann.
Verwenden von SQLBrowseConnect
SQLBrowseConnect erfordert eine zugeordnete Verbindung. Der Treiber-Manager lädt den Treiber, der in angegeben wurde oder dem Namen der Datenquelle entspricht, der in der anfänglichen Verbindungszeichenfolge der Suchanforderung angegeben ist. Weitere Informationen dazu finden Sie im Abschnitt "Kommentare" 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 Verbindungspools. Wenn SQLBrowseConnect aufgerufen wird, während verbindungspooling aktiviert ist, wird SQLSTATE HY000 (Allgemeiner Fehler) zurückgegeben.
Wenn SQLBrowseConnect zum ersten Mal für eine Verbindung aufgerufen wird, muss die Verbindungszeichenfolge der Browseanforderung das DSN-Schlüsselwort oder das DRIVER-Schlüsselwort enthalten. Wenn die Verbindungszeichenfolge für die Durchsuchenanforderung das DSN-Schlüsselwort enthält, sucht der Treiber-Manager in den Systeminformationen nach einer entsprechenden Datenquellenspezifikation:
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, gibt er SQL_ERROR mit SQLSTATE IM002 zurück (Datenquelle nicht gefunden und kein Standardtreiber angegeben).
Wenn die Verbindungszeichenfolge der Browseanforderung das DRIVER-Schlüsselwort enthält, lädt der Treiber-Manager den angegebenen Treiber. es versucht nicht, 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 den Verbindungszeichenfolgen der Suchanforderung verwendet werden.
Bei jedem Aufruf von SQLBrowseConnect gibt die Anwendung die Verbindungsattributwerte in der Verbindungszeichenfolge für die Durchsuchenanforderung an. Der Treiber gibt aufeinanderfolgende Ebenen von Attributen und Attributwerten in der Verbindungszeichenfolge des Suchergebniss zurück. es gibt SQL_NEED_DATA zurück, solange Verbindungsattribute vorhanden sind, die noch nicht in der Verbindungszeichenfolge der Suchanforderung aufgelistet wurden. Die Anwendung verwendet den Inhalt der Verbindungszeichenfolge zum Durchsuchen des Ergebnisses, um die Verbindungszeichenfolge für die Durchsuchenanforderung für den nächsten Aufruf von SQLBrowseConnect zu erstellen. Alle obligatorischen Attribute (denen, denen kein Sternchen im Argument OutConnectionString vorangestellt ist) müssen im nächsten Aufruf von SQLBrowseConnect eingeschlossen werden. Beachten Sie, dass die Anwendung beim Erstellen der aktuellen Suchanforderungs-Verbindungszeichenfolge nicht den Inhalt der vorherigen Suchergebnis-Verbindungszeichenfolge verwenden kann. Das heißt, es kann keine anderen Werte für Attribute angeben, die in vorherigen Ebenen festgelegt wurden.
Wenn alle Verbindungsebenen und die zugehörigen Attribute aufgelistet 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, um eine weitere Verbindung herzustellen. Die vollständige Verbindungszeichenfolge kann jedoch nicht in einem anderen Aufruf von SQLBrowseConnect verwendet werden. Wenn SQLBrowseConnect erneut aufgerufen würde, müsste die gesamte Sequenz von Aufrufen wiederholt werden.
SQLBrowseConnect gibt auch SQL_NEED_DATA zurück, wenn während des Durchsuchens wiederherstellbare, nicht schwerwiegende Fehler auftreten. z. B. ein ungültiges Kennwort oder ein ungültiges Attributschlüsselwort, das von der Anwendung bereitgestellt wird. Wenn SQL_NEED_DATA zurückgegeben wird und die Verbindungszeichenfolge für das Durchsuchen des Ergebnisses unverändert ist, ist ein Fehler aufgetreten, und die Anwendung kann SQLGetDiagRec aufrufen, um SQLSTATE für Browserzeitfehler zurückzugeben. Dadurch kann die Anwendung das Attribut korrigieren und die Suche fortsetzen.
Eine Anwendung kann den Suchvorgang jederzeit durch Aufrufen von SQLDisconnect beenden. Der Treiber beendet alle ausstehenden Verbindungen und versetzt 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 SQL_NEED_DATA zurückgegeben wird, muss eine Anwendung SQLDisconnect verwenden, um den Durchstöbervorgang abzubrechen. Wenn SQLBrowseConnect SQL_STILL_EXECUTING zurückgibt, sollte eine Anwendung SQLCancelHandle verwenden, um den laufenden Vorgang abzubrechen. Das Aufrufen von SQLCancelHandle , nachdem die Funktion SQL_NEED_DATA zurückgegeben hat, hat keine Auswirkung.
Weitere Informationen finden Sie unter Herstellen einer Verbindung mit SQLBrowseConnect.
Wenn ein Treiber SQLBrowseConnect unterstützt, muss der Treiberschlüsselwortabschnitt 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 in der Verbindungszeichenfolge angebenTrusted_Connection=yes.
Im folgenden Beispiel ruft eine Anwendung SQLBrowseConnect wiederholt auf. Jedes Mal, wenn SQLBrowseConnect SQL_NEED_DATA zurückgibt, werden Informationen zu den Daten zurückgegeben, die in *OutConnectionString benötigt werden. Die Anwendung übergibt OutConnectionString an ihre Routine GetUserInput (nicht dargestellt). 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 Benutzerinformationen beim nächsten Aufruf von SQLBrowseConnect an den Treiber. Nachdem die Anwendung alle erforderlichen Informationen für den Treiber zum Herstellen einer Verbindung mit der Datenquelle bereitgestellt hat, gibt SQLBrowseConnect SQL_SUCCESS zurück, und die Anwendung wird fortgesetzt.
Ein ausführlicheres Beispiel für das Herstellen einer Verbindung mit einem SQL Server-Treiber durch Aufrufen von SQLBrowseConnect finden Sie unter beispiel für SQL Server Browsen.
Um beispielsweise eine Verbindung mit der Datenquelle Sales 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 Sales zugeordnet ist. Anschließend wird die SQLBrowseConnect-Funktion des Treibers mit denselben Argumenten aufgerufen, die er von der Anwendung erhalten hat. 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 benutzerdefinierten 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 Sesame herzustellen, und gibt dann die folgende Zeichenfolge in *OutConnectionString zurück:
"*DATABASE:Database={SalesEmployees,SalesGoals,SalesOrders}"
Die Anwendung übergibt diese Zeichenfolge an ihre 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 abgeschlossene 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
| Informationen über | Finden Sie unter |
|---|---|
| Zuweisen eines Verbindungshandles | SQLAllocHandle-Funktion |
| Aufbauen der Verbindung zu einer Datenquelle | SQLConnect-Funktion |
| Trennen einer Datenquelle | SQLDisconnect-Funktion |
| Herstellen einer Verbindung mit einer Datenquelle mithilfe einer Verbindungszeichenfolge oder eines Dialogfelds | SQLDriverConnect-Funktion |
| Zurückgeben von Treiberbeschreibungen und Attributen | SQLDrivers-Funktion |
| Freigeben eines Verbindungshandles | SQLFreeHandle-Funktion |
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für