SQLConnect 函數

發行項
03/02/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 長度。

使用者名稱
[輸入]使用者識別碼。

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

驗證
[輸入]驗證字串 (通常是密碼) 。

NameLength3
[輸入]*驗證的長度，以字元為單位。

傳回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_INVALID_HANDLE或SQL_STILL_EXECUTING。

診斷

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

SQLSTATE	錯誤	Description
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 驅動程式中開發Connection-Pool感知。
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 (Driver 的 SQLSetConnectOption 失敗) ，如果驅動程式傳回 SQLSetConnectAttr的錯誤，則連線函式SQL_SUCCESS_WITH_INFO。如需詳細資訊，請參閱連接到資料來源或驅動程式。
如果指定的驅動程式已在 ConnectionHandle上連接到，驅動程式管理員只會呼叫驅動程式中的連接函式。在此情況下，驅動程式必須確定 ConnectionHandle 的所有連線屬性都會維持其目前的設定。
如果連線到不同的驅動程式，驅動程式管理員會使用handleType SQL_HANDLE_DBC 呼叫SQLFreeHandle，然後在該環境中沒有其他驅動程式連線，它會使用連線驅動程式中SQL_HANDLE_ENV的 HandleType呼叫SQLFreeHandle，然後中斷該驅動程式的連接。然後，它會執行與驅動程式未連線時相同的作業。

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

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

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

驅動程式管理員指導方針

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

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

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

如果在資料來源的系統資訊中指定預設翻譯程式庫，驅動程式會連線到該程式庫。使用 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 函數

語法

引數

傳回

診斷

註解

驅動程式管理員指導方針

連接共用

優化連線共用效能

程式碼範例

相關函數

另請參閱

其他資源

其他資源