以下範例展示如何使用 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,而非使用者 ID 和密碼資訊。
驅動程式判斷這是第一次呼叫 SQLBrowseConnect ,並回傳第二層級的連線屬性:伺服器、使用者名稱、密碼、應用程式名稱及工作站 ID。 對於伺服器屬性,它會回傳一個有效的伺服器名稱清單。 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);