SQLDriveConnect-Funktion
Konformität
Version eingeführt: ODBC 1.0-Standardkonformität: ODBC
Zusammenfassung
SQLDriverConnect ist eine Alternative zu SQLConnect. Es unterstützt Datenquellen, die mehr Verbindungsinformationen erfordern als die drei Argumente in SQLConnect, Dialogfelder, um den Benutzer zur Eingabe aller Verbindungsinformationen aufzufordern, und Datenquellen, die nicht in den Systeminformationen definiert sind. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit SQLDriverConnect.
Syntax
SQLRETURN SQLDriverConnect(
SQLHDBC ConnectionHandle,
SQLHWND WindowHandle,
SQLCHAR * InConnectionString,
SQLSMALLINT StringLength1,
SQLCHAR * OutConnectionString,
SQLSMALLINT BufferLength,
SQLSMALLINT * StringLength2Ptr,
SQLUSMALLINT DriverCompletion);
Argumente
ConnectionHandle
[Eingabe] Verbindungshandle.
WindowHandle
[Eingabe] Fensterhandle. Die Anwendung kann ggf. das Handle des übergeordneten Fensters oder einen NULL-Zeiger übergeben, wenn das Fensterhandle nicht anwendbar ist oder SQLDriverConnect keine Dialogfelder zeigt.
InConnectionString
[Eingabe] Eine vollständige Verbindungszeichenfolge (siehe Syntax in "Kommentare"), eine partielle Verbindungszeichenfolge oder eine leere Zeichenfolge.
StringLength1
[Eingabe] Länge von *InConnectionString, in Zeichen, wenn die Zeichenfolge Unicode ist, oder Bytes, wenn Zeichenfolge ANSI oder DBCS ist.
OutConnectionString
[Ausgabe] Zeiger auf einen Puffer für die abgeschlossene Verbindungszeichenfolge. Nach erfolgreicher Verbindung mit der Zieldatenquelle enthält dieser Puffer die abgeschlossene Verbindungszeichenfolge. Anwendungen sollten für diesen Puffer mindestens 1.024 Zeichen zuordnen.
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] Zeiger auf einen Puffer, in dem die Gesamtzahl der Zeichen (mit Ausnahme des NULL-Terminierungszeichens) zurückgegeben werden soll, die in *OutConnectionString zurückgegeben werden können. Wenn die Anzahl der zurückzugebenden Zeichen größer oder gleich BufferLength ist, wird die abgeschlossene Verbindungszeichenfolge in *OutConnectionString in BufferLength abzüglich der Länge eines NULL-Terminierungszeichens abgeschnitten.
DriverCompletion
[Eingabe] Flag, das angibt, ob der Treiber-Manager oder Treiber zur Eingabe weiterer Verbindungsinformationen aufgefordert werden muss:
SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED oder SQL_DRIVER_NOPROMPT.
(Weitere Informationen finden Sie unter "Kommentare".)
Gibt zurück
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR, SQL_INVALID_HANDLE oder SQL_STILL_EXECUTING.
Diagnose
Wenn SQLDriverConnect entweder SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert abgerufen werden, indem SQLGetDiagRec mit einem fHandleType von SQL_HANDLE_DBC und einem hHandle von ConnectionHandle aufgerufen wird. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die häufig von SQLDriverConnect zurückgegeben werden, und die einzelnen Werte werden 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 | 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 Verbindungszeichenfolge zurückzugeben, sodass die Verbindungszeichenfolge abgeschnitten wurde. Die Länge der unwahren Verbindungszeichenfolge wird in *StringLength2Ptr zurückgegeben. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 01S00 | Ungültiges Verbindungszeichenfolgen-Attribut | In der Verbindungszeichenfolge (InConnectionString) wurde ein ungültiges Attributschlüsselwort angegeben, aber der Treiber konnte trotzdem eine Verbindung mit der Datenquelle herstellen. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 01S02 | Optionswert geändert | Der Treiber hat den angegebenen Wert, auf den das ValuePtr-Argument in SQLSetConnectAttr verweist, nicht unterstützt und einen ähnlichen Wert ersetzt. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 01S08 | Fehler beim Speichern des DATEI-DSN | Die Zeichenfolge in *InConnectionString enthielt ein FILEDSN-Schlüsselwort , aber die DSN-Datei wurde nicht gespeichert. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 01S09 | Ungültiges Schlüsselwort | (DM) Die Zeichenfolge in *InConnectionString enthielt ein SAVEFILE-Schlüsselwort , aber kein DRIVER - oder FILEDSN-Schlüsselwort . (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) Der angegebene ConnectionHandle wurde bereits verwendet, um eine Verbindung mit einer Datenquelle herzustellen, und die Verbindung war noch offen. |
| 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 SqlDriverConnect-Funktion die Verarbeitung abgeschlossen hat. |
| 28000 | Ungültige Autorisierungsspezifikation | Entweder der Benutzerbezeichner oder die Autorisierungszeichenfolge oder beide, wie in der Verbindungszeichenfolge (InConnectionString) angegeben, verletzten 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 *szMessageText-Puffer zurückgegebene Fehlermeldung beschreibt den Fehler und seine Ursache. |
| HY000 | Allgemeiner Fehler: Ungültiger Datei-DSN | (DM) Die Zeichenfolge in *InConnectionString enthielt ein FILEDSN-Schlüsselwort, aber der Name der DSN-Datei wurde nicht gefunden. |
| HY000 | Allgemeiner Fehler: Dateipuffer kann nicht erstellt werden | (DM) Die Zeichenfolge in *InConnectionString enthielt ein FILEDSN-Schlüsselwort, aber die DSN-Datei war nicht lesbar. |
| HY001 | Fehler bei der Speicherbelegung | Der Treiber-Manager konnte keinen Arbeitsspeicher zuordnen, der zur Unterstützung der Ausführung oder Vervollständigung der SQLDriverConnect-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 | Die asynchrone Verarbeitung wurde für ConnectionHandle aktiviert. Die Funktion wurde aufgerufen, und bevor die Ausführung abgeschlossen wurde, wurde die FUNKTION SQLCancelHandle für ConnectionHandle aufgerufen, und dann wurde die FUNKTION SQLDriverConnect erneut für ConnectionHandle aufgerufen. Oder die SQLDriverConnect-Funktion wurde aufgerufen, und bevor die Ausführung abgeschlossen wurde, wurde SQLCancelHandle auf der ConnectionHandle aus einem anderen Thread in einer Multithreadanwendung aufgerufen. |
| HY010 | Funktionssequenzfehler | (DM) Eine weitere asynchron ausgeführte Funktion (nicht SQLDriverConnect) wurde für ConnectionHandle aufgerufen und wurde weiterhin ausgeführt, als die FUNKTION SQLDriverConnect aufgerufen wurde. |
| HY013 | Fehler bei der Speicherverwaltung | Der SqlDriverConnect-Funktionsaufruf konnte nicht verarbeitet werden, da 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. |
| HY092 | Ungültiger Attribut-/Optionsbezeichner | (DM) Das Argument DriverCompletion wurde SQL_DRIVER_PROMPT, und das Argument WindowHandle war ein NULL-Zeiger. |
| HY110 | Ungültiger Treiberabschluss | (DM) Der für das Argument DriverCompletion angegebene Wert war nicht gleich SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED oder SQL_DRIVER_NOPROMPT. (DM) Verbindungspooling wurde aktiviert, und der für das Argument DriverCompletion angegebene Wert war nicht gleich SQL_DRIVER_NOPROMPT. |
| HYC00 | Optionales Feature nicht implementiert | Der Treiber unterstützt nicht die version des ODBC-Verhaltens, das von der Anwendung angefordert wurde. |
| 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 (InConnectionString) angegebene Datenquellenname wurde in den Systeminformationen nicht gefunden, und es gab keine 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 SQLDriverConnect hat der Treiber-Manager die SQLAllocHandle-Funktion des Treibers mit einem fHandleType 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 SQLDriverConnect hat der Treiber-Manager die FUNKTION SQLAllocHandle des Treibers mit einem fHandleType von SQL_HANDLE_DBC aufgerufen, und der Treiber hat einen Fehler zurückgegeben. |
| IM006 | Fehler bei SQLSetConnectAttr des Treibers | (DM) Während SQLDriverConnect hat der Treiber-Manager die SQLSetConnectAttr-Funktion des Treibers aufgerufen, und der Treiber hat einen Fehler zurückgegeben. |
| IM007 | Keine Datenquelle oder Treiber angegeben; Dialog verboten | In der Verbindungszeichenfolge wurde kein Datenquellenname oder -treiber angegeben, und DriverCompletion wurde SQL_DRIVER_NOPROMPT. |
| IM008 | Dialogfeld fehlgeschlagen | Der Treiber hat versucht, das Anmeldedialogfeld anzuzeigen, und ist fehlgeschlagen. WindowHandle war ein NULL-Zeiger, und DriverCompletion wurde nicht SQL_DRIVER_NO_PROMPT. |
| 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. (DM) Die Zeichenfolge in *InConnectionString enthielt ein FILEDSN-Schlüsselwort , aber die DSN-Datei enthielt kein DRIVER-Schlüsselwort oder ein DSN-Schlüsselwort . |
| 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. |
| IM015 | Fehler beim SQLDriverConnect-Treiber auf SQL_HANDLE_DBC_INFO_HANDLE | Wenn ein Treiber SQL_ERROR zurückgibt, gibt der Treiber-Manager SQL_ERROR an die Anwendung zurück, und die Verbindung schlägt fehl. Weitere Informationen zu SQL_HANDLE_DBC_INFO_TOKEN finden Sie unter Developing Connection-Pool Awareness in an ODBC Driver.For more information about SQL_HANDLE_DBC_INFO_TOKEN, see Developing Connection-Pool Awareness in an ODBC Driver. |
| 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. |
Kommentare
Eine Verbindungszeichenfolge weist die folgende Syntax auf:
connection-string ::= empty-string[;] | attribut[;] | -Attribut; Verbindungszeichenfolge
empty-string ::=attribute ::= attribute-keyword=attribute-value | DRIVER=[{]attribute-value[}]
attribute-keyword ::= DSN | UID | PWD | 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 []{}(),;? *=!@ nicht mit geschweiften Klammern eingeschlossen, sollte vermieden werden. Der Wert des DSN-Schlüsselworts darf nicht nur aus Leerzeichen bestehen und sollte keine führenden Leerzeichen enthalten. Aufgrund der Grammatik der Systeminformationen können Schlüsselwörter und Datenquellennamen den umgekehrten Schrägstrich (\) nicht enthalten.
Anwendungen müssen nach dem DRIVER-Schlüsselwort keine Klammern um den Attributwert hinzufügen, es sei denn, das Attribut enthält ein Semikolon (;), in diesem Fall sind die geschweiften Klammern erforderlich. Wenn der Vom Treiber empfangene Attributwert geschweifte Klammern enthält, sollte der Treiber diese nicht entfernen, sondern Teil der zurückgegebenen Verbindungszeichenfolge sein.
Ein DSN- oder Verbindungszeichenfolgenwert, der in geschweifte Klammern ({}) eingeschlossen ist, die eines der Zeichen []{}(),;? *=!@ wird intakt an den Treiber übergeben. Wenn Sie diese Zeichen jedoch in einem Schlüsselwort verwenden, gibt der Treiber-Manager bei der Arbeit mit Datei-DSNs einen Fehler zurück, übergibt jedoch die Verbindungszeichenfolge für reguläre Verbindungszeichenfolgen an den Treiber. Vermeiden Sie die Verwendung eingebetteter Klammern in einem Schlüsselwortwert.
Die Verbindungszeichenfolge kann eine beliebige Anzahl von vom Treiber definierten Schlüsselwörtern enthalten. 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, die nur die Informationen in der Verbindungszeichenfolge verwendet. (Weitere Informationen finden Sie weiter unten in diesem Abschnitt unter "Treiberrichtlinien".) Der Treiber definiert, welche Schlüsselwörter erforderlich sind, um eine Verbindung mit der Datenquelle herzustellen.
In der folgenden Tabelle werden die Attributwerte der Schlüsselwörter DSN, FILEDSN, DRIVER, UID, PWD und SAVEFILE beschrieben.
| Schlüsselwort | Beschreibung des Attributwerts |
|---|---|
| DSN | Name einer Datenquelle, wie er von SQLDataSources oder dem Dialogfeld Datenquellen von SQLDriverConnect zurückgegeben wird. |
| FILEDSN | Name einer DSN-Datei, aus der eine Verbindungszeichenfolge für die Datenquelle erstellt wird. Diese Datenquellen werden als Dateidatenquellen bezeichnet. |
| TREIBER | Beschreibung des Treibers, der von der SQLDrivers-Funktion zurückgegeben wird. Beispiel: Rdb oder SQL Server. |
| UID | Eine Benutzer-ID. |
| PWD | Das Kennwort, das der Benutzer-ID entspricht, oder eine leere Zeichenfolge, wenn kein Kennwort für die Benutzer-ID vorhanden ist (PWD=;). |
| SAVEFILE | Der Dateiname einer DSN-Datei, in der die Attributwerte der Schlüsselwörter gespeichert werden sollen, die zum Herstellen der aktuellen, erfolgreichen Verbindung verwendet werden. |
Informationen dazu, wie eine Anwendung eine Datenquelle oder einen Treiber auswählt, finden Sie unter Auswählen einer Datenquelle oder eines Treibers.
Wenn Schlüsselwörter in der 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 Verbindungszeichenfolge enthalten sind, verwenden der Treiber-Manager und der Treiber das schlüsselwort, das zuerst angezeigt wird.
Die Schlüsselwörter FILEDSN und DSN schließen sich gegenseitig aus: Das Schlüsselwort, das zuerst angezeigt wird, wird verwendet, und das Schlüsselwort, das als zweites angezeigt wird, wird ignoriert. Die Schlüsselwörter FILEDSN und DRIVER schließen sich dagegen nicht aus. Wenn ein Schlüsselwort in einer Verbindungszeichenfolge mit FILEDSN angezeigt wird, wird der Attributwert des Schlüsselworts in der Verbindungszeichenfolge anstelle des Attributwerts desselben Schlüsselworts in der DSN-Datei verwendet.
Wenn das SCHLÜSSELwort FILEDSN verwendet wird, werden die in einer DSN-Datei angegebenen Schlüsselwörter verwendet, um eine Verbindungszeichenfolge zu erstellen. (Weitere Informationen finden Sie weiter unten in diesem Abschnitt unter "Dateidatenquellen".) Das UID-Schlüsselwort ist optional. Eine DSN-Datei kann nur mit dem Schlüsselwort DRIVER erstellt werden. Das PWD-Schlüsselwort wird nicht in einer DSN-Datei gespeichert. Das Standardverzeichnis zum Speichern und Laden einer DSN-Datei ist eine Kombination aus dem Pfad, der von CommonFileDir in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ Windows\CurrentVersion und "ODBC\DataSources" angegeben wird. (Wenn CommonFileDir "C:\Programme\Common Files" wäre, wäre das Standardverzeichnis "C:\Programme\Common Files\ODBC\Data Sources".)
Hinweis
Eine DSN-Datei kann direkt bearbeitet werden, indem die Funktionen SQLReadFileDSN und SQLWriteFileDSN in der Installer-DLL aufgerufen werden.
Wenn das SAVEFILE-Schlüsselwort verwendet wird, werden die Attributwerte der Schlüsselwörter, die beim Herstellen der vorhandenen, erfolgreichen Verbindung verwendet werden, als DSN-Datei mit dem Namen des Attributwerts des SAVEFILE-Schlüsselworts gespeichert. Das SAVEFILE-Schlüsselwort muss in Verbindung mit dem Schlüsselwort DRIVER , dem Schlüsselwort FILEDSN oder beidem verwendet werden, oder die Funktion gibt SQL_SUCCESS_WITH_INFO mit SQLSTATE 01S09 (Ungültiges Schlüsselwort) zurück. Das SAVEFILE-Schlüsselwort muss vor dem DRIVER-Schlüsselwort in der Verbindungszeichenfolge angezeigt werden, sonst werden die Ergebnisse nicht definiert.
Treiber-Manager-Richtlinien
Der Treiber-Manager erstellt eine Verbindungszeichenfolge, die im Argument InConnectionString der SQLDriverConnect-Funktion des Treibers an den Treiber übergeben wird. Der Treiber-Manager ändert das Argument InConnectionString , das von der Anwendung an ihn übergeben wird, nicht.
Die Aktion des Treiber-Managers basiert auf dem Wert des Arguments DriverCompletion :
SQL_DRIVER_PROMPT: Wenn die Verbindungszeichenfolge weder das Schlüsselwort DRIVER, DSN noch FILEDSN enthält, zeigt der Treiber-Manager das Dialogfeld Datenquellen an. Es erstellt eine Verbindungszeichenfolge aus dem Datenquellennamen, der vom Dialogfeld zurückgegeben wird, und aus allen anderen Schlüsselwörtern, die von der Anwendung an sie übergeben werden. Wenn der vom Dialogfeld zurückgegebene Datenquellenname leer ist, gibt der Treiber-Manager das Schlüsselwort-Wert-Paar DSN=Default an. (In diesem Dialogfeld wird keine Datenquelle mit dem Namen "Standard" angezeigt.)
SQL_DRIVER_COMPLETE oder SQL_DRIVER_COMPLETE_REQUIRED: Wenn die von der Anwendung angegebene Verbindungszeichenfolge das Schlüsselwort DSN enthält, kopiert der Treiber-Manager die von der Anwendung angegebene Verbindungszeichenfolge. Andernfalls werden dieselben Aktionen ausgeführt wie beim SQL_DRIVER_PROMPT von DriverCompletion .
SQL_DRIVER_NOPROMPT: Der Treiber-Manager kopiert die von der Anwendung angegebene Verbindungszeichenfolge.
Wenn die von der Anwendung angegebene Verbindungszeichenfolge das Schlüsselwort DRIVER enthält, kopiert der Treiber-Manager die von der Anwendung angegebene Verbindungszeichenfolge.
Mithilfe der erstellten Verbindungszeichenfolge ermittelt der Treiber-Manager, welcher Treiber verwendet werden soll, stellt eine Verbindung mit diesem Treiber bereit und übergibt die erstellte Verbindungszeichenfolge an den Treiber. Weitere Informationen zur Interaktion von Treiber-Manager und Treiber finden Sie im Abschnitt "Kommentare" unter SQLConnect-Funktion. Wenn die Verbindungszeichenfolge nicht das Schlüsselwort DRIVER enthält, bestimmt der Treiber-Manager wie folgt, welcher Treiber verwendet werden soll:
Wenn die Verbindungszeichenfolge das Schlüsselwort DSN enthält, ruft der Treiber-Manager den der Datenquelle zugeordneten Treiber aus den Systeminformationen ab.
Wenn die Verbindungszeichenfolge das DSN-Schlüsselwort nicht enthält oder die Datenquelle nicht gefunden wird, ruft der Treiber-Manager den Treiber ab, der der Standarddatenquelle zugeordnet ist, aus den Systeminformationen. (Weitere Informationen finden Sie unter Standardunterschlüssel.) Der Treiber-Manager ändert den Wert des Schlüsselworts DSN in der Verbindungszeichenfolge in "DEFAULT".
Wenn das DSN-Schlüsselwort in der Verbindungszeichenfolge auf "DEFAULT" festgelegt ist, ruft der Treiber-Manager den Treiber ab, der der Standarddatenquelle aus den Systeminformationen zugeordnet ist.
Wenn die Datenquelle nicht gefunden und die Standarddatenquelle nicht gefunden wird, gibt der Treiber-Manager SQL_ERROR mit SQLSTATE IM002 zurück (Datenquelle nicht gefunden und kein Standardtreiber angegeben).
Dateidatenquellen
Wenn die von der Anwendung im Aufruf von SQLDriverConnect angegebene Verbindungszeichenfolge das Schlüsselwort FILEDSN enthält und dieses Schlüsselwort weder durch das Schlüsselwort DSN noch durch das DRIVER-Schlüsselwort ersetzt wird, erstellt der Treiber-Manager eine Verbindungszeichenfolge unter Verwendung der Informationen in der DSN-Datei und dem Argument InConnectionString . Der Treiber-Manager geht wie folgt vor:
Überprüft, ob der Dateiname der DSN-Datei gültig ist. Andernfalls wird SQL_ERROR mit SQLSTATE IM014 (Ungültiger Name des Datei-DSN) zurückgegeben. Wenn der Dateiname eine leere Zeichenfolge ("") ist und SQL_DRIVER_NOPROMPT nicht angegeben ist, wird das Dialogfeld Datei öffnen angezeigt. Wenn der Dateiname einen gültigen Pfad, aber keinen Dateinamen oder einen ungültigen Dateinamen enthält und SQL_DRIVER_NOPROMPT nicht angegeben ist, wird das Dialogfeld Datei öffnen angezeigt, wobei das aktuelle Verzeichnis auf das im Dateinamen angegebene Verzeichnis festgelegt ist. Wenn der Dateiname eine leere Zeichenfolge ("") ist oder der Dateiname einen gültigen Pfad, aber keinen Dateinamen oder einen ungültigen Dateinamen enthält und SQL_DRIVER_NOPROMPT angegeben ist, wird SQL_ERROR mit SQLSTATE IM014 (Ungültiger Name des Datei-DSN) zurückgegeben.
Liest alle Schlüsselwörter im Abschnitt [ODBC] der DSN-Datei. Wenn das DRIVER-Schlüsselwort nicht vorhanden ist, gibt es SQL_ERROR mit SQLSTATE IM012 (Syntaxfehler des Driver-Schlüsselworts) zurück, außer wenn die DSN-Datei nicht freigegeben werden kann und daher nur das DSN-Schlüsselwort enthält.
Wenn die Dateidatenquelle nicht freigegeben werden kann, liest der Treiber-Manager den Wert des DSN-Schlüsselworts und stellt bei Bedarf eine Verbindung mit der Benutzer- oder Systemdatenquelle her, auf die von der nicht freigegebenen Dateidatenquelle verwiesen wird. Die Schritte 3 bis 5 werden nicht ausgeführt.
Erstellt eine Verbindungszeichenfolge für den Treiber. Die Treiberverbindungszeichenfolge ist die Union der In der DSN-Datei angegebenen Schlüsselwörter und der in der ursprünglichen Anwendungsverbindungszeichenfolge angegebenen Schlüsselwörter. Regeln für die Erstellung der Treiberverbindungszeichenfolge, bei der sich Schlüsselwörter überlappen, sind wie folgt:
Wenn das DRIVER-Schlüsselwort in der Anwendungsverbindungszeichenfolge vorhanden ist und die durch die DRIVER-Schlüsselwörter angegebenen Treiber in der DSN-Datei und der Anwendungsverbindungszeichenfolge nicht identisch sind, werden die Treiberinformationen in der DSN-Datei ignoriert, und die Treiberinformationen in der Anwendungsverbindungszeichenfolge werden verwendet. Wenn die durch das DRIVER-Schlüsselwort angegebenen Treiber in der DSN-Datei und der Verbindungszeichenfolge der Anwendung identisch sind, haben die in der Anwendungsverbindungszeichenfolge angegebenen Schlüsselworte Vorrang vor den in der DSN-Datei angegebenen.
In der neuen Verbindungszeichenfolge wird das Schlüsselwort FILEDSN entfernt.
Lädt den Treiber, indem Sie im Registrierungseintrag HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\<Treibername>\Driver suchen, wobei <Der Treibername> durch das DRIVER-Schlüsselwort angegeben wird.
Übergibt dem Treiber die neue Verbindungszeichenfolge.
Beispiele für DSN-Dateien finden Sie unter Herstellen einer Verbindung mithilfe von Dateidatenquellen.
SAVEFILE-Schlüsselwort
Wenn die von der Anwendung angegebene Verbindungszeichenfolge das Schlüsselwort SAVEFILE enthält, speichert der Treiber-Manager die Verbindungszeichenfolge in einer DSN-Datei. Der Treiber-Manager geht wie folgt vor:
Überprüft, ob der Dateiname der DSN-Datei, die als Attributwert des SAVEFILE-Schlüsselworts enthalten ist, gültig ist. Andernfalls wird SQL_ERROR mit SQLSTATE IM014 (Ungültiger Name des Datei-DSN) zurückgegeben. Die Gültigkeit des Dateinamens wird durch Standardsystembenennungsregeln bestimmt. Wenn der Dateiname eine leere Zeichenfolge ("") ist und das Argument DriverCompletion nicht SQL_DRIVER_NOPROMPT ist, ist der Dateiname gültig. Wenn der Dateiname bereits vorhanden ist, wird die Datei überschrieben, wenn DriverCompletion SQL_DRIVER_NOPROMPT ist. Wenn DriverCompletion SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE oder SQL_DRIVER_COMPLETE_REQUIRED ist, fordert ein Dialogfeld den Benutzer auf, anzugeben, ob die Datei überschrieben werden soll. Wenn Nein eingegeben wird, wird das Dialogfeld Datei-Speichern angezeigt.
Wenn der Treiber SQL_SUCCESS zurückgibt und der Dateiname keine leere Zeichenfolge war, schreibt der Treiber-Manager die im Argument OutConnectionString zurückgegebenen Verbindungsinformationen in die angegebene Datei mit dem Format, das im Abschnitt "Verbindungszeichenfolgen" weiter oben in diesem Abschnitt angegeben wurde.
Wenn der Treiber SQL_SUCCESS zurückgibt und der Dateiname eine leere Zeichenfolge war (""), ruft der Treiber-Manager das Dialogfeld Datei-Speichern gemeinsam mit dem angegebenen hwnd auf und schreibt die in OutConnectionString zurückgegebenen Verbindungsinformationen in die datei, die im File-Save dialogfeld common mit dem format angegeben wurde, das im Abschnitt "Verbindungszeichenfolgen" weiter oben in diesem Abschnitt angegeben ist.
Wenn der Treiber SQL_SUCCESS zurückgibt, gibt er das OutConnectionString-Argument zurück, das die Verbindungszeichenfolge für die Anwendung enthält.
Wenn der Treiber SQL_SUCCESS_WITH_INFO oder SQL_ERROR zurückgibt, gibt der Treiber-Manager sqlSTATE an die Anwendung zurück.
Fahrerrichtlinien
Der Treiber überprüft, ob die vom Treiber-Manager an ihn übergebene Verbindungszeichenfolge das Schlüsselwort DSN oder DRIVER enthält. Wenn die Verbindungszeichenfolge das Schlüsselwort DRIVER enthält, kann der Treiber keine Informationen zur Datenquelle aus den Systeminformationen abrufen. Wenn die Verbindungszeichenfolge das DSN-Schlüsselwort enthält oder weder den DSN noch das Schlüsselwort DRIVER enthält, kann der Treiber Informationen zur Datenquelle wie folgt aus den Systeminformationen abrufen:
Wenn die Verbindungszeichenfolge das Schlüsselwort DSN enthält, ruft der Treiber die Informationen für die angegebene Datenquelle ab.
Wenn die Verbindungszeichenfolge nicht das DSN-Schlüsselwort enthält, die angegebene Datenquelle nicht gefunden wird oder das DSN-Schlüsselwort auf "DEFAULT" festgelegt ist, ruft der Treiber die Informationen für die Standarddatenquelle ab.
Der Treiber verwendet alle Informationen, die er aus den Systeminformationen abruft, um die in der Verbindungszeichenfolge an ihn übergebenen Informationen zu erweitern. Wenn die Informationen in den Systeminformationen Informationen in der Verbindungszeichenfolge duplizieren, verwendet der Treiber die Informationen in der Verbindungszeichenfolge.
Basierend auf dem Wert von DriverCompletion fordert der Treiber den Benutzer zur Eingabe von Verbindungsinformationen, z. B. benutzer-ID und Kennwort, auf und stellt eine Verbindung mit der Datenquelle bereit:
SQL_DRIVER_PROMPT: Der Treiber zeigt ein Dialogfeld an, in dem die Werte aus der Verbindungszeichenfolge und die Systeminformationen (falls vorhanden) als Anfangswerte verwendet werden. Wenn der Benutzer das Dialogfeld beendet, stellt der Treiber eine Verbindung mit der Datenquelle her. Außerdem wird eine Verbindungszeichenfolge aus dem Wert des DSN - oder DRIVER-Schlüsselworts in *InConnectionString und den vom Dialogfeld zurückgegebenen Informationen erstellt. Diese Verbindungszeichenfolge wird im *OutConnectionString-Puffer platziert.
SQL_DRIVER_COMPLETE oder SQL_DRIVER_COMPLETE_REQUIRED: Wenn die Verbindungszeichenfolge genügend Informationen enthält und diese Informationen korrekt sind, stellt der Treiber eine Verbindung mit der Datenquelle her und kopiert *InConnectionString in *OutConnectionString. Wenn Informationen fehlen oder falsch sind, führt der Treiber die gleichen Aktionen wie beim SQL_DRIVER_PROMPT DriverCompletion aus. Wenn DriverCompletion SQL_DRIVER_COMPLETE_REQUIRED ist, deaktiviert der Treiber die Steuerelemente für alle Informationen, die nicht zum Herstellen einer Verbindung mit der Datenquelle erforderlich sind.
SQL_DRIVER_NOPROMPT: Wenn die Verbindungszeichenfolge genügend Informationen enthält, stellt der Treiber eine Verbindung mit der Datenquelle her und kopiert *InConnectionString nach *OutConnectionString. Andernfalls gibt der Treiber SQL_ERROR für SQLDriverConnect zurück.
Bei erfolgreicher Verbindung mit der Datenquelle legt der Treiber *StringLength2Ptr auch auf die Länge der Ausgabeverbindungszeichenfolge fest, die in *OutConnectionString zurückgegeben werden kann.
Wenn der Benutzer ein vom Treiber-Manager oder treiber angezeigtes Dialogfeld abbricht, gibt SQLDriverConnect SQL_NO_DATA zurück.
Informationen dazu, wie der Treiber-Manager und der Treiber während des Verbindungsvorgangs interagieren, finden Sie unter SQLConnect-Funktion.
Wenn ein Treiber SQLDriverConnect unterstützt, muss der Treiberschlüsselwortabschnitt der Systeminformationen für den Treiber das Schlüsselwort ConnectFunctions enthalten, wobei das zweite Zeichen auf "Y" festgelegt ist.
Herstellen einer Verbindung, wenn verbindungspooling aktiviert ist
Verbindungspooling ermöglicht es einer Anwendung, eine bereits erstellte Verbindung wiederzuverwenden. Wenn SQLDriverConnect aufgerufen wird, versucht der Treiber-Manager, die Verbindung mithilfe einer Verbindung herzustellen, die Teil eines Verbindungspools in einer Umgebung ist, die für verbindungspooling festgelegt wurde. Weitere Informationen zum Verbindungspooling finden Sie unter SQLConnect-Funktion.
Eine Anwendung kann SQL_ATTR_RESET_CONNECTION festlegen, bevor SQLDisconnect für eine Verbindung aufgerufen wird, bei der das Pooling aktiviert ist. Weitere Informationen finden Sie unter SQLSetConnectAttr-Funktion.
Die folgenden Einschränkungen gelten, wenn eine Anwendung SQLDriverConnect aufruft, um eine Verbindung mit einer Gepoolverbindung herzustellen:
Wenn das SaveFILE-Schlüsselwort in der Verbindungszeichenfolge angegeben ist, wird keine Verbindungspoolverarbeitung ausgeführt.
Wenn verbindungspooling aktiviert ist, kann SQLDriverConnect nur mit dem DriverCompletion-Argument SQL_DRIVER_NOPROMPT aufgerufen werden. Wenn SQLDriverConnect mit einer anderen DriverCompletion aufgerufen wird, wird SQLSTATE HY110 (ungültiger Treiberabschluss) zurückgegeben.
Verbindungsattribute
Das SQL_ATTR_LOGIN_TIMEOUT-Verbindungsattribut, das mithilfe von SQLSetConnectAttr festgelegt wird, definiert die Anzahl von Sekunden, die auf den Abschluss einer Anmeldeanforderung mit einer erfolgreichen Verbindung durch den Treiber gewartet werden muss, bevor sie zur Anwendung zurückkehren. Wenn der Benutzer aufgefordert wird, die Verbindungszeichenfolge abzuschließen, beginnt eine Wartezeit für jede Anmeldeanforderung, wenn der Treiber den Verbindungsvorgang startet.
Der Treiber öffnet die Verbindung standardmäßig im zugriffsmodus SQL_MODE_READ_WRITE. Um den Zugriffsmodus auf SQL_MODE_READ_ONLY festzulegen, muss die Anwendung SQLSetConnectAttr mit dem attribut SQL_ATTR_ACCESS_MODE aufrufen, bevor SQLDriverConnect aufgerufen wird.
Wenn in den Systeminformationen für die Datenquelle eine Standardübersetzungsbibliothek angegeben ist, lädt der Treiber sie. Eine andere Übersetzungsbibliothek kann geladen werden, indem SQLSetConnectAttr mit dem attribut SQL_ATTR_TRANSLATE_LIB aufgerufen wird. Eine Übersetzungsoption kann durch Aufrufen von SQLSetConnectAttr mit der Option SQL_ATTR_TRANSLATE_OPTION angegeben werden.
Weitere Informationen finden Sie unter Herstellen einer Verbindung mit SQLDriverConnect.
// SQLDriverConnect_ref.cpp
// compile with: odbc32.lib user32.lib
#include <windows.h>
#include <sqlext.h>
int main() {
SQLHENV henv;
SQLHDBC hdbc;
SQLHSTMT hstmt;
SQLRETURN retcode;
SQLCHAR OutConnStr[255];
SQLSMALLINT OutConnStrLen;
HWND desktopHandle = GetDesktopWindow(); // desktop's window handle
// Allocate environment handle
retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
// Set the ODBC version environment attribute
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);
// Allocate connection handle
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);
// Set login timeout to 5 seconds
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);
retcode = SQLDriverConnect( // SQL_NULL_HDBC
hdbc,
desktopHandle,
(SQLCHAR*)"driver=SQL Server",
_countof("driver=SQL Server"),
OutConnStr,
255,
&OutConnStrLen,
SQL_DRIVER_PROMPT );
// Allocate statement handle
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
// Process data
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
SQLFreeHandle(SQL_HANDLE_STMT, hstmt);
}
SQLDisconnect(hdbc);
}
SQLFreeHandle(SQL_HANDLE_DBC, hdbc);
}
}
SQLFreeHandle(SQL_HANDLE_ENV, henv);
}
}
Siehe auch Beispiel-ODBC-Programm.
Verwandte Funktionen
| Informationen über | Finden Sie unter |
|---|---|
| Zuweisen eines Handles | SQLAllocHandle-Funktion |
| Ermitteln und Aufzählen von Werten, die zum Herstellen einer Verbindung mit einer Datenquelle erforderlich sind | SQLBrowseConnect-Funktion |
| Aufbauen der Verbindung zu einer Datenquelle | SQLConnect-Funktion |
| Trennen einer Datenquelle | SQLDisconnect-Funktion |
| Zurückgeben von Treiberbeschreibungen und Attributen | SQLDrivers-Funktion |
| Freigeben eines Handles | SQLFreeHandle-Funktion |
| Festlegen eines Verbindungsattributes | SQLSetConnectAttr-Funktion |