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 |
無効な文字列長または無効なバッファ長 |
|
○ |
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を実行してください。または,アプリケーションを強制終了してください。