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.

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.

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".)

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:

1. Wenn die Verbindungszeichenfolge das Schlüsselwort DSN enthält, ruft der Treiber-Manager den der Datenquelle zugeordneten Treiber aus den Systeminformationen ab.

2. 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".

3. 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.

4. 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:

1. Ü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.

2. 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.

3. 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.

4. 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.

5. Ü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:

1. Ü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.

2. 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.

3. 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.

4. Wenn der Treiber SQL_SUCCESS zurückgibt, gibt er das OutConnectionString-Argument zurück, das die Verbindungszeichenfolge für die Anwendung enthält.

5. 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:

1. Wenn die Verbindungszeichenfolge das Schlüsselwort DSN enthält, ruft der Treiber die Informationen für die angegebene Datenquelle ab.

2. 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

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien