SQLAllocHandle - ハンドルの割り当て

目的

SQLAllocHandle() は環境ハンドル、接続ハンドル、または ステートメント・ハンドルを割り当てます。

この関数は、ハンドル割り当て用の汎用関数であり、バージョン 2 の 使用すべきでない関数 SQLAllocConnect()、SQLAllocEnv()、および SQLAllocStmt() を置き換えます。

構文

SQLRETURN   SQLAllocHandle   (SQLSMALLINT       HandleType,
                              SQLHANDLE         InputHandle,
                              SQLHANDLE         *OutputHandlePtr);

関数の引き数

表 30. SQLAllocHandle の引き数

使用法

SQLAllocHandle() は、以下に示すように、環境ハンドル、接続ハンドル、 およびステートメント・ハンドルを割り当てるために使用します。

1 つのアプリケーションによって一度に複数のステートメント・ハンドルを割り当て ることができます。

すでに存在している環境、接続、ステートメント、または 記述子ハンドルに対して設定されている *OutputHandlePtr を指定 してアプリケーションで SQLAllocHandle() を呼び出すと、DB2 CLI はハ ンドルに関連する情報 を上書きします。DB2 CLI では、*OutputHandlePtr に入力されたハ ンドルがすで に使用中であるかどうかのチェックは行いません。また、上書きの前に、ハン ドルの直前の内容をチェックすることもしません。

DB2 Everyplace の場合、ステートメント・ハンドルを除くすべてのハンドルは ダミー・ハンドルであり、使用可能な情報を持っていません。

ステートメント・ハンドルでは、エラー・メッセージ、および SQL ステートメント処理 に関する状況情報などの、ステートメント情報へのアクセスが行えます。 ステートメント・ハンドルを要求するには、アプリケーションでデータ・ソースに 接続した後 SQLAllocHandle() を呼び出して、その後で SQL ステート メントを実行依頼します。 この呼び出しのとき、HandleType を SQL_HANDLE_STMT に設定する とともに、InputHandle に関しては、そのハンドルを割り当てた SQLAllocHandle() への呼び出しが戻してきた接続ハンドルに設定す る必要があります。 DB2 CLI は、ステートメント・ハンドルを割り当てて、そのス テートメント・ハンドルを指定された接続に関連付け、関連付けされたハンドルの値を *OutputHandlePtr に戻します。 アプリケーションでは、ステートメント・ハンドルを要求した後続のすべての呼び 出し時に *OutputHandlePtr 値を渡します。

アプリケーションが終了すると、そのアプリケーションに割り当てられたすべて の DB2 Everyplace リソースが解放されるため、そのアプリケーションが使用 していたハンドルは無効になります。

DB2 Everyplace の場合、アプリケーションによって変更される可能性がある属性 を持つステートメント・ハンドルに関連する記述子はありません。

Visual Basic と DB2 Everyplace CLI/ODBC インターフェースで DB2 Everyplace を使用する場合は 、sqlcli.h で定義されているマップ/基礎 CLI 関数を明示的に呼び出さなければなりません。

例えば、SQLAllocHandle() の呼び出しは失敗します。 SQLAllocHandleVer(SQL_HANDLE_STMT, hdbc, hstmt, DB2eVersion) の呼び出しは成功します。

戻りコード

• SQL_SUCCESS
• SQL_SUCCESS_WITH_INFO
• SQL_INVALID_HANDLE
• SQL_ERROR

環境ハンドル以外のハンドルを割り当てる際に SQLAllocHandle() が SQL_ERROR を戻す場合、 SQLAllocHandle() は出力引き数がヌル・ポインターでなければ、 OutputHandlePtr を SQL_NULL_HENV、SQL_NULL_HDBC、または SQL_NULL_HSTMT に設定します。 このうちのどれに設定されるかは、HandleType の値によって決まります。 この後、アプリケーションは、InputHandle 引き数内のハンドルに関連する 診断データ構造から追加情報を入手することができます。

診断

表 31. SQLAllocHandle の SQLSTATE

関連した解説

• DB2 CLI 関数の説明の要点
• DB2 CLI 関数の要約
• SQLExecDirect - ステートメントの直接の実行
• SQLFreeHandle - ハンドル・リソースの解放