Freigeben über

SQLCreateDataSource-Funktion

  • Artikel

Konformität
Eingeführte Version: ODBC 2.0

Zusammenfassung
SQLCreateDataSource zeigt ein Dialogfeld an, mit dem der Benutzer eine Datenquelle hinzufügen kann.

Syntax

  
BOOL SQLCreateDataSource(  
     HWND    hwnd,  
     LPSTR   lpszDS);

Argumente

hwnd
[Eingabe] Handle des übergeordneten Fensters.

lpszDS
[Eingabe] Datenquellenname. lpszDS kann ein NULL-Zeiger oder eine leere Zeichenfolge sein.

Gibt zurück

SQLCreateDataSource gibt TRUE zurück, wenn die Datenquelle erstellt wird. Andernfalls wird FALSE zurückgegeben.

Diagnose

Wenn SQLCreateDataSource FALSE zurückgibt, kann durch Aufrufen von SQLInstallerError ein zugeordneter *pfErrorCode-Wert abgerufen werden. In der folgenden Tabelle sind die *pfErrorCode-Werte aufgeführt, die von SQLInstallerError zurückgegeben werden können, und erläutert die einzelnen Werte im Kontext dieser Funktion.

*pfErrorCode Fehler BESCHREIBUNG
ODBC_ERROR_GENERAL_ERR Allgemeiner Installationsfehler Es ist ein Fehler aufgetreten, für den kein spezifischer Installationsfehler aufgetreten ist.
ODBC_ERROR_INVALID_HWND Ungültiges Fensterhandle Das Argument hwnd war ungültig oder NULL.
ODBC_ERROR_INVALID_DSN Ungültiger DSN Das lpszDS-Argument enthielt eine Zeichenfolge, die für einen DSN ungültig war.
ODBC_ERROR_REQUEST_FAILED Fehler bei der Anforderung Fehler beim Aufruf von ConfigDSN mit der Option ODBC_ADD_DSN.
ODBC_ERROR_LOAD_LIBRARY_FAILED Die Setupbibliothek für Treiber oder Übersetzer konnte nicht geladen werden. Die Setupbibliothek des Treibers konnte nicht geladen werden.
ODBC_ERROR_USER_CANCELED Vom Benutzer abgebrochener Vorgang Der Benutzer hat die Erstellung einer neuen Datenquelle abgebrochen.
ODBC_ERROR_CREATE_DSN_FAILED Der angeforderte DSN konnte nicht erstellt werden. Es konnte keine Verbindung mit der Datenbank hergestellt werden. Der Aufruf von SQLDriverConnect für einen Datei-DSN hat keine erfolgreiche Verbindung zurückgegeben.

In die Datei konnte nicht geschrieben werden.
ODBC_ERROR_OUT_OF_MEM Nicht genügend Arbeitsspeicher. Das Installationsprogramm konnte die Funktion aufgrund eines Mangels an Arbeitsspeicher nicht ausführen.

Kommentare

Wenn hwnd NULL ist, gibt SQLCreateDataSource FALSE zurück. Andernfalls wird das Dialogfeld Neue Datenquelle erstellen mit einer Assistentenseite zum Auswählen des Typs der einzurichtenden Datenquelle angezeigt, wie in der folgenden Abbildung dargestellt.

Dialogfeld "

Die Standardoption ist Dateidatenquelle. Wenn eine Datenquelle ausgewählt wurde und auf Weiter geklickt wurde, wird die folgende Assistentenseite angezeigt, die eine Liste der installierten Treiber enthält.

Dialogfeld

Wenn auf Abbrechen geklickt wird, wird das Dialogfeld ausgeblendet, und SQLCreateDataSource gibt FALSE mit dem Fehlercode ODBC_ERROR_USER_CANCELED zurück. Wenn entweder die Option Benutzerdatenquelle oder Systemdatenquelle ausgewählt wurde, ist die Schaltfläche Erweitert nicht verfügbar.

Wenn auf die Schaltfläche Weiter geklickt wird, tritt eine der folgenden Aktionen auf, je nachdem, welcher Typ von Datenquelle ausgewählt wurde:

  • Wenn Dateidatenquelle ausgewählt wurde, wird eine Assistentenseite angezeigt, auf der der Benutzer einen Dateinamen eingeben kann.

  • Wenn entweder Benutzerdatenquelle oder Systemdatenquelle ausgewählt wurde, wird eine Assistentenseite mit dem Typ der Datenquelle und des Treibers zur Überprüfung angezeigt, und wenn auf Fertig stellen geklickt wird, wird die Datenquelle eingerichtet.

Wenn auf der Assistentenseite "Neue Datenquelle erstellen" auf Erweitert geklickt wird, wird eine Assistentenseite angezeigt, auf der der Benutzer treiberspezifische Informationen eingeben kann. Geben Sie im Textfeld dieses Dialogfelds den Treiber und die Schlüsselwörter getrennt durch Rückgaben ein, wie in der folgenden Abbildung gezeigt.

Dialogfeld

Weitere treiberspezifische Schlüsselwörter finden Sie unter der Beschreibung von SQLDriverConnect. Alle außer DSN sind zulässig.

Der Standardwert für die Option Diese Verbindung überprüfen ist TRUE. Diese Standardeinstellung gilt unabhängig davon, ob diese Assistentenseite aktiviert ist. Wenn auf OK geklickt wird, werden die im Textfeld angegebene Zeichenfolge und der Wert der Option Diese Verbindung überprüfen zwischengespeichert. (Wenn auf die Schaltfläche Schließen oder Abbrechen geklickt wird, gehen alle neu eingegebenen treiberspezifischen Informationen verloren, da die im Textfeld angegebene Zeichenfolge und der Wert der Option "Diese Verbindung überprüfen " nicht zwischengespeichert werden.)

Wenn Dateidatenquelle auf der ersten Seite des Assistenten ausgewählt wurde, wird der Benutzer aufgefordert, einen Dateinamen einzugeben, nachdem ein Treiber ausgewählt und die Schlüsselwortwerte auf der Seite Erweitert eingegeben wurden. Klicken Sie auf Durchsuchen , um nach einem Dateinamen zu suchen. In diesem Fall wird das Standardverzeichnis im Feld Durchsuchen durch eine Kombination des Pfads angegeben, der von CommonFileDir in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion und "ODBC\DataSources" angegeben wird. (Wenn CommonFileDir "C:\Programme\Common Files" wäre, lautet das Standardverzeichnis "C:\Programme\Common Files\ODBC\Data Sources".)

Wenn ein Dateiname eingegeben und auf Weiter geklickt wird, wird der eingegebene Dateiname anhand der Standarddateinamensregeln des Betriebssystems auf Gültigkeit überprüft. Wenn der Dateiname ungültig ist, benachrichtigt ein Fehlermeldungsfeld den Benutzer, dass ein ungültiger Dateiname eingegeben wurde. Nachdem der Benutzer das Meldungsfeld bestätigt hat, wird der Fokus auf die Seite des Assistenten zurückgegeben, auf der der Dateiname eingegeben wird. Wenn der Dateiname gültig ist, wird eine Assistentenseite mit den ausgewählten Schlüsselwort-Wert-Paaren zur Überprüfung angezeigt, wie in der folgenden Abbildung gezeigt.

Dialogfeld

Wenn auf Fertig stellen geklickt wird und Dateidatenquelle als Datenquellentyp ausgewählt wurde, und wenn die Option Diese Verbindung überprüfen auf TRUE festgelegt ist, wird SQLDriverConnect mit den Schlüsselwörtern SAVEFILE und DRIVER aufgerufen. Das Argument DriverCompletion ist auf SQL_DRIVER_COMPLETE festgelegt. Der Dateiname für das SAVEFILE-Schlüsselwort ist der Name, der eingegeben oder ausgewählt wurde, und der Treibername für das DRIVER-Schlüsselwort ist der name, der ausgewählt wurde. Wenn auf der Seite erweiterter Assistent eine treiberspezifische Verbindungszeichenfolge angegeben wurde, wird diese Zeichenfolge nach dem DRIVER-Schlüsselwort angefügt.

Wenn SQLDriverConnect SQL_SUCCESS zurückgibt, hat der Treiber-Manager den Datei-DSN erstellt. SQLCreateDataSource gibt TRUE zurück. Wenn SQLDriverConnect nicht SQL_SUCCESS zurückgibt, gibt ein Warnmeldungsfeld an, dass keine Verbindung mit der Datenquelle hergestellt werden konnte. Ein DSN mit minimalen Verbindungsinformationen kann weiterhin erstellt werden. In diesem Meldungsfeld kann der Benutzer die Erstellung des Datei-DSN abbrechen oder fortsetzen.

Wenn der Benutzer die Erstellung des DSN fortsetzen möchte, wird dieser Prozess fortgesetzt, als ob die Option Diese Verbindung überprüfen auf FALSE festgelegt wäre. Wenn der Benutzer sich für den Abbruch entscheidet, wird FALSE für SQLCreateDataSource mit dem Fehlercode ODBC_ERROR_CREATE_DSN_FAILED zurückgegeben.

Wenn Dateidatenquelle als Datenquellentyp ausgewählt wurde und die Option Diese Verbindung überprüfen auf FALSE festgelegt ist, wird auf der Seite Erweiterter Assistent ein Datei-DSN mit dem SCHLÜSSELwort DRIVER und der vom Benutzer angegebenen Verbindungszeichenfolge (sofern vorhanden) erstellt. Wenn die Dateierstellung erfolgreich war, wird TRUE für SQLCreateDataSource zurückgegeben. Wenn die Dateierstellung nicht erfolgreich war, benachrichtigt ein Fehlermeldungsfeld den Benutzer mit dem vom Betriebssystem zurückgegebenen Fehler. FALSE wird für SQLCreateDataSource mit dem Fehlercode ODBC_ERROR_CREATE_DSN_FAILED zurückgegeben. Weitere Informationen zu Dateidatenquellen finden Sie unter Herstellen einer Verbindung mithilfe von Dateidatenquellen oder unter SQLDriverConnect.

Wenn Benutzer - oder Systemdatenquelle als Datenquellentyp ausgewählt wurde, wird ConfigDSN in der Treibereinrichtungsbibliothek mit dem ODBC_ADD_DSN fRequest aufgerufen. Weitere Informationen finden Sie unter ConfigDSN.

Informationen über Finden Sie unter
Verwalten von Datenquellen SQLManageDataSources