16.3.4　SQLBrowseConnect，SQLBrowseConnectW

(1)　機能

データソース（HADBサーバ）との接続に必要な属性と属性値を1つずつ参照する方法をサポートします。SQLBrowseConnectまたはSQLBrowseConnectWを呼び出すたびに，連続するレベルの属性と属性値を返します。すべてのレベルの属性を指定すると，データソースへの接続が完了し，完全な接続文字列を返します。

なお，SQLBrowseConnectまたはSQLBrowseConnectWを実行するにはCONNECT権限が必要です。

ページの先頭へ

(2)　形式

• SQLBrowseConnectの場合

  SQLRETURN SQLBrowseConnect
  (
    SQLHDBC         ConnectionHandle,        /* In */
    SQLCHAR       * InConnectionString,      /* In */
    SQLSMALLINT     StringLength1,           /* In */
    SQLCHAR       * OutConnectionString,     /* Out */
    SQLSMALLINT     BufferLength,            /* In */
    SQLSMALLINT   * StringLength2Ptr         /* Out */
  )

• SQLBrowseConnectWの場合

  SQLRETURN SQLBrowseConnectW
  (
    SQLHDBC         ConnectionHandle,        /* In */
    SQLWCHAR      * InConnectionString,      /* In */
    SQLSMALLINT     StringLength1,           /* In */
    SQLWCHAR      * OutConnectionString,     /* Out */
    SQLSMALLINT     BufferLength,            /* In */
    SQLSMALLINT   * StringLength2Ptr         /* Out */
  )

ページの先頭へ

(3)　引数

ConnectionHandle：

接続ハンドルを指定します。

InConnectionString：

ブラウズ要求接続文字列を指定します。

ブラウズ要求接続文字列に指定できる接続属性は次のとおりです。

接続属性	説明
DSN	データソース名称
DRIVER	ODBCドライバ名称："Hitachi Advanced Data Binder ODBC Driver"
UID	認可識別子
PWD	パスワード
CLTPATH	クライアント定義ファイルの絶対パス

StringLength1：

InConnectionStringに指定したブラウズ要求接続文字列の長さ^※を指定します。

InConnectionStringに指定したブラウズ要求接続文字列がNULL終端文字で終わる場合は，SQL_NTSを指定する必要があります。

また，0や負の値を指定した場合は，エラーとなります。

OutConnectionString：

ブラウズ結果接続文字列を格納するバッファへのポインタを指定します。

HADBサーバへの接続に成功した場合の接続文字列を完全な接続文字列として返します。

SQL_NEED_DATAを返す場合，HADBサーバとの接続時に不足した接続属性を返します。

BufferLength：

OutConnectionStringを格納するバッファの長さ^※を指定します。

この長さにNULL終端文字は含まれます。SQL_NTSは指定できません。

StringLength2Ptr：

ブラウズ結果接続文字列の有効な長さ^※を格納するバッファへのポインタを指定します。この長さにNULL終端文字は含まれません。

OutConnectionStringに返される文字列の有効な長さ^※を返します。

重要

ここに格納された接続文字列の長さ^※が，BufferLengthからNULL終端文字分を引いた長さ^※より大きい場合，OutConnectionStringに格納される文字列はBufferLengthからNULL終端文字分を引いた長さ^※に切り捨てられ，末尾にNULL終端文字が付加されます。

注※

長さの単位は，SQLBrowseConnectの場合はバイト長，SQLBrowseConnectWの場合は文字数となります。

ページの先頭へ

(4)　戻り値

SQL_SUCCESS，SQL_SUCCESS_WITH_INFO，SQL_NEED_DATA，SQL_ERROR，またはSQL_INVALID_HANDLEが返されます。

ページの先頭へ

(5)　SQLSTATE

この関数では次のSQLSTATEを返します。

SQLSTATE	説明	備考	返却
01000	一般警告	−	×
01004	文字列データの右側が切り捨てられた	*OutConnectionStringバッファの大きさが不足しているため，ブラウズ結果接続文字列を格納できませんでした（情報が切り捨てられました）。切り捨てられる前のブラウズ結果接続文字列の長さが，*StringLength2Ptrバッファに格納されます。このとき，SQL_NEED_DATAを返します。	○
01S00	無効な接続文字列属性	ブラウズ要求接続文字列（InConnectionString）に無効な属性キーワードが含まれています。このとき，SQL_NEED_DATAを返します。 ブラウズ要求接続文字列（InConnectionString）に指定された属性キーワードは現在の接続レベルに適用できません。このとき，SQL_NEED_DATAを返します。	○
01S02	オプション値の変更	HADB ODBCドライバはSQLSetConnectAttrまたはSQLSetConnectAttrWのValuePtrに指定された値をサポートしていないため，類似の値で置き換えられました。このとき，SQL_SUCCESS_WITH_INFOを返します。	×
01S51	文字コード変換時に置き換えが発生した	変換できない文字コードを検出し，指定の文字に置き換えました。このとき，SQL_SUCCESS_WITH_INFOを返します。	○
08001	クライアントが接続を確立できない	HADB ODBCドライバは，データソースに接続できません。	×
08002	接続名が使用中である	−	×
08S01	通信リンク失敗		×
28000	無効な認証指定	ブラウズ要求接続文字列で指定された認可識別子またはパスワードが，データソースの制限に違反しています。	○
5C002	文字コードの変換エラー	変換できない文字コードを検出しました。	○
5C052	バージョン不一致エラー	ODBCドライバとHADBクライアントのバージョンが異なります。	○
5D001	HADB固有のエラー	HADBでエラーが発生しましたが，固有のSQLSTATEまたはエラーメッセージが取得できません。	○
HY000	一般エラー	−	×
HY001	メモリ割り当てエラー		×
HY013	メモリ管理エラー	メモリオブジェクトにアクセスできないため，関数の呼び出しを処理できません。	×
HY090	無効な文字列長または無効なバッファ長	InConnectionStringに指定された接続属性に対する属性値が無効な長さです。 BufferLengthに無効な値（SQL_NTS）が指定されました。	○
HYT00	タイムアウト終了	データソースの接続が完了する前にログインタイムアウト時間が経過しました。ログインタイムアウト時間は，SQLSetConnectAttrまたはSQLSetConnectAttrWのSQL_ATTR_LOGIN_TIMEOUTで設定できます。	×
HYT01	接続タイムアウト終了	データソースが要求に応答する前に接続タイムアウト時間が経過しました。接続タイムアウト時間は，SQLSetConnectAttrまたはSQLSetConnectAttrWのSQL_ATTR_CONNECTION_TIMEOUTで設定できます。	×
IM001	ドライバはこの関数をサポートしていない	−	×
IM002	データソースが見つからない かつ デフォルトのドライバが指定されていない		×
IM003	指定されたドライバがロードできない		×
IM004	ドライバがSQL_HANDLE_ENVに対するSQLAllocHandleに失敗した		×
IM005	ドライバがSQL_HANDLE_DBCに対するSQLAllocHandleに失敗した		×
IM006	ドライバがSQLSetConnectAttrまたはSQLSetConnectAttrWに失敗した		×
IM009	トランスレータDLLをロードできない		×
IM010	データソース名が長過ぎる		×
IM011	ドライバ名が長過ぎる		×
IM012	DRIVERキーワードの構文エラー		×

（凡例）

○：HADB ODBCドライバが返すことがあるSQLSTATEです。

×：HADB ODBCドライバが返さないSQLSTATEです。

−：なし。

ページの先頭へ

(6)　注意事項

• ブラウズ要求接続文字列に指定する接続属性を次の表に示します。

  表16‒3　ブラウズ要求接続文字列に指定する接続属性

  項番	接続属性	接続属性値	指定要否
  			DSN接続	DRIVER接続
  1	DSN	データソース名称を指定してください。	○	−
  2	DRIVER	ODBCドライバ名称を指定してください。ODBCドライバの名称は"Hitachi Advanced Data Binder ODBC Driver"です。	−	○
  3	UID	認可識別子を指定してください。	○	○
  4	PWD	パスワードを指定します。 255バイト以下の文字列を指定してください。	○	○
  5	CLTPATH	クライアント定義ファイルを絶対パスで指定してください。クライアント定義ファイルを絶対パスで指定する際，255バイト以下の文字列を指定してください。この指定を省略した場合は，環境定義ADBCLTDIRに指定したフォルダ下にあるファイルを使用します。	−	△

  （凡例）

  ○：必ず指定する接続属性です。

  △：任意で指定する接続属性です。

  −：指定する必要がない接続属性です。

• ブラウズ要求接続文字列の指定例を次に示します。

  • "DSN=XXXXX;UID=YYYYY;PWD=ZZZZZ"

  • "DRIVER=Hitachi Advanced Data Binder ODBC Driver;CLTPATH=XXXXX;UID=YYYYY;PWD=ZZZZZ"

• DSN接続属性およびDRIVER接続属性をブラウズ要求接続文字列中に両方指定した場合，あとに指定した接続属性が有効になります。

• 同じ接続属性がブラウズ要求接続文字列中に重複して指定されている場合，先に指定した接続属性の接続属性値が有効になります。

• ブラウズ要求接続文字列に指定する接続属性は順不同に指定できますが，最初の要求時に"DSN=XXXXX"または"DRIVER=Hitachi Advanced Data Binder ODBC Driver"の指定がない場合，ODBCドライバマネージャでエラーになります。

• 接続属性は大文字，小文字を区別しません。

• 接続属性値は大文字，小文字を区別します。

• ;（セミコロン）は，区切り文字として扱います。このため，接続属性値のパスワード文字列中に;（セミコロン）を含めることはできません。また，ODBC実装規約によって，パスワードには，[，]，{，}，(，)，,，?，*，=，!，@の12種類の文字は含めないことを推奨します。HADBのパスワードについては，マニュアルHADB　システム構築・運用ガイドのパスワードの指定規則を参照してください。

• この関数の引数に指定したパラメタの値不正によってSQL_NEED_DATAが返却された場合にこの関数を再実行し，パスワードの文字列などの不正によってSQL_ERRORが返却されたときは，そのままSQLFreeHandleを実行してもODBCドライバマネージャからSQL_ERROR（SQLSTATE：HY010）が返却されて，ハンドルが解放されないおそれがあります。この場合，正しいパラメタを設定して関数を再実行したあとに，SQLFreeHandleを実行してください。または，アプリケーションを強制終了してください。

ページの先頭へ