SQLInstallDriverEx 関数

  • [アーティクル]

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

まとめ
SQLInstallDriverEx は、システム情報のOdbcinst.ini エントリにドライバーに関する情報を追加し、ドライバーの UsageCount を 1 ずつインクリメントします。 ただし、ドライバーのバージョンが既に存在するが、ドライバーの UsageCount 値が存在しない場合、新しい UsageCount 値は 2 に設定されます。

この関数は、実際にはファイルをコピーしません。 ドライバーのファイルをターゲット ディレクトリに適切にコピーするのは、呼び出し元のプログラムの責任です。

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

構文

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

引数

lpszDriver
[入力]物理ドライバー名ではなく、ユーザーに提示されるドライバーの説明 (通常は関連付けられている DBMS の名前)。 lpszDriver 引数には、ドライバーを記述するキーワードと値のペアの二重に null で終わるリストが含まれている必要があります。 キーワードと値のペアの詳細については、「 ドライバー仕様サブキー」を参照してください。 2 倍の null で終わる文字列の詳細については、「 ConfigDSN 関数」を参照してください。

lpszPathIn
[入力]インストールのターゲット ディレクトリの完全パス、または null ポインター。 lpszPathIn が null ポインターの場合、ドライバーはシステム ディレクトリにインストールされます。

lpszPathOut
[出力]ドライバーをインストールする必要があるターゲット ディレクトリのパス。 ドライバーが以前にインストールされていない場合、 lpszPathOut は lpszPathIn と同じである必要があります。 ドライバーが以前にインストールされていた場合、 lpszPathOut は以前のインストールのパスです。

cbPathOutMax
[入力] lpszPathOut の長さ。

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

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

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

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

lpdwUsageCount
[出力]この関数が呼び出された後のドライバーの使用数。

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

戻り値

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

診断

SQLInstallDriverEx が 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 キーワードと値のペアが無効です lpszDriver 引数に構文エラーが含まれていました。
ODBC_ERROR_INVALID_PATH インストール パスが無効です lpszPathIn 引数に無効なパスが含まれていました。
ODBC_ERROR_LOAD_LIBRARY_FAILED ドライバーまたはトランスレーターのセットアップ ライブラリを読み込めませんでした ドライバー セットアップ ライブラリを読み込めませんでした。
ODBC_ERROR_INVALID_PARAM_SEQUENCE パラメーター シーケンスが無効です lpszDriver 引数にキーワードと値のペアのリストが含まれていませんでした。
ODBC_ERROR_USAGE_UPDATE_FAILED コンポーネントの使用数をインクリメントまたはデクリメントできませんでした インストーラーは、ドライバーの使用数を増やすことができませんでした。

説明

lpszDriver 引数は、キーワードと値のペアの形式の属性の一覧です。 各ペアは null バイトで終了し、リスト全体が null バイトで終了します。 (つまり、2 つの null バイトがリストの末尾をマークします)。このリストの形式は次のとおりです。

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

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

\0 は null バイトで、 driver-attr-keywordn は任意のドライバー属性キーワードです。 キーワードは、指定した順序で指定する必要があります。 たとえば、書式設定されたテキスト ファイルのドライバーに個別のドライバーとセットアップ DLL があり、.txtと.csv拡張子を持つファイルを使用できるとします。 このドライバー の lpszDriver 引数は次のようになります。

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

SQL Serverのドライバーに個別のセットアップ DLL が設定されておらず、ドライバー属性キーワードが含まれていないとします。 このドライバー の lpszDriver 引数は次のようになります。

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

SQLInstallDriverEx は、lpszDriver 引数からドライバーに関する情報を取得した後、システム情報のOdbcinst.ini エントリの [ODBC Drivers] セクションにドライバーの説明を追加します。 次に、ドライバーの説明を含むセクションを作成し、ドライバー DLL とセットアップ DLL の完全なパスを追加します。 最後に、インストールのターゲット ディレクトリのパスを返しますが、ドライバー ファイルはコピーしません。 呼び出し元のプログラムは、ドライバー ファイルを実際にターゲット ディレクトリにコピーする必要があります。

SQLInstallDriverEx は、インストールされているドライバーのコンポーネントの使用数を 1 ずつインクリメントします。 ドライバーのバージョンが既に存在するが、ドライバーのコンポーネント使用量の数が存在しない場合、新しいコンポーネントの使用数の値は 2 に設定されます。

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

Note

コンポーネントの使用状況数とファイル使用量の数の詳細については、「 使用状況カウント」を参照してください。

以前のバージョンのドライバー ファイルが以前にアプリケーションによってインストールされている場合は、ドライバー コンポーネントの使用数が有効になるように、ドライバーをアンインストールしてから再インストールする必要があります。 SQLConfigDriver ( fRequest of ODBC_REMOVE_DRIVER) を最初に呼び出し、次に SQLRemoveDriver を呼び出してコンポーネントの使用数を減らす必要があります。 その後、SQLInstallDriverEx を呼び出してドライバーを再インストールし、コンポーネントの使用数を増やす必要があります。 アプリケーション セットアップ プログラムは、古いファイルを新しいファイルに置き換える必要があります。 ファイルの使用数は変わらず、古いバージョンのファイルを使用した他のアプリケーションでは、新しいバージョンが使用されるようになります。

Note

ドライバーが以前にインストールされていて、別のディレクトリにドライバーをインストールするために SQLInstallDriverEx が呼び出された場合、関数は TRUE を返しますが、 lpszPathOut にはドライバーが既にインストールされているディレクトリが含まれます。 lpszDriver 引数に入力されたディレクトリは含まれません。

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

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

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

SQLInstallDriverEx が呼び出され、アプリケーション セットアップ プログラムがドライバー ファイルをコピーした後 (必要な場合)、ドライバーセットアップ DLL は SQLConfigDriver を呼び出してドライバーの構成を設定する必要があります。

対象 解決方法については、
ドライバー マネージャーのインストール SQLInstallDriverManager