SQLBrowseConnect 函式

發行項
08/21/2023

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

摘要
SQLBrowseConnect 支援反復的方法來探索和列舉連線至資料來源所需的屬性和屬性值。每個對 SQLBrowseConnect 的呼叫 都會傳回連續的屬性和屬性值層級。列舉所有層級之後，資料來源的連接就會完成，SQLBrowseConnect 會傳回完整的連接字串。 SQL_SUCCESS或SQL_SUCCESS_WITH_INFO傳回碼表示已指定所有連接資訊，而且應用程式現在已連線到資料來源。

語法

  
SQLRETURN SQLBrowseConnect(  
     SQLHDBC         ConnectionHandle,  
     SQLCHAR *       InConnectionString,  
     SQLSMALLINT     StringLength1,  
     SQLCHAR *       OutConnectionString,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   StringLength2Ptr);

引數

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

InConnectionString
[輸入]流覽要求連接字串（請參閱「Comments」中的「 InConnectionString 引數」）。

StringLength1
[輸入]字元中的 * InConnectionString 長度。

OutConnectionString
[輸出]要在其中傳回流覽結果連接字串的字元緩衝區指標（請參閱「Comments」中的「 OutConnectionString 引數」）。

如果 OutConnectionString 為 Null， StringLength2Ptr 仍會傳回字元總數（不包括字元資料的 Null 終止字元），以在 OutConnectionString 所指向的緩衝區中傳回。

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

StringLength2Ptr
[輸出]可在 * OutConnectionString 中傳回的字元總數（不包括 Null 終止）。如果可用傳回的字元數大於或等於 BufferLength ，則 * OutConnectionString 中的連接字串會截斷為 BufferLength 減去 Null 終止字元的長度。

傳回

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

診斷

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

SQLSTATE	錯誤	描述
01000	一般警告	驅動程式特定的資訊訊息。（函式會傳回SQL_SUCCESS_WITH_INFO。）
01004	字串資料，右截斷	緩衝區 * OutConnectionString 不夠大，無法傳回整個流覽結果連接字串，因此字串已截斷。緩衝區 * StringLength2Ptr 包含未解構流覽結果連接字串的長度。（函式會傳回SQL_NEED_DATA。）
01S00	不正確連接字串屬性	在流覽要求連接字串中指定了不正確屬性關鍵字（ InConnectionString ）。（函式會傳回SQL_NEED_DATA。）在流覽要求連接字串（ InConnectionString ）中指定了屬性關鍵字，該連接字串不適用於目前的連接層級。（函式會傳回SQL_NEED_DATA。）
01S02	值已變更	驅動程式不支援 SQLSetConnectAttr 中 ValuePtr 引數的指定值，並取代了類似的值。（函式會傳回SQL_SUCCESS_WITH_INFO。）
08001	用戶端無法建立連線	驅動程式無法與資料來源建立連線。
08002	使用中的連線名稱	（DM）指定的連接已經用來建立與資料來源的連線，而且連接已開啟。
08004	伺服器拒絕連線	資料來源拒絕基於實作定義的原因建立連線。
08S01	通訊連結失敗	驅動程式與驅動程式嘗試連線的資料來源之間的通訊連結在函式完成處理之前失敗。
28000	授權規格無效	使用者識別碼或授權字串或兩者，如流覽要求連接字串（ InConnectionString ）中所指定，違反資料來源所定義的限制。
HY000	一般錯誤	發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 MessageText 緩衝區中* SQLGetDiagRec 傳回的錯誤訊息描述錯誤及其原因。
HY001	記憶體配置錯誤	（DM）驅動程式管理員無法配置支援執行或完成函式所需的記憶體。驅動程式無法配置支援執行或完成函式所需的記憶體。
HY008	作業已取消	呼叫 SQLCancelHandle 函式來取消非同步作業。然後，在 ConnectionHandle 上再次呼叫原始函式。從多執行緒應用程式中的不同執行緒呼叫 ConnectionHandle 上的 SQLCancelHandle 來取消作業。
HY010	函式順序錯誤	（DM）呼叫 ConnectionHandle 的非同步執行函式（不是此函式），而且在呼叫此函式時仍在執行中。
HY013	記憶體管理錯誤	無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。
HY090	不正確字串或緩衝區長度	（DM）為引數 StringLength1 指定的值小於 0，且不等於SQL_NTS。（DM）為引數 BufferLength 指定的值小於 0。
HY114	驅動程式不支援連線層級非同步函式執行	（DM）應用程式在進行連接之前，已在連接控制碼上啟用非同步作業。不過，驅動程式不支援連接控制碼上的非同步作業。
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）在 SQLBrowseConnect 期間，驅動程式管理員呼叫驅動程式的 SQLAllocHandle 函式，且具有 handleType 為 SQL_HANDLE_ENV，而驅動程式傳回錯誤。
IM005	SQL_HANDLE_DBC上的驅動程式 SQLAllocHandle 失敗	（DM）在 SQLBrowseConnect 期間，驅動程式管理員呼叫驅動程式的 SQLAllocHandle 函式，其 HandleType 為 SQL_HANDLE_DBC，而驅動程式傳回錯誤。
IM006	驅動程式的 SQLSetConnectAttr 失敗	（DM）在 SQLBrowseConnect 期間，驅動程式管理員稱為驅動程式的 SQLSetConnectAttr 函式，而驅動程式傳回錯誤。
IM009	無法載入翻譯 DLL	驅動程式無法載入為數據源或連接指定的轉譯 DLL。
IM010	資料來源名稱太長	（DM） DSN 關鍵字的屬性值超過SQL_MAX_DSN_LENGTH個字元。
IM011	驅動程式名稱太長	（DM） DRIVER 關鍵字的屬性值超過 255 個字元。
IM012	DRIVER 關鍵字語法錯誤	（DM） DRIVER 關鍵字的關鍵字/值組包含語法錯誤。
IM014	指定的 DSN 包含驅動程式與應用程式之間的架構不符	（DM） 32 位應用程式使用連線到 64 位驅動程式的 DSN;反之亦然。
IM017	在非同步通知模式中停用輪詢	每當使用通知模型時，輪詢就會停用。
IM018	尚未呼叫 SQLCompleteAsync ，以完成此控制碼上的先前非同步作業。	如果控制碼上的上一個函式呼叫傳回SQL_STILL_EXECUTING且啟用通知模式，則必須在控制碼上呼叫 SQLCompleteAsync ，才能執行後續處理並完成作業。
S1118	驅動程式不支援非同步通知	當驅動程式不支援非同步通知時，您無法設定SQL_ATTR_ASYNC_DBC_EVENT或SQL_ATTR_ASYNC_DBC_RETCODE_PTR。

InConnectionString 引數

流覽要求連接字串具有下列語法：

connection-string ：：= attribute [ ; ] | 屬性 ; 連接字串 ;
attribute ：：= attribute-keyword = attribute-value[ { ] attribute-value | DRIVER= [] }
attribute-keyword ：：= DSNPWD | UID | | driver-defined-attribute-keyword
attribute-value ：：= character-string
driver-defined-attribute-keyword ：：= identifier

其中 字元字串 有零個或多個字元; 識別碼 有一或多個字元; attribute-keyword 不區分大小寫; 屬性值可能會區分大小寫;而 DSN 關鍵字的值 不只包含空白。因為連接字串和初始化檔案文法、關鍵字和屬性值包含字元 [] {} （），;？應避免 *=！@ 。由於系統資訊中的文法，關鍵字和資料來源名稱不能包含反斜線（\）字元。針對 ODBC 2。 x 驅動程式，在 DRIVER 關鍵字的屬性值周圍需要大括弧。

如果在流覽要求連接字串中重複任何關鍵字，驅動程式會使用與關鍵字第一次出現相關聯的值。 如果 DSN 和 DRIVER 關鍵字包含在相同的流覽要求連接字串中，驅動程式管理員和驅動程式會使用第一個出現的關鍵字。

如需應用程式如何選擇資料來源或驅動程式的資訊，請參閱選擇資料來源或驅動程式。

OutConnectionString 引數

流覽結果連接字串是連接屬性的清單。連接屬性是由屬性關鍵字和對應的屬性值所組成。流覽結果連接字串具有下列語法：

connection-string ：：= attribute [ ; ] | 屬性 ; 連接字串
attribute ：：= [ * ] attribute-keyword = attribute-value
attribute-keyword ：：= ODBC-attribute-keyword | driver-defined-attribute-keyword
ODBC-attribute-keyword = { UIDPWD | }[ : localized-identifier ] driver-defined-attribute-keyword ：：= identifier [ : localized-identifier ] attribute-value ：：= { attribute-value-list ?} | （大括弧為常值;驅動程式會傳回它們。
attribute-value-list ：：= character-string [ : localized-character string ] | character-string [ : localized-character string ] , attribute-value-list

其中 字元字串 和 當地語系化字元字串 具有零個或多個字元; identifier 和 localized-identifier 有一或多個字元; attribute-keyword 不區分大小寫;而 屬性值 可能區分大小寫。因為連接字串和初始化檔案文法、關鍵字、當地語系化識別碼，以及包含字元 [] {} （），;？應避免 *=！@ 。由於系統資訊中的文法，關鍵字和資料來源名稱不能包含反斜線（\）字元。

流覽結果連接字串語法會根據下列語意規則使用：

如果星號在 attribute-keyword 前面加上星號，屬性 是選擇性的， 而且可以在下一次對 SQLBrowseConnect 的呼叫 中省略。
屬性關鍵字 UID 和 PWD 的意義與 SQLDriverConnect 中所定義的意義相同。
driver-defined-attribute-keyword 會命名可能提供屬性值的屬性類型。例如，可能是 SERVER 、 DATABASE 、 HOST 或 DBMS 。
ODBC-attribute-keywords 和 driver-defined-attribute-keywords 包含當地語系化或使用者易記版本的關鍵字。應用程式可能會使用此專案作為對話方塊中的標籤。不過，將流覽要求字串傳遞至驅動程式時， 必須使用 UID 、 PWD 或 單獨識別碼 。
{ attribute-value-list } 是對應 attribute-keyword 的有效實際值列舉。請注意，大括弧（ {} ）不會指出選項清單;驅動程式會傳回這些選項。例如，可能是伺服器名稱的清單或資料庫名稱清單。
如果屬性值 是單一問號（？），單一值會對應至 attribute-keyword 。例如，UID=JohnS;PWD=Sesame。
每個對 SQLBrowseConnect 的呼叫 只會傳回滿足下一層連線程式所需的資訊。驅動程式會將狀態資訊與連接控制碼產生關聯，以便一律在每個呼叫上判斷內容。

使用 SQLBrowseConnect

SQLBrowseConnect 需要配置的連線。驅動程式管理員會載入在中指定的驅動程式，或對應至初始流覽要求連接字串中指定的資料來源名稱;如需何時發生此情況的詳細資訊，請參閱 SQLConnect 函式中的一節。驅動程式可能會在流覽程式期間與資料來源建立連線。如果 SQLBrowseConnect 傳回SQL_ERROR，則會終止未處理的連線，並將連線傳回至未連線的狀態。

注意

SQLBrowseConnect 不支援連線共用。如果 啟用連線共用時呼叫 SQLBrowseConnect ，則會傳回 SQLSTATE HY000 （一般錯誤）。

第一次在連線上呼叫 SQLBrowseConnect 時，流覽要求連接字串必須包含 DSN 關鍵字或 DRIVER 關鍵字。如果流覽要求連接字串包含 DSN 關鍵字，驅動程式管理員會在系統資訊中找到對應的資料來源規格：

如果驅動程式管理員找到對應的資料來源規格，它會載入相關聯的驅動程式 DLL;驅動程式可以從系統資訊擷取資料來源的相關資訊。
如果驅動程式管理員找不到對應的資料來源規格，它會找出預設資料來源規格，並載入相關聯的驅動程式 DLL;驅動程式可以從系統資訊擷取預設資料來源的相關資訊。「DEFAULT」會傳遞至 DSN 的驅動程式。
如果驅動程式管理員找不到對應的資料來源規格，而且沒有預設資料來源規格，則會傳回具有 SQLSTATE IM002 的SQL_ERROR（找不到資料來源，也沒有指定的預設驅動程式）。

如果流覽要求連接字串包含 DRIVER 關鍵字，驅動程式管理員會載入指定的驅動程式;它不會嘗試在系統資訊中尋找資料來源。 因為 DRIVER 關鍵字不會使用系統資訊的資訊，所以驅動程式必須定義足夠的關鍵字，讓驅動程式只能使用流覽要求連接字串中的資訊連線到資料來源。

在每次呼叫 SQLBrowseConnect 時，應用程式會在流覽要求連接字串中指定連接屬性值。驅動程式會傳回流覽結果連接字串中連續的屬性和屬性值層級;只要流覽要求連接字串中尚未列舉連線屬性，它就會傳回SQL_NEED_DATA。應用程式會使用流覽結果連接字串的內容來建置流覽要求連接字串，以供下一次呼叫 SQLBrowseConnect 。所有強制屬性（OutConnectionString 引數中沒有星號 之前的屬性）都必須包含在下一次對 SQLBrowseConnect 的呼叫 中。請注意，建置目前的流覽要求連接字串時，應用程式無法使用先前流覽結果連接字串的內容;也就是說，它無法為先前層級中設定的屬性指定不同的值。

列舉所有連線層級及其相關聯的屬性時，驅動程式會傳回SQL_SUCCESS、資料來源的連接已完成，而且會傳回完整的連接字串給應用程式。連接字串可與 SQLDriverConnect 搭配使用，並搭配SQL_DRIVER_NOPROMPT選項來建立另一個連線。不過，完整連接字串不能用於另一個 SQLBrowseConnect 呼叫中;如果 再次呼叫 SQLBrowseConnect ，則必須重複整個呼叫序列。

如果流覽程式期間發生可復原、非嚴重錯誤，SQLBrowseConnect 也會傳回SQL_NEED_DATA;例如，應用程式提供的無效密碼或屬性關鍵字。傳回SQL_NEED_DATA且流覽結果連接字串未變更時，發生錯誤，而且應用程式可以呼叫 SQLGetDiagRec 傳回 SQLSTATE 以取得流覽時間錯誤。這可讓應用程式更正屬性並繼續流覽。

應用程式可以隨時呼叫 SQLDisconnect 來終止流覽程式。驅動程式將會終止任何未處理的連線，並將連線傳回至未線上狀態。

如果在連接控制碼上啟用非同步作業， SQLBrowseConnect 也可能傳回SQL_STILL_EXECUTING。傳回SQL_NEED_DATA時，應用程式必須使用 SQLDisconnect 來取消流覽程式。如果 SQLBrowseConnect 傳回SQL_STILL_EXECUTING，應用程式應該使用 SQLCancelHandle 取消進行中的作業。在函式傳回SQL_NEED_DATA之後呼叫 SQLCancelHandle 沒有任何作用。

如需詳細資訊，請參閱使用 SQLBrowseConnect 連線。

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

程式碼範例

注意

如果您要連線到支援 Windows 驗證的資料來源提供者，您應該指定 Trusted_Connection=yes，而不是在連接字串中指定使用者識別碼和密碼資訊。

在下列範例中，應用程式會重複呼叫 SQLBrowseConnect 。每次 SQLBrowseConnect 傳回SQL_NEED_DATA時，都會傳回 * OutConnectionString 中所需資料的相關資訊。應用程式會將 OutConnectionString 傳遞給 其常式 GetUserInput （未顯示）。 GetUserInput 會剖析資訊、建置和顯示對話方塊，並傳回使用者在 * InConnectionString 中輸入的資訊。應用程式會在下一次呼叫 SQLBrowseConnect 時，將使用者的資訊傳遞給驅動程式。在應用程式提供驅動程式連線至資料來源的所有必要資訊之後， SQLBrowseConnect 會傳回SQL_SUCCESS，然後應用程式繼續進行。

如需透過呼叫 SQLBrowseConnect 連線到 SQL Server 驅動程式的更詳細範例，請參閱 SQL Server 流覽範例。

例如，若要連線到資料來源 Sales，可能會發生下列動作。首先，應用程式會將下列字串傳遞至 SQLBrowseConnect ：

"DSN=Sales"

驅動程式管理員會載入與資料來源 Sales 相關聯的驅動程式。然後，它會使用從應用程式收到的相同引數，呼叫驅動程式的 SQLBrowseConnect 函式。驅動程式會在 * OutConnectionString 中傳回下列字串：

"HOST:Server={red,blue,green};UID:ID=?;PWD:Password=?"

應用程式會將此字串傳遞至其 GetUserInput 常式，其會建置對話方塊，要求使用者選取紅色、藍色或綠色伺服器，並輸入使用者識別碼和密碼。常式會將下列使用者指定的資訊傳回 * InConnectionString ，應用程式會傳遞至 SQLBrowseConnect ：

"HOST=red;UID=Smith;PWD=Sesame"

SQLBrowseConnect 會使用這項資訊，使用密碼 Sesame 連線到紅色伺服器，然後在 * OutConnectionString 中傳回下列字串：

"*DATABASE:Database={SalesEmployees,SalesGoals,SalesOrders}"

應用程式會將此字串傳遞至其 GetUserInput 常式，此常式會建置對話方塊，要求使用者選取資料庫。使用者選取 empdata，而應用程式會使用此字串呼叫 SQLBrowseConnect 最後一次：

"DATABASE=SalesOrders"

這是驅動程式連線至資料來源所需的最後一項資訊; SQLBrowseConnect 會傳回SQL_SUCCESS，而 * OutConnectionString 包含已完成的連接字串：

// SQLBrowseConnect_Function.cpp  
// compile with: odbc32.lib  
#include <windows.h>  
#include <sqltypes.h>  
#include <sqlext.h>  
  
#define BRWS_LEN 100  
SQLHENV henv;  
SQLHDBC hdbc;  
SQLHSTMT hstmt;  
SQLRETURN retcode;  
SQLCHAR szConnStrIn[BRWS_LEN], szConnStrOut[BRWS_LEN];  
SQLSMALLINT cbConnStrOut;  
  
void GetUserInput(SQLCHAR * szConnStrOut, SQLCHAR * szConnStrIn) {}  
  
int main() {  
   // Allocate the environment handle.  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);        
   if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
  
      // Set the version environment attribute.  
      retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);  
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
  
         // Allocate the connection handle.  
         retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  
         if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
            // Call SQLBrowseConnect until it returns a value other than SQL_NEED_DATA   
            // (pass data source name the first time).  If SQL_NEED_DATA is returned, call GetUserInput   
            // (not shown) to build a dialog from the values in szConnStrOut.  The user-supplied values   
            // are returned in szConnStrIn, which is passed in the next call to SQLBrowseConnect.  
  
            strcpy_s((char*)szConnStrIn, _countof(szConnStrIn), "DSN=Sales");  
            do {  
               retcode = SQLBrowseConnect(hdbc, szConnStrIn, SQL_NTS,  
                  szConnStrOut, BRWS_LEN, &cbConnStrOut);  
               if (retcode == SQL_NEED_DATA)  
                  GetUserInput(szConnStrOut, szConnStrIn);  
            } while (retcode == SQL_NEED_DATA);  
  
            if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO){  
  
               // Allocate the statement handle.  
               retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
               if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO)  
                  // Process data after successful connection  
                  SQLFreeHandle(SQL_HANDLE_STMT, hstmt);  
               SQLDisconnect(hdbc);  
            }  
         }  
         SQLFreeHandle(SQL_HANDLE_DBC, hdbc);  
      }  
   }  
   SQLFreeHandle(SQL_HANDLE_ENV, henv);  
}

如需下列資訊	請參閱
配置連接控制碼	SQLAllocHandle 函式
連線到資料來源	SQLConnect 函式
中斷與資料來源的連線	SQLDisconnect 函式
使用連接字串或對話方塊連接到資料來源	SQLDriverConnect 函式
傳回驅動程式描述和屬性	SQLDrivers 函式
釋放連接控制碼	SQLFreeHandle 函式

另請參閱

ODBC API 參考
 ODBC 標頭檔

SQLBrowseConnect 函式

語法

引數

傳回

診斷

InConnectionString 引數

OutConnectionString 引數

使用 SQLBrowseConnect

程式碼範例

另請參閱

意見反應

意見反應

其他資源

SQLBrowseConnect 函式

語法

引數

傳回

診斷

InConnectionString 引數

OutConnectionString 引數

使用 SQLBrowseConnect

程式碼範例

相關函數

另請參閱

意見反應

意見反應

其他資源