SQLBrowseConnect 関数

準拠
導入されたバージョン: ODBC 1.0 Standards Compliance: 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
[出力]参照結果接続文字列を返す文字バッファーへのポインター (「コメント」の「OutConnectionString 引数」を参照)。

OutConnectionString が NULL の場合、StringLength2Ptr は引き続き、OutConnectionString が指すバッファーで返される文字の合計数 (文字データの null 終端文字を除く) を返します。

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 のHandle を使用してSQLGetDiagRecを呼び出すことによって、関連付けられた SQLSTATE 値を取得できます。 次の表に、 SQLBrowseConnect によって一般的に返される SQLSTATE 値を示し、この関数のコンテキストでそれぞれについて説明します。表記 "(DM)" は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERROR。

InConnectionString 引数

参照要求接続文字列には、次の構文があります。

connection-string ::= attribute[;] | attribute ; connection-string;
attribute ::= attribute-keyword=attribute-value | DRIVER=[{]attribute-value[}]
attribute-keyword ::= DSN | UID | PWD | driver-defined-attribute-keyword
attribute-value ::= character-string
driver-defined-attribute-keyword ::= identifier

ここで、 character-string には 0 個以上の文字があります。 識別子 には 1 つ以上の文字があります。 attribute-keyword では大文字と小文字は区別されません。 属性値 では大文字と小文字が区別される場合があります。また、 DSN キーワードの値は空白のみで構成されるわけではありません。 接続文字列と初期化ファイルの文法により、キーワードと属性値に文字[]{}(),?*=!@は避けてください。 システム情報の文法のため、キーワードとデータ ソース名に円記号 (\) 文字を含めることはできません。 ODBC 2. の場合x ドライバーでは、DRIVER キーワードの属性値を囲む中かっこが必要です。

参照要求接続文字列でキーワードが繰り返される場合、ドライバーはキーワードの最初の出現に関連付けられた値を使用します。 DSNおよびDRIVERキーワードが同じ参照要求接続文字列に含まれている場合、ドライバー マネージャーとドライバーは、最初に表示されるキーワードを使用します。

アプリケーションでデータ ソースまたはドライバーを選択する方法については、「 データ ソースまたはドライバーの選択を参照してください。

OutConnectionString 引数

接続文字列参照結果は、接続属性の一覧です。 接続属性は、属性キーワードと対応する属性値で構成されます。 参照結果接続文字列には、次の構文があります。

connection-string ::= attribute[;] | attribute ; connection-string
attribute ::= [*]attribute-keyword=attribute-value
attribute-keyword ::= ODBC-attribute-keyword | driver-defined-attribute-keyword
ODBC-attribute-keyword = {UID | PWD}[: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

ここで、 文字文字列 および 割り当てられた文字列 0 個以上の文字が含まれます。 identifier と localized-identifier には 1 つ以上の文字があります。 attribute-keyword では大文字と小文字が区別されず、 attribute-value では大文字と小文字が区別される場合があります。 接続文字列と初期化ファイルの文法、キーワード、ローカライズされた識別子、および文字を含む属性値[]{}(),;?*=!@は避けてください。 システム情報の文法のため、キーワードとデータ ソース名に円記号 (\) 文字を含めることはできません。

参照結果接続文字列構文は、次のセマンティック ルールに従って使用されます。

• アスタリスク (*) が attribute-keyword の前にある場合、 attribute は省略可能であり、 SQLBrowseConnect の次の呼び出しでは省略できます。

• 属性キーワード UID および PWD は、 SQLDriverConnect で定義されているのと同じ意味を持ちます。

• driver-defined-attribute-keywordは、属性値を指定できる属性の種類を指定します。 たとえば、SERVER、DATABASE、HOST、DBMS など。

• ODBC-attribute-keywords および driver-defined-attribute-keywords キーワードのローカライズされたバージョンまたはわかりやすいバージョンが含まれます。 これは、アプリケーションによってダイアログ ボックスのラベルとして使用される場合があります。 ただし、 UID、 PWD、または identifier のみを使用して、参照要求文字列をドライバーに渡す必要があります。

• {attribute-value-list} は、対応する attribute-keyword に対して有効な実際の値の列挙です。 中かっこ ({}) は選択肢の一覧を示していません。これらはドライバーによって返されます。 たとえば、サーバー名の一覧やデータベース名の一覧などです。

• attribute-valueが 1 つの疑問符 (?) の場合、1 つの値が attribute-keyword に対応します。 たとえば、UID=JohnS です。PWD=ゴマ。

• SQLBrowseConnect を呼び出すたびに、接続プロセスの次のレベルを満たすために必要な情報のみが返されます。 ドライバーは、各呼び出しでコンテキストを常に決定できるように、接続ハンドルに状態情報を関連付けます。

SQLBrowseConnect の使用

SQLBrowseConnect には割り当てられた接続が必要です。 ドライバー マネージャーは、最初の参照要求接続文字列で指定されたデータ ソース名に対応するドライバーを読み込みます。これが発生するタイミングについては、「SQLConnect 関数」の「コメント」セクションを参照してください。 ドライバーは、参照プロセス中にデータ ソースとの接続を確立できます。 SQLBrowseConnectがSQL_ERRORを返すと、未処理の接続が終了し、接続が未接続状態に戻ります。

接続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 をサポートしている場合、ドライバーのシステム情報のドライバー キーワード セクションには、3 番目の文字が "Y" に設定された ConnectFunctions キーワードが含まれている必要があります。

コード例

次の例では、アプリケーションは 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 ルーチンに渡します。このルーチンは、赤、青、緑のサーバーを選択し、ユーザー ID とパスワードを入力するようにユーザーに求めるダイアログ ボックスを作成します。 このルーチンは、次のユーザー指定の情報を *InConnectionString に戻します。この情報は、アプリケーションが SQLBrowseConnect に渡します。

"HOST=red;UID=Smith;PWD=Sesame"  

SQLBrowseConnect は、この情報を使用して、パスワードを使用して Smith として赤いサーバーに接続し、*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);  
}  

関連する関数

参照

ODBC API リファレンス
ODBC ヘッダー ファイル