配列を使用してパラメーター値を入力する
Db2® ODBC では Db2 表を更新するために配列の入力方式を用意しています。
データ入力および更新アプリケーションでは、データ入力フォーム内の多くのセルを挿入、削除、または変更 してから、これらの変更内容をデータベースに送ることがよくあります。 このような状態に備えて、Db2 ODBC では配列入力方式を用意しており、同じ INSERT、DELETE、UPDATE、または MERGE ステートメントで、SQLExecute() を繰り返し呼び出す必要はありません。 さらに、パラメーター値を渡すのに配列を使用すると、ネットワークの流れを削減することができます。
- メモリー内の入力配列にバインドするそれぞれのパラメーター・マーカー
ごとに、SQLBindParameter() を呼び出します。
この関数呼び出しでは、以下の引数を使用します。
- 引数 fParamType を設定して SQL_PARAM_INPUT にします。
- 引数 rgbValue は、パラメーター・マーカーの入力データの入っている配列を 指すようにします。
- 文字データおよびバイナリー入力データの場合、入力引数 cbValueMax を用いて、 入力配列のそれぞれのエレメントの長さ (バイト) を指定します。(その他の入力データ・タイプの場合は、この引数は 無視されます。)
- オプションで、引数 pcbValue は、入力配列のそれぞれの値の長さ (バイト) が 入っている配列を指すようにします。 pcbValue 配列内のそれぞれの長さの値を指定して、rgbValue 配列内の対応する値 の長さとなるようにします。
- SQLSetStmtAttr を呼び出し、入力配列内にある行数を引数 crow で指定します。この値は、各パラメーターごとの異なる値の個数を示しています。
- SQLExecute() を呼び出し、すべてのパラメーター値をデータベースに送ります。
配列を用いて行の挿入、更新、またはマージを行う場合、SQLRowCount() を使用して変更した行数を検査します。
WHERE 文節で配列にバインドされたパラメーター・マーカーを用いた照会では、 複数の順次結果セットが生成されます。そのような照会で個別に戻される結果セットをアプリケーションが 処理します。 最初の結果セットを処理した後、SQLMoreResults() を呼び出して、さらに結果セットを取り出します。
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 回ずつ呼び出す必要があります。

前の図の左側は、パラメーター値の受け渡しに配列を使用しない一括操作方式を示しています。SQLBindParameter() は、単一値が入ったホスト変数に各パラメーター・マーカーを バインドします。この方式では配列挿入を行わないため、 SQLExecute() は繰り返し呼び出されます。アプリケーションは、それぞれの SQLExecute() 呼び出しの前に、入力パラメーターにバインドされた 変数を更新します。この方式では、SQLExecute() を呼び出してすべての操作を行います。
図 1 の右側は、パラメーター値の受け渡しに配列を使用する一括操作方式 を示しています。SQLExecute() は、すべての一括操作数に対して一度だけ呼び出されます。この配列の方式では、 ステートメント属性 SQL_ATTR_PARAMSET_SIZE を指定して SQLSetStmtAttr() を呼び出し、 その後、SQLExecute() を呼び出します。
/* ... */
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
/* ... */
- マージされる行の EMPNO 値が DSN8B10.EMP 表の EMPNO 値と一致する場合、既存の表の行の SALARY 値が更新されます。
- マージされる行の EMPNO 値が DSN8B10.EMP 表の EMPNO 値と一致しない場合は、その行が DSN8B10.EMP 表に挿入されます。
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 部分のパラメーター数です。これは、各パラメーターに対して単一値となります。

前の図の左側は、MERGE ステートメントを複数回実行する必要がある場合に使用できるマージ方式を示しています。 ステートメントは、Db2 で準備されたステートメント・キャッシングが設定されていれば、準備されたステートメントが使用できるように 2 つの別々のステップで準備されて実行されます。
図 2 の右側は、MERGE ステートメントを一回のみ実行する必要がある場合に使用できる一括操作方式を示しています。ステートメントは単一ステップで準備され実行されます。
/* 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