SQLDriverConnect 函式
一致性
引進的版本：ODBC 1.0 標準合規性：ODBC
摘要
SQLDriverConnect 是 SQLConnect 的 替代方案。 它支援需要比 SQLConnect 中 三個引數更多的連接資訊、對話方塊來提示使用者輸入所有連接資訊，以及系統資訊中未定義的資料來源。 如需詳細資訊，請參閱 使用 SQLDriverConnect 連線。
語法
SQLRETURN SQLDriverConnect(
SQLHDBC ConnectionHandle,
SQLHWND WindowHandle,
SQLCHAR * InConnectionString,
SQLSMALLINT StringLength1,
SQLCHAR * OutConnectionString,
SQLSMALLINT BufferLength,
SQLSMALLINT * StringLength2Ptr,
SQLUSMALLINT DriverCompletion);
引數
ConnectionHandle
[輸入] 連線控制代碼。
WindowHandle
[輸入]視窗控制碼。 如果適用，應用程式可以傳遞父視窗的控制碼，如果視窗控制碼不適用，或 SQLDriverConnect 將不會顯示任何對話方塊，則為 Null 指標。
InConnectionString
[輸入]完整連接字串（請參閱「批註」中的語法）、部分連接字串或空字串。
StringLength1
[輸入]* InConnectionString 的長度，如果字串為 Unicode，則為字元，如果字串為 ANSI 或 DBCS，則為位元組。
OutConnectionString
[輸出]已完成連接字串之緩衝區的指標。 成功連線至目標資料來源時，此緩衝區會包含已完成的連接字串。 應用程式應該為此緩衝區至少配置 1，024 個字元。
如果 OutConnectionString 為 Null， StringLength2Ptr 仍會傳回字元總數（不包括字元資料的 Null 終止字元），以在 OutConnectionString 所 指向的緩衝區中傳回。
BufferLength
[輸入]* OutConnectionString 緩衝區的長度，以字元為單位。
StringLength2Ptr
[輸出]緩衝區的指標，用來傳回可在 * OutConnectionString 中傳回的字元總數（不包括 Null 終止字元）。 如果可用傳回的字元數大於或等於 BufferLength ，則 * OutConnectionString 中已完成的連接字串會截斷為 BufferLength 減去 Null 終止字元的長度。
DriverCompletion
[輸入]指出驅動程式管理員或驅動程式是否必須提示輸入更多連線資訊的旗標：
SQL_DRIVER_PROMPT、SQL_DRIVER_COMPLETE、SQL_DRIVER_COMPLETE_REQUIRED或SQL_DRIVER_NOPROMPT。
（如需其他資訊，請參閱）
傳回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_ERROR、SQL_INVALID_HANDLE或SQL_STILL_EXECUTING。
診斷
當 SQLDriverConnect 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，可以使用 SQL_HANDLE_DBC 的 fHandleType 和 ConnectionHandle 的 hHandle 呼叫 SQLGetDiagRec 來取得相關聯的 SQLSTATE 值。 下表列出 SQLDriverConnect 通常傳 回的 SQLSTATE 值，並說明此函式內容中的每個值;標記法 「（DM）」 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。
| SQLSTATE | 錯誤 | 描述 |
|---|---|---|
| 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。 *szMessageText 緩衝區中 SQLGetDiagRec 傳 回的錯誤訊息描述錯誤及其原因。 |
| HY000 | 一般錯誤：不正確檔案 dsn | （DM） * InConnectionString 中的字串包含 FILESN 關鍵字，但找不到 .dsn 檔案的名稱。 |
| HY000 | 一般錯誤：無法建立檔案緩衝區 | （DM） * InConnectionString 中的字串包含 FILESN 關鍵字，但 .dsn 檔案無法讀取。 |
| HY001 | 記憶體配置錯誤 | 驅動程式管理員無法配置支援 SQLDriverConnect 函式執行或完成 所需的記憶體。 驅動程式無法配置支援執行或完成函式所需的記憶體。 |
| HY008 | 作業已取消 | ConnectionHandle 已啟用 非同步處理。 已呼叫函式，並在完成執行之前， 在 ConnectionHandle 上 呼叫 SQLCancelHandle 函式，然後在 ConnectionHandle 上 再次呼叫 SQLDriverConnect 函 式。 或者，呼叫 SQLDriverConnect 函式，並在完成執行之前， 從多執行緒應用程式中的不同執行緒呼叫 SQLCancelHandle 。 |
| HY010 | 函式順序錯誤 | （DM） 另一個非同步執行的函式 （不是 SQLDriverConnect ） 已針對 ConnectionHandle 呼叫 ，而且在呼叫 SQLDriverConnect 函式時 仍在執行中。 |
| HY013 | 記憶體管理錯誤 | 無法處理 SQLDriverConnect 函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。 |
| HY090 | 不正確字串或緩衝區長度 | （DM） 為引數 StringLength1 指定的值小於 0，且不等於SQL_NTS。 （DM） 為引數 BufferLength 指定的值小於 0。 |
| HY092 | 不正確屬性/選項識別碼 | （DM） DriverCompletion 引數已SQL_DRIVER_PROMPT，而 WindowHandle 引數為 Null 指標。 |
| 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 | SQL_HANDLE_ENV上的驅動程式 SQLAllocHandle 失敗 | （DM） 在 SQLDriverConnect 期間 ，驅動程式管理員會使用 SQL_HANDLE_ENV fHandleType 的 fHandleType 呼叫驅動程式的 SQLAllocHandle 函式，而驅動程式傳回錯誤。 |
| IM005 | SQL_HANDLE_DBC上的驅動程式 SQLAllocHandle 失敗。 | （DM） 在 SQLDriverConnect 期間 ，驅動程式管理員會使用 SQL_HANDLE_DBC fHandleType 的 fHandleType 呼叫驅動程式的 SQLAllocHandle 函式，而驅動程式傳回錯誤。 |
| IM006 | 驅動程式的 SQLSetConnectAttr 失敗 | （DM） 在 SQLDriverConnect 期間 ，驅動程式管理員稱為驅動程式的 SQLSetConnectAttr 函式，而驅動程式傳回錯誤。 |
| IM007 | 未指定資料來源或驅動程式;對話方塊禁止 | 連接字串中未指定資料來源名稱或驅動程式，且 驅動程式Completion SQL_DRIVER_NOPROMPT。 |
| IM008 | 對話方塊失敗 | 驅動程式嘗試顯示其登入對話方塊並失敗。 WindowHandle 是 Null 指標，且 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 中的 字串包含 FILESN 關鍵字，但 .dsn 檔案不包含 DRIVER 關鍵字或 DSN 關鍵字。 |
| IM014 | 指定的 DSN 包含驅動程式與應用程式之間的架構不符 | （DM） 32 位應用程式使用連線到 64 位驅動程式的 DSN;反之亦然。 |
| IM015 | SQL_HANDLE_DBC_INFO_HANDLE上的驅動程式 SQLDriverConnect 失敗 | 如果驅動程式傳回SQL_ERROR，驅動程式管理員會將SQL_ERROR傳回應用程式，而連線將會失敗。 如需SQL_HANDLE_DBC_INFO_TOKEN的詳細資訊，請參閱 在 ODBC 驅動程式 中開發連線集區感知。 |
| 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 ; connection-string
empty-string ：：= attribute ：：= attribute-keyword = attribute-value |DRIVER=[{] attribute-value [}]
attribute-keyword ：：= DSN |UID |PWD | driver-defined-attribute-keyword
attribute-value ：：= character-string
driver-defined-attribute-keyword ：：= identifier
其中 字元字串 有零個或多個字元; 識別碼 有一或多個字元; attribute-keyword 不區分大小寫; 屬性值可能會區分大小寫;而 DSN 關鍵字的值 不只包含空白。
因為連接字串和初始化檔案文法、關鍵字和屬性值包含字元 [] {} （），;？應避免使用大括弧括住 *=！@ 。 DSN 關鍵字的值不能只包含空白，而且不應該包含前置空白。 由於系統資訊的文法，關鍵字和資料來源名稱不能包含反斜線 （\） 字元。
除非屬性包含分號（;)，否則應用程式不必在 DRIVER 關鍵字後面 加上大括弧。在此情況下，需要大括弧。 如果驅動程式接收的屬性值包含大括弧，則驅動程式不應該移除它們，但應該是傳回連接字串的一部分。
以大括弧 （ {} ） 括住的 DSN 或連接字串值，其中包含任何字元 [] {} （），;？*=！@ 會完整傳遞至驅動程式。 不過，在關鍵字中使用這些字元時，驅動程式管理員會在使用檔案 DSN 時傳回錯誤，但將連接字串傳遞至驅動程式以進行一般連接字串。 避免在關鍵字值中使用內嵌大括弧。
連接字串可能包含任意數目的驅動程式定義關鍵字。 因為 DRIVER 關鍵字不使用系統資訊的資訊，所以驅動程式必須定義足夠的關鍵字，讓驅動程式只能使用連接字串中的資訊連接到資料來源。 （如需詳細資訊，請參閱本節稍後的。驅動程式會定義連線至資料來源所需的關鍵字。
下表描述 DSN 、FILEDSN 、 DRIVER 、 UID 、 PWD 和 SAVEFILE 關鍵字的屬性值 。
| 關鍵字 | 屬性值描述 |
|---|---|
| DSN | SQLDataSources 所 傳回的資料來源名稱，或 SQLDriverConnect 的 資料來源對話方塊。 |
| FILEDSN | 將針對資料來源建置連接字串的 .dsn 檔案名稱。 這些資料來源稱為檔案資料來源。 |
| 司機 | SQLDrivers 函式所傳回的 驅動程式描述。 例如，Rdb 或 SQL Server。 |
| UID | 使用者識別碼。 |
| PWD | 對應至使用者識別碼的密碼，如果沒有使用者識別碼的密碼，則為空字串（PWD=;)。 |
| SAVEFILE | .dsn 檔案的檔案名，其中應該儲存在進行目前成功連線時所使用的關鍵字屬性值。 |
如需應用程式如何選擇資料來源或驅動程式的資訊，請參閱 選擇資料來源或驅動程式 。
如果連接字串中重複任何關鍵字，驅動程式會使用與關鍵字第一次出現相關聯的值。 如果 DSN 和 DRIVER 關鍵字包含在相同的連接字串中，驅動程式管理員和驅動程式會先使用哪一個關鍵字。
FILEDSN 和 DSN 關鍵字互斥：會先使用哪一個關鍵字，並忽略第二個出現的關鍵字。 另一方面，FILEDSN 和 DRIVER 關鍵字並不互斥。 如果有任何關鍵字出現在具有 FILEDSN 的連接字串中，則會使用連接字串中的 關鍵字屬性值，而不是 .dsn 檔案中相同關鍵字的屬性值。
如果使用 FILESN 關鍵字，則會使用 .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」。
注意
在安裝程式 DLL 中呼叫 SQLReadFileDSN 和 SQLWriteFileDSN 函式，即可直接操作 .dsn 檔案。
如果使用 SAVEFILE 關鍵字，則用於進行目前時，成功連線的關鍵字屬性值將會儲存為 .dsn 檔案，其屬性值為 SAVEFILE 關鍵字的 屬性值。 SAVEFILE 關鍵字必須與 DRIVER 關鍵字、 FILEDSN 關鍵字或兩者搭配 使用，或者函式會使用 SQLSTATE 01S09 傳回SQL_SUCCESS_WITH_INFO （Invalid 關鍵字）。 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 關鍵字，Driver Manager 會複製應用程式指定的連接字串。
使用它所建構的連接字串，驅動程式管理員會決定要使用的驅動程式、連接到該驅動程式，並將它所建構的連接字串傳遞給驅動程式;如需驅動程式管理員和驅動程式互動的詳細資訊，請參閱 SQLConnect 函 式中的 一節。 如果連接字串不包含 DRIVER 關鍵字，驅動程式管理員會決定要使用的驅動程式，如下所示：
如果連接字串包含 DSN 關鍵字，驅動程式管理員會從系統資訊擷取與資料來源相關聯的驅動程式。
如果連接字串不包含 DSN 關鍵字或找不到資料來源，驅動程式管理員會從系統資訊擷取與預設資料來源相關聯的驅動程式。 （如需詳細資訊，請參閱 預設子機碼 。）驅動程式管理員會將連接字串中的 DSN 關鍵字值 變更為 「DEFAULT」。
如果連接字串中的 DSN 關鍵字設定為 「DEFAULT」，驅動程式管理員會從系統資訊擷取與 Default 資料來源相關聯的驅動程式。
如果找不到資料來源且找不到預設資料來源，驅動程式管理員會傳回SQL_ERROR SQLSTATE IM002 （找不到資料來源，也沒有指定預設驅動程式）。
檔案資料來源
如果呼叫 SQLDriverConnect 中應用程式所指定的連接字串包含 FILEDSN 關鍵字，而且 DSN 或 DRIVER 關鍵字不會取代 此關鍵字，則 Driver Manager 會使用 .dsn 檔案和 InConnectionString 引數中的資訊來建立連接字串。 驅動程式管理員會繼續進行，如下所示：
檢查 .dsn 檔案的檔案名是否有效。 如果沒有，它會使用 SQLSTATE IM014 傳回SQL_ERROR（不正確 DSN 檔案名）。 如果檔案名是空字串 （「」） 且未指定SQL_DRIVER_NOPROMPT，則會 顯示 [檔案開啟 ] 對話方塊。 如果檔案名包含有效的路徑，但沒有檔案名或不正確檔案名，且未指定SQL_DRIVER_NOPROMPT，則 [檔案 開啟] 對話方塊會顯示為檔案名中所指定目錄的目前目錄。 如果檔案名是空字串 （「」） 或檔案名包含有效的路徑，但沒有檔案名或不正確檔案名，而且指定了SQL_DRIVER_NOPROMPT，則會使用 SQLSTATE IM014 傳回SQL_ERROR （檔案名不正確 DSN）。
讀取 .dsn 檔案之 [ODBC] 區段中的所有關鍵詞。 如果 DRIVER 關鍵字不存在，它會以 SQLSTATE IM012 傳回SQL_ERROR（Driver 關鍵字語法錯誤），但 .dsn 檔案無法共用，因此只 包含 DSN 關鍵字。
如果檔案資料來源無法共用，驅動程式管理員會讀取 DSN 關鍵字的值 ，並視需要連接到無法共用檔案資料來源所指向的使用者或系統資料來源。 不會執行步驟 3 到 5。
建構驅動程式的連接字串。 驅動程式連接字串是 .dsn 檔案中指定的關鍵字聯集，以及原始應用程式連接字串中指定的關鍵字聯集。 驅動程式連接字串建構的規則，其中關鍵字重迭如下：
如果 DRIVER 關鍵字存在於應用程式連接字串中，而 DRIVER 關鍵字所 指定的驅動程式在 .dsn 檔案和應用程式連接字串中並不相同，則會忽略 .dsn 檔案中的驅動程式資訊，並使用應用程式連接字串中的驅動程式資訊。 如果 DRIVER 關鍵字所 指定的驅動程式在 .dsn 檔案和應用程式的連接字串中相同，則所有關鍵詞重迭的位置，則應用程式連接字串中指定的驅動程式優先于 .dsn 檔案中指定的驅動程式。
在新連接字串中， 會消除 FILEDSN 關鍵字。
在登錄專案HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST 中尋找來載入驅動程式。INI\ < Driver Name\Driver，其中 < Driver Name >> 是由 DRIVER 關鍵字所指定。
傳遞驅動程式新的連接字串。
如需 .dsn 檔案的範例，請參閱 使用檔案資料來源 連接。
SAVEFILE 關鍵字
如果應用程式指定的連接字串包含 SAVEFILE 關鍵字，則 Driver Manager 會將連接字串儲存在 .dsn 檔案中。 驅動程式管理員會繼續進行，如下所示：
檢查包含為 SAVEFILE 關鍵字屬性值之 .dsn 檔案的 檔案名是否有效。 如果沒有，它會使用 SQLSTATE IM014 傳回SQL_ERROR（不正確 DSN 檔案名）。 檔案名的有效性取決於標準系統命名規則。 如果檔案名是空字串 （「」） 且 DriverCompletion 引數未SQL_DRIVER_NOPROMPT，則檔案名有效。 如果檔案名已經存在，則如果 DriverCompletion 已SQL_DRIVER_NOPROMPT，則會覆寫檔案。 如果 DriverCompletion 是SQL_DRIVER_PROMPT、SQL_DRIVER_COMPLETE或SQL_DRIVER_COMPLETE_REQUIRED，對話方塊會提示使用者指定是否應該覆寫檔案。 如果輸入 [否]，則會出現 [ 檔案儲存 ] 對話方塊。
如果驅動程式傳回SQL_SUCCESS，而且檔案名不是空字串，則 Driver Manager 會將 OutConnectionString 引數中 傳回的連接資訊寫入至本節稍早的「連接字串」區段中所指定格式的指定檔案。
如果驅動程式傳回SQL_SUCCESS且檔案名是空字串 （「），則驅動程式管理員會呼叫 具有 指定 hwnd 的 File-Save 一般對話方塊，並將 OutConnectionString 中所 傳回的連接資訊寫入到本節稍早的 」Connection Strings「 區段中所指定的檔案。
如果驅動程式傳回SQL_SUCCESS，它會傳 回 OutConnectionString 引數，其中包含應用程式的連接字串。
如果驅動程式傳回SQL_SUCCESS_WITH_INFO或SQL_ERROR，則驅動程式管理員會將 SQLSTATE 傳回應用程式。
驅動程式指導方針
驅動程式會檢查驅動程式管理員傳遞給它的連接字串是否包含 DSN 或 DRIVER 關鍵字。 如果連接字串包含 DRIVER 關鍵字，驅動程式就無法從系統資訊擷取資料來源的相關資訊。 如果連接字串包含 DSN 關鍵字或不包含 DSN 或 DRIVER 關鍵字，驅動程式可以從系統資訊擷取資料來源的相關資訊，如下所示：
如果連接字串包含 DSN 關鍵字，驅動程式會擷取指定資料來源的資訊。
如果連接字串不包含 DSN 關鍵字，則找不到指定的資料來源，或 DSN 關鍵字設定為 「DEFAULT」，驅動程式會擷取 Default 資料來源的資訊。
驅動程式會使用從系統資訊擷取的任何資訊，以增強連接字串中傳遞給它的資訊。 如果系統資訊中的資訊重複連接字串中的資訊，驅動程式會使用連接字串中的資訊。
根據 DriverCompletion 的值 ，驅動程式會提示使用者輸入連線資訊，例如使用者識別碼和密碼，並聯機到資料來源：
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 。 否則，驅動程式會傳 回 SQLDriverConnect 的SQL_ERROR。
成功連線至資料來源時，驅動程式也會將 * StringLength2Ptr 設定為可在 * OutConnectionString 中傳回的輸出連接字串長度。
如果使用者取消驅動程式管理員或驅動程式所呈現的對話方塊， SQLDriverConnect 會傳回SQL_NO_DATA。
如需驅動程式管理員和驅動程式在連線過程中互動方式的相關資訊，請參閱 SQLConnect 函式 。
如果驅動程式支援 SQLDriverConnect ，驅動程式的系統資訊驅動程式關鍵字區段必須包含 ConnectFunctions 關鍵字，並將第二個字元設定為 「Y」。
啟用連線共用時連線
連線共用可讓應用程式重複使用已建立的連接。 呼叫 SQLDriverConnect 時 ，驅動程式管理員會嘗試使用連接，該連接是已指定用於連接共用的環境中連接集區的一部分。 如需連線共用的詳細資訊，請參閱 SQLConnect 函式 。
應用程式可以在啟用共用的連線上呼叫 SQLDisconnect 之前，先設定SQL_ATTR_RESET_CONNECTION。 如需詳細資訊，請參閱 SQLSetConnectAttr 函式 。
當應用程式呼叫 SQLDriverConnect 以連線到集區連線時，適用下列限制：
當連接字串中指定 SAVEFILE 關鍵字時 ，不會執行連線共用處理。
如果啟用連線共用， 則只能使用 SQL_DRIVER_NOPROMPT 的 DriverCompletion 引數呼叫 SQLDriverConnect ;如果 以任何其他 DriverCompletion 呼叫 SQLDriverConnect ，則會傳回 SQLSTATE HY110 （不正確驅動程式完成）。
連接屬性
使用 SQLSetConnectAttr 設定 SQL_ATTR_LOGIN_TIMEOUT連接屬性會定義等待驅動程式成功連接完成登入要求的秒數，再返回應用程式。 如果系統提示使用者完成連接字串，則驅動程式啟動連線程式時，會開始每個登入要求的等候期間。
驅動程式預設會以SQL_MODE_READ_WRITE存取模式開啟連線。 若要將存取模式設定為 SQL_MODE_READ_ONLY，應用程式必須在呼叫 SQLDriverConnect 之前，使用 SQL_ATTR_ACCESS_MODE 屬性呼叫 SQLSetConnect 。
如果在資料來源的系統資訊中指定預設翻譯程式庫，驅動程式就會載入它。 藉由使用 SQL_ATTR_TRANSLATE_LIB 屬性呼叫 SQLSetConnectAttr ，即可載入不同的翻譯程式庫。 您可以使用 SQL_ATTR_TRANSLATE_OPTION 選項呼叫 SQLSetConnectAttr 來指定翻譯選項。
如需詳細資訊，請參閱 使用 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 函式 |
另請參閱
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應