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引数には、ドライバーを記述するキーワードと値のペアの 2 倍の null で終わるリストが含まれている必要があります。 キーワードと値のペアの詳細については、「 Driver 仕様サブキーを参照してください。 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 を返す場合、関連付けられている *pfErrorCode 値を取得するには、SQLInstallerError を呼び出します。 次の表は、SQLInstallerError によって返される*pfErrorCode 値の一覧を示しこの関数のコンテキストでそれぞれについて説明します。

Comments

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 ドライバー] セクションにドライバーの説明を追加します。 次に、ドライバーの説明とタイトル付きのセクションを作成し、ドライバー DLL とセットアップ DLL の完全なパスを追加します。 最後に、インストールのターゲット ディレクトリのパスを返しますが、ドライバー ファイルはコピーしません。 呼び出し元のプログラムは、実際にドライバー ファイルをターゲット ディレクトリにコピーする必要があります。

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

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

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

SQLInstallDriverEx のlpszPathOutのパスの長さにより、2 フェーズのインストール プロセスが可能になるため、アプリケーションはODBC_INSTALL_INQUIRYモードの fRequest でSQLInstallDriverExsqlInstallDriverExを呼び出すことによって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を呼び出してドライバーの構成を設定する必要があります。

関連する関数