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	クライアントが接続を確立できない	HADB ODBCドライバは，データソースに接続できません。 DriverCompletionにSQL_DRIVER_NOPROMPTが指定されていますが，接続に必要な属性文字列がInConnectionStringに指定されていません。	○
08002	接続名が使用中である	−	×
08004	サーバが接続を拒否した	データソースは実装時に定義された理由で接続の確立を拒否しました。	×
08S01	通信リンク失敗	−	×
28000	無効な認証指定	接続文字列で指定された認可識別子またはパスワードが，データソース定義の制限に違反しています。	○
5C002	文字コードの変換エラー	変換できない文字コードを検出しました。	○
5C052	バージョン不一致エラー	ODBCドライバとHADBクライアントのバージョンが異なります。	○
5D001	HADB固有のエラー	HADBでエラーが発生しましたが，固有のSQLSTATEまたはエラーメッセージが取得できません。	○
HY000	一般エラー	−	×
HY001	メモリ割り当てエラー		×
HY013	メモリ管理エラー	メモリオブジェクトにアクセスできないため，関数の呼び出しを処理できません。	×
HY090	無効な文字列長または無効なバッファ長	InConnectionStringに指定された接続属性に対する属性値が無効な長さです。 BufferLengthに無効な値（SQL_NTS）が指定されました。	○
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　システム構築・運用ガイドのパスワードの指定規則を参照してください。

ページの先頭へ