配列を使用してパラメーター値を入力する

Db2® ODBC では Db2 表を更新するために配列の入力方式を用意しています。

データ入力および更新アプリケーションでは、データ入力フォーム内の多くのセルを挿入、削除、または変更 してから、これらの変更内容をデータベースに送ることがよくあります。 このような状態に備えて、Db2 ODBC では配列入力方式を用意しており、同じ INSERT、DELETE、UPDATE、または MERGE ステートメントで、SQLExecute() を繰り返し呼び出す必要はありません。 さらに、パラメーター値を渡すのに配列を使用すると、ネットワークの流れを削減することができます。

以下の方法によって、配列をパラメーター・マーカーに渡します。
  1. メモリー内の入力配列にバインドするそれぞれのパラメーター・マーカー ごとに、SQLBindParameter() を呼び出します。 この関数呼び出しでは、以下の引数を使用します。
    • 引数 fParamType を設定して SQL_PARAM_INPUT にします。
    • 引数 rgbValue は、パラメーター・マーカーの入力データの入っている配列を 指すようにします。
    • 文字データおよびバイナリー入力データの場合、入力引数 cbValueMax を用いて、 入力配列のそれぞれのエレメントの長さ (バイト) を指定します。(その他の入力データ・タイプの場合は、この引数は 無視されます。)
    • オプションで、引数 pcbValue は、入力配列のそれぞれの値の長さ (バイト) が 入っている配列を指すようにします。 pcbValue 配列内のそれぞれの長さの値を指定して、rgbValue 配列内の対応する値 の長さとなるようにします。
    ファイル内の LOB データに対しては、SQLBindFileToParam() を使用できます。
  2. SQLSetStmtAttr を呼び出し、入力配列内にある行数を引数 crow で指定します。この値は、各パラメーターごとの異なる値の個数を示しています。
  3. SQLExecute() を呼び出し、すべてのパラメーター値をデータベースに送ります。

配列を用いて行の挿入、更新、またはマージを行う場合、SQLRowCount() を使用して変更した行数を検査します。

WHERE 文節で配列にバインドされたパラメーター・マーカーを用いた照会では、 複数の順次結果セットが生成されます。そのような照会で個別に戻される結果セットをアプリケーションが 処理します。 最初の結果セットを処理した後、SQLMoreResults() を呼び出して、さらに結果セットを取り出します。

INSERT 例: 図 1 の右側に示すような、配列挿入を実行するアプリケーションを考えてみます。 このアプリケーションで、ユーザーは、出退勤データ入力形式の OVERTIME_WORKED およ び OVERTIME_PAID 列の値を変更できるものと想定します。また、基礎となる EMPLOYEE 表 の主キーは EMPLOY_ID であるとします。この場合、このアプリケーションは次の ような SQL ステートメントを準備するよう要求することができます。
UPDATE EMPLOYEE SET OVERTIME_WORKED= ? and OVERTIME_PAID= ?
WHERE EMPLOY_ID=?

このステートメントは、3 つのパラメーター・マーカーを含んでいるため、アプリケーション は、3 つの配列を使用して入力データを保管します。ユーザーが n 行に変更を加えた場合、 アプリケーションは n 個の値をそれぞれの配列に入れます。 ユーザーがこれらの変更内容をデータベースに送ることに決めた場合は、アプリケーションは 準備済み SQL ステートメントのパラメーター・マーカーをこの配列にバインドします。 その後、アプリケーションは、n が設定された引数 crow を指定して 、SQLSetStmtAttr() を呼び出します。この「n」値には、各配列にあるエレメント数を指定します。

次の図は、m 個のパラメーターがあるステートメントを n 回実行する 2 つの方式を示しています。 いずれの方式も、パラメーターごとに SQLBindParameter() を 1 回ずつ呼び出す必要があります。

図 1. 配列挿入
図の要約の開始 この図は、複数の値をパラメーター・マーカーに渡すために呼び出す
関数を表したフローチャートです。
詳細な説明が可能

前の図の左側は、パラメーター値の受け渡しに配列を使用しない一括操作方式を示しています。SQLBindParameter() は、単一値が入ったホスト変数に各パラメーター・マーカーを バインドします。この方式では配列挿入を行わないため、 SQLExecute() は繰り返し呼び出されます。アプリケーションは、それぞれの SQLExecute() 呼び出しの前に、入力パラメーターにバインドされた 変数を更新します。この方式では、SQLExecute() を呼び出してすべての操作を行います。

図 1 の右側は、パラメーター値の受け渡しに配列を使用する一括操作方式 を示しています。SQLExecute() は、すべての一括操作数に対して一度だけ呼び出されます。この配列の方式では、 ステートメント属性 SQL_ATTR_PARAMSET_SIZE を指定して SQLSetStmtAttr() を呼び出し、 その後、SQLExecute() を呼び出します。

以下の例 は、配列の INSERT ステートメント を示しています。
/* ... */
    SQLUINTEGER pirow = 0;
    SQLCHAR         stmt[] =
    "INSERT INTO CUSTOMER ( Cust_Num, First_Name, Last_Name) "
      "VALUES (?, ?, ?)";
    SQLINTEGER      Cust_Num[25] = {
        10, 20, 30, 40, 50, 60, 70, 80, 90, 100,
        110, 120, 130, 140, 150, 160, 170, 180, 190, 200,
        210, 220, 230, 240, 250
    };
    SQLCHAR         First_Name[25][31] = {
        "EVA",     "EILEEN",     "THEODORE", "VINCENZO",  "SEAN",
        "DOLORES", "HEATHER",    "BRUCE",    "ELIZABETH", "MASATOSHI",
        "MARILYN", "JAMES",      "DAVID",    "WILLIAM",   "JENNIFER",
        "JAMES",    "SALVATORE", "DANIEL",   "SYBIL",     "MARIA",
        "ETHEL",    "JOHN",      "PHILIP",   "MAUDE",     "BILL"
    };
    SQLCHAR         Last_Name[25][31] = {
        "SPENSER", "LUCCHESI", "O'CONNELL", "QUINTANA",
        "NICHOLLS", "ADAMSON", "PIANKA", "YOSHIMURA",
        "SCOUTTEN", "WALKER", "BROWN", "JONES",
        "LUTZ", "JEFFERSON", "MARINO", "SMITH",
        "JOHNSON", "PEREZ", "SCHNEIDER", "PARKER",
        "SMITH", "SETRIGHT", "MEHTA", "LEE",
        "GOUNOT"
    };
/* ... */
    /* Prepare the statement */
    rc = SQLPrepare(hstmt, stmt, SQL_NTS);
    rc = SQLParamOptions(hstmt, 25, &pirow);
    rc = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_SLONG, SQL_INTEGER,
                          0, 0, Cust_Num, 0, NULL);
    rc = SQLBindParameter(hstmt, 2, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR,
                          31, 0, First_Name, 31, NULL);
    rc = SQLBindParameter(hstmt, 3, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR,
                         31, 0, Last_Name, 31, NULL);
    rc = SQLExecute(hstmt);
    printf("Inserted 
/* ... */
MERGE 例: 図 2 で示すような配列マージを実行するアプリケーションを考えてみます。 このアプリケーションは EMPNO、FIRSTNME、MIDINIT、LASTNAME、および SALARY 値の配列を DSN8B10.EMP サンプル表にマージします。マージされる値のそれぞれの行については、以下のとおりです。
  • マージされる行の EMPNO 値が DSN8B10.EMP 表の EMPNO 値と一致する場合、既存の表の行の SALARY 値が更新されます。
  • マージされる行の EMPNO 値が DSN8B10.EMP 表の EMPNO 値と一致しない場合は、その行が DSN8B10.EMP 表に挿入されます。
これを遂行する MERGE ステートメントは、以下のとおりです。
MERGE INTO DSN8B10.EMP AS t
 USING VALUES 
 (CAST (? AS CHAR(6)), 
 CAST (? AS VARCHAR(12)), 
 CAST (? AS CHAR(1)), 
 CAST (? AS VARCHAR(15)), 
 CAST (? AS INTEGER))
 AS s (EMPNO, FIRSTNME, MIDINIT, LASTNAME, SALARY)              
 ON t.EMPNO = s.EMPNO  
 WHEN MATCHED THEN UPDATE SET SALARY = s.SALARY            
 WHEN NOT MATCHED THEN INSERT 
 (EMPNO, s.FIRSTNME, s.MIDINIT, s.LASTNAME, s.SALARY)
 NOT ATOMIC CONTINUE ON SQLEXCEPTION;

このステートメントは、5 つのパラメーター・マーカーを含んでいるため、アプリケーション は、5 つの配列を使用して入力データを保管します。ユーザーが n 行を変更すると、アプリケーションは n 個の値をそれぞれの配列に入れます。 ユーザーがこれらの変更内容をデータベースに送ることに決めた場合は、アプリケーションは準備済み SQL ステートメントのパラメーター・マーカーをこの配列にバインドします。 その後、アプリケーションは、n が設定された引数 crow を指定して 、SQLSetStmtAttr() を呼び出します。この「n」値には、各配列にあるエレメント数を指定します。

次の図は、m+p 個のパラメーターがある MERGE ステートメントを実行する 2 つの方式を示しています。 m は各パラメーターに対する 1 つ以上の値を持つパラメーター数です。p は MERGE ステートメントの UPDATE 部分と INSERT 部分のパラメーター数です。これは、各パラメーターに対して単一値となります。

図 2. 配列マージ
図の要約の開始 この図は、一部のパラメーター・マーカーに対して、複数の値を指定した MERGE ステートメントを実行するための機能呼び出しを表したフローチャートです。
詳細な説明が可能

前の図の左側は、MERGE ステートメントを複数回実行する必要がある場合に使用できるマージ方式を示しています。 ステートメントは、Db2 で準備されたステートメント・キャッシングが設定されていれば、準備されたステートメントが使用できるように 2 つの別々のステップで準備されて実行されます。

図 2 の右側は、MERGE ステートメントを一回のみ実行する必要がある場合に使用できる一括操作方式を示しています。ステートメントは単一ステップで準備され実行されます。

次の図は、配列 MERGE のコードを示しています。
図 3. 配列マージを実行するアプリケーション
/* declare and initialize local variables */ 
SQLUINTEGER cRow  = 10; 
SQLUINTEGER
piRow = 0;  
SQLCHAR     sqlStmt[] = 
  "MERGE INTO DSN8B10.EMP AS t"
  " USING VALUES"
  " (CAST (? AS CHAR(6))," 
  " CAST (? AS VARCHAR(12))," 
  " CAST (? AS CHAR(1))," 
  " CAST (? AS VARCHAR(15))," 
  " CAST (? AS INTEGER))"
  " AS s (EMPNO, FIRSTNME, MIDINIT, LASTNAME, SALARY)"
  " ON t.EMPNO = s.EMPNO"  
  " WHEN MATCHED THEN UPDATE SET SALARY = s.SALARY"
  " WHEN NOT MATCHED THEN INSERT" 
  " (EMPNO, s.FIRSTNME, s.MIDINIT, s.LASTNAME, s.SALARY)"
  " NOT ATOMIC CONTINUE ON SQLEXCEPTION";
SQLCHAR     empno[10][7];
SQLCHAR     firstname[10][13];
SQLCHAR     middlename[10][2];
SQLCHAR     lastname[10][16];
SQLINTEGER  salary[10];
/* set up data for empno, firstname, middlename, lastname and salary */
/* ... */
/* prepare the statement */
rc = SQLPrepare(hstmt, sqlStmt, SQL_NTS);
/* specify the number of rows to be merged */
rc = SQLParamOptions(hstmt, cRow, &piRow);
/* bind the parameters to input arrays */
rc = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR,
                      6, 0, empno, 7, NULL);
rc = SQLBindParameter(hstmt, 2, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_VARCHAR,
                      12, 0, firstname, 13, NULL);
rc = SQLBindParameter(hstmt, 3, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR,
                      1, 0, middlename, 2, NULL);
rc = SQLBindParameter(hstmt, 4, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_VARCHAR,
                      15, 0, lastname, 16, NULL);
rc = SQLBindParameter(hstmt, 5, SQL_PARAM_INPUT, SQL_C_LONG, SQL_INTEGER,
                      0, 0, salary, 0, NULL);
/* execute the statement */
rc = SQLExecute(hstmt);
/* display the total number of rows either updated or inserted by MERGE */
printf("MERGEd