SQLBrowseConnect 函式

發行項
07/04/2024

一致性
引進的版本：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
[輸入]流覽要求連接字串（請參閱中的<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 = {PWD | UID}[: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

程式碼範例

相關函數

另請參閱

意見反應

其他資源