目的
仕様: | DB2 CLI 5.0 | ODBC 3.0 | ISO CLI |
SQLAllocHandle() は、環境、接続、ステートメント、または記述子ハンドルを割り振ります。
注: | この関数は、ハンドルを割り振るための汎用関数で、使用すべきでないバージョン 2 の関数 SQLAllocConnect()、 SQLAllocEnv()、および SQLAllocStmt() にとって代わるものです。 |
構文
SQLRETURN SQLAllocHandle (SQLSMALLINT HandleType, SQLHANDLE InputHandle, SQLHANDLE *OutputHandlePtr);
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLSMALLINT | HandleType | 入力 | SQLAllocHandle() によって割り振られるハンドルのタイプ。以下の値のうちの 1 つでなければなりません。
|
SQLHANDLE | InputHandle | 入力 | 割り振られる新規ハンドルに対してコンテキストとして使用する既存のハンドル。 HandleType が SQL_HANDLE_ENV である場合、これは SQL_NULL_HANDLE になります。 HandleType が SQL_HANDLE_DBC の場合は、これは環境ハンドルでなければなりません。また HandleType が SQL_HANDLE_STMT または SQL_HANDLE_DESC である場合は、接続ハンドルでなければなりません。 |
SQLHANDLE | OutputHandlePtr | 出力 | バッファーを指すポインター。そのバッファーの中で、新規に割り振られたデータ構造にハンドルが返されます。 |
使用法
SQLAllocHandle() は、以下に示すように、環境、接続、ステートメント、および記述子ハンドルを割り振るために使用します。
複数の環境、接続、またはステートメント・ハンドルを、アプリケーションによって一度に割り振ることができます。
アプリケーションが、既存の環境、接続、ステートメント、または記述子ハンドルに対して、 SQLAllocHandle() と *OutputHandlePtr を呼び出す場合、 DB2 CLI はハンドルに関連した情報を上書きします。 DB2 CLI は、*OutputHandlePtr に入力されたハンドルがすでに使用中であるかどうかを調べませんし、そのハンドルに上書きする前にハンドルの以前の内容を調べることもしません。
マルチ・スレッドをサポートするオペレーティング・システムでは、アプリケーションは、異なるスレッド上で同じ環境、接続、ステートメント、または記述子ハンドルを使用できます。 DB2 CLI は、すべてのハンドルおよび関数呼び出しについてスレッド・セーフのアクセスを提供します。アプリケーションの作成するスレッドが DB2 CLI 資源の使用を調整しない場合は、アプリケーション自体が予期しない動作を経験するかもしれません。詳細については、マルチスレッドのアプリケーション作成を参照してください。
環境ハンドルの割り振り
環境ハンドルは、有効な接続ハンドルおよび活動状態の接続ハンドルのようなグローバル情報へのアクセスを提供します。環境ハンドルを要求するには、アプリケーションが、SQL_HANDLE_ENV の HandleType および SQL_NULL_HANDLE の HandleType を用いて SQLAllocHandle() を呼び出します。 DB2 CLI は、環境ハンドルを割り振って、関連したハンドルの値を *OutputHandlePtr 引き数に渡します。アプリケーションは、*OutputHandle 値を、環境ハンドル引き数を必要とする後続のすべての呼び出しに渡します。
DB2 CLI が SQL_HANDLE_ENV の HandleType を使用して SQLAllocHandle() 関数を処理するとき、 DB2 CLI は db2cli.ini ファイルの [COMMON] セクション内の Trace キーワードを調べます。 1 に設定してある場合、DB2 CLI は現行のアプリケーションをトレースすることができます。トレース・フラグが設定されている場合、トレースは、最初の環境ハンドルが割り当てられる時に開始し、最後の環境ハンドルが解放される時に終了します。詳細については、TRACE を参照してください。
環境ハンドルを割り振った後、アプリケーションは、環境ハンドル上で SQLSetEnvAttr() を呼び出して、 SQL_ATTR_ODBC_VERSION 環境属性を設定しなければなりません。アプリケーションが ODBC アプリケーションとして実行され、そして環境に接続ハンドルを割り振るために SQLAllocHandle() が呼び出される前にこの属性が設定されない場合は、接続を割り振る呼び出しが SQLSTATE HY010 (関数の順序エラーです。) を返します。
接続ハンドルの割り振り
接続ハンドルは、接続上の有効なステートメントおよび記述子ハンドルなどの情報や、トランザクションが現在オープンしているかどうかといった情報を使用できるようにします。接続ハンドルを要求するには、アプリケーションが、 SQL_HANDLE_DBC の HandleType を用いて SQLAllocHandle() を呼び出します。 InputHandle 引き数は、ハンドルを割り振った SQLAllocHandle() への呼び出しによって返された環境ハンドルに設定されます。 DB2 CLI は、接続ハンドルを割り振って、関連したハンドルの値を *OutputHandlePtr に戻します。アプリケーションは、接続ハンドルを必要とするすべての後続の呼び出しで *OutputHandlePtr を渡します。
その環境で接続ハンドルを割り振るために SQLAllocHandle() が呼び出される前に、 SQL_ATTR_ODBC_VERSION 環境属性が設定されていない場合は、接続を割り振る呼び出しは、アプリケーションが ODBC ドライバー・マネージャーを使用中のときは、 SQLSTATE HY010 (関数の順序エラーです。) を返すことになります。
ステートメント・ハンドルの割り振り
ステートメント・ハンドルは、エラー・メッセージ、カーソル名のようなステートメント情報、および SQL ステートメント処理の状況情報を使用できるようにします。ステートメント・ハンドルを要求するには、アプリケーションがデータ・ソースに接続して、 SQL ステートメントの実行前に、SQLAllocHandle() を呼び出します。この呼び出しで、HandleType を SQL_HANDLE_STMT に設定し、 InputHandle を接続ハンドルに設定してください。その接続ハンドルは、ハンドルを割り振る SQLAllocHandle() への呼び出しによって返されたものです。 DB2 CLI は、ステートメント・ハンドルを割り振り、指定した接続とステートメント・ハンドルを関連付け、そして関連付けたハンドルの値を *OutputHandlePtr に戻します。アプリケーションは、ステートメント・ハンドルを必要とするすべての後続の呼び出しで *OutputHandlePtr 値を渡します。
ステートメント・ハンドルが割り振られるとき、DB2 CLI は、自動的に 1 組の 4 つの記述子を割り振り、その記述子用ハンドルを SQL_ATTR_APP_ROW_DESC、SQL_ATTR_APP_PARAM_DESC、 SQL_ATTR_IMP_ROW_DESC、SQL_ATTR_IMP_PARAM_DESC ステートメント属性に割り当てます。自動的に割り振られたものの代わりに明示的に割り当てられたアプリケーション記述子を使用するには、以下の『記述子ハンドルの割り振り』の項を参照してください。
記述子ハンドルの割り振り
アプリケーションが SQL_HANDLE_DESC の HandleType を用いて SQLAllocHandle() を呼び出すと、 DB2 CLI は、アプリケーション記述子を明示的に割り振ります。アプリケーションは、自動的に割り振られたアプリケーション記述子の代わりに、 SQL_ATTR_APP_ROW_DESC または SQL_ATTR_APP_PARAM_DESC 属性付きの SQLSetStmtAttr() を呼び出すことにより、明示的に割り振られたアプリケーション記述子を使用することができます。実装記述子は、明示的に割り振ることができず、また SQLSetStmtAttr() 関数の中に指定することもできません。
明示的に割り振られる記述子は、(自動的に割り振られた記述子がそうであるように) ステートメント・ハンドルよりも、接続ハンドルに関連があります。記述子は、アプリケーションが実際にデータベースに接続中のときにだけ、接続ハンドルに関連付けることができます。明示的に割り振られた記述子は、接続ハンドルに関連付けられるので、アプリケーションは、割り振られた記述子を接続内の複数のステートメントに明示的に関連付けることができます。他方、自動的に割り振られたアプリケーション記述子は、複数のステートメント・ハンドルに関連付けることができません。明示的に割り振られた記述子ハンドルは、 SQL_HANDLE_DESC の HandleType を用いて SQLFreeHandle() を呼び出すことにより、アプリケーションによって明示的に解放するか、または切断の際に接続ハンドルが解放されるときに、暗黙的に解放することができます。
明示的に割り振られたアプリケーション記述子がステートメントに関連付けられるときに、もはや使用されていない自動的に割り振られた記述子は、まだ接続ハンドルに関連付けられています。明示的に割り振られた記述子が解放されるとき、自動的に割り振られた記述子は、再びステートメントと関連付けられます (そのステートメント用の SQL_ATTR_APP_ROW_DESC または SQL_ATTR_APP_PARAM_DESC 属性は、自動的に割り振られた記述子ハンドルに設定されます)。このことは、明示的に割り振られた記述子に接続で関連付けられたすべてのステートメントにあてはまります。各ステートメントの元の自動的に割り振られた記述子ハンドルは、再びそのステートメントと関連付けられます。
記述子が最初に使用されるとき、その SQL_DESC_TYPE フィールドの初期値は SQL_C_DEFAULT です。 DATA_PTR、INDICATOR_PTR、および OCTET_LENGTH_PTR は、すべてヌル・ポインターに初期設定されます。その他のフィールドの初期値については、SQLSetDescField - 記述子レコードの単一フィールドを設定するを参照してください。
詳細については、記述子の使用を参照してください。
戻りコード
環境ハンドル以外のハンドルを割り振るとき、 SQLAllocHandle() が SQL_ERROR を返すならば、出力引き数が NULL ポインターでなければ、HandleType の値によって、 OutputHandlePtr を SQL_NULL_HENV、 SQL_NULL_HDBC、SQL_NULL_HSTMT、または SQL_NULL_HDESC に設定します。アプリケーションは、次に、 InputHandle 引き数内のハンドルに関連付けられる診断データ構造体から追加情報を入手することができます。
環境ハンドルの割り振りエラー
診断
SQLSTATE | 説明 | 解説 |
---|---|---|
01000 | 警告。 | 通知メッセージ。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。) |
08003 | 接続がクローズされています。 | HandleType 引き数は、SQL_HANDLE_STMT または SQL_HANDLE_DESC でしたが、 InputHandle 引き数によって指定される接続は、オープンしていませんでした。 DB2 CLI がステートメント・ハンドルまたは記述子ハンドルを割り振るには、接続処理が正常に完了して (そして接続がオープンされて) いなければなりません。 |
HY000 | 一般的なエラーです。 | 特定の SQLSTATE がなかった場合のエラーが発生しました。 SQLGetDiagRec() により *MessageText バッファーに返されたエラー・メッセージに、そのエラーと原因が記述されています。 |
HY001 | メモリーの割り振り失敗です。 | DB2 CLI は、指定したハンドル用のメモリーを割り振りできませんでした。 |
HY010 | 関数の順序エラーです。 | HandleType 引き数は SQL_HANDLE_DBC でしたが、 SQLSetEnvAttr() は、 SQL_ODBC_VERSION 環境属性の設定用に呼び出されていません。 |
HY013 | 予期しないメモリーのハンドル・エラーが起きました。 | HandleType 引き数が SQL_HANDLE_DBC、 SQL_HANDLE_STMT、または SQL_HANDLE_DESC であり、基礎メモリー・オブジェクトにアクセスできない (メモリー不足が原因と考えられる) ため、関数呼び出しを処理できませんでした。 |
HY014 | もはやハンドルはありません。 | HandleType 引き数によって指定されるハンドルのタイプについて割り振ることのできるハンドルの数の限界に達しました。 |
HY092 | オプション・タイプが範囲外です。 | HandleType 引き数は、以下のものではありませんでした。
|
HYC00 | ドライバーが機能していません。 | HandleType 引き数は SQL_HANDLE_DESC でしたが、 DB2 CLI ドライバーは、バージョン 2 またはそれ以前のものでした。 |
制約
なし。
(ここで完全サンプル utilcli.c を使用することもできます 。)
/* From the CLI sample utilcli.c */ /* ... */ /* allocate an environment handle */ sqlrc = SQLAllocHandle( SQL_HANDLE_ENV, SQL_NULL_HANDLE, pHenv ) ; if ( sqlrc != SQL_SUCCESS ) { printf( "\n--ERROR while allocating the environment handle.\n" ) ; printf( " sqlrc = %d\n", sqlrc); printf( " line = %d\n", __LINE__); printf( " file = %s\n", __FILE__); return( 1 ) ; } /* ... */ /* allocate a database connection handle */ sqlrc = SQLAllocHandle( SQL_HANDLE_DBC, *pHenv, pHdbc ) ; HANDLE_CHECK( SQL_HANDLE_ENV, *pHenv, sqlrc, pHenv, pHdbc ) ;
参照