SQLDriverConnect 函式

文章
08/21/2023

一致性
引進的版本：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 函式

另請參閱

ODBC API 參考
 ODBC 標頭檔

分享方式：

SQLDriverConnect 函式

語法

引數

傳回

診斷

註解

驅動程式管理員指導方針

檔案資料來源

SAVEFILE 關鍵字

驅動程式指導方針

啟用連線共用時連線

連接屬性

另請參閱

意見反映

更多資源

分享方式：

SQLDriverConnect 函式

語法

引數

傳回

診斷

註解

驅動程式管理員指導方針

檔案資料來源

SAVEFILE 關鍵字

驅動程式指導方針

啟用連線共用時連線

連接屬性

相關函數

另請參閱

意見反映

更多資源