SQLInstallDriverEx-Funktion

Konformität
Version eingeführt: ODBC 3.0

Zusammenfassung
SQLInstallDriverEx fügt informationen zum Treiber zum Odbcinst.ini Eintrag in den Systeminformationen hinzu und erhöht das UsageCount des Treibers um 1. Wenn jedoch bereits eine Version des Treibers vorhanden ist, der UsageCount-Wert für den Treiber nicht vorhanden ist, wird der neue UsageCount-Wert auf 2 festgelegt.

Mit dieser Funktion werden keine Dateien kopiert. Es liegt in der Verantwortung des aufrufenden Programms, die Dateien der Treiber ordnungsgemäß in das Zielverzeichnis zu kopieren.

Auf die Funktionalität von SQLInstallDriverEx kann auch mit ODBCCONF.EXE zugegriffen werden.

Syntax

  
BOOL SQLInstallDriverEx(  
     LPCSTR    lpszDriver,  
     LPCSTR    lpszPathIn,  
     LPSTR     lpszPathOut,  
     WORD      cbPathOutMax,  
     WORD *    pcbPathOut,  
     WORD      fRequest,  
     LPDWORD   lpdwUsageCount);  

Argumente

lpszDriver
[Eingabe] Die Treiberbeschreibung (in der Regel der Name des zugeordneten DBMS) wird Benutzern anstelle des physischen Treibernamens angezeigt. Das lpszDriver-Argument muss eine doubly null-terminated-Liste von Schlüsselwort-Wert-Paaren enthalten, die den Treiber beschreiben. Weitere Informationen zu Schlüsselwort-Wert-Paaren finden Sie unter Driver Specification Subkeys. Weitere Informationen zur doubly null-terminated-Zeichenfolge finden Sie unter ConfigDSN-Funktion.

lpszPathIn
[Eingabe] Vollständiger Pfad des Zielverzeichnisses der Installation oder eines NULL-Zeigers. Wenn lpszPathIn ein NULL-Zeiger ist, werden die Treiber im Systemverzeichnis installiert.

lpszPathOut
[Ausgabe] Pfad des Zielverzeichnisses, in dem der Treiber installiert werden soll. Wenn der Treiber noch nicht installiert wurde, sollte lpszPathOut mit lpszPathIn identisch sein. Wenn der Treiber zuvor installiert wurde, ist lpszPathOut der Pfad der vorherigen Installation.

cbPathOutMax
[Eingabe] Länge von lpszPathOut.

pcbPathOut
[Ausgabe] Gesamtanzahl der Bytes (mit Ausnahme des Null-Beendigungszeichens), die in lpszPathOut zurückgegeben werden können. Wenn die Anzahl der zurückzugebenden Bytes größer oder gleich cbPathOutMax ist, wird der Ausgabepfad in lpszPathOutOut abgeschnitten zu cbPathOutMax minus dem Nullendpunktzeichen. Das PcbPathOut-Argument kann ein Nullzeiger sein.

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

ODBC_INSTALL_INQUIRY: Fragen Sie, wo ein Treiber installiert werden kann.

ODBC_INSTALL_COMPLETE: Schließen Sie die Installationsanforderung ab.

lpdwUsageCount
[Ausgabe] Die Verwendungsanzahl des Treibers, nachdem diese Funktion aufgerufen wurde.

Anwendungen sollten den Verwendungszähler nicht festlegen. Dieser Zähler wird von ODBC geführt.

Gibt zurück

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

Diagnostik

Wenn SQLInstallDriverEx FALSE zurückgibt, kann ein zugeordneter *pfErrorCode-Wert 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 erläutert die einzelnen Werte im Kontext dieser Funktion.

*pfErrorCode	Error	Beschreibung
ODBC_ERROR_GENERAL_ERR	Allgemeiner Installationsfehler	Es ist ein Fehler aufgetreten, für den kein bestimmter Installationsfehler aufgetreten ist.
ODBC_ERROR_INVALID_BUFF_LEN	Ungültige Pufferlänge	Das lpszPathOut-Argument war nicht groß genug, um den Ausgabepfad zu enthalten. Der Puffer enthält den abgeschnittenen Pfad. Das cbPathOutMax-Argument war 0, und fRequest wurde ODBC_INSTALL_COMPLETE.
ODBC_ERROR_INVALID_REQUEST_TYPE	Ungültiger Anforderungstyp	Das Argument "fRequest " war nicht einer der folgenden: ODBC_INSTALL_INQUIRY ODBC_INSTALL_COMPLETE
ODBC_ERROR_INVALID_KEYWORD_VALUE	Ungültige Schlüsselwort-Wert-Paare	Das lpszDriver-Argument enthielt einen Syntaxfehler.
ODBC_ERROR_INVALID_PATH	Ungültiger Installationspfad	Das lpszPathIn-Argument enthielt einen ungültigen Pfad.
ODBC_ERROR_LOAD_LIBRARY_FAILED	Die Setupbibliothek für Treiber oder Übersetzer konnte nicht geladen werden.	Die Treibersetupbibliothek konnte nicht geladen werden.
ODBC_ERROR_INVALID_PARAM_SEQUENCE	Ungültige Parametersequenz	Das lpszDriver-Argument enthielt keine Liste von Schlüsselwort-Wert-Paaren.
ODBC_ERROR_USAGE_UPDATE_FAILED	Die Anzahl der Komponentennutzung konnte nicht erhöht oder verringert werden.	Das Installationsprogramm konnte die Anzahl der Treibernutzung nicht erhöhen.

Kommentare

Das lpszDriver-Argument ist eine 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 Nullbytes markieren das Ende der Liste.) Das Format dieser Liste lautet wie folgt:

driver-desc\ 0Driver=driver-DLL-filename\0[Setup-DLL-filename=\0]

[driver-attr-keyword1 value1\=0][driver-attr-keyword2 value2=\0]...\0

Dabei ist \0 ein NULL-Byte und ein Treiber-Attr-Schlüsselwort ein beliebiges Treiberattribute-Schlüsselwort. Die Schlüsselwörter müssen in der angegebenen Reihenfolge angezeigt werden. Angenommen, ein Treiber für formatierte Textdateien verfügt über separate Treiber- und Setup-DLLs und kann Dateien mit den Erweiterungen .txt und .csv verwenden. Das lpszDriver-Argument für diesen Treiber kann wie folgt aussehen:

Text\0Driver=TEXT.DLL\0Setup=TXTSETUP.DLL\0FileUsage=1\0  
FileExtns=*.txt,*.csv\0\0  

Angenommen, ein Treiber für SQL Server verfügt nicht über eine separate Setup-DLL und verfügt nicht über Treiberattributestichwörter. Das lpszDriver-Argument für diesen Treiber kann wie folgt aussehen:

SQL Server\0Driver=SQLSRVR.DLL\0\0  

Nachdem SQLInstallDriverEx Informationen über den Treiber aus dem lpszDriver-Argument abgerufen hat, wird die Treiberbeschreibung dem Abschnitt [ODBC Drivers] des Odbcinst.ini Eintrags in den Systeminformationen hinzugefügt. Anschließend wird ein Abschnitt mit der Beschreibung des Treibers erstellt und die vollständigen Pfade der Treiber-DLL und der Setup-DLL hinzugefügt. Schließlich wird der Pfad des Zielverzeichnisses der Installation zurückgegeben, aber die Treiberdateien werden nicht kopiert. Das aufrufende Programm muss die Treiberdateien tatsächlich in das Zielverzeichnis kopieren.

SQLInstallDriverEx erhöht die Anzahl der Komponentennutzung für den installierten Treiber um 1. Wenn bereits eine Version des Treibers vorhanden ist, die Komponentenverwendungsanzahl für den Treiber jedoch nicht vorhanden ist, wird der neue Wert für die Komponentenverwendung auf 2 festgelegt.

Das Anwendungssetupprogramm ist für das physische Kopieren der Treiberdatei und die Aufrechterhaltung der Anzahl der Dateinutzungen verantwortlich. Wenn die Treiberdatei noch nicht installiert wurde, muss das Anwendungssetupprogramm die Datei im lpszPathIn-Pfad kopieren und die Anzahl der Dateinutzung erstellen. Wenn die Datei zuvor installiert wurde, erhöht das Setupprogramm lediglich die Anzahl der Dateiverwendungen und gibt den Pfad der vorherigen Installation im lpszPathOut-Argument zurück.

Hinweis

Weitere Informationen zur Anzahl der Komponentennutzung und zur Anzahl der Dateinutzung finden Sie unter Verwendungszählung.

Wenn eine ältere Version der Treiberdatei zuvor von der Anwendung installiert wurde, sollte der Treiber deinstalliert und dann erneut installiert werden, damit die Anzahl der Treiberkomponenten gültig ist. SQLConfigDriver (mit einer fRequest von ODBC_REMOVE_DRIVER) sollte zuerst aufgerufen werden, und dann sollte SQLRemoveDriver aufgerufen werden, um die Anzahl der Komponentennutzung zu verringern. SQLInstallDriverEx sollte dann aufgerufen werden, um den Treiber neu zu installieren, wobei die Anzahl der Komponentennutzung erhöht wird. Das Anwendungssetupprogramm muss die alte Datei durch die neue Datei ersetzen. Die Anzahl der Dateiverwendungen bleibt gleich, und alle anderen Anwendungen, die die ältere Versionsdatei verwendet haben, verwenden jetzt die neuere Version.

Hinweis

Wenn der Treiber zuvor installiert wurde und SQLInstallDriverEx aufgerufen wird, um den Treiber in einem anderen Verzeichnis zu installieren, gibt die Funktion TRUE zurück, aber lpszPathOut enthält das Verzeichnis, in dem der Treiber bereits installiert wurde. Es enthält nicht das im lpszDriver-Argument eingegebene Verzeichnis.

Die Länge des Pfads in lpszPathOut in SQLInstallDriverEx ermöglicht einen zweistufigen Installationsprozess, sodass eine Anwendung bestimmen kann, was cbPathOutMax sein soll, indem SQLInstallDriverEx mit einer fRequest des ODBC_INSTALL_INQUIRY Modus aufgerufen wird. Dadurch wird die Gesamtanzahl der im PcbPathOut-Puffer verfügbaren Bytes zurückgegeben. SQLInstallDriverEx kann dann mit einer fRequest von ODBC_INSTALL_COMPLETE aufgerufen werden und das cbPathOutMax-Argument auf den Wert im pcbPathOut-Puffer und das Nullendpunktzeichen festgelegt werden.

Wenn Sie sich entscheiden, das zweistufige Modell für SQLInstallDriverEx nicht zu verwenden, müssen Sie cbPathOutMax festlegen, wodurch die Größe des Speichers für den Pfad des Zielverzeichnisses definiert wird, auf den Wert _MAX_PATH, wie in Stdlib.h definiert, um das Abschneiden zu verhindern.

Wenn fRequest ODBC_INSTALL_COMPLETE ist, lässt SQLInstallDriverEx nicht zu, dass lpszPathOut NULL (oder cbPathOutMax auf 0) festgelegt ist. Wenn fRequest ODBC_INSTALL_COMPLETE ist, wird FALSE zurückgegeben, wenn die Anzahl der zurückzugebenden Bytes größer oder gleich cbPathOutMax ist, und das Ergebnis, das abgeschnitten wird.

Nachdem SQLInstallDriverEx aufgerufen wurde und das Anwendungssetupprogramm die Treiberdatei kopiert hat (falls erforderlich), muss die Treibersetup-DLL SQLConfigDriver aufrufen, um die Konfiguration für den Treiber festzulegen.

Verwandte Funktionen

Weitere Informationen zu	Siehe
Installieren des Treiber-Managers	SQLInstallDriverManager