SQLDriverConnect 函式

符合性
推出版本：ODBC 1.0 標準合規性：ODBC

總結
SQLDriverConnect 是 SQLConnet 的替代方案。 它支援需要比 SQLConncect 三個參數更多的連線資訊來源、提示使用者提供所有連線資訊的對話框，以及系統資訊中未定義的資料來源。 欲了解更多資訊，請參閱 「與 SQLDriverConnect 連結」。

Syntax

  
SQLRETURN SQLDriverConnect(  
     SQLHDBC         ConnectionHandle,  
     SQLHWND         WindowHandle,  
     SQLCHAR *       InConnectionString,  
     SQLSMALLINT     StringLength1,  
     SQLCHAR *       OutConnectionString,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   StringLength2Ptr,  
     SQLUSMALLINT    DriverCompletion);  

Arguments

ConnectionHandle
[輸入] 連線控制代碼。

視窗帳柄
[輸入]窗戶把手。 應用程式可以傳遞父視窗的句柄（如適用），若視窗柄不適用或 SQLDriverConnect 不會顯示任何對話框，則可傳遞空指標。

InConnectionString
[輸入]完整的 連接字串（詳見「Comments」中的語法）、部分 連接字串，或空字串。

字串長度1
[輸入]*InConnectionString 的長度，若字串是 Unicode，則以字元為單位;若字串是 ANSI 或 DBCS，則以位元組為單位。

連接字串
[輸出]指標指向已完成的 連接字串 緩衝區。 成功連接目標資料來源後，此緩衝區會包含已完成的 連接字串。 應用程式應為此緩衝區配置至少 1,024 個字元。

如果 OutConnectionString 是 NULL，StringLength2Ptr 仍會回傳 OutConnectionString 指向緩衝區中可返回的字元總數（不含字元資料的 null 終止字元）。

BufferLength
[輸入]*OutConnectionString 緩衝區的長度，以字元為單位。

字串長度2Ptr
[輸出]指標指向緩衝區，回傳 *OutConnectionString 中可回傳的字元總數（不含空終止字元）。 若可回傳的字元數大於或等於 BufferLength，則 *OutConnectionString 中完成的 連接字串 會被截斷為 BufferLength 減去一個空終止字元的長度。

DriverCompletion
[輸入]標示驅動管理員或駕駛是否必須提示更多連線資訊：

SQL_DRIVER_PROMPT、SQL_DRIVER_COMPLETE、SQL_DRIVER_COMPLETE_REQUIRED或SQL_DRIVER_NOPROMPT。

（更多資訊請參見「評論」。）

Returns

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_ERROR、SQL_INVALID_HANDLE或SQL_STILL_EXECUTING。

Diagnostics

當 SQLDriverConnect 回傳 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 時，可透過呼叫 SQLGetDiagRec 取得對應的 SQLSTATE 值，並設定 fHandleType 為 SQL_HANDLE_DBC，hHandle 為 ConnectionHandle。 下表列出 SQLDriverConnect 常見回傳的 SQLSTATE 值，並在此函式情境下說明每個值;「（DM）」符號會置於驅動程式管理器回傳的 SQLSTATE 描述前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。

SQLSTATE	錯誤	Description
01000	一般警告	驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。）
01004	字串數據，右截斷	緩衝區 *OutConnectionString 不夠大，無法回傳整個 連接字串，因此 連接字串 被截斷。 未截斷的 連接字串 長度以 *StringLength2ptr 回傳。 （函式會傳回SQL_SUCCESS_WITH_INFO。）
01S00	無效的 連接字串 屬性	連接字串（InConnectionString）中指定了一個無效的屬性關鍵字，但驅動程式仍能連接到資料來源。 （函式會傳回SQL_SUCCESS_WITH_INFO。）
01S02	選項值已變更	驅動程式不支援 SQLSetConnectAttr 中 ValuePtr 參數所指向的指定值，並以類似值替換。 （函式會傳回SQL_SUCCESS_WITH_INFO。）
01S08	錯誤儲存檔案 DSN	*InConnectionString 中的字串包含 FILEDSN 關鍵字，但 .dsn 檔案未被儲存。 （函式會傳回SQL_SUCCESS_WITH_INFO。）
01S09	無效關鍵字	（DM） *InConnectionString 中的字串包含 SAVEFILE 關鍵字，但沒有 DRIVER 或 FILEDSN 關鍵字。 （函式會傳回SQL_SUCCESS_WITH_INFO。）
08001	客戶端無法建立連線	駕駛無法與資料來源建立連線。
08002	連接名稱的使用方式	（DM） 指定的 ConnectionHandle 已被用於與資料來源建立連線，且該連線仍保持開啟狀態。
08004	伺服器拒絕了連線	資料來源因實作定義的原因拒絕建立該連線。
08S01	通訊連結故障	驅動程式與驅動程式嘗試連接的資料來源之間的通訊連結在 SQLDriverConnect 函式完成處理前就已失效。
28000	無效授權規範	使用者識別碼或授權字串，或兩者皆如 連接字串（InConnectionString）所規定，違反了資料來源所定義的限制。
HY000	一般誤差	發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 SQLGetDiagRec 在 *szMessageText 緩衝區中回傳的錯誤訊息描述了錯誤及其原因。
HY000	一般錯誤：無效檔案 dsn	（DM） *InConnectionString 中的字串包含 FILEDSN 關鍵字，但找不到 .dsn 檔案的名稱。
HY000	一般錯誤：無法建立檔案緩衝區	（DM） *InConnectionString 中的字串包含 FILEDSN 關鍵字，但 .dsn 檔案無法讀取。
HY001	記憶體配置錯誤	驅動程式管理器無法分配支援 SQLDriverConnect 函式執行或完成所需的記憶體。 驅動程式無法配置支援執行或完成函式所需的記憶體。
HY008	作業已取消	ConnectionHandle 啟用了非同步處理。 函式被呼叫後，在執行完成前，SQLCancelHandle 函式被呼叫到 ConnectionHandle，接著又在 ConnectionHandle 上呼叫 SQLDriverConnect 函式。 或者， SQLDriverConnect 函式被呼叫，但在執行完成前， SQLCancelHandle 從多執行緒應用程式中的另一個執行緒呼叫了 ConnectionHandle 。
HY010	函式順序錯誤	（DM） 另一個非同步執行的函式（非 SQLDriverConnect）被呼叫用於 ConnectionHandle ，且在呼叫 SQLDriverConnect 函式時仍在執行中。
HY013	記憶體管理錯誤	SQLDriverConnect 函式呼叫無法被處理，因為底層記憶體物件無法被存取，可能是因為記憶體狀況不足。
HY090	無效的字串或緩衝區長度	（DM） 參數 StringLength1 指定的值小於 0，且不等於 SQL_NTS。 （DM） 為自變數 BufferLength 指定的值小於 0。
HY092	無效屬性/選項識別碼	（DM） DriverCompletion 參數是 SQL_DRIVER_PROMPT，而 WindowHandle 參數是空指標。
HY110	無效驅動程式補全	（DM） DriverCompletion 參數指定的值不等於 SQL_DRIVER_PROMPT、SQL_DRIVER_COMPLETE、SQL_DRIVER_COMPLETE_REQUIRED 或 SQL_DRIVER_NOPROMPT。 （DM） 連線池已啟用，且參數 DriverCompletion 指定的值不等於 SQL_DRIVER_NOPROMPT。
HYC00	未實作選擇性功能	驅動程式不支援應用程式所要求的 ODBC 行為版本。
HYT00	逾時已超過	登入逾時期在與資料來源連線完成前就已結束。 逾時時間由 SQLSetConnectAttr 設定，SQL_ATTR_LOGIN_TIMEOUT。
HYT01	連線已逾時	在數據源回應要求之前，連線逾時期限已過期。 線上逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。
IM001	驅動程式不支援此函式	（DM） 對應於指定資料來源名稱的驅動程式不支援該函式。
IM002	找不到資料來源，且未指定預設驅動程式	（DM） 連接字串 中指定的資料來源名稱（InConnectionString）未在系統資訊中，且沒有預設驅動程式規範。 （DM） 系統資訊中找不到 ODBC 資料來源及預設驅動程式資訊。
IM003	無法載入指定的驅動程式	（DM） 系統資訊中資料來源規範中列出的驅動程式，或由 DRIVER 關鍵字指定的驅動程式未被找到，或因其他原因無法載入。
IM004	驅動程式的 SQLAllocHandle 在 SQL_HANDLE_ENV 失敗	（DM） 在 SQLDriverConnect 期間，驅動程式管理器呼叫驅動程式的 SQLAllocHandle 函式，並設定 fHandleType 為 SQL_HANDLE_ENV，驅動程式回傳錯誤。
IM005	驅動程式的 SQLAllocHandle 在 SQL_HANDLE_DBC 上失敗了。	（DM） 在 SQLDriverConnect 期間，驅動程式管理器呼叫驅動程式的 SQLAllocHandle 函式，並設定 fHandleType 為 SQL_HANDLE_DBC，驅動程式回傳錯誤。
IM006	驅動程式的 SQLSetConnectAttr 失敗	（DM） 在 SQLDriverConnect 期間，驅動程式管理器呼叫驅動程式的 SQLSetConnectAttr 函式，驅動程式回傳錯誤。
IM007	未指定資料來源或驅動程式;禁止對話	連接字串中未指定資料來源名稱或驅動程式，且驅動完成（DriverCompletion）SQL_DRIVER_NOPROMPT。
IM008	對話失敗	驅動程式嘗試顯示登入對話框但失敗了。 WindowHandle 是空指標， DriverCompletion 也未被 SQL_DRIVER_NO_PROMPT。
IM009	無法載入翻譯 DLL	驅動程式無法載入指定為資料來源或連線的轉換 DLL。
IM010	資料來源名稱太長了	（DM） DSN 關鍵字的屬性值超過 SQL_MAX_DSN_LENGTH 個字元。
IM011	車手名字太長	（DM） DRIVER 關鍵字的屬性值超過 255 字元。
IM012	DRIVER 關鍵字語法錯誤	（DM） DRIVER 關鍵字的關鍵字與值對包含語法錯誤。 （DM） *InConnectionString 中的字串包含 FILEDSN 關鍵字，但 .dsn 檔案中沒有 DRIVER 關鍵字或 DSN 關鍵字。
IM014	指定的 DSN 包含驅動程式與應用程式之間的架構不匹配	（DM） 32 位元應用程式使用 DSN 連接 64 位元驅動程式;反之亦然。
IM015	驅動程式的 SQLDriverConnect 在 SQL_HANDLE_DBC_INFO_HANDLE 上失敗	若驅動程式回SQL_ERROR，驅動程式管理員會將SQL_ERROR回應用程式，連線將失敗。 欲了解更多SQL_HANDLE_DBC_INFO_TOKEN資訊，請參閱《 ODBC駕駛員中培養 Connection-Pool 意識》。
IM017	在異步通知模式中停用輪詢	每當使用通知模型時，輪詢就會停用。
IM018	尚未呼叫 SQLCompleteAsync ，以完成此句柄上的先前異步操作。	如果句柄上的上一個函式呼叫傳回SQL_STILL_EXECUTING且啟用通知模式， 則必須在句柄上呼叫 SQLCompleteAsync ，才能執行後續處理並完成作業。
S1118	驅動程式不支援非同步通知	當驅動程式不支援非同步通知時，你無法設定SQL_ATTR_ASYNC_DBC_EVENT或SQL_ATTR_ASYNC_DBC_RETCODE_PTR。

評論

一個 連接字串 具有以下語法：

connection-string ：：= empty-string[;] | attribute[;] | 屬性; 連接串

空字串 ：：=屬性 ：：= 屬性-關鍵字=attribute-value |DRIVER=[{]attribute-value[}]

attribute-關鍵字 ：：= DSN |UID |身心障礙 | driver-defined-attribute-keyword

attribute-value ：：= 字串

driver-defined-attribute-keyword ：：= 識別碼

其中字串有零個或多個字元;識別碼包含一個或多個字元;attribute-keyword 不區分大小寫;屬性值可以區分大小寫;DSN 關鍵字的價值並非僅由空白組成。

由於 連接字串 和初始化檔案文法、關鍵字和屬性值包含字元 []{}（），;？*=！@ 未用支架包圍的物品應避免。 DSN 關鍵字的值不能只包含空白，也不應該包含前置空白。 由於系統資訊的文法，關鍵字與資料來源名稱無法包含反斜線（\）字元。

除非屬性包含分號（;)，否則應用程式不必在 DRIVER 關鍵字後的屬性值周圍加上大括號，此時則需要大括號。 如果驅動程式收到的屬性值包含大括號，驅動程式不應移除它們，但它們應該包含在回傳的連接字串中。

以大括號（{}）包圍的 DSN 或 連接字串 值，包含任一字元 []{}（），;？*=！@ 會完整傳給駕駛員。 然而，當在關鍵字中使用這些字元時，驅動程式管理器在處理檔案 DSN 時會回傳錯誤，但對於一般的連接字串，則會將 連接字串 傳給驅動程式。 避免在關鍵字值中使用嵌入的大括號。

連接字串可包含任意數量的驅動程式定義關鍵字。 由於 DRIVER 關鍵字不使用系統資訊，驅動程式必須定義足夠的關鍵字，使得驅動程式能僅用 連接字串 中的資訊連接資料來源。 （更多資訊請參見本節後面的「駕駛指引」。）驅動程式定義連接資料來源所需的關鍵字。

下表描述了 DSN、FILEDSN、DRIVER、UID、PWD 及 SAVEFILE 關鍵字的屬性值。

Keyword	屬性值描述
DSN	資料來源名稱由 SQLDataSources 回傳，或 SQLDriverConnect 的資料來源對話框。
檔案	一個 .dsn 檔案的名稱，從中建立資料來源的 連接字串。 這些資料來源稱為檔案資料來源。
駕駛員	SQLDrivers 函式回傳的驅動程式描述。 例如，Rdb 或 SQL Server。
UID	一個使用者ID。
PWD	密碼對應使用者 ID，或若沒有密碼則為空字串（PWD=;)。
存檔檔	.dsn 檔案的檔名，該檔案中用於建立目前成功連線的關鍵字屬性值應被儲存。

關於應用程式如何選擇資料來源或驅動程式的資訊，請參見 「選擇資料來源或驅動程式」。

如果 連接字串 中有任何關鍵字重複出現，驅動程式會使用該關鍵字首次出現時所對應的值。 如果 DSN 和 DRIVER 關鍵字包含在同一個 連接字串 中，驅動程式管理員與驅動程式會使用先出現的關鍵字。

FILEDSN 與 DSN 關鍵字互斥：先出現的關鍵字被使用，後出現的則忽略。 另一方面， FILEDSN 和 DRIVER 關鍵字並非互斥。 若 FILEDSN 的 連接字串 中出現任何關鍵字，則使用 連接字串 中該關鍵字的屬性值，而非 .dsn 檔案中相同關鍵字的屬性值。

若使用 FILEDSN 關鍵字，則使用 .dsn 檔案中指定的關鍵字來建立 連接字串。 （更多資訊請參見本節後面的「檔案資料來源」。） UID 關鍵字為可選;可以只用 DRIVER 關鍵字建立 .dsn 檔案。 PWD 關鍵字不會儲存在 .dsn 檔案中。 儲存與載入 .dsn 檔案的預設目錄會是 CommonFileDir 在 HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ Windows\CurrentVersion 中指定的路徑與「ODBC\DataSources」的組合。 （如果 CommonFileDir 是「C：\Program Files\Common Files」，預設目錄會是「C：\Program Files\Common Files\ODBC\Data Sources」。）

Note

.dsn 檔案可直接透過呼叫安裝程式 DLL 中的 SQLReadFileDSN 與 SQLWriteFileDSN 函式來操作。

若使用 SAVEFILE 關鍵字，用於建立目前成功連線的關鍵字屬性值將儲存為 .dsn 檔案，該檔案名稱為 SAVEFILE 關鍵字的屬性值。 SAVEFILE 關鍵字必須與 DRIVER 關鍵字、FILEDSN 關鍵字或兩者同時使用，否則函式會與 SQLSTATE 01S09（無效關鍵字）SQL_SUCCESS_WITH_INFO回傳。 SAVEFILE 關鍵字必須出現在 DRIVER 關鍵字之前，否則結果將連接字串未定義。

駕駛經理指引

驅動程式管理器會建構一個 連接字串，在驅動程式的 SQLDriverConnect 函式中，透過 InConnectionString 參數傳遞給驅動程式。 驅動程式管理器不會修改應用程式傳遞給它的 InConnectionString 參數。

驅動程式管理器的動作基於 DriverCompletion 參數的值：

• SQL_DRIVER_PROMPT：若連接字串中未包含 DRIVER、DSN 或 FILEDSN 關鍵字，驅動程式管理員會顯示資料來源對話框。 它會根據對話框回傳的資料來源名稱及應用程式傳遞給該框的其他關鍵字，構建一個連接字串。 如果對話框回傳的資料來源名稱為空，驅動程式管理員會指定關鍵字與值對 DSN=Default。 （此對話框不會顯示名為「Default」的資料來源。）

• SQL_DRIVER_COMPLETE或SQL_DRIVER_COMPLETE_REQUIRED：若應用程式指定的連接字串包含 DSN 關鍵字，驅動程式管理員會複製該應用程式指定的連接字串。 否則，它會採取與 DriverCompletion SQL_DRIVER_PROMPT相同的動作。

• SQL_DRIVER_NOPROMPT：驅動程式管理器會複製應用程式指定的連接字串。

如果應用程式指定的 連接字串 包含 DRIVER 關鍵字，驅動程式管理器會複製該應用程式指定的 連接字串。

利用它所建構的 連接字串，驅動程式管理器決定使用哪個驅動程式，連接到該驅動程式，並將所建構的 連接字串 傳給驅動程式;關於驅動程式管理器與驅動程式的互動，請參閱 SQLConnect 函式中的「註解」區塊。 如果 連接字串 沒有包含 DRIVER 關鍵字，驅動程式管理器會依下列方式決定要使用哪個驅動程式：

1. 如果 連接字串 包含 DSN 關鍵字，驅動程式管理員會從系統資訊中擷取與資料來源相關的驅動程式。

2. 若 連接字串 未包含 DSN 關鍵字或找不到資料來源，驅動程式管理員會從系統資訊中擷取與預設資料來源相關的驅動程式。 （更多資訊請參見預設子鍵。）驅動程式管理器會將 連接字串 中 DSN 關鍵字的值改為「DEFAULT」。

3. 若 連接字串 中的 DSN 關鍵字設為「DEFAULT」，驅動程式管理員會從系統資訊中擷取與預設資料來源相關的驅動程式。

4. 若找不到資料來源且未找到預設資料來源，驅動程式管理器會回傳 SQLSTATE IM002（找不到資料來源且未指定預設驅動程式）SQL_ERROR。

檔案數據源

如果應用程式在呼叫 SQLDriverConnect 時指定的 連接字串 包含 FILEDSN 關鍵字，且該關鍵字未被 DSN 或 DRIVER 關鍵字取代，則驅動程式管理器會利用 .dsn 檔案中的資訊及 InConnectionString 參數建立一個 連接字串。 駕駛經理的流程如下：

1. 檢查 .dsn 檔案的檔名是否有效。 若不符合，則回傳 SQLSTATE IM014（檔案名稱 DSN 無效）SQL_ERROR。 若檔名為空字串（“”）且未指定SQL_DRIVER_NOPROMPT，則會顯示 「檔案開啟 」對話框。 若檔名包含有效路徑但沒有檔名或檔名無效，且未指定SQL_DRIVER_NOPROMPT，則會顯示檔案 開啟 對話框，並顯示目前目錄為檔名中指定的目錄。 若檔名為空字串（“”），或檔名包含有效路徑但無檔名或檔名無效，且指定SQL_DRIVER_NOPROMPT，則SQL_ERROR會回傳 SQLSTATE IM014（檔案 DSN 名稱無效）。

2. 讀取 .dsn 檔案中 [ODBC] 區塊中的所有關鍵字。 若不存在 DRIVER 關鍵字，則會回SQL_ERROR傳 SQLSTATE IM012（Driver 關鍵字語法錯誤），除非 .dsn 檔案無法共享，僅包含 DSN 關鍵字。

   若檔案資料來源不可共享，驅動程式管理器會讀取 DSN 關鍵字的值，並視需要連接至不可共享檔案來源所指向的使用者或系統資料來源。 步驟3到5則不執行。

3. 為驅動程式構建一個 連接字串。 驅動程式 連接字串 是 .dsn 檔案中指定的關鍵字與原始應用程式 連接字串 中指定的關鍵字的合併。 關鍵字重疊的驅動程式 連接字串 建構規則如下：

   • 若 DRIVER 關鍵字存在於應用程式 連接字串 中，且 DRIVER 關鍵字指定的驅動程式在 .dsn 檔案與應用程式 連接字串 中不相同，則忽略 .dsn 檔案中的驅動程式資訊，改用應用程式 連接字串 中的驅動程式資訊。 如果 DRIVER 關鍵字指定的驅動程式在 .dsn 檔案中與應用程式的 連接字串 相同，則當所有關鍵字重疊時，應用程式 連接字串 中指定的驅動程式優先於 .dsn 檔案中指定的。

   • 在新的 連接字串 中，FILEDSN 關鍵字被刪除。

4. 透過在 Driver Name<\Driver 登錄檔 HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\>中尋找驅動程式，<該>欄位由 DRIVER 關鍵字指定驅動程式名稱。

5. 將新的連接線傳給驅動器。

關於 .dsn 檔案的範例，請參見 使用檔案資料來源連接。

SAVEFILE 關鍵字

如果應用程式指定的 連接字串 包含 SAVEFILE 關鍵字，則驅動程式管理員會將該 連接字串 儲存在 .dsn 檔案中。 駕駛經理的流程如下：

1. 檢查 SAVEFILE 關鍵字屬性值所包含的 .dsn 檔案名稱是否有效。 若不符合，則回傳 SQLSTATE IM014（檔案名稱 DSN 無效）SQL_ERROR。 檔案名稱的有效性由標準系統命名規則決定。 如果檔名是空字串（“”）且 DriverCompletion 參數未SQL_DRIVER_NOPROMPT，則該檔名有效。 如果檔名已經存在，則若 DriverCompletion 被SQL_DRIVER_NOPROMPT，該檔案會被覆寫。 若 DriverCompletion 為 SQL_DRIVER_PROMPT、SQL_DRIVER_COMPLETE 或 SQL_DRIVER_COMPLETE_REQUIRED，則會跳出對話框，提示使用者指定是否應該覆寫該檔案。 若輸入「否」，則會出現 檔案儲存 對話框。

2. 若驅動程式回傳 SQL_SUCCESS 且檔名非空字串，驅動程式管理器會將 OutConnectionString 參數中回傳的連線資訊寫入指定檔案，格式為本節前述「連線字串」章節所指定的格式。

3. 若驅動程式回傳 SQL_SUCCESS 且檔名為空字串（“”），則驅動程式管理員會呼叫指定 hwnd 的 File-Save 公共對話框，並將 OutConnectionString 中回傳的連線資訊寫入本節前述「連線字串」章節中指定的 File-Save 共用對話框中指定的檔案。

4. 若驅動返回 SQL_SUCCESS，則回傳包含 連接字串 的 OutConnectionString 參數給應用程式。

5. 若驅動程式回傳 SQL_SUCCESS_WITH_INFO 或 SQL_ERROR，驅動程式管理器會將 SQLSTATE 回傳給應用程式。

駕駛指引

驅動程式會檢查由驅動程式管理器傳遞給它的 連接字串 是否包含 DSN 或 DRIVER 關鍵字。 若 連接字串 包含 DRIVER 關鍵字，驅動程式無法從系統資訊中取得資料來源資訊。 如果 連接字串 包含 DSN 關鍵字，或不包含 DSN 或 DRIVER 關鍵字，驅動程式可從系統資訊中取得資料來源資訊，方法如下：

1. 若 連接字串 包含 DSN 關鍵字，驅動程式會取得指定資料來源的資訊。

2. 若 連接字串 未包含 DSN 關鍵字、找不到指定的資料來源，或 DSN 關鍵字設為「DEFAULT」，驅動程式會取得預設資料來源的資訊。

驅動程式會利用從系統資訊中擷取的任何資訊，來補充 連接字串 中傳遞給它的資訊。 如果系統資訊中的資訊與 連接字串 中的資訊重複，驅動程式會使用該 連接字串 中的資訊。

根據 DriverCompletion 的值，驅動程式會提示使用者輸入連線資訊，如使用者 ID 與密碼，並連接到資料來源：

• SQL_DRIVER_PROMPT：驅動程式會顯示一個對話框，使用連接字串和系統資訊（如有）的值作為初始值。 當使用者退出對話框時，驅動程式會連接到資料來源。 它也會根據 *InConnectionString 中的 DSN 或 DRIVER 關鍵字值與對話框回傳的資訊，構建一個 連接字串。 它會將這個 連接字串 放在 *OutConnectionString 緩衝區。

• SQL_DRIVER_COMPLETE或SQL_DRIVER_COMPLETE_REQUIRED：如果連接字串包含足夠資訊且該資訊正確，驅動程式會連接到資料來源，並將 *InConnectionString 複製到 *OutConnectionString。 若有任何資訊缺失或錯誤，驅動程式採取與 DriverCompletion SQL_DRIVER_PROMPT相同的操作，但若 DriverCompletion SQL_DRIVER_COMPLETE_REQUIRED，則會停用所有非連接資料來源所需資訊的控制。

• SQL_DRIVER_NOPROMPT：如果連接字串包含足夠資訊，驅動程式會連接到資料來源，並將 *InConnectionString 複製到 *OutConnectionString。 否則，驅動程式會回傳 SQL_ERROR SQLDriverConnect。

成功連接資料來源後，驅動程式也會將 *StringLength2Ptr 設為輸出 連接字串 的長度，該長度可返回於 *OutConnectionString。

若使用者取消驅動程式管理器或驅動程式所呈現的對話框， SQLDriverConnect 會回傳SQL_NO_DATA。

關於驅動程式管理器與驅動程式在連線過程中互動的資訊，請參見 SQLConnect 函式。

若驅動程式支援 SQLDriverConnect，則該驅動程式系統資訊中的驅動關鍵字區塊必須包含 ConnectFunctions 關鍵字，第二個字元設為「Y」。

啟用連線池時的連線

連線池允許應用程式重用已建立的連線。 當呼叫 SQLDriverConnect 時，驅動程式管理器會嘗試使用一個位於指定為連線池的連線池中的連線。 欲了解更多連線池的資訊，請參閱 SQLConnect 函式。

應用程式可以在啟用池化連線時呼叫 SQLDisconnect 前設定 SQL_ATTR_RESET_CONNECTION。 如需詳細資訊，請參閱 SQLSetConnectAttr 函式。

當應用程式呼叫 SQLDriverConnect 連接至池化連線時，會受到以下限制：

• 當 連接字串 中指定 SAVEFILE 關鍵字時，不會執行連線池處理。

• 若啟用連線池， SQLDriverConnect 只能以 DriverCompletion 參數為 SQL_DRIVER_NOPROMPT 來呼叫;若 SQLDriverConnect 被呼叫其他驅動 完成，則會回傳 SQLSTATE HY110（無效驅動完成）。

連接屬性

SQL_ATTR_LOGIN_TIMEOUT 連線屬性使用 SQLSetConnectAttr，定義了等待登入請求完成並由驅動程式成功連線後，返回應用程式的秒數。 若使用者被要求完成 連接字串，則從驅動程式啟動連線程序時，每個登入請求的等待期即開始。

驅動程式預設會以SQL_MODE_READ_WRITE存取模式開啟連線。 若要將存取模式設為 SQL_MODE_READ_ONLY，應用程式必須在呼叫 SQLDriverConnect 前，先以 SQL_ATTR_ACCESS_MODE 屬性呼叫 SQLSetConnectAttr。

如果資料來源的系統資訊中指定了預設的轉譯函式庫，驅動程式會載入該函式庫。 透過呼叫帶有 SQL_ATTR_TRANSLATE_LIB 屬性的 SQLSetConnectAttr 來載入不同的轉譯函式庫。 轉換選項可透過呼叫 SQLSetConnectAttr 並設定 SQL_ATTR_TRANSLATE_OPTION 選項來指定。

欲了解更多資訊，請參閱 「與 SQLDriverConnect 連結」。

// SQLDriverConnect_ref.cpp  
// compile with: odbc32.lib user32.lib  
#include <windows.h>  
#include <sqlext.h>  
  
int main() {  
   SQLHENV henv;  
   SQLHDBC hdbc;  
   SQLHSTMT hstmt;  
   SQLRETURN retcode;  
  
   SQLCHAR OutConnStr[255];  
   SQLSMALLINT OutConnStrLen;  
  
   HWND desktopHandle = GetDesktopWindow();   // desktop's window handle  
  
   // Allocate environment handle  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
  
   // Set the ODBC version environment attribute  
   if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
      retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);   
  
      // Allocate connection handle  
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
         retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);   
  
         // Set login timeout to 5 seconds  
         if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
            SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);  
  
            retcode = SQLDriverConnect( // SQL_NULL_HDBC  
               hdbc,   
               desktopHandle,   
               (SQLCHAR*)"driver=SQL Server",   
               _countof("driver=SQL Server"),  
               OutConnStr,  
               255,   
               &OutConnStrLen,  
               SQL_DRIVER_PROMPT );  
  
            // Allocate statement handle  
            if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {                 
               retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);   
  
               // Process data  
               if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
                  SQLFreeHandle(SQL_HANDLE_STMT, hstmt);  
               }  
  
               SQLDisconnect(hdbc);  
            }  
  
            SQLFreeHandle(SQL_HANDLE_DBC, hdbc);  
         }  
      }  
      SQLFreeHandle(SQL_HANDLE_ENV, henv);  
   }  
}  

另請參閱 ODBC範例課程。

相關職能

如需有關	看！
分配帳柄	SQLAllocHandle 函數
發現並列舉連接資料來源所需的數值	SQLBrowseConnect 函式
連線至資料來源	SQLConnect 函式
斷開與資料來源的連接	SQLDisconnect 函式
回歸車手描述與屬性	SQLDrivers 函式
釋放把手	SQLFreeHandle 函數
設定連線屬性	SQLSetConnectAttr 函式

相關內容

• ODBC API 參考
• ODBC 標頭檔