仕様: | DB2 CLI 5.0 | ODBC 1 |
SQLBrowseConnect() は、データ・ソースへの接続に必要な属性および属性値を、反復して発見および列挙する方法をサポートします。 SQLBrowseConnect() への呼び出しごとにそれぞれ、属性および属性値の継承レベルを返します。すべてのレベルを列挙し終わると、データ・ソースへの接続が完了し、完全な接続ストリングが SQLBrowseConnect() によって返されます。 SQL_SUCCESS または SQL_SUCCESS_WITH_INFO の戻りコードは、すべての接続情報が指定され、アプリケーションが今やデータ・ソースに接続されていることを示しています。
構文
SQLRETURN SQLBrowseConnect (SQLHDBC ConnectionHandle, SQLCHAR *InConnectionString, SQLSMALLINT StringLength1, SQLCHAR *OutConnectionString, SQLSMALLINT BufferLength, SQLSMALLINT *StringLength2Ptr);
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLHDBC | ConnectionHandle | 入力 | 接続ハンドル。 |
SQLCHAR | *szConnStrIn | 入力 | 要求接続ストリングをブラウズします (『InConnectionString 引き数』を参照)。 |
SQLSMALLINT | cbConnStrIn | 入力 | *InConnectionString の長さ。 |
SQLCHAR | *OutConnectionString | 出力 | バッファーを指すポインター。そのバッファーの中にブラウズ結果の接続ストリングを返します (『OutConnectionString 引き数』 を参照)。 |
SQLINTEGER | BufferLength | 入力 | *OutConnectionString バッファーの長さ。 |
SQLSMALLINT | *StringLength2Ptr | 出力 | *OutConnectionString 内に返すために使用できる総バイト数 (ヌル終了バイトを除く) 。戻りに使用できるバイト数が BufferLength より大きい場合、 *OutConnectionString 内の接続ストリングは、 BufferLength からヌル終了文字分を差し引いた長さに切り捨てられます。 |
使用法
ブラウズ要求の接続ストリングは、次の構文になります。
connection-string ::= attribute[;] | attribute; connection-string
attribute ::= attribute-keyword=attribute-value | DRIVER=[{]attribute-value[}]
attribute-keyword ::= DSN | UID | PWD | NEWPWD
| driver-defined-attribute-keyword
attribute-value ::= character-string
driver-defined-attribute-keyword ::= identifier
ここで、
接続ストリングと初期設定ファイルの文法上の理由から、 []{}(),;?*=!@ 文字の入っているキーワードおよび属性値は避けるべきです。システム情報の文法上の理由から、キーワードとデータ・ソース名には、円記号 (\) を入れることができません。 DB2 CLI バージョン 2 の場合、中括弧が DRIVER キーワードの前後に必要です。
あるキーワードがブラウズ要求の接続ストリングの中で繰り返される場合、 DB2 CLI は、そのキーワードの最初のオカレンスに関連した値を使用します。 DSN および DRIVER キーワードが同じブラウズ要求の接続ストリングに含まれている場合は、 DB2 CLI は、最初に現れたキーワードの方を使用します。
ブラウズ結果の接続ストリングは、接続属性のリストになっています。接続属性は、属性キーワードとそれに対応する属性値から成っています。ブラウズ結果の接続ストリングは、次の構文になります。
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 ::= identifer[:localized-identifier]
attribute-value ::= {attribute-value-list} | ?
(中括弧はリテラルであり、DB2 CLI によって返されます。)
attribute-value-list ::= character-string [:localized-character
string] | character-string [:localized-character string], attribute-value-list
ここで、
接続ストリングと初期化ファイルの文法上の理由から、 []{}(),;?*=!@ 文字の入っているキーワード、ローカライズ識別子、および属性値は避けるべきです。システム情報の文法上の理由から、キーワードとデータ・ソース名には、円記号 (\) を入れることができません。
ブラウズ結果の接続ストリングの構文は、以下のセマンティクス規則に従って使用されます。
SQLBrowseConnect の使用
SQLBrowseConnect() は、割り当てられた接続を必要とします。 SQLBrowseConnect() が SQL_ERROR を返すとき、未解決の接続は終了し、その接続は未接続の状態に戻されます。
SQLBrowseConnect() が接続に初めて呼び出されるときは、ブラウズ要求の接続ストリングには DSN キーワードが入っていなければなりません。
SQLBrowseConnect() への各呼び出しの際に、アプリケーションはブラウズ要求の接続ストリングに接続属性値を指定します。 DB2 CLI は、ブラウズ結果の接続ストリング内で属性の継承レベルおよび属性値を返します。 DB2 CLI は、ブラウズ要求の接続ストリングにまだ列挙されていない接続属性がある限り、 SQL_NEED_DATA を返します。アプリケーションは、ブラウズ結果の接続ストリングの内容を使用して、 SQLBrowseConnect() への次の呼び出し用のブラウズ要求接続ストリングを作成します。すべての必須属性 (OutConnectionString 引き数内のアスタリスクが先頭に付いていない属性) は、 SQLBrowseConnect() への次回の呼び出しに含める必要があります。アプリケーションは、以前のブラウズ結果の接続ストリングの内容を、現在のブラウズ要求接続ストリングを構築する際には使用できないことにご注意ください。すなわち、アプリケーションは、前のレベルで設定された属性セットについて異なる値を指定することはできません。
接続の全レベルとそれに関連した属性が列挙されたら、DB2 CLI が SQL_SUCCESS を返して、データ・ソースへの接続が完了し、完全な接続ストリングがアプリケーションに返されます。接続ストリングは、 SQL_DRIVER_NOPROMPT オプションを指定した SQLDriverConnect() と一緒に使用して別の接続を確立するのに適しています。その完全な接続ストリングは、 SQLBrowseConnect() への別の呼び出しに使用することはできません。しかし、SQLBrowseConnect() が再度呼び出された場合は、呼び出しのシーケンス全体が繰り返されることになります。
また、SQLBrowseConnect() は、ブラウズ処理の間に、回復可能な非致命的エラーが起きる場合、SQL_NEED_DATA を返します。そのようなエラーには、たとえば、アプリケーションによって提供された無効なパスワードや、アプリケーションによって提供された無効な属性キーワードがあります。 SQL_NEED_DATA が返されて、ブラウズ結果の接続ストリングが未変更の場合、エラーが発生し、アプリケーションは、 SQLGetDiagRec() を呼び出してブラウズ時のエラーについて SQLSTATE を返します。これにより、アプリケーションは属性を修正してブラウズを続行できます。
アプリケーションは、 SQLDisconnect() を呼び出すことによりいつでもブラウズ処理を終了させることができます。 DB2 CLI は、未解決の接続を終了させて、接続を非接続状態へ戻します。
戻りコード
診断
表 24. SQLBrowseConnect SQLSTATE
SQLSTATE | 説明 | 解説 |
---|---|---|
01000 | 警告。 | 通知メッセージ。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。) |
01004 | データが切り捨てられました。 | バッファー *OutConnectionString は、ブラウズ結果の接続ストリング全部を返せるほど大きくなかったので、ストリングが切り捨てられました。バッファー *StringLength2Ptr には、切り捨てられなかったブラウズ結果の接続ストリングの長さが入っています。 (関数は、 SQL_SUCCESS_WITH_INFO を戻します。) |
01S00 | 接続ストリング属性が無効です。 | 無効な属性キーワードが、ブラウズ要求の接続ストリング (InConnectionString) の中に指定されました。
(関数は
SQL_NEED_DATA を返します。)
属性キーワードがブラウズ要求の接続ストリング (InConnectionString) の中で指定されましたが、現在の接続レベルにあてはまりません。 (関数は SQL_NEED_DATA を返します。) |
01S02 | オプション値が変更されました。 | DB2 CLI は、SQLSetConnectAttr() 内の ValuePtr 引き数に指定した値をサポートしておらず、類似した値を代用しました。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。) |
08001 | データ・ソースに接続できませんでした。 | DB2 CLI がデータ・ソースとの接続を確立できませんでした。 |
08002 | 接続が使用中です。 | 指定された接続は、データ・ソースとの接続を確立するためにすでに使用されており、接続がまだオープンしています。 |
08004 | アプリケーション・サーバーが、接続の確立を拒否しました。 | データ・ソースが、処理系で定義された理由により接続の確立を拒否しました。 |
08S01 | 通信リンクに障害が起きました。 | 関数が処理を完了する前に、 DB2 CLI と接続を試行していたデータ・ソースとの間の通信リンクが失敗しました。 |
28000 | 許可指定が無効です。 | ブラウズ要求の接続ストリング (InConnectionString) に指定されているように、ユーザー識別子または許可ストリングもしくはその両方が、データ・ソースにより定義されている制約に違反していました。 |
HY000 | 一般的なエラーです。 | 特定の SQLSTATE がなかった場合のエラーが発生しました。 SQLGetDiagRec() により *MessageText バッファーに返されたエラー・メッセージに、そのエラーと原因が記述されています。 |
HY001 | メモリーの割り振り失敗です。 | DB2 CLI は、この関数の実行または完了をサポートするために必要なメモリーを割り当てられませんでした。 |
HY013 | 予期しないメモリーのハンドル・エラーが起きました。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを使用することができませんでした。 |
HY090 | ストリングまたはバッファー長が無効です。 | 引き数 StringLength1 に指定された値は、
0 より小さい値で、SQL_NTS に等しくありませんでした。
引き数 BufferLength に指定された値は、0 より小さい値でした。 |
制約
なし。
例
該当するサンプルの一覧については、 sqllib\samples\cli (または sqllib/samples/cli) サブディレクトリー内の README ファイルを参照してください。
参照