SQLInstallTranslatorEx-Funktion

Konformität
Version eingeführt: ODBC 3.0

Zusammenfassung
SQLInstallTranslatorEx fügt dem Odbcinst.ini Abschnitt der Systeminformationen (HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\ODBC Translators-Registrierungsschlüssel) Informationen zu einem Übersetzer hinzu.

Auf die Funktionalität von SQLInstallTranslatorEx kann auch mit ODBCCONF.EXEzugegriffen werden.

Syntax

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

Argumente

lpszTranslator
[Eingabe] Dies muss eine doppelt mit NULL beendete Liste von Schlüsselwort-Wert-Paaren enthalten, die den Übersetzer beschreiben. Weitere Informationen zur Syntax des Schlüsselwort-Wert-Paares finden Sie unter Unterschlüssel für die Übersetzerspezifikation.

Die Schlüsselwörter Translator und Setup müssen in der lpszTranslator-Zeichenfolge enthalten sein. Die Übersetzungs-DLL wird mit dem Schlüsselwort Translator aufgeführt, und die Setup-DLL des Übersetzers wird mit dem Setup-Schlüsselwort aufgeführt. 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.) Das Format von lpszTranslator ist wie folgt:

\0Translator=translator-DLL-filename\0[Setup=setup-DLL-filename\0]\0

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

lpszPathOut
[Ausgabe] Der Pfad des Zielverzeichnisses, in dem der Übersetzer installiert werden soll. Wenn der Translator noch nie installiert wurde, ist lpszPathOut mit lpszPathIn identisch. Wenn eine vorherige Installation des Translators vorhanden ist, ist lpszPathOut der Pfad der vorherigen Installation.

cbPathOutMax
[Eingabe] Länge von lpszPathOut.

pcbPathOut
[Ausgabe] Gesamtanzahl der Bytes, 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 auf pcbPathOutMax abgeschnitten, abzüglich des Null-Beendigungszeichens. Das argument pcbPathOut kann ein NULL-Zeiger sein.

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

ODBC_INSTALL_INQUIRY: Erkundigen Sie sich, wo ein Übersetzer installiert werden kann.

ODBC_INSTALL_COMPLETE: Führen Sie die Installationsanforderung aus.

lpdwUsageCount
[Ausgabe] Die Nutzungsanzahl des Übersetzers, nachdem diese Funktion aufgerufen wurde.

Anwendungen sollten die Nutzungsanzahl nicht festlegen. ODBC behält diese Anzahl bei.

Gibt zurück

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

Diagnose

Wenn SQLInstallTranslatorEx FALSE zurückgibt, kann ein zugeordneter *pfErrorCode-Wert abgerufen werden, indem SQLInstallerError aufgerufen wird. 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_GENERAL_ERR	Allgemeiner Installationsfehler	Es ist ein Fehler aufgetreten, für den kein spezifischer Installerfehler 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 argument cbPathOutMax war 0, und das fRequest-Argument wurde ODBC_INSTALL_COMPLETE.
ODBC_ERROR_INVALID_REQUEST_TYPE	Ungültiger Anforderungstyp	Das fRequest-Argument war nicht eines der folgenden: ODBC_INSTALL_INQUIRY ODBC_INSTALL_COMPLETE
ODBC_ERROR_INVALID_KEYWORD_VALUE	Ungültige Schlüsselwort-Wert-Paare	Das lpszTranslator-Argument enthielt einen Syntaxfehler.
ODBC_ERROR_INVALID_PATH	Ungültiger Installationspfad	Das lpszPathIn-Argument enthielt einen ungültigen Pfad.
ODBC_ERROR_INVALID_PARAM_SEQUENCE	Ungültige Parametersequenz	Das lpszTranslator-Argument enthielt keine Liste von Schlüsselwort-Wert-Paaren.
ODBC_ERROR_USAGE_UPDATE_FAILED	Die Anzahl der Komponentennutzung der Registrierung konnte nicht erhöht oder verringert werden.	Das Installationsprogramm konnte die Nutzungsanzahl des Übersetzers nicht erhöhen.

Kommentare

SQLInstallTranslatorEx bietet einen Mechanismus, um nur den Übersetzer zu installieren. Diese Funktion kopiert keine Dateien. Das aufrufende Programm ist für das Kopieren der Übersetzerdateien verantwortlich.

SQLInstallTranslatorEx erhöht die Anzahl der Komponentennutzung für den installierten Übersetzer um 1. Wenn bereits eine Version des Übersetzers vorhanden ist, die Komponentenverwendungsanzahl für den Übersetzer jedoch nicht vorhanden ist, wird der neue Wert für die Komponentennutzungsanzahl auf 2 festgelegt.

Das Programm zum Einrichten der Anwendung ist für das physische Kopieren der Übersetzerdatei und die Verwaltung der Anzahl der Dateinutzungen verantwortlich. Wenn die Übersetzerdatei noch nicht installiert wurde, muss das Programm zum Einrichten der Anwendung die Datei bzw. die Dateien kopieren und die Anzahl der Datei- oder Dateiverwendungen erstellen. Wenn die Datei zuvor installiert wurde, erhöht das Setupprogramm einfach die Anzahl der Dateinutzungen.

Wenn zuvor eine ältere Version des Übersetzers von der Anwendung installiert wurde, sollte der Übersetzer deinstalliert und dann erneut installiert werden, damit die Anzahl der Übersetzerkomponenten gültig ist. SQLRemoveTranslator sollte aufgerufen werden, um die Anzahl der Komponentennutzung zu verringern, und dann sollte SQLInstallTranslatorEx aufgerufen werden, um die Anzahl der Komponentennutzung zu erhöhen. Das Programm zum Einrichten der Anwendung muss die alte Datei oder die alten Dateien durch die neue Datei ersetzen. Die Anzahl der Dateinutzungen bleibt unverändert, und andere Anwendungen, die die ältere Version verwendet haben, verwenden jetzt die neuere Version.

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

Wenn Sie das Zweiphasenmodell für SQLInstallTranslatorEx nicht verwenden möchten, müssen Sie cbPathOutMax, das die Größe des Speichers für den Pfad des Zielverzeichnisses definiert, auf den Wert _MAX_PATH festlegen, wie in Stdlib.h definiert, um eine Abschneidung zu verhindern.

Wenn fRequest ODBC_INSTALL_COMPLETE ist, erlaubt SQLInstallTranslatorEx nicht, dass lpszPathOut NULL (oder cbPathOutMax 0) ist. Wenn fRequest ODBC_INSTALL_COMPLETE ist, wird FALSE zurückgegeben, wenn die Anzahl der zurückzugebenden Bytes größer oder gleich cbPathOutMax ist, sodass eine Abkürzung auftritt.

Verwandte Funktionen

Informationen über	Finden Sie unter
Zurückgeben einer Standardübersetzungsoption	ConfigTranslator
Auswählen von Übersetzern	SQLGetTranslator
Entfernen von Übersetzern	SQLRemoveTranslator