ConfigDSN-Funktion

  • Artikel

Konformität
Version eingeführt: ODBC 1.0

Zusammenfassung
ConfigDSN fügt Datenquellen aus den Systeminformationen hinzu, ändert oder löscht sie. Der Benutzer wird möglicherweise zur Eingabe von Verbindungsinformationen aufgefordert. Dies kann sich in der Treiber-DLL oder in einer separaten Setup-DLL befinden.

Syntax

  
BOOL ConfigDSN(  
     HWND     hwndParent,  
     WORD     fRequest,  
     LPCSTR   lpszDriver,  
     LPCSTR   lpszAttributes);

Argumente

hwndParent
[Eingabe] Übergeordnetes Fensterhandle. Die Funktion zeigt keine Dialogfelder an, wenn das Handle NULL ist.

fRequest
[Eingabe] Anforderungstyp. Das Argument fRequest muss einen der folgenden Werte enthalten:

ODBC_ADD_DSN: Fügen Sie eine neue Datenquelle hinzu.

ODBC_CONFIG_DSN: Konfigurieren (Ändern) einer vorhandenen Datenquelle.

ODBC_REMOVE_DSN: Entfernen Sie eine vorhandene Datenquelle.

lpszDriver
[Eingabe] Treiberbeschreibung (in der Regel der Name des zugeordneten DBMS), der benutzern anstelle des physischen Treibernamens angezeigt wird.

lpszAttributes
[Eingabe] Eine doppelt mit NULL beendete Liste von Attributen in Form von Schlüsselwort-Wert-Paaren. Weitere Informationen finden Sie unter Kommentare.

Gibt zurück

Die Funktion gibt TRUE zurück, wenn sie erfolgreich ist, FALSE, wenn sie fehlschlägt.

Diagnose

Wenn ConfigDSN FALSE zurückgibt, wird ein zugeordneter *pfErrorCode-Wert durch einen Aufruf von SQLPostInstallerError an den Installerfehlerpuffer gesendet und kann durch aufrufen von SQLInstallerError abgerufen werden. In der folgenden Tabelle sind die *pfErrorCode-Werte aufgeführt, die von SQLInstallerError zurückgegeben werden können, und die einzelnen Werte im Kontext dieser Funktion werden erläutert.

*pfErrorCode Fehler BESCHREIBUNG
ODBC_ERROR_INVALID_HWND Ungültiges Fensterhandle Das Argument hwndParent war ungültig.
ODBC_ERROR_INVALID_KEYWORD_VALUE Ungültige Schlüsselwort-Wert-Paare Das lpszAttributes-Argument enthielt einen Syntaxfehler.
ODBC_ERROR_INVALID_NAME Ungültiger Treiber- oder Übersetzername Das argument lpszDriver war ungültig. Es konnte nicht in der Registrierung gefunden werden.
ODBC_ERROR_INVALID_REQUEST_TYPE Ungültiger Anforderungstyp Das fRequest-Argument war nicht eines der folgenden:

ODBC_ADD_DSN ODBC_CONFIG_DSN ODBC_REMOVE_DSN
ODBC_ERROR_REQUEST_FAILED Fehler bei der Anforderung Der vom Argument fRequest angeforderte Vorgang konnte nicht ausgeführt werden.
ODBC_ERROR_DRIVER_SPECIFIC Treiber- oder Übersetzer-spezifischer Fehler Ein treiberspezifischer Fehler, für den kein definierter ODBC-Installerfehler vorliegt. Das SzError-Argument in einem Aufruf der SQLPostInstallerError-Funktion sollte die treiberspezifische Fehlermeldung enthalten.

Kommentare

ConfigDSN empfängt Verbindungsinformationen von der Installer-DLL als Liste von Attributen in Form von Schlüsselwort-Wert-Paaren. Jedes Paar wird mit einem NULL-Byte beendet, und die gesamte Liste wird mit einem NULL-Byte beendet. (Das heißt, zwei NULL-Bytes markieren das Ende der Liste.) Leerzeichen sind um das Gleichheitszeichen im Schlüsselwort-Wert-Paar nicht zulässig. ConfigDSN kann Schlüsselwörter akzeptieren, die keine gültigen Schlüsselwörter für SQLBrowseConnect und SQLDriverConnect sind. ConfigDSN unterstützt nicht unbedingt alle Schlüsselwörter, die gültige Schlüsselwörter für SQLBrowseConnect und SQLDriverConnect sind. (ConfigDSN akzeptiert das DRIVER-Schlüsselwort nicht.) Die von der ConfigDSN-Funktion verwendeten Schlüsselwörter müssen alle Optionen unterstützen, die zum erneuten Erstellen der Datenquelle mithilfe der Auto-Setup-Funktion des Installers erforderlich sind. Wenn die Verwendungen der ConfigDSN-Werte und der Verbindungszeichenfolgenwerte identisch sind, sollten dieselben Schlüsselwörter verwendet werden.

Wie in SQLBrowseConnect und SQLDriverConnect sollten die Schlüsselwörter und ihre Werte nicht []{}(),;? enthalten. *=!@ Zeichen, und der Wert des DSN-Schlüsselworts darf nicht nur aus Leerzeichen bestehen. Aufgrund der Registrierungsgrammatik dürfen Schlüsselwörter und Datenquellennamen den umgekehrten Schrägstrich (\) nicht enthalten.

ConfigDSN sollte SQLValidDSN aufrufen, um die Länge des Datenquellennamens zu überprüfen und zu überprüfen, ob im Namen keine ungültigen Zeichen enthalten sind. Wenn der Datenquellenname länger als SQL_MAX_DSN_LENGTH ist oder ungültige Zeichen enthält, gibt SQLValidDSN einen Fehler und ConfigDSN einen Fehler zurück. Die Länge des Datenquellennamens wird auch von SQLWriteDSNToIni überprüft.

Um beispielsweise eine Datenquelle zu konfigurieren, die eine Benutzer-ID, ein Kennwort und einen Datenbanknamen erfordert, kann eine Setupanwendung die folgenden Schlüsselwort-Wert-Paare übergeben:

DSN=Personnel Data\0UID=Smith\0PWD=Sesame\0DATABASE=Personnel\0\0

Weitere Informationen zu diesen Schlüsselwörtern finden Sie unter SQLDriverConnect und in der Dokumentation zu den einzelnen Treibern.

Um ein Dialogfeld anzuzeigen, darf hwndParent nicht NULL sein.

Hinzufügen von Datenquellen

Wenn ein Datenquellenname in lpszAttributes an ConfigDSN übergeben wird, überprüft ConfigDSN, ob der Name gültig ist. Wenn der Datenquellenname mit einem vorhandenen Datenquellennamen übereinstimmt und hwndParent NULL ist, überschreibt ConfigDSN den vorhandenen Namen. Wenn es mit einem vorhandenen Namen übereinstimmt und hwndParent nicht NULL ist, fordert ConfigDSN den Benutzer auf, den vorhandenen Namen zu überschreiben.

Wenn lpszAttributes genügend Informationen zum Herstellen einer Verbindung mit einer Datenquelle enthält, kann ConfigDSN die Datenquelle hinzufügen oder ein Dialogfeld anzeigen, mit dem der Benutzer die Verbindungsinformationen ändern kann. Wenn lpszAttributes nicht genügend Informationen zum Herstellen einer Verbindung mit einer Datenquelle enthält, muss ConfigDSN die erforderlichen Informationen ermitteln. wenn hwndParent nicht NULL ist, wird ein Dialogfeld zum Abrufen der Informationen vom Benutzer angezeigt.

Wenn ConfigDSN ein Dialogfeld anzeigt, müssen alle Verbindungsinformationen angezeigt werden, die an ihn in lpszAttributes übergeben werden. Insbesondere wenn ein Datenquellenname an sie übergeben wurde, zeigt ConfigDSN diesen Namen an, erlaubt dem Benutzer jedoch nicht, ihn zu ändern. ConfigDSN kann Standardwerte für Verbindungsinformationen bereitstellen, die in lpszAttributes nicht an sie übergeben werden.

Wenn ConfigDSN keine vollständigen Verbindungsinformationen für eine Datenquelle abrufen kann, wird FALSE zurückgegeben.

Wenn ConfigDSN vollständige Verbindungsinformationen für eine Datenquelle abrufen kann, ruft es SQLWriteDSNToIni in der Installer-DLL auf, um die neue Datenquellenspezifikation der Odbc.ini-Datei (oder Registrierung) hinzuzufügen. SQLWriteDSNToIni fügt dem Abschnitt [ODBC-Datenquellen] den Datenquellennamen hinzu, erstellt den Abschnitt zur Datenquellenspezifikation und fügt das SCHLÜSSELWORT DRIVER mit der Treiberbeschreibung als Wert hinzu. ConfigDSN ruft SQLWritePrivateProfileString in der Installer-DLL auf, um alle zusätzlichen Schlüsselwörter und Werte hinzuzufügen, die vom Treiber verwendet werden.

Ändern einer Datenquelle

Um eine Datenquelle zu ändern, muss ein Datenquellenname in lpszAttributes an ConfigDSN übergeben werden. ConfigDSN überprüft, ob sich der Name der Datenquelle in der Odbc.ini Datei (oder Registrierung) befindet.

Wenn hwndParent NULL ist, verwendet ConfigDSN die Informationen in lpszAttributes , um die Informationen in der Odbc.ini-Datei (oder registrierung) zu ändern. Wenn hwndParent nicht NULL ist, zeigt ConfigDSN ein Dialogfeld mit den Informationen in lpszAttributes an. Für Informationen, die nicht in lpszAttributes enthalten sind, werden Informationen aus den Systeminformationen verwendet. Der Benutzer kann die Informationen ändern , bevor ConfigDSN sie in den Systeminformationen speichert.

Wenn der Datenquellenname geändert wurde, ruft ConfigDSN zuerst SQLRemoveDSNFromIni in der Installer-DLL auf, um die vorhandene Datenquellenspezifikation aus der Odbc.ini-Datei (oder Registrierung) zu entfernen. Anschließend werden die Schritte im vorherigen Abschnitt ausgeführt, um die neue Datenquellenspezifikation hinzuzufügen. Wenn der Name der Datenquelle nicht geändert wurde, ruft ConfigDSNSQLWritePrivateProfileString in der Installer-DLL auf, um weitere Änderungen vorzunehmen. ConfigDSN darf den Wert des Schlüsselworts Driver nicht löschen oder ändern.

Löschen einer Datenquelle

Zum Löschen einer Datenquelle muss ein Datenquellenname an ConfigDSN in lpszAttributes übergeben werden. ConfigDSN überprüft, ob sich der Name der Datenquelle in der Odbc.ini Datei (oder Registrierung) befindet. Anschließend wird SQLRemoveDSNFromIni in der Installer-DLL aufgerufen, um die Datenquelle zu entfernen.

Hinweis

Wenn Sie eine Unicode-Version dieser Routine schreiben, muss sie ConfigDSNW mit LPCWSTR-Argumenten anstelle von LPCSTR heißen.

Informationen über Finden Sie unter
Hinzufügen, Ändern oder Entfernen einer Datenquelle SQLConfigDataSource
Abrufen eines Werts aus der Odbc.ini-Datei oder der Registrierung SQLGetPrivateProfileString
Entfernen der Standarddatenquelle SQLRemoveDefaultDataSource
Entfernen eines Datenquellennamens aus Odbc.ini (oder Registrierung) SQLRemoveDSNFromIni
Hinzufügen eines Datenquellennamens zu Odbc.ini (oder Registrierung) SQLWriteDSNToIni
Schreiben eines Werts in die Odbc.ini-Datei oder die Registrierung SQLWritePrivateProfileString