次の例は、 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 認証をサポートするデータ ソース プロバイダーに接続する場合は、接続文字列でユーザー ID とパスワード情報の代わりに Trusted_Connection=yes を指定する必要があります。
ドライバーは、これが SQLBrowseConnect への最初の呼び出しであると判断し、2 番目のレベルの接続属性 (サーバー、ユーザー名、パスワード、アプリケーション名、ワークステーション ID) を返します。 サーバー属性の場合、有効なサーバー名の一覧が返されます。 SQLBrowseConnect からのリターン コードがSQL_NEED_DATA。 参照結果の文字列を次に示します。
"SERVER:Server={red,blue,green,yellow};UID:Login ID=?;PWD:Password=?;
*APP:AppName=?;*WSID:WorkStation ID=?;"
参照結果文字列内の各キーワードの後には、等号の前にコロンと 1 つ以上の単語が続きます。 これらの単語は、アプリケーションがダイアログ ボックスの作成に使用できるわかりやすい名前です。 APP キーワードと WSID キーワードの前にはアスタリスクが付きます。これは、省略可能であることを意味します。 SERVER、UID、および PWD キーワードの前にアスタリスクが付いていません。値は、次の参照要求文字列で指定する必要があります。 SERVER キーワードの値には、SQLBrowseConnect によって返されるサーバーの 1 つ、またはユーザー指定の名前を指定できます。
アプリケーションは 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 を呼び出し、DATABASE キーワードの前に LANGUAGE キーワードとアスタリスクを省略します。
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);