SQL Server 瀏覽範例

下列範例顯示如何使用 SQLBrowseConnect 來瀏覽 SQL Server 驅動程式可用的連線。 首先，應用程式會要求連線控制代碼：

SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  

接著，應用程式會呼叫 SQLBrowseConnect，並使用 SQLDrivers 傳回的驅動程式描述來指定 SQL Server 驅動程式：

SQLBrowseConnect(hdbc, "DRIVER={SQL Server};", SQL_NTS, BrowseResult,  
                  sizeof(BrowseResult), &BrowseResultLen);  

這是第一次呼叫 SQLBrowseConnect，因此驅動程式管理員會載入 SQL Server 驅動程式，並使用從應用程式收到的相同引數呼叫驅動程式的 SQLBrowseConnect 函式。

注意

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

驅動程式會判斷這是第一次呼叫 SQLBrowseConnect，並傳回第二層連線屬性：伺服器、使用者名稱、密碼、應用程式名稱和工作站識別碼。 針對伺服器屬性，它會傳回有效的伺服器名稱清單。 SQLBrowseConnect 的傳回碼為 SQL_NEED_DATA。 以下是瀏覽結果字串：

"SERVER:Server={red,blue,green,yellow};UID:Login ID=?;PWD:Password=?;  
   *APP:AppName=?;*WSID:WorkStation ID=?;"  

瀏覽結果字串中的每個關鍵字後面都會加上冒號，並在等號後面加上一或多個字。 這些字是應用程式可用來建置對話方塊的使用者易記名稱。 APP 和 WSID 關鍵字前會加上星號，這表示它們為非必要。 SERVER、UID 和 PWD 關鍵字不會加上星號；請務必在下一個瀏覽要求字串中為其提供值。 SERVER 關鍵字的值可能是 SQLBrowseConnect 傳回的伺服器之一或使用者提供的名稱。

應用程式再次呼叫 SQLBrowseConnect，指定綠色伺服器並省略 APP 和 WSID 關鍵字，以及每個關鍵字之後的使用者易記名稱：

SQLBrowseConnect(hdbc, "SERVER=green;UID=Smith;PWD=Sesame;", SQL_NTS,  
                  BrowseResult, sizeof(BrowseResult), &BrowseResultLen);  

驅動程式會嘗試連線到綠色伺服器。 如果有任何非嚴重錯誤，例如遺漏關鍵字/值組，SQLBrowseConnect 會傳回 SQL_NEED_DATA，並維持與發生錯誤之前相同的狀態。 應用程式可以呼叫 SQLGetDiagField 或 SQLGetDiagRec 來判斷錯誤。 如果連線成功，驅動程式會傳回 SQL_NEED_DATA 並傳回瀏覽結果字串：

"*DATABASE:Database={master,model,pubs,tempdb};  
   *LANGUAGE:Language={us_english,Franais};"  

此字串中的屬性為非必要，因此應用程式可以省略它們。 不過，應用程式必須再次呼叫 SQLBrowseConnect。 如果應用程式選擇省略資料庫名稱和語言，它會指定空白瀏覽要求字串。 在此範例中，應用程式會選擇 pubs 資料庫，並最後一次呼叫 SQLBrowseConnect，省略 LANGUAGE 關鍵字，以及 DATABASE 關鍵字前面的星號：

SQLBrowseConnect(hdbc, "DATABASE=pubs;", SQL_NTS, BrowseResult,  
                  sizeof(BrowseResult), &BrowseResultLen);  

DATABASE 屬性是驅動程式所需的最終連線屬性，因此瀏覽流程已完成，應用程式會連線到資料來源，而且 SQLBrowseConnect 會傳回 SQL_SUCCESS。 SQLBrowseConnect 也會傳回完整的連接字串，當作瀏覽結果字串：

"DSN=MySQLServer;SERVER=green;UID=Smith;PWD=Sesame;DATABASE=pubs;"  

驅動程式傳回的最終連接字串不包含每個關鍵字之後的使用者易記名稱，也不包含應用程式未指定的非必要關鍵字。 應用程式可以將此字串與 SQLDriverConnect 搭配使用，以重新連線至目前連線控制代碼上的資料來源 (於中斷連線後操作)，或連接到不同連線控制代碼上的資料來源。 例如：

SQLDriverConnect(hdbc, hwnd, BrowseResult, SQL_NTS, ConnStrOut,  
                  sizeof(ConnStrOut), &ConnStrOutLen, SQL_DRIVER_NOPROMPT);