16.3.3 SQLDriverConnect,SQLDriverConnectW
(1) 機能
次の接続属性のどれかを使用して,データソース(HADBサーバ)との接続を確立します。
-
データソース名称,1つ以上の認可識別子,1つ以上のパスワード,およびデータソースとの接続に必要なほかの情報を含む接続文字列を使用して接続を確立します。
-
部分的な接続文字列および追加情報を使用しないで接続を確立します。この場合,ドライバマネージャとHADB ODBCドライバは,APに接続情報を要求します。
-
システム定義で定義されていないデータソースとの接続を確立します。アプリケーションが部分的な接続文字列を提供した場合,HADB ODBCドライバはユーザに接続情報を要求します。
-
.dsnファイルの情報から作成された接続文字列を使用して,データソースとの接続を確立します。
接続が確立すると,SQLDriverConnectまたはSQLDriverConnectWは完全な接続文字列を返します。
なお,SQLDriverConnectまたはSQLDriverConnectWを実行するにはCONNECT権限が必要です。
(2) 形式
-
SQLDriverConnectの場合
SQLRETURN SQLDriverConnect ( SQLHDBC ConnectionHandle, /* In */ SQLHWND WindowHandle, /* In */ SQLCHAR * InConnectionString, /* In */ SQLSMALLINT StringLength1, /* In */ SQLCHAR * OutConnectionString, /* Out */ SQLSMALLINT BufferLength, /* In */ SQLSMALLINT * StringLength2Ptr, /* Out */ SQLUSMALLINT DriverCompletion /* In */ )
-
SQLDriverConnectWの場合
SQLRETURN SQLDriverConnectW ( SQLHDBC ConnectionHandle, /* In */ SQLHWND WindowHandle, /* In */ SQLWCHAR * InConnectionString, /* In */ SQLSMALLINT StringLength1, /* In */ SQLWCHAR * OutConnectionString, /* Out */ SQLSMALLINT BufferLength, /* In */ SQLSMALLINT * StringLength2Ptr, /* Out */ SQLUSMALLINT DriverCompletion /* In */ )
(3) 引数
- ConnectionHandle:
-
接続ハンドルを指定します。
- WindowHandle:
-
親ウィンドウのハンドルを指定します。
ウィンドウを適用できない,またはダイアログボックスを表示しない場合は,NULLポインタを指定してください。
- InConnectionString:
-
接続文字列を指定します。
接続文字列に指定できる接続属性は次のとおりです。
接続属性
説明
DSN
データソース名称
DRIVER
ODBCドライバ名称:"Hitachi Advanced Data Binder ODBC Driver"
UID
認可識別子
PWD
パスワード
CLTPATH
クライアント定義ファイルの絶対パス
- StringLength1:
-
InConnectionStringに指定した接続文字列の長さ※を指定します。
InConnectionStringに指定した接続文字列がNULL終端文字で終わる場合は,SQL_NTSを指定する必要があります。
また,0や負の値を指定した場合は,エラーとなります。
- OutConnectionString:
-
完全な接続文字列を格納するバッファへのポインタを指定します。
HADBサーバへの接続に成功した場合の接続文字列を完全な接続文字列として返します。
- BufferLength:
-
OutConnectionStringを格納するバッファの長さ※を指定します。
この長さにNULL終端文字は含まれます。SQL_NTSは指定できません。
- StringLength2Ptr:
-
完全な接続文字列の有効な長さ※を格納するバッファへのポインタを指定します。この長さにNULL終端文字は含まれません。
- 重要
-
ここに格納された接続文字列の長さ※が,BufferLengthからNULL終端文字分を引いた長さ※より大きい場合,OutConnectionStringに格納される文字列はBufferLengthからNULL終端文字分を引いた長さ※に切り捨てられ,末尾にNULL終端文字が付加されます。
- DriverCompletion:
-
ドライバマネージャまたはHADB ODBCドライバがさらに接続情報を必要とするかどうかをフラグで指定します。次のフラグが指定できます。
-
SQL_DRIVER_PROMPT
-
SQL_DRIVER_COMPLETE
-
SQL_DRIVER_COMPLETE_REQUIRED
-
SQL_DRIVER_NOPROMPT
-
- 注※
-
長さの単位は,SQLDriverConnectの場合はバイト長,SQLDriverConnectWの場合は文字数となります。
(4) 戻り値
SQL_SUCCESS,SQL_SUCCESS_WITH_INFO,SQL_NEED_DATA,SQL_NO_DATA,SQL_ERROR,またはSQL_INVALID_HANDLEが返されます。
(5) SQLSTATE
この関数では次のSQLSTATEを返します。
SQLSTATE |
説明 |
備考 |
返却 |
---|---|---|---|
01000 |
一般警告 |
− |
× |
01004 |
文字列データの右側が切り捨てられた |
*OutConnectionStringバッファの大きさが不足しているため,完全な接続文字列を格納できませんでした(情報が切り捨てられました)。切り捨てられる前の完全な接続文字列の長さが,*StringLength2Ptrバッファに格納されます。このとき,SQL_SUCCESS_WITH_INFOを返します。 |
○ |
01S00 |
無効な接続文字列属性 |
接続文字列(InConnectionString)に無効な属性キーワードが含まれています。このとき,SQL_SUCCESS_WITH_INFOを返します。 |
○ |
01S02 |
オプション値の変更 |
HADB ODBCドライバはSQLSetConnectAttrまたはSQLSetConnectAttrWのValuePtrに指定された値をサポートしていないため,類似の値で置き換えました。このとき,SQL_SUCCESS_WITH_INFOを返します。 |
× |
01S08 |
ファイルDSNの保存エラー |
*InConnectionStringの接続文字列にFILEDSNキーワードが含まれていますが,.dsnファイルが保存されませんでした。このとき,SQL_SUCCESS_WITH_INFOを返します。 |
× |
01S09 |
無効なキーワード |
− |
× |
01S51 |
文字コード変換時に置き換えが発生した |
変換できない文字コードを検出し,指定の文字に置き換えました。このとき,SQL_SUCCESS_WITH_INFOを返します。 |
○ |
08001 |
クライアントが接続を確立できない |
|
○ |
08002 |
接続名が使用中である |
− |
× |
08004 |
サーバが接続を拒否した |
データソースは実装時に定義された理由で接続の確立を拒否しました。 |
× |
08S01 |
通信リンク失敗 |
− |
× |
28000 |
無効な認証指定 |
接続文字列で指定された認可識別子またはパスワードが,データソース定義の制限に違反しています。 |
○ |
5C002 |
文字コードの変換エラー |
変換できない文字コードを検出しました。 |
○ |
5C052 |
バージョン不一致エラー |
ODBCドライバとHADBクライアントのバージョンが異なります。 |
○ |
5D001 |
HADB固有のエラー |
HADBでエラーが発生しましたが,固有のSQLSTATEまたはエラーメッセージが取得できません。 |
○ |
HY000 |
一般エラー |
− |
× |
HY001 |
メモリ割り当てエラー |
× |
|
HY013 |
メモリ管理エラー |
メモリオブジェクトにアクセスできないため,関数の呼び出しを処理できません。 |
× |
HY090 |
無効な文字列長または無効なバッファ長 |
|
○ |
HY092 |
無効な属性識別子,または無効なオプション識別子 |
− |
× |
HY110 |
DriverCompletionが無効なオプション識別子 |
× |
|
HYC00 |
オプション機能は実装されていない |
HADB ODBCドライバはアプリケーションが要求したODBCの動作をサポートしていません。 |
× |
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に失敗した |
× |
|
IM007 |
データソースまたはドライバが指定されていない かつ ダイアログが禁止された |
接続文字列にデータソース名称またはドライバ名称が指定されていませんが,DriverCompletionにSQL_DRIVER_NOPROMPTが指定されています。 |
× |
IM008 |
ダイアログの失敗 |
ドライバはログインダイアログボックスを表示しようとしましたが失敗しました。 WindowHandleにNULLポインタが指定されていますが,DriverCompletionにSQL_DRIVER_NOPROMPTが指定されていません。 |
× |
IM009 |
トランスレータDLLをロードできない |
− |
× |
IM010 |
データソース名が長過ぎる |
× |
|
IM011 |
ドライバ名が長過ぎる |
× |
|
IM012 |
DRIVERキーワードの構文エラー |
× |
|
IM014 |
ファイルDSNの名前が無効である |
× |
|
IM015 |
ファイルデータソースが壊れている |
× |
- (凡例)
-
○:HADB ODBCドライバが返すことがあるSQLSTATEです。
×:HADB ODBCドライバが返さないSQLSTATEです。
−:なし。
(6) 注意事項
-
接続文字列に指定する接続属性を次の表に示します。
表16‒2 接続文字列に指定する接続属性 項番
接続属性
接続属性値
指定要否
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ドライバマネージャでエラーになります。ただし,FILEDSN指定の場合は該当しません。
-
接続属性は大文字,小文字を区別しません。
-
接続属性値は大文字,小文字を区別します。
-
;(セミコロン)は,区切り文字として扱います。このため,接続属性値のパスワード文字列中に;(セミコロン)を含めることはできません。また,ODBC実装規約によって,パスワードには,[,],{,},(,),,,?,*,=,!,@の12種類の文字は含めないことを推奨します。HADBのパスワードについては,マニュアルHADB システム構築・運用ガイドのパスワードの指定規則を参照してください。