SQLAllocHandle() - ハンドルを割り振る

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

SQLAllocHandle() の ODBC 仕様

表 1. SQLAllocHandle() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
3.0 あり あり

構文

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

関数の引数

次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。

表 2. SQLAllocHandle() の引数
データ・タイプ 引数 使用法 説明
SQLSMALLINT HandleType 入力 割り振るハンドルのタイプを指定します。 この引数に、次のいずれかの値を設定します。
  • SQL_HANDLE_ENV -- 環境ハンドルの場合
  • SQL_HANDLE_DBC -- 接続ハンドルの場合
  • SQL_HANDLE_STMT -- ステートメント・ハンドルの場合
SQLHANDLE InputHandle 入力 新しいハンドルをそこから割り振るハンドルを指定します。 割り振るハンドルのタイプに応じて、異なる値をこの引数に設定します。 引数 InputHandle を次のいずれかの値に設定します。
  • 環境ハンドルを割り振る場合は、SQL_NULL_HANDLE (または、この引数を無視する)。
  • 接続ハンドルを割り振る場合は、環境ハンドル。
  • ステートメント・ハンドルを割り振る場合は、接続ハンドル。
SQLHANDLE * OutputHandlePtr 出力 SQLAllocHandle() が新しく割り振られたハンドルを戻すバッファーを指します。

使用法

SQLAllocHandle() を使用して、環境ハンドル、接続ハンドル、およびステートメント・ハンドルを割り振ります。
  • 環境ハンドルの割り当て

    環境ハンドルは、グローバル情報へのアクセスを提供します。 アプリケーションで環境ハンドルを要求するには、引数 HandleType を SQL_HANDLE_ENV に設定し、引数 InputHandle を SQL_NULL_HANDLE に設定して、SQLAllocHandle() を 呼び出します。(環境ハンドルを割り振る場合は、InputHandle は無視され ます。) Db2® ODBC は環境ハンドルを割り振り、関連付けられたハンドルの値を引数 *OutputHandlePtr に 渡します。 アプリケーションは、環境ハンドル引数を必要とする後続のすべての呼び出し に、*OutputHandle 値を渡します。

    SQLAllocHandle() を呼び出して環境ハンドルを要求する場合、Db2 ODBC 3.0 ドライバーは暗黙的 に SQL_ATTR_ODBC_VERSION = SQL_OV_ODBC3 を設定します。

    環境ハンドルを割り振る場合、Db2 ODBC 3.0 ドライバーは Db2 ODBC 初期化ファイルの共通セクションにあるトレース・キーワードをチェックします。 このキーワードが設定されている場合は、Db2 ODBC はトレースを使用可能にします。Db2 ODBC は、環境 ハンドルが解放されると、トレースを終了します。

    Db2 ODBC 3.0 ドライバーは複数環境をサポートしません。

  • 接続ハンドルの割り当て

    接続ハンドルは、接続上の有効なステートメント・ハンドル、および トランザクションが現在オープンしているかどうかなどの情報にアクセスします。 接続ハンドルを要求するには、引数 HandleType を SQL_HANDLE_DBC に 設定して、SQLAllocHandle() を呼び出します。引数 InputHandle を 現行の環境ハンドルに設定します。Db2 ODBC は接続ハンドルを割り振り、 関連付けられたハンドルの値を *OutputHandlePtr に戻します。 この接続ハンドルが引数として必要な後続のすべての関数呼び出し に、*OutputHandlePtr を渡します。

    単一の環境ハンドルのコンテキストから、複数の接続ハンドルを割り振ることができます。

  • ステートメント・ハンドルの割り当て

    ステートメント・ハンドルは、メッセージ、カーソル名、 および SQL ステートメント処理に関する状況情報など、 ステートメント・ハンドル情報にアクセスします。 ステートメント・ハンドルを要求するには、データ・ソースに接続して から、SQLAllocHandle() を呼び出します。SQL ステートメントをサブミットする前に、ステートメント ・ハンドルを割り振る必要があります。この呼び出しでは、引数 HandleType を SQL_HANDLE_STMT に 設定します。引数 InputHandle は、SQL を実行する接続に関連した接続ハンドルに設定 します。Db2 ODBC は、ステートメント・ハンドルを割り振り、ステートメント・ハンドルを 指定された接続に関連付け、さらに関連したハンドルの値を *OutputHandlePtr に 戻します。このステートメント・ハンドルが引数として必要な後続のすべての関数呼び出し に、*OutputHandlePtr の値を渡します。

    単一の接続ハンドルのコンテキストから、複数のステートメント・ハンドルを割り振ることができます。

  • ハンドルの管理
    Db2 ODBC アプリケーションは、複数の接続ハンドルと複数のステートメント・ハンドルを 同時に割り振ることができます。以下の条件が 1 つ以上当てはまる場合のみ、複数の接続ハンドルを割り振り、 複数の接続を行うことができます。
    • 接続が整合して動くように、接続タイプが設定されている。
    • 複数のコンテキストが使用可能。
    • 複数の言語処理環境のスレッドを使用。
    これらの条件が 1 つも当てはまらない場合に複数の接続ハンドルを割り振ろうと すると、Db2 ODBC ドライバーは SQLSTATE 08001 を戻します。

    また、Db2 ODBC 3.0 ドライバー・アプリケーションも、同じ環境ハンドル、同じ接続ハンドル、 または同じステートメント・ハンドルを、複数のスレッドで使用することができ ます。Db2 ODBC は、すべてのハンドル呼び出しおよび関数呼び出しに対して、 スレッド・セーフのアクセスを提供します。単一の言語処理環境のスレッド内のそれぞれの接続は、それ自体のリカバリー単位を 維持しています。

    複数の言語処理環境のスレッドを使用するアプリケーションの場合、お客様が複数の リカバリー単位を調整し、言語処理環境のスレッド間で Db2 ODBC リソースを管理する必要があります。お客様のアプリケーションでこの調整と管理操作を行っていないと、アプリケーションは予期せぬ動きをする ことがあります。例えば、異なるスレッドで同じ接続に対して ODBC 関数を同時に呼び出した場合、 データベースでのこれらの関数の実行順序は予測不能です。

    重要: 以前に割り振った接続ハンドルまたはステートメント・ハンドル に *OutputHandlePtr を設定して、SQLAllocHandle() を呼び出すと、Db2 ODBC はハンドルに 関連した情報を上書きします。Db2 ODBC は、*OutputHandlePtr に入力されたハンドルが既に使用中か どうかもチェックせず、Db2 ODBC は上書きする前のハンドルの内容をチェックすることもしません。

戻りコード

SQLAllocHandle() は、呼び出された後、次のいずれかの値を戻します。
  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_INVALID_HANDLE
  • SQL_ERROR

診断

SQLAllocHandle() から診断情報を取り出す方法は、割り振りハンドルのタイプによって 異なります。SQLAllocHandle() から診断情報を取り出すめには、ハンドル割り振り時の以下のタイプのエラーを考慮する必要があります。

環境ハンドル割り振りエラー: 環境ハンドル割り振り時にエラーを受け取った場合、引数 OutputHandlePtr が指している値によって、SQLGetDiagRec() を使用して診断情報が取り出せるかどうかが決まります。 環境ハンドルの割り振りに失敗すると、以下のいずれかのケースが生じます。
  • SQLAllocHandle() が SQL_ERROR を戻したときに、引数 OutputHandlePtr が SQL_NULL_HENV を指している場合。この場合は、SQLGetDiagRec() を呼び出して、このエラーに関する情報を取り出すことは できません。エラーに関連しているハンドルはないため、このエラーに関する情報を取り出すことは できません。
  • SQLAllocHandle() が SQL_ERROR を戻したときに、引数 OutputHandlePtr が SQL_NULL_HENV 以外の値を指している場合。 この場合、引数 OutputHandlePtr が指している値は、制限された環境ハンドルと なります。 この制限状態でハンドルを使用してできることは、SQLGetDiagRec() を呼び出してさらにエラー情報を取得するか、あるいは SQLFreeHandle() を呼び出して制限されたハンドルを解放することだけです。
接続ハンドルまたはステートメント・ハンドルの割り振りエラー: 環境ハンドル以外のハンドルを割り振る際に、以下のタイプの情報を取り出すことができます。
  • SQLAllocHandle() が SQL_ERROR を戻す場合、OutputHandlePtr は、接続ハンドルの 場合は SQL_NULL_HDBC に、ステートメント・ハンドルの場合は SQL_NULL_HSTMT に設定 されます (出力引数が NULL ポインターではない限り)。環境ハンドルで SQLGetDiagRec() を呼び出し、失敗した接続ハンドルの割り振りに関する情報を 取得します。接続ハンドルで SQLGetDiagRec() を呼び出し、失敗したステートメント・ハンドルの割り振りに 関する情報を取得します。
  • SQLAllocHandle() が SQL_SUCCESS_WITH_INFO を戻す場合は、 割り振られたハンドルを OutputHandlePtr に戻します。 割り振りに関する追加情報を取得するには、SQLAllocHandle() の引数 InputHandle で 指定したハンドルで、SQLGetDiagRec() を呼び出します。

次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。

表 3. SQLAllocHandle() の SQLSTATE
SQLSTATE 説明 説明
01000 警告。 通知メッセージ。(SQLAllocHandle() は、この SQLSTATE で SQL_SUCCESS_WITH_INFO を戻します。)
08003 接続はクローズされています。 引数 HandleType は SQL_HANDLE_STMT を指定していますが、引数 InputHandle で 指定されている接続がオープンしていません。Db2 ODBC がステートメント・ハンドルを割り振るためには、 接続処理が正常に完了 (かつ、接続がオープン) している必要があります。
08S01 通信リンクに障害が起きました。 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。
58004 予期しないシステム障害です。 これは、Db2 for z/OS® サブシステムとの関連を設定する際の障害か、 または他のいずれかのシステム関連エラーの可能性があります。
HY000 一般エラー。 特定の SQLSTATE が存在しないエラーが起こりました。SQLGetDiagRec() は、引数 MessageText が 示しているバッファーに、エラーとその原因を記述したエラー・メッセージを戻します。
HY001 メモリーの割り振りに失敗しました。 Db2 ODBC は指定されたハンドルのメモリーを割り振ることができませんでした。
HY009 NULL ポインターの使用は無効です。 引数 OutputHandlePtr が NULL ポインターを指定しています。
HY013 予期しないメモリー処理エラーです。 引数 HandleType は SQL_HANDLE_DBC または SQL_HANDLE_STMT を指定していますが、 この関数呼び出しは処理できませんでした。その理由は、おそらくメモリー不足状態により、 基礎となるメモリー・オブジェクトをアクセスできなかったことが原因です。
HY014 これ以上ハンドルがありません。 引数 HandleType で示されたタイプのハンドルに割り振り可能なハンドルの数の 限界に達しました。
HY092 オプションのタイプが範囲外です。 引数 HandleType は、以下のいずれの値も指定していません。
  • SQL_HANDLE_ENV
  • SQL_HANDLE_DBC
  • SQL_HANDLE_STMT

制約事項

Db2 ODBC 3.0 ドライバーは複数環境をサポートしていません。したがって、一時点では 1 つの アクティブな環境しか割り振ることはできません。それ以上の環境ハンドルを割り振るために SQLAllocHandle() を呼び出すと、この関数は 元の環境ハンドルと SQL_SUCCESS を戻します。Db2 ODBC ドライバーは、このような環境要求の 内部カウントを保持しています。それぞれの環境ハンドルの要求が成功するごとに、環境ハンドルで SQLFreeHandle() を呼び出す必要があります。 環境ハンドルでの SQLFreeHandle() 呼び出しが最後に成功したときに、Db2 ODBC 3.0 ドライバー環境が解放 されます。 この動作によって、ODBC アプリケーションが早まってドライバー環境を 割り振り解除しないことが保証されます。この状態では、Db2 ODBC 2.0 ドライバーおよび Db2 ODBC 3.0 ドライバーは、一貫性のある動作をします。

例

サンプル・アプリケーション DSN803VP、あるいは DSN1110.SDSNSAMP データ・セットにある DSN8O3VP を参照してください。