SQLBrowseConnect 函數

發行項
03/02/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 Argument」。

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

OutConnectionString
[輸出]要傳回流覽結果連接字串的字元緩衝區指標， (「Comments」 ) 中看到「OutConnectionString Argument」。

如果 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時，可以藉由呼叫 SQLGetDiagRec 來取得相關聯的 SQLSTATE 值，方法是使用 SQL_HANDLE_STMT 的 HandleType 和 ConnectionHandle 的 HandleHandle來取得。下表列出 SQLBrowseConnect 通常傳回的 SQLSTATE 值，並說明此函式內容中的每個值;標記法「 (DM) 」在驅動程式管理員傳回的 SQLSTATE 描述之前。除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。

SQLSTATE	錯誤	Description
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[ ; ] |屬性;connection-string;
attribute ：：= attribute-keyword=attribute-value | DRIVER= [ { ]attribute-value[ } ]
attribute-keyword ：：= DSNPWDUID | | | driver-defined-attribute-keyword
attribute-value ：：= character-string
driver-defined-attribute-keyword ：：= 識別碼

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

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

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

OutConnectionString 引數

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

connection-string ：：= attribute[ ; ] |屬性;connection-string
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 的驅動程式。
如果驅動程式管理員找不到對應的資料來源規格，而且沒有預設資料來源規格，它會傳回SQL_ERROR SQLSTATE IM002 (找不到資料來源，而且找不到預設驅動程式) 。

如果流覽要求連接字串包含 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

程式碼範例

相關函數

另請參閱

其他資源

其他資源