SQLInstallTranslatorEx 関数

  • [アーティクル]

準拠
導入されたバージョン: ODBC 3.0

まとめ
SQLInstallTranslatorEx は、変換ツールに関する情報をシステム情報のOdbcinst.ini セクションに追加します (HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\ODBC Translators レジストリ キー)。

SQLInstallTranslatorEx の機能には、ODBCCONF.EXEを使用してアクセスすることもできます。

構文

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

引数

lpszTranslator
[入力]これには、トランスレーターを記述するキーワードと値のペアの null で終わる二重のリストが含まれている必要があります。 キーワードと値のペア構文の詳細については、「 Translator Specification Subkeys」を参照してください。

Translator キーワードと Setup キーワードは、lpszTranslator 文字列に含める必要があります。 翻訳 DLL は Translator キーワードと共に一覧表示され、Translator セットアップ DLL は Setup キーワードと共に一覧表示されます。 各ペアは NULL バイトで終了し、リスト全体が NULL バイトで終了します。 (つまり、2 つの NULL バイトがリストの末尾をマークします)。 lpszTranslator の形式は次のとおりです。

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

lpszPathIn
[入力]トランスレーターがインストールされる場所の完全パスまたは null ポインター。 lpszPath が null ポインターの場合、変換プログラムは System ディレクトリにインストールされます。

lpszPathOut
[出力]トランスレーターをインストールするターゲット ディレクトリのパス。 トランスレーターがインストールされていない場合、 lpszPathOut は lpszPathIn と同じです。 トランスレーターの以前のインストールが存在する場合、 lpszPathOut は以前のインストールのパスです。

cbPathOutMax
[入力]lpszPathOut の長さ。

pcbPathOut
[出力] lpszPathOut で返すために使用できる合計バイト数。 返すことができるバイト数が cbPathOutMax 以上の場合、 lpszPathOut の出力パスは pcbPathOutMax から null 終端文字を引いた値に切り捨てられます。 pcbPathOut 引数には null ポインターを指定できます。

fRequest
[入力]要求の種類。 fRequest には、次のいずれかの値が含まれている必要があります。

ODBC_INSTALL_INQUIRY: 翻訳者をインストールできる場所について問い合わせてください。

ODBC_INSTALL_COMPLETE: インストール要求を完了します。

lpdwUsageCount
[出力]この関数が呼び出された後のトランスレーターの使用数。

アプリケーションでは、使用量の数を設定しないでください。 ODBC は、この数を維持します。

戻り値

関数は成功した場合は TRUE を返し、失敗した場合は FALSE を返します。

診断

SQLInstallTranslatorEx が FALSE を返すと、SQLInstallerError を呼び出すことによって、関連付けられた *pfErrorCode 値を取得できます。 次の表に、SQLInstallerError によって返される *pfErrorCode 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。

*pfErrorCode エラー 説明
ODBC_ERROR_GENERAL_ERR 一般的なインストーラー エラー 特定のインストーラー エラーがないエラーが発生しました。
ODBC_ERROR_INVALID_BUFF_LEN バッファー長が無効です lpszPathOut 引数は、出力パスを格納するのに十分な大きさではありません。 バッファーには、切り捨てられたパスが含まれています。

cbPathOutMax 引数は 0 で、fRequest 引数はODBC_INSTALL_COMPLETEされました。
ODBC_ERROR_INVALID_REQUEST_TYPE 要求の種類が無効です fRequest 引数は次のいずれかではありません。

ODBC_INSTALL_INQUIRY ODBC_INSTALL_COMPLETE
ODBC_ERROR_INVALID_KEYWORD_VALUE キーワードと値のペアが無効です lpszTranslator 引数に構文エラーが含まれていました。
ODBC_ERROR_INVALID_PATH インストール パスが無効です lpszPathIn 引数に無効なパスが含まれていました。
ODBC_ERROR_INVALID_PARAM_SEQUENCE パラメーター シーケンスが無効です lpszTranslator 引数にキーワードと値のペアのリストが含まれていませんでした。
ODBC_ERROR_USAGE_UPDATE_FAILED レジストリのコンポーネントの使用数をインクリメントまたはデクリメントできませんでした インストーラーは、トランスレーターの使用数を増やできませんでした。

説明

SQLInstallTranslatorEx には、トランスレーターのみをインストールするメカニズムが用意されています。 この関数は、実際にはファイルをコピーしません。 呼び出し元のプログラムは、トランスレーター ファイルのコピーを担当します。

SQLInstallTranslatorEx は、インストールされているトランスレーターのコンポーネントの使用数を 1 ずつインクリメントします。 翻訳者のバージョンが既に存在するが、変換プログラムのコンポーネント使用数が存在しない場合、新しいコンポーネントの使用数の値は 2 に設定されます。

アプリケーション セットアップ プログラムは、トランスレーター ファイルを物理的にコピーし、ファイルの使用数を維持する役割を担います。 トランスレーター ファイルが以前にインストールされていない場合は、アプリケーション セットアップ プログラムでファイルまたはファイルをコピーし、ファイルまたはファイルの使用数を作成する必要があります。 ファイルが以前にインストールされている場合、セットアップ プログラムはファイルの使用数を増やすだけです。

以前のバージョンのトランスレーターがアプリケーションによって以前にインストールされている場合は、トランスレーターコンポーネントの使用数が有効になるように、トランスレーターをアンインストールしてから再インストールする必要があります。 SQLRemoveTranslator を呼び出してコンポーネントの使用数を減らし、 次に SQLInstallTranslatorEx を 呼び出してコンポーネントの使用数を増やす必要があります。 アプリケーション セットアップ プログラムは、古いファイルを新しいファイルに置き換える必要があります。 ファイル使用量の数は変わりません。古いバージョンのファイルを使用した他のアプリケーションでは、新しいバージョンが使用されるようになります。

SQLInstallTranslatorEx の lpszPathOut 内のパスの長さは、2 フェーズインストール プロセスを可能にするため、アプリケーションは、ODBC_INSTALL_INQUIRY モードの fRequest を使用して SQLInstallTranslatorEx を呼び出すことによって、cbPathOutMax が必要かどうかを判断できます。 これにより、 pcbPathOut バッファーで使用可能な合計バイト数が返されます。 sqlInstallTranslatorEx は、 ODBC_INSTALL_COMPLETEの fRequest と cbPathOutMax 引数を pcbPathOut バッファーの値に加えて null 終端文字に設定して呼び出すことができます。

SQLInstallTranslatorEx に 2 フェーズ モデルを使用しない場合は、切り捨てを防ぐために、ターゲット ディレクトリのパスのストレージのサイズを定義する cbPathOutMax を、Stdlib.h で定義されている_MAX_PATH値に設定する必要があります。

fRequest がODBC_INSTALL_COMPLETEされている場合、SQLInstallTranslatorEx では lpszPathOut を NULL (または cbPathOutMax を 0) にすることはできません。 fRequest がODBC_INSTALL_COMPLETEの場合、返されるバイト数が cbPathOutMax 以上の場合に FALSE が返され、切り捨てが発生します。

対象 解決方法については、
既定の翻訳オプションを返す ConfigTranslator
翻訳者の選択 SQLGetTranslator
トランスレーターの削除 SQLRemoveTranslator