ConfigDSN 関数
準拠
導入されたバージョン: ODBC 1.0
まとめ
ConfigDSN は 、システム情報からデータ ソースを追加、変更、または削除します。 ユーザーに接続情報の入力を求めるメッセージが表示される場合があります。 ドライバー DLL または別のセットアップ DLL に含めることができます。
構文
BOOL ConfigDSN(
HWND hwndParent,
WORD fRequest,
LPCSTR lpszDriver,
LPCSTR lpszAttributes);
引数
hwndParent
[入力]親ウィンドウ ハンドル。 ハンドルが null の場合、関数はダイアログ ボックスを表示しません。
fRequest
[入力]要求の種類。 fRequest 引数には、次のいずれかの値が含まれている必要があります。
ODBC_ADD_DSN: 新しいデータ ソースを追加します。
ODBC_CONFIG_DSN: 既存のデータ ソースを構成 (変更) します。
ODBC_REMOVE_DSN: 既存のデータ ソースを削除します。
lpszDriver
[入力]物理ドライバー名ではなく、ユーザーに提示されるドライバーの説明 (通常は関連付けられている DBMS の名前)。
lpszAttributes
[入力]キーワードと値のペアの形式の属性の 2 倍の null で終わるリスト。 詳細については、「コメント」を参照してください。
戻り値
関数は成功した場合は TRUE を返し、失敗した場合は FALSE を返します。
診断
ConfigDSN が FALSE を返すと、関連付けられた *pfErrorCode 値が SQLPostInstallerError の呼び出しによってインストーラー エラー バッファーにポストされ、SQLInstallerError を呼び出すことで取得できます。 次の表に、SQLInstallerError によって返される *pfErrorCode 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。
| *pfErrorCode | エラー | 説明 |
|---|---|---|
| ODBC_ERROR_INVALID_HWND | 無効なウィンドウ ハンドル | hwndParent 引数が無効です。 |
| ODBC_ERROR_INVALID_KEYWORD_VALUE | キーワードと値のペアが無効です | lpszAttributes 引数に構文エラーが含まれていました。 |
| ODBC_ERROR_INVALID_NAME | ドライバーまたはトランスレーター名が無効です | lpszDriver 引数が無効です。 レジストリに見つかりませんでした。 |
| ODBC_ERROR_INVALID_REQUEST_TYPE | 要求の種類が無効です | fRequest 引数は次のいずれかではありません。 ODBC_ADD_DSN ODBC_CONFIG_DSN ODBC_REMOVE_DSN |
| ODBC_ERROR_REQUEST_FAILED | 要求 が失敗しました | fRequest 引数によって要求された操作を実行できませんでした。 |
| ODBC_ERROR_DRIVER_SPECIFIC | ドライバー固有またはトランスレーター固有のエラー | 定義された ODBC インストーラー エラーがないドライバー固有のエラー。 SQLPostInstallerError 関数の呼び出しの SzError 引数には、ドライバー固有のエラー メッセージが含まれている必要があります。 |
説明
ConfigDSN は、インストーラー DLL からキーワードと値のペアの形式で属性の一覧として接続情報を受け取ります。 各ペアは null バイトで終了し、リスト全体は null バイトで終了します。 (つまり、2 つの null バイトがリストの末尾をマークします)。キーワードと値のペアの等号の周囲にはスペースを使用できません。 ConfigDSN は、 SQLBrowseConnect および SQLDriverConnect の有効なキーワードではないキーワード を受け入れます。 ConfigDSN では、 SQLBrowseConnect と SQLDriverConnect の有効なキーワードがすべてサポートされるとは限りません。 (ConfigDSN は DRIVER キーワードを受け入れていません。) ConfigDSN 関数で使用されるキーワードは、インストーラーの AUTO セットアップ機能を使用してデータ ソースを再作成するために必要なすべてのオプションをサポートする必要があります。 ConfigDSN 値と接続文字列値の使用が同じ場合は、同じキーワードを使用する必要があります。
SQLBrowseConnect と SQLDriverConnect と同様に、キーワードとその値には []{}(),;?*=!@ 文字、および DSN キーワードの値はブランクのみで構成することはできません。 レジストリ文法のため、キーワードとデータ ソース名に円記号 (\) 文字を含めることはできません。
ConfigDSN は SQLValidDSN を呼び出して、データ ソース名の長さを確認し、名前に無効な文字が含まれていないことを確認する必要があります。 データ ソース名がSQL_MAX_DSN_LENGTHより長い場合、または無効な文字が含まれている場合、 SQLValidDSN はエラーを返し、 ConfigDSN はエラーを返します。 データ ソース名の長さは、 SQLWriteDSNToIni によっても確認されます。
たとえば、ユーザー ID、パスワード、およびデータベース名を必要とするデータ ソースを構成するために、セットアップ アプリケーションは次のキーワードと値のペアを渡す場合があります。
DSN=Personnel Data\0UID=Smith\0PWD=Sesame\0DATABASE=Personnel\0\0
これらのキーワードの詳細については、 SQLDriverConnect と各ドライバーのドキュメントを参照してください。
ダイアログ ボックスを表示するには、 hwndParent を null にすることはできません。
データ ソースの追加
データ ソース名が lpszAttributes の ConfigDSN に渡された場合、ConfigDSN は名前が有効であることを確認します。 データ ソース名が既存のデータ ソース名と一致し、 hwndParent が null の場合、 ConfigDSN は既存の名前を上書きします。 既存の名前と一致し、 hwndParent が null でない場合、 ConfigDSN はユーザーに既存の名前を上書きするように求めます。
lpszAttributes にデータ ソースに接続するための十分な情報が含まれている場合、ConfigDSN はデータ ソースを追加したり、ユーザーが接続情報を変更できるダイアログ ボックスを表示したりできます。 lpszAttributes にデータ ソースに接続するための十分な情報が含まれていない場合、ConfigDSN は必要な情報を決定する必要があります。hwndParent が null でない場合は、ユーザーから情報を取得するためのダイアログ ボックスが表示されます。
ConfigDSN がダイアログ ボックスを表示する場合は、それに渡された接続情報を lpszAttributes に表示する必要があります。 特に、データ ソース名が渡された場合、 ConfigDSN はその名前を表示しますが、ユーザーによる変更は許可しません。 ConfigDSN では、 lpszAttributes で渡されない接続情報の既定値を指定できます。
ConfigDSN がデータ ソースの完全な接続情報を取得できない場合は、FALSE を返します。
ConfigDSN がデータ ソースの完全な接続情報を取得できる場合は、インストーラー DLL の SQLWriteDSNToIni を呼び出して、新しいデータ ソース仕様をOdbc.ini ファイル (またはレジストリ) に追加します。 SQLWriteDSNToIni は 、[ODBC データ ソース] セクションにデータ ソース名を追加し、データ ソース仕様セクションを作成し、ドライバーの説明を値として DRIVER キーワードを追加します。 ConfigDSN は 、インストーラー DLL で SQLWritePrivateProfileString を呼び出して、ドライバーで使用されるキーワードと値を追加します。
データ ソースの変更
データ ソースを変更するには、lpszAttributes の ConfigDSN にデータ ソース名を渡す必要があります。 ConfigDSN は、データ ソース名がOdbc.ini ファイル (またはレジストリ) にあることを確認します。
hwndParent が null の場合、ConfigDSN は lpszAttributes 内の情報を使用して、Odbc.ini ファイル (またはレジストリ) 内の情報を変更します。 hwndParent が null でない場合、ConfigDSN は lpszAttributes の情報を使用してダイアログ ボックスを表示します。lpszAttributes にない情報については、システム情報からの情報を使用します。 ユーザーは、 ConfigDSN がシステム情報に格納する前に情報を変更できます。
データ ソース名が変更された場合、 ConfigDSN は最初にインストーラー DLL で SQLRemoveDSNFromIni を呼び出して、Odbc.ini ファイル (またはレジストリ) から既存のデータ ソース仕様を削除します。 次に、前のセクションの手順に従って、新しいデータ ソース仕様を追加します。 データ ソース名が変更されていない場合、 ConfigDSN はインストーラー DLL で SQLWritePrivateProfileString を呼び出して、他の変更を行います。 ConfigDSNは、Driver キーワードの値を削除または変更することはできません。
データ ソースの削除
データ ソースを削除するには、データ ソース名を lpszAttributes の ConfigDSN に渡す必要があります。 ConfigDSN は、データ ソース名がOdbc.ini ファイル (またはレジストリ) にあることを確認します。 次に、インストーラー DLL で SQLRemoveDSNFromIni を呼び出して、データ ソースを削除します。
Note
このルーチンの Unicode バージョンを記述する場合は、LPCSTR ではなく LPCWSTR 引数を使用して ConfigDSNW と呼ぶ必要があります。
関連する関数
| 対象 | 解決方法については、 |
|---|---|
| データ ソースの追加、変更、または削除 | SQLConfigDataSource |
| Odbc.ini ファイルまたはレジストリから値を取得する | SQLGetPrivateProfileString |
| 既定のデータ ソースの削除 | SQLRemoveDefaultDataSource |
| Odbc.ini (またはレジストリ) からデータ ソース名を削除する | SQLRemoveDSNFromIni |
| Odbc.ini (またはレジストリ) へのデータ ソース名の追加 | SQLWriteDSNToIni |
| Odbc.ini ファイルまたはレジストリへの値の書き込み | SQLWritePrivateProfileString |
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示