SQLCreateDataSource 函式
一致性
引進的版本：ODBC 2.0
摘要
SQLCreateDataSource 會顯示一個對話方塊，讓使用者可以新增資料來源。
語法
BOOL SQLCreateDataSource(
HWND hwnd,
LPSTR lpszDS);
引數
hwnd
[輸入]父視窗控制碼。
lpszDS
[輸入]資料來源名稱。 lpszDS 可以是 Null 指標或空字串。
傳回
如果建立資料來源，SQLCreateDataSource 會傳回 TRUE。 否則會傳回 FALSE。
診斷
當 SQLCreateDataSource 傳回 FALSE 時 ，可以呼叫 SQLInstallerError 來取得相關聯的 *pfErrorCode 值。 下表列出 SQLInstallerError 可傳 回的 *pfErrorCode 值，並說明此函式內容中的每個值。
| *pfErrorCode | 錯誤 | 描述 |
|---|---|---|
| ODBC_ERROR_GENERAL_ERR | 一般安裝程式錯誤 | 發生錯誤，沒有特定的安裝程式錯誤。 |
| ODBC_ERROR_INVALID_HWND | 不正確視窗控制碼 | hwnd 引數無效或 Null。 |
| ODBC_ERROR_INVALID_DSN | 不正確 DSN | lpszDS 引數包含 DSN 不正確字串。 |
| ODBC_ERROR_REQUEST_FAILED | 要求 失敗 | 使用 ODBC_ADD_DSN 選項呼叫 ConfigDSN 失敗。 |
| ODBC_ERROR_LOAD_LIBRARY_FAILED | 無法載入驅動程式或翻譯工具設定程式庫 | 無法載入驅動程式設定程式庫。 |
| ODBC_ERROR_USER_CANCELED | 使用者取消作業 | 使用者已取消建立新的資料來源。 |
| ODBC_ERROR_CREATE_DSN_FAILED | 無法建立要求的 DSN | 無法連線到資料庫; 呼叫 FILE DSN 的 SQLDriverConnect 未傳回成功的連線。 無法寫入檔案。 |
| ODBC_ERROR_OUT_OF_MEM | 記憶體不足 | 由於記憶體不足，安裝程式無法執行函式。 |
註解
如果 hwnd 為 null， SQLCreateDataSource 會傳回 FALSE。 否則，它會顯示 [建立新的資料來源 ] 對話方塊，其中包含精靈頁面，以選擇要設定的資料來源類型，如下圖所示。
預設選項為 [檔案資料來源 ]。 選擇資料來源並 按 [下一步 ] 時，會顯示包含已安裝驅動程式清單的下列精靈頁面。
如果 按一下 [取消 ]，對話方塊就會消失，而 SQLCreateDataSource 會傳回 FALSE，並傳回錯誤碼為 ODBC_ERROR_USER_CANCELED。 如果已選取 [使用者資料來源 ] 或 [系統資料來源 ] 選項，[ 進階 ] 按鈕將無法使用。
按一下 [ 下一步 ] 按鈕時，會視選取的資料來源類型而定，會發生下列其中一項：
如果 選取 [檔案資料來源 ]，則會顯示精靈頁面，讓使用者輸入檔案名。
如果已選取 [使用者資料來源 ] 或 [系統資料來源 ]，則會顯示資料來源類型和驅動程式類型的精靈頁面以供檢閱，而且按一下 [完成 ] 時 ，就會設定資料來源。
如果 從 [建立新的資料來源精靈] 頁面按一下 [進階 ]，則會顯示精靈頁面，讓使用者輸入驅動程式特定資訊。 在此對話方塊的文字方塊中，輸入以傳回分隔的驅動程式和關鍵字，如下圖所示。
您可以在 SQLDriverConnect 的描述 下找到其他驅動程式特定的關鍵字。 不允許 DSN 以外的 所有專案。
[驗證此連線 ] 選項的 預設值為 TRUE。 此預設值適用於是否啟用此精靈頁面。 如果 按一下 [確定 ]，則會快取文字方塊中指定的字串，並快取 [ 驗證此連線 ] 選項值。 （如果 按一下 [關閉 ] 按鈕或 [取消 ]，任何新輸入的驅動程式特定資訊會遺失，因為文字方塊中指定的字串，而且 不會快取 [驗證此連線 ] 選項值。
如果在 第一個精靈頁面中選取 [檔案資料來源 ]，則在選取驅動程式且已在 [進階精靈] 頁面中輸入關鍵字值之後，系統會提示使用者輸入檔案名。 按一下 [ 流覽] 來搜尋檔案名，在此情況下，[流覽 ] 方塊中的 預設目錄是由 commonFileDir 在 HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion 和 「ODBC\DataSources」 中指定的路徑組合所指定。 （如果 CommonFileDir 是 「C：\Program Files\Common Files」，預設目錄會是 「C：\Program Files\Common Files\ODBC\Data Sources」。
輸入檔案名且 按一下 [下一步 ] 時，系統會根據作業系統的標準檔案命名規則，檢查輸入的檔案名是否有效。 如果檔案名無效，錯誤訊息框會通知使用者輸入不正確檔案名。 在使用者確認訊息框之後，焦點會傳回至輸入檔案名的精靈頁面。 如果檔案名有效，則會顯示所選取關鍵字/值組的精靈頁面以供檢閱，如下圖所示。
如果 按一下 [完成 ]，並 選取 [檔案資料來源 ] 作為資料來源類型，而且如果 [驗證此連接 ] 選項為 TRUE， 則會使用 SAVEFILE 和 DRIVER 關鍵字呼叫 SQLDriverConnect 。 DriverCompletion 引數設定為 SQL_DRIVER_COMPLETE。 SAVEFILE 關鍵字的 檔案名是輸入或選擇的名稱，而 DRIVER 關鍵字的 驅動程式名稱是所選的名稱。 如果在 [進階精靈] 頁面中指定驅動程式特定的連接字串，該字串會在 DRIVER 關鍵字後面 附加。
如果 SQLDriverConnect 傳回SQL_SUCCESS，驅動程式管理員已建立檔案 DSN。 SQLCreateDataSource 會傳回 TRUE。 如果 SQLDriverConnect 未傳回SQL_SUCCESS，警告訊息框表示無法連線至資料來源。 仍然可以建立具有最少連線資訊的 DSN。 此訊息方塊可讓使用者取消或繼續建立檔案 DSN。
如果使用者選擇繼續建立 DSN，此程式會繼續，就像確認此連線 選項設定為 FALSE 一樣 。 如果使用者選擇取消，則會針對 SQLCreateDataSource 傳回 FALSE，錯誤碼為 ODBC_ERROR_CREATE_DSN_FAILED。
如果 選取 [檔案資料來源 ] 做為資料來源類型，且 [驗證此連接 ] 選項為 FALSE，則會使用 [進階精靈] 頁面中的 DRIVER 關鍵字和使用者指定的連接字串建立 [檔案 DSN]。 如果檔案建立成功，則會針對 SQLCreateDataSource 傳回 TRUE。 如果檔案建立未成功，錯誤訊息框會通知使用者從作業系統傳回的任何錯誤。 SQLCreateDataSource 傳回 FALSE，錯誤碼為 ODBC_ERROR_CREATE_DSN_FAILED。 如需檔案資料來源的詳細資訊，請參閱 使用檔案資料來源 連線，或參閱 SQLDriverConnect 。
如果 選取 [使用者 ] 或 [系統資料來源 ] 作為資料來源類型， 則會使用 ODBC_ADD_DSN fRequest 呼叫驅動程式安裝連結 庫中的 ConfigDSN 。 如需詳細資訊，請參閱 ConfigDSN 。
相關函數
| 如需下列資訊 | 請參閱 |
|---|---|
| 管理資料來源 | SQLManageDataSources |