配列データの行方向バインディング

行方向バインディングでは、結果セットの 1 つの行全体を構造に関連付けます。この方法で構造の配列にバインドされた行セットを取り出します。 各構造には、1 つの行全体から取り出したデータ・フィールドとその関連した長さフィールドが入っています。 行方向バインディングを使用して、データの取り出しのみを行います。データを送ることはありません。

次の図は、行方向バインディングを図解入り表示したものです。

図 1. 行方向バインド
図の要約の開始 この図は、3 列を持った結果セットの例とこのデータを取り出すのに使用する構造
を示しています。
詳細な説明が可能

SQLSetStmtAttr() を呼び出し、取り出す行数を設定してから、SQLBindCol() を呼び出す必要があります。

行方向に配列を取り出すためには、アプリケーションに以下の手順を組み込みます。
  1. SQLSetStmtAttr() を呼び出し、一度に取り出す行数を示します。

    SQLExtendedFetch() を使用して行をフェッチする計画ならば、SQL_ATTR_ROWSET_SIZE 属性設定を各フェッチで取り出す行数に設定します。

    SQLFetchScroll() を使用して行をフェッチする計画ならば、SQL_ATTR_ROW_ARRAY_SIZE 属性設定を各フェッチで取り出す行数に設定します。

  2. 結果列のバインド対象の構造サイズを設定した SQL_ATTR_BIND_TYPE 属性値を指定して、 再度、SQLSetStmtAttr() を呼び出します。Db2® ODBC は、データを戻すときに、SQL_ATTR_BIND_TYPE 属性の値を 使用して、構造の配列のどこに連続する行を保管するかを判別します。
  3. SQLBindCol() を呼び出して、構造の配列を結果セットにバインドします。この呼び出しで、以下の引数値を組み込みます。
    • 引数 rgbValue が、配列における最初の構造のエレメント・アドレスを指す ようにします。この構造は、引数 icol で指定した列からデータを受け取ろうとします。
    • 文字入力データおよびバイナリー入力データの場合、入力引数 cbValueMax の中に、 入力配列の各エレメント長 (バイト) を指定します。(その他の入力データ・タイプの場合は、この引数は 無視されます。)
    • オプションとして、引数 pcbValue が、配列内の最初の構造エレメント・アドレスを 指すようにします。この構造は、このバインドに対応する列値が必要とするバイト数を受け取ります。 それ以外の場合は、この値は NULL に設定します。
  4. SQLExtendedFetch() または SQLFetchScroll() を呼び出して、結果データを取り出して配列に入れます。

次の図は、SQLExtendedFetch() を使用して列方向および行方向にバインドされたデータを戻すために必要な関数を示します。この図では、n は SQL_ATTR_ROWSET_SIZE 属性の値であり、m は結果セットの 列の数です。 図の左側では、n 行を選択し、一度に 1 行を取り出して m 個のアプリケーション変数に入れる方法を記載してあります。 一方、図の右側では、同じ n 行を選択し、配列の中に直接 取り出す方法を記載してあります。

図 2. 配列取り出し
図の要約の開始この図は、一度に結果セットの 1 行を取り出した場合と結果セットを直接配列へ取り出した場合を比較したフローチャートです。
詳細な説明が可能
配列取り出しを実行する場合:
  • 値 n を SQL_ATTR_ROWSET_SIZE に (または SQL_ATTR_ROW_ARRAY_SIZE を SQLFetchScroll() に) 指定する場合、その結果セットを取り出して、少なくとも n 個のエレメントを持つ配列に入れる必要があります。 そうしないと、メモリー・オーバーレイが発生する可能性があります。
  • m 列をアプリケーション変数または配列にバインドする場合は、 常に、SQLBindCol() を m 回呼び出す必要があります。
  • SQL_ATTR_ROWSET_SIZE または SQL_ATTR_ROW_ARRAY_SIZE で指定する行数よりも多くの行数が結果セットにある場合、SQLExtendedFetch() または SQLFetchScroll() を複数回呼び出して、結果セットのすべての行を取り出す必要があります。SQLExtendedFetch() または SQLFetchScroll() を複数回呼び出す際、これらの呼び出しの間に前にフェッチされたデータを保管するために操作を実行する必要があります。これらの操作は、『結果セットを配列の中に取り出す』にリストされています。