SQLConnect 函式

發行項
08/21/2023

一致性
引進版本：ODBC 1.0 標準合規性：ISO 92

摘要
SQLConnect 會建立驅動程式和資料來源的連接。連接控制碼會參考資料源連線相關資訊的儲存，包括狀態、交易狀態和錯誤資訊。

語法

  
SQLRETURN SQLConnect(  
     SQLHDBC        ConnectionHandle,  
     SQLCHAR *      ServerName,  
     SQLSMALLINT    NameLength1,  
     SQLCHAR *      UserName,  
     SQLSMALLINT    NameLength2,  
     SQLCHAR *      Authentication,  
     SQLSMALLINT    NameLength3);

引數

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

ServerName
[輸入]資料來源名稱。資料可能和程式位於相同的電腦上，也可能位於網路內的其他電腦上。如需應用程式如何選擇資料來源的資訊，請參閱選擇資料來源或驅動程式。

NameLength1
[輸入]字元的 * ServerName 長度。

UserName
[輸入]使用者識別碼。

NameLength2
[輸入]字元的 * UserName 長度。

驗證
[輸入]驗證字串（通常是密碼）。

NameLength3
[輸入]* 以字元表示驗證 的長度。

傳回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_INVALID_HANDLE或SQL_STILL_EXECUTING。

診斷

當 SQLConnect 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，可以藉由呼叫 SQLGetDiagRec 搭配 SQL_HANDLE_DBC的 HandleType 和 ConnectionHandle 的 HandleHandle 來取得相關聯的 SQLSTATE 值。下表列出 SQLConnect 通常傳 回的 SQLSTATE 值，並說明此函式內容中的每個值;標記法「（DM）」在驅動程式管理員傳回的 SQLSTATE 描述之前。除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。

SQLSTATE	錯誤	描述
01000	一般警告	驅動程式特定的資訊訊息。（函式會傳回SQL_SUCCESS_WITH_INFO。）
01S02	選項值已變更	驅動程式不支援 SQLSetConnectAttr 中 ValuePtr 引數的指定值，並取代了類似的值。（函式會傳回SQL_SUCCESS_WITH_INFO。）
08001	用戶端無法建立連線	驅動程式無法與資料來源建立連線。
08002	使用中的連線名稱	（DM）指定的 ConnectionHandle 已經用來建立與資料來源的連線，而且連線仍在開啟，或使用者正在流覽連線。
08004	伺服器拒絕連線	資料來源拒絕基於實作定義的原因建立連線。
08S01	通訊連結失敗	驅動程式與驅動程式嘗試連線的資料來源之間的通訊連結在函式完成處理之前失敗。
28000	授權規格無效	為引數 UserName 指定的值，或針對引數 Authentication 指定的值違反資料來源所定義的限制。
HY000	一般錯誤	發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 MessageText 緩衝區中* SQLGetDiagRec 傳回的錯誤訊息描述錯誤及其原因。
HY001	記憶體配置錯誤	（DM）驅動程式管理員無法配置支援執行或完成函式所需的記憶體。
HY008	作業已取消	ConnectionHandle 已啟用非同步處理。已呼叫 SQLConnect 函式，並在完成執行之前，在 ConnectionHandle 上呼叫 SQLCancelHandle 函式，然後在 ConnectionHandle 上再次呼叫 SQLConnect 函式。或者，呼叫 SQLConnect 函式，並在完成執行之前，從多執行緒應用程式中的不同執行緒呼叫 SQLCancelHandle 。
HY010	函式順序錯誤	（DM）呼叫 ConnectionHandle 的非同步執行函式（不是此函式），而且在呼叫此函式時仍在執行中。
HY013	記憶體管理錯誤	無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。
HY090	不正確字串或緩衝區長度	（DM）為引數 NameLength1 、 NameLength2 或 NameLength3 指定的值小於 0，但不等於 SQL_NTS。（DM）為引數 NameLength1 指定的值超過資料來源名稱的最大長度。
HYT00	逾時已超過	查詢逾時期限在資料來源連線完成之前過期。逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_LOGIN_TIMEOUT。
HY114	驅動程式不支援連線層級非同步函式執行	（DM）應用程式在進行連接之前，已在連接控制碼上啟用非同步作業。不過，驅動程式不支援連接控制碼上的非同步作業。
HYT01	已超過連線逾時	在資料來源回應要求之前，連線逾時期限已過期。連線逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。
IM001	驅動程式不支援此函式	（DM）資料來源名稱所指定的驅動程式不支援函式。
IM002	找不到資料來源，也沒有指定預設驅動程式	（DM）在系統資訊中找不到引數 ServerName 中指定的資料來源名稱，也沒有預設的驅動程式規格。
IM003	指定的驅動程式無法連線到	（DM）找不到系統資訊中資料來源規格中列出的驅動程式，或因其他原因而無法連線。
IM004	SQL_HANDLE_ENV 上的驅動程式 SQLAllocHandle 失敗	（DM）在 SQLConnect 期間，驅動程式管理員會呼叫驅動程式的 SQLAllocHandle 函式，且具有 handleType 為 SQL_HANDLE_ENV，而驅動程式傳回錯誤。
IM005	SQL_HANDLE_DBC上的驅動程式 SQLAllocHandle 失敗	（DM）在 SQLConnect 期間，驅動程式管理員會呼叫驅動程式的 SQLAllocHandle 函式，且具有 handleType 為 SQL_HANDLE_DBC，而驅動程式傳回錯誤。
IM006	驅動程式的 SQLSetConnectAttr 失敗	在 SQLConnect 期間，驅動程式管理員稱為驅動程式的 SQLSetConnectAttr 函式，而驅動程式傳回錯誤。（函式會傳回SQL_SUCCESS_WITH_INFO。）
IM009	無法連線到翻譯 DLL	驅動程式無法連線到為數據源指定的翻譯 DLL。
IM010	資料來源名稱太長	（DM） *ServerName 超過SQL_MAX_DSN_LENGTH個字元。
IM014	指定的 DSN 包含驅動程式與應用程式之間的架構不符	（DM） 32 位應用程式使用連線到 64 位驅動程式的 DSN;反之亦然。
IM015	SQL_HANDLE_DBC_INFO_HANDLE 上的驅動程式 SQLConnect 失敗	如果驅動程式傳回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。

註解

如需應用程式為何使用 SQLConnect 的詳細資訊，請參閱使用 SQLConnect 進行連線。

驅動程式管理員不會連線到驅動程式，直到應用程式呼叫函式（ SQLConnect、 SQLDriverConnect 或 SQLBrowseConnect ）以連線到驅動程式為止。在那一點之前，驅動程式管理員會使用自己的控制碼並管理連接資訊。當應用程式呼叫連接函式時，驅動程式管理員會檢查驅動程式目前是否已連線至指定的 ConnectionHandle ：

如果驅動程式未連線，驅動程式管理員會連線到驅動程式，並使用 handleType 為 SQL_HANDLE_ENV 呼叫 SQLAllocHandle 、 SQLAllocHandle 的 HandleType 為 SQL_HANDLE_DBC、 SQLSetConnectAttr （如果應用程式指定任何連接屬性），以及驅動程式中的連接函式。驅動程式管理員會傳回 SQLSTATE IM006（驅動程式的 SQLSetConnectOption 失敗），如果驅動程式傳 回 SQLSetConnectAttr 的錯誤，則為連線函式傳回SQL_SUCCESS_WITH_INFO。如需詳細資訊，請參閱連接到資料來源或驅動程式。
如果指定的驅動程式已經連線到 ConnectionHandle ，驅動程式管理員只會呼叫驅動程式中的連接函式。在此情況下，驅動程式必須確定 ConnectionHandle 的所有連線屬性 都會維護其目前設定。
如果不同的驅動程式已連線，驅動程式管理員會呼叫 SQLFreeHandle ，其 HandleType 為 SQL_HANDLE_DBC，然後，如果沒有其他驅動程式在該環境中連線，則會呼叫 SQLFreeHandle，其會使用 已連線驅動程式中的 HandleType SQL_HANDLE_ENV 呼叫 SQLFreeHandle ，然後中斷該驅動程式的連線。然後，它會執行與驅動程式未連線時相同的作業。

驅動程式接著會配置控制碼並初始化本身。

當應用程式呼叫 SQLDisconnect 時，驅動程式管理員會在驅動程式呼叫 SQLDisconnect。不過，它不會中斷驅動程式的連線。這會將驅動程式保留在記憶體中，以供重複連線至資料來源的應用程式中斷連線。當應用程式使用 SQL_HANDLE_DBC HandleType 呼叫 SQLFreeHandle 時，Driver Manager 會呼叫 SQLFreeHandle ，其 HandleType 為 SQL_HANDLE_DBC，然後在 驅動程式中使用 handleType SQL_HANDLE_ENV SQLFreeHandle ，然後中斷驅動程式的連線。

ODBC 應用程式可以建立多個連線。

驅動程式管理員指導方針

* ServerName 的內容會影響驅動程式管理員和驅動程式一起運作的方式，以建立與資料來源的連線。

如果 * ServerName 包含有效的資料來源名稱，驅動程式管理員會在系統資訊中找到對應的資料來源規格，並連接到相關聯的驅動程式。驅動程式管理員會將每個 SQLConnect 引數傳遞至驅動程式。
如果找不到資料來源名稱或 ServerName 是 Null 指標，驅動程式管理員會找出預設資料來源規格，並連接到相關聯的驅動程式。驅動程式管理員會將未修改的 UserName 和 Authentication 引數傳遞至驅動程式 ，並針對 ServerName 引數傳遞「DEFAULT」。
如果 ServerName 引數為「DEFAULT」，驅動程式管理員會找出預設資料來源規格，並聯機到相關聯的驅動程式。驅動程式管理員會將每個 SQLConnect 引數傳遞至驅動程式。
如果找不到資料來源名稱或 ServerName 是 Null 指標，且預設資料來源規格不存在，驅動程式管理員會傳回具有 SQLSTATE IM002 的SQL_ERROR （找不到資料來源名稱，也沒有指定預設驅動程式）。

驅動程式管理員連線到驅動程式管理員之後，驅動程式可以在系統資訊中找到其對應的資料來源規格，並使用規格中的驅動程式特定資訊來完成其一組必要的連接資訊。

如果資料來源的系統資訊中指定了預設翻譯程式庫，驅動程式就會連線到該程式庫。使用 SQL_ATTR_TRANSLATE_LIB 屬性呼叫 SQLSetConnectAttr ，即可連線到不同的翻譯程式庫。您可以使用 SQL_ATTR_TRANSLATE_OPTION 屬性呼叫 SQLSetConnectAttr 來指定翻譯選項。

如果驅動程式支援 SQLConnect ，驅動程式的系統資訊驅動程式關鍵字區段必須包含 ConnectFunctions 關鍵字，並將第一個字元設定為「Y」。

連接共用

連線共用可讓應用程式重複使用已建立的連接。啟用連線共用並 呼叫 SQLConnect 時，驅動程式管理員會嘗試使用已指定用於連接共用的環境中連接集區中的連接來建立連線。此環境是共用環境，可供所有使用集區中連線的應用程式使用。

在環境配置之前，會先啟用連線共用，方法是呼叫 SQLSetEnvAttr 將SQL_ATTR_CONNECTION_POOLING設定為SQL_CP_ONE_PER_DRIVER（指定每個驅動程式最多一個集區）或SQL_CP_ONE_PER_HENV（指定每個環境最多一個集區）。 在此案例中，會呼叫 SQLSetEnvAttr ，並將 EnvironmentHandle 設定為 null，讓屬性成為進程層級屬性。如果SQL_ATTR_CONNECTION_POOLING設定為 SQL_CP_OFF，則會停用連線共用。

啟用連線共用之後， 會呼叫具有 handleType SQL_HANDLE_ENV 的 SQLAllocHandle 來配置環境。此呼叫所配置的環境是共用環境，因為已啟用連線共用。不過，在呼叫具有 SQL_HANDLE_DBC HandleType 的 SQLAllocHandle 之前，不會決定將使用的環境。

呼叫具有 handleType SQL_HANDLE_DBC 的 SQLAllocHandle 來配置連線。驅動程式管理員會嘗試尋找符合應用程式所設定環境屬性的現有共用環境。如果不存在這類環境，則會建立一個作為隱含 共用環境 。如果找到相符的共用環境，環境控制碼會傳回至應用程式，且其參考計數會遞增。

不過，在呼叫 SQLConnect 之前，不會決定將使用的連接。此時，驅動程式管理員會嘗試在連線集區中尋找符合應用程式所要求準則的現有連線。這些準則包括呼叫 SQLConnect 時所要求的連接選項（ServerName、 UserName 和 Authentication 關鍵字的值 ），以及呼叫具有 handleType SQL_HANDLE_DBC 的 SQLAllocHandle 之後 所設定的任何連接屬性。驅動程式管理員會根據集區中連接中的對應連接關鍵字和屬性，檢查這些準則。如果找到相符專案，則會使用集區中的連線。如果找不到相符專案，則會建立新的連線。

如果SQL_ATTR_CP_MATCH環境屬性設定為 SQL_CP_STRICT_MATCH，則比對必須與集區中的連接完全相符。如果SQL_ATTR_CP_MATCH環境屬性設定為SQL_CP_RELAXED_MATCH，則對 SQLConnect 呼叫中的連接選項必須相符，但並非所有連接屬性都必須相符。

當呼叫 SQLConnect 之前，應用程式所設定的連接屬性不符合集區中連接的連接屬性時，就會套用下列規則：

如果在建立連接之前必須設定連接屬性：

如果SQL_ATTR_CP_MATCH SQL_CP_STRICT_MATCH，集區連線中的SQL_ATTR_PACKET_SIZE必須與應用程式所設定的屬性相同。如果SQL_CP_RELAXED_MATCH，SQL_ATTR_PACKET_SIZE的值可能會不同。

SQL_ATTR_LOGIN_VALUE的值不會影響比對。
如果連接屬性可以在連接建立之前或之後設定：

如果應用程式尚未設定連接屬性，但已在集區中的連接上設定，而且有預設值，則集區連線中的連接屬性會設定回預設值，並宣告相符專案。如果沒有預設值，則共用連線不會被視為相符專案。

如果應用程式已設定連接屬性，但尚未在集區中的連接上設定，則集區上的連接屬性會變更為應用程式所設定的連線屬性，並宣告相符專案。

如果應用程式已設定連接屬性，而且也已在集區中的連接上設定，但值不同，則會使用應用程式的連接屬性值，並宣告相符專案。
如果驅動程式特定連接屬性的值不相同，且SQL_ATTR_CP_MATCH設定為 SQL_CP_STRICT_MATCH，就不會使用集區中的連線。

當應用程式呼叫 SQLDisconnect 以中斷連線時，連線會傳回至連線集區，並可供重複使用。

優化連線共用效能

涉及分散式交易時，可以使用 sqlUINTEGER 位元遮罩SQL_DTC_TRANSITION_COST 來優化連線共用效能 。所參考的轉換是連接屬性的轉換SQL_ATTR_ENLIST_IN_DTC從值 0 轉換為非零，反之亦然。這是一種連線，從未登記在分散式交易中，到在分散式交易中登記，反之亦然。根據驅動程式實作登記的方式（設定連接屬性SQL_ATTR_ENLIST_IN_DTC），這些轉換可能很昂貴，因此應避免達到最佳效能。

驅動程式傳回的值包含下列位的任何組合：

SQL_DTC_ENLIST_EXPENSIVE設定時，表示零到非零的轉換比從非零轉換為另一個非零值的成本要高得多（在下一筆交易中登記先前登記的連接）。
SQL_DTC_UNENLIST_EXPENSIVE，當設定時，表示非零到零的轉換比使用SQL_ATTR_ENLIST_IN_DTC屬性已經設定為零的連接要高得多。

效能與連線使用量取捨。如果驅動程式指出這些轉換的一或多個成本很高，驅動程式管理員的連接共用器會藉由在集區中保留更多連線來回應此情況。集區中的某些連線是非交易用途的慣用連線，有些則優先用於交易式使用。不過，如果驅動程式指出這些轉換並不昂貴，則可以使用較少的連線，或許會在非交易式與交易式使用之間交替。

不支援SQL_ATTR_ENLIST_IN_DTC的驅動程式不需要支援SQL_DTC_TRANSITION_COST。對於支援SQL_ATTR_ENLIST_IN_DTC但不支援SQL_DTC_TRANSITION_COST的驅動程式，假設轉換成本不高，就好像驅動程式針對此值傳回 0 （沒有設定位）。

雖然SQL_DTC_TRANSITION_COST是在 ODBC 3.5 中引進的，但 ODBC 2。 x 驅動程式也可以支援它，因為驅動程式管理員會查詢此資訊，而不論驅動程式版本為何。

程式碼範例

在下列範例中，應用程式會配置環境和連線控制碼。然後，它會使用使用者識別碼 JohnS 和密碼 Sesame 連接到 SalesOrders 資料來源，並處理資料。當它完成處理資料時，它會中斷與資料來源的連線，並釋放控制碼。

// SQLConnect_ref.cpp  
// compile with: odbc32.lib  
#include <windows.h>  
#include <sqlext.h>  
  
int main() {  
   SQLHENV henv;  
   SQLHDBC hdbc;  
   SQLHSTMT hstmt;  
   SQLRETURN retcode;  
  
   SQLCHAR * OutConnStr = (SQLCHAR * )malloc(255);  
   SQLSMALLINT * OutConnStrLen = (SQLSMALLINT *)malloc(255);  
  
   // 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, (void*)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);  
  
            // Connect to data source  
            retcode = SQLConnect(hdbc, (SQLCHAR*) "NorthWind", SQL_NTS, (SQLCHAR*) NULL, 0, NULL, 0);  
  
            // 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);  
   }  
}

如需下列資訊	請參閱
配置控制碼	SQLAllocHandle 函式
探索和列舉連接到資料來源所需的值	SQLBrowseConnect 函式
中斷與資料來源的連線	SQLDisconnect 函式
使用連接字串或對話方塊連接到資料來源	SQLDriverConnect 函式
傳回連接屬性的設定	SQLGetConnectAttr 函式
設定連接屬性	SQLSetConnectAttr 函式

另請參閱

ODBC API 參考
 ODBC 標頭檔

SQLConnect 函式

語法

引數

傳回

診斷

註解

驅動程式管理員指導方針

連接共用

優化連線共用效能

程式碼範例

另請參閱

意見反應

意見反應

其他資源

SQLConnect 函式

語法

引數

傳回

診斷

註解

驅動程式管理員指導方針

連接共用

優化連線共用效能

程式碼範例

相關函數

另請參閱

意見反應

意見反應

其他資源