共用方式為

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
[輸入]以關鍵字/值組形式，以 Null 結束的屬性清單。 如需詳細資訊，請參閱。

傳回

如果函式成功，則傳回 TRUE，如果失敗，則傳回 FALSE。

診斷

當 ConfigDSN 傳回 FALSE 時 ，相關聯的 *pfErrorCode 值會透過呼叫 SQLPostInstallerError 將相關聯的 *pfError 張貼至安裝程式錯誤緩衝區，而且可以藉由呼叫 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 位元組終止。 （也就是說，兩個 Null 位元組會標示清單的結尾。關鍵字/值組中的等號周圍不允許空格。 ConfigDSN 可以接受 SQLBrowseConnect 和 SQLDriverConnect 無效關鍵字的 關鍵字。 ConfigDSN 不一定支援 SQLBrowseConnect 和 SQLDriverConnect 有效關鍵字的所有關鍵詞 。 （ ConfigDSN 不接受 DRIVER 關鍵字。ConfigDSN 函式所使用的 關鍵字必須支援使用安裝程式的 AUTO 安裝程式功能重新建立資料來源所需的所有選項。 當使用 ConfigDSN 值和連接字串值時，應該使用相同的關鍵字。

如同 SQLBrowseConnect 和 SQLDriverConnect ，關鍵字及其值不應該包含 [] {} （），;？*=！@ 字元和 DSN 關鍵字的值 不能只包含空白。 由於登錄文法，關鍵字和資料來源名稱不能包含反斜線 (\) 字元。

ConfigDSN 應該呼叫 SQLValidDSN 來檢查資料來源名稱的長度，並確認名稱中未包含無效字元。 如果資料來源名稱超過SQL_MAX_DSN_LENGTH或包含無效字元， SQLValidDSN 會傳回錯誤，而 ConfigDSN 會傳回錯誤。 SQLWriteDSNToIni 也會檢查 資料來源名稱的長度。

例如，若要設定需要使用者識別碼、密碼和資料庫名稱的資料來源，安裝程式應用程式可能會傳遞下列關鍵字/值組：

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 ，以移除資料來源。

注意

如果撰寫此常式的 Unicode 版本，則必須使用 LPCWSTR 引數而不是 LPCSTR 來呼叫 ConfigDSNW 。

如需下列資訊 請參閱
新增、修改或移除資料來源 SQLConfigDataSource
從 Odbc.ini 檔案或登錄取得值 SQLGetPrivateProfileString
移除預設資料來源 SQLRemoveDefaultDataSource
從 Odbc.ini 移除資料來源名稱 （或登錄） SQLRemoveDSNFromIni
將資料來源名稱新增至 Odbc.ini （或登錄） SQLWriteDSNToIni
將值寫入 Odbc.ini 檔案或登錄 SQLWritePrivateProfileString