CLI の手引きおよび解説書

SQLFreeHandle - ハンドル資源を解放する

目的


仕様: DB2 CLI 5.0 ODBC 3.0 ISO CLI

SQLFreeHandle() は、特定の環境、接続、ステートメント、または記述子ハンドルに関連した資源を解放します。

注:この関数は、資源を解放するための一般的な関数です。これは、バージョン 2 の関数 SQLFreeConnect (接続ハンドルを解放する) および SQLFreeEnv() (環境ハンドルを解放する) から置き換わったものです。 SQLFreeHandle() はさらに、ステートメント・ハンドルを解放するためのバージョン 2 の関数 SQLFreeStmt() (SQL_DROP オプションを使用する) も置き換えます。

構文

SQLRETURN   SQLFreeHandle    (SQLSMALLINT       HandleType,
                              SQLHANDLE         Handle);

関数引き数

表 86. SQLFreeHandle 引き数
データ・タイプ 引き数 使用法 説明
SQLSMALLINT HandleType 入力 SQLFreeHandle() によって解放するハンドルのタイプ。以下の値のうちの 1 つでなければなりません。
  • SQL_HANDLE_ENV
  • SQL_HANDLE_DBC
  • SQL_HANDLE_STMT
  • SQL_HANDLE_DESC
HandleType が上記の値のいずれでもでない場合は、SQLFreeHandle() は SQL_INVALID_HANDLE を返します。
SQLHANDLE Handle 入力 解放するハンドル。

使用法

SQLFreeHandle() は環境、接続、ステートメント、および記述子のハンドルを、以下の要領で解放するために使用します。

アプリケーションは、ハンドルが解放された後はそのハンドルを使用できません。 DB2 CLI は、関数呼び出しのハンドルの妥当性検査は行いません。

環境ハンドルの解放

SQL_HANDLE_ENV の HandleType を使って SQLFreeHandle() を呼び出す前に、アプリケーションは、その環境のもとで割り当てられている接続すべてに対して SQL_HANDLE_DBC の HandleType を使って SQLFreeHandle() を呼び出さなければなりません。これを行わないと、SQLFreeHandle() の呼び出しは、 SQL_ERROR と環境を返し、活動状態にある接続はすべて有効のままになります。

接続ハンドルの解放

SQL_HANDLE_DBC の HandleType を使用して SQLFreeHandle() を呼び出す前に、アプリケーションは接続のために SQLDisconnect() を呼び出さなければなりません。これを行わないと、SQLFreeHandle() の呼び出しは、SQL_ERROR を返し、接続はすべて有効のままになります。

ステートメント・ハンドルの解放

SQL_HANDLE_STMT の HandleType を使用して SQLFreeHandle() を呼び出すと、 SQL_HANDLE_STMT の HandleType を使用して行う SQLAllocHandle() の呼び出しによって割り当てられた資源をすべて解放します。アプリケーションが SQLFreeHandle() を呼び出して結果を保留にしているステートメントを解放するときに、保留になっている結果は解放されます。アプリケーションがステートメント・ハンドルを解放するときに、 DB2 CLI はそのハンドルに関連して自動的に生成された記述子をすべて解放します。 SQLFreeHandle() が呼び出されたときに結果が保留になっている場合、結果セットは破棄されます。

接続上でオープンしているステートメントと記述子を SQLDisconnect() はすべて自動的に除去するので注意してください。

記述子ハンドルの解放

SQL_HANDLE_DESC の HandleType を使用して SQLFreeHandle() を呼び出すと、 Handle の記述子ハンドルが解放されます。 SQLFreeHandle() の呼び出しは、 Handle の記述子レコードの据え置きフィールド (SQL_DESC_DATA_PTR、 SQL_DESC_INDICATOR_PTR、および SQL_DESC_OCTET_LENGTH_PTR) によって参照される可能性のあるアプリケーションが割り当てるメモリーを解放することはありません。明示的に割り当てられている記述子ハンドルが解放されると、解放されたハンドルが関連していたすべてのステートメントは、自動的に割り当てられた記述子ハンドルに返ります。

接続上でオープンしているステートメントと記述子を SQLDisconnect() はすべて自動的に除去するので注意してください。アプリケーションがステートメント・ハンドルを解放するときに、 DB2 CLI はそのハンドルに関連して自動的に生成された記述子をすべて解放します。

戻りコード

SQLFreeHandle() が SQL_ERROR を返す場合、ハンドルはまだ有効です。

診断

表 87. SQLFreeHandle SQLSTATE
SQLSTATE 説明 解説
01000 警告。 通知メッセージ。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。)
08S01 通信リンクに障害が起きました。 HandleType 引き数は SQL_HANDLE_DBC であり、 DB2 CLI とそれが接続しようとしていたデータ・ソース間の通信リンクは、関数が処理を完了する前に失敗しました。
HY000 一般的なエラーです。 特定の SQLSTATE がなかった場合のエラーが発生しました。 SQLGetDiagRec() により *MessageText バッファーに返されたエラー・メッセージに、そのエラーと原因が記述されています。
HY001 メモリーの割り振り失敗です。 DB2 CLI は、この関数の実行または完了をサポートするために必要なメモリーを割り当てられませんでした。
HY010 関数の順序エラーです。 HandleType 引き数が SQL_HANDLE_ENV であり、少なくとも 1 つの接続が割り当てられているか、接続されている状態にあります。 HandleType を SQL_HANDLE_ENV として SQLFreeHandle() を呼び出す前に、 HandleType が SQL_HANDLE_DBC である SQLDisconnect() および SQLFreeHandle() を、各接続のために呼び出さなければなりません。 HandleType 引き数は SQL_HANDLE_DBC であり、関数は、接続のための SQLDisconnect() を呼び出す前に呼び出されました。

HandleType 引き数は SQL_HANDLE_STMT でした。非同期的に実行する関数がステートメント・ハンドル上で呼び出されました。そして、関数は、この関数が呼び出されたときもまだ実行中でした。

HandleType 引き数は SQL_HANDLE_STMT でした。 SQLExecute() または SQLExecDirect() はステートメント・ハンドルを使用して呼び出され、 SQL_NEED_DATA が返されました。データがすべての実行時データ・パラメーターまたは列用に送られる前に、この関数が呼び出されました。 (DM) すべての補足的なハンドルと他の資源は、 SQLFreeHandle() が呼び出される前には解放されませんでした。

HY013 予期しないメモリーのハンドル・エラーが起きました。 HandleType 引き数が SQL_HANDLE_STMT または SQL_HANDLE_DESC であり、基礎メモリー・オブジェクトにアクセスできない (メモリー不足が原因と考えられる) ため、関数呼び出しを処理できませんでした。
HY017 自動割り振りの記述子ハンドルについて無効な使用です。 Handle 引き数が、自動的に割り当てられた記述子または実装記述子のハンドルに設定されました。

制約

なし。

CLI サンプル utilcli.c

(ここで完全サンプル utilcli.c を使用することもできます 。)

/* From the CLI sample utilcli.c */
/* ... */
    /* free the environment handle */
    printf("\nFreeing the environment handle ...\n");
    sqlrc = SQLFreeHandle( SQL_HANDLE_ENV,  *pHenv ) ;
    rc    = HandleInfoPrint( SQL_HANDLE_ENV, *pHenv,
                             sqlrc, __LINE__, __FILE__);
    if( rc == 0)
    {   printf("The environment handle is free.\n");
    }
 
 

参照


[ ページのトップ | 前ページ | 次ページ | 目次 | 索引 ]