パラメーターの配列の使用

パラメーターの配列を使用するには、アプリケーションは SQL_ATTR_PARAMSET_SIZE のAttribute 引数を指定して SQLSetStmtAttr を呼び出し、パラメーターのセットの数を指定します。 SQL_ATTR_PARAMS_PROCESSED_PTR という Attribute 引数を指定して SQLSetStmtAttr を呼び出し、エラー セットを含む処理されたパラメーターセットの数をドライバーが返すことができる変数のアドレスを指定します。 SQL_ATTR_PARAM_STATUS_PTR という Attribute 引数を指定して SQLSetStmtAttr を呼び出し、パラメーター値の各行の状態情報を返す配列を指します。 ドライバーは、ステートメントの維持する構造にこれらのアドレスを格納します。

ステートメントを実行する前に、アプリケーションはバインドされた各配列の各要素の値を設定します。 ステートメントが実行されると、ドライバーは格納された情報を使用してパラメーター値を取得し、データ ソースに送信します。可能であれば、ドライバーはこれらの値を配列として送信する必要があります。 パラメーターの配列の使用は、データ ソースを 1 回の呼び出しで配列内のすべてのパラメーターを使って SQL ステートメントを実行することによって最適に実装されますが、現在、この機能は DBMS ではあまり使用できません。 ただし、ドライバーは SQL ステートメントを複数回実行することで、それぞれ 1 セットでパラメーターをシミュレートできます。

アプリケーションでパラメーターの配列を使用する前に、アプリケーションで使用されるドライバーによってサポートされていることを確認する必要があります。 これには、2 つの方法があります。

• パラメーターの配列をサポートすることが分かっているドライバーのみを使用します。 アプリケーションは、これらのドライバーの名前をハードコーディングすることも、ユーザーにこれらのドライバーのみを使用するように指示することもできます。 カスタム アプリケーションと垂直アプリケーションでは、通常、限られたドライバー セットが使用されます。

• 実行時にパラメーターの配列がサポートされているか確認します。 SQL_ATTR_PARAMSET_SIZE ステートメント属性を 1 より大きい値に設定できる場合、ドライバーはパラメーターの配列をサポートします。 一般的なアプリケーションと垂直アプリケーションでは、通常、実行時にパラメーターの配列がサポートされているか確認します。

パラメーター化された実行での行数と結果セットの可用性は、SQL_PARAM_ARRAY_ROW_COUNTS オプションと SQL_PARAM_ARRAY_SELECTS オプションを使用して SQLGetInfo を呼び出すことによって判断できます。 INSERT、UPDATE、DELETE ステートメントでは、SQL_PARAM_ARRAY_ROW_COUNTS オプションは、個々の行数 (パラメーター セットごとに 1 つ) を使用できるかどうか (SQL_PARC_BATCH)、または行数を 1 つにロールアップ (SQL_PARC_NO_BATCH) するかを示します。 SELECT ステートメントの場合、SQL_PARAM_ARRAY_SELECTS オプションは、パラメーターのセットごとに結果セットを使用できるかどうか (SQL_PAS_BATCH)、または 1 つの結果セットのみが使用できるか (SQL_PAS_NO_BATCH) を示します。 ドライバーがパラメーターの配列を使用して結果セット生成ステートメントを実行することを許可していない場合、SQL_PARAM_ARRAY_SELECTS は SQL_PAS_NO_SELECT を返します。 パラメーターの配列を他のタイプのステートメントで使用できるかどうかはデータ ソースによって異なります。特に、これらのステートメントでのパラメーターの使用はデータ ソースによって異なり、ODBC SQL 文法に従わないためです。

SQL_ATTR_PARAM_OPERATION_PTR ステートメント属性が指す配列を使用して、パラメーターの行を無視できます。 配列の要素が SQL_PARAM_IGNORE に設定されている場合、その要素に対応するパラメーターのセットは SQLExecute または SQLExecDirect の呼び出しから除外されます。 SQL_ATTR_PARAM_OPERATION_PTR 属性が指す配列は、アプリケーションによって割り当てられ、入力され、ドライバーによって読み取られます。 フェッチされた行を入力パラメーターとして使用する場合は、行状態配列の値をパラメーター操作配列で使用できます。

エラー処理

ステートメントの実行中にエラーが発生した場合、実行関数はエラーを返し、行番号変数にエラーを含む行の番号を設定します。 エラー セットを除くすべての行が実行されるかどうか、またはエラー セットの前 (ただし後ではない) のすべての行が実行されるかは、データ ソースによって異なります。 パラメーターのセットを処理するため、ドライバーは、現在処理中の行の数に SQL_ATTR_PARAMS_PROCESSED_PTR ステートメント属性で指定されたバッファーを設定します。 エラー セットを除くすべてのセットが実行された場合、ドライバーは、すべての行が処理された後、このバッファーを SQL_ATTR_PARAMSET_SIZE に設定します。

SQL_ATTR_PARAM_STATUS_PTR ステートメント属性が設定されている場合、SQLExecute または SQLExecDirect は パラメーターの状態配列 を返します。これは、パラメーターの各セットの状態を提供します。 パラメーターの状態配列は、アプリケーションによって割り当てられ、ドライバーによって埋められます。 その要素は、パラメーターの行に対して SQL ステートメントが正常に実行されたかどうか、またはパラメーターセットの処理中にエラーが発生したかどうかを示します。 エラーが発生した場合、ドライバーはパラメーター状態配列の対応する値を SQL_PARAM_ERROR に設定し、SQL_SUCCESS_WITH_INFO を返します。 アプリケーションでは、状態配列を確認して、処理された行を特定できます。 多くの場合、アプリケーションは行番号を使用してエラーを修正し、処理を再開できます。

パラメーター状態配列の使用方法は、SQLGetInfo の呼び出しによって返される SQL_PARAM_ARRAY_ROW_COUNTS オプションと SQL_PARAM_ARRAY_SELECTS オプションによって決まります。 INSERT、UPDATE、DELETE ステートメントの場合、SQL_PARAM_ARRAY_ROW_COUNTS に対して SQL_PARC_BATCH が返された場合、パラメーターの状態配列には状態情報が書き込まれますが、SQL_PARC_NO_BATCH が返された場合は書き込まれません。 SELECT ステートメントの場合、パラメーターの状態配列は、SQL_PARAM_ARRAY_SELECT に対して SQL_PAS_BATCH が返された場合は書き込まれますが、SQL_PAS_NO_BATCH または SQL_PAS_NO_SELECT が返される場合は書き込まれません。

実行時データ パラメーター

長さ/インジケーター配列のいずれかの値が SQL_DATA_AT_EXEC または SQL_LEN_DATA_AT_EXEC(長さ) マクロの結果である場合、それらの値のデータは通常の方法で SQLPutData で送信されます。 このプロセスの次の側面は、簡単には明らかにならないため、特別なコメントを付けます。

• ドライバーは、SQL_NEED_DATA を返すときは、データが必要な行に行番号変数のアドレスを設定する必要があります。 単一値の場合と同様に、アプリケーションはドライバーがパラメーターの 1 つのセット内のパラメーター値を要求する順序に関する仮定を行うことはできません。 実行時データ パラメーターの実行中にエラーが発生した場合、SQL_ATTR_PARAMS_PROCESSED_PTR ステートメント属性で指定されたバッファーにエラーが発生した行の数が設定され、SQL_ATTR_PARAM_STATUS_PTR ステートメント属性で指定された行状態配列の行の状態が SQL_PARAM_ERROR に設定されます。 SQLExecute、SQLExecDirect、SQLParamData、または SQLPutData の呼び出しは、SQL_ERROR を返します。 SQLExecute、SQLExecDirect、または SQLParamData が SQL_STILL_EXECUTING を返す場合、このバッファーの内容は未定義です。

• ドライバーは、実行時データ パラメーターの SQLBindParameter の ParameterValuePtr 引数の値を解釈しないため、アプリケーションが配列へのポインターを提供する場合、SQLParamData はこの配列の要素を抽出してアプリケーションに返しません。 代わりに、アプリケーションが指定したスカラー値を返します。 つまり、SQLParamData によって返される値は、アプリケーションがデータを送信する必要があるパラメーターを指定するのに十分ではありません。アプリケーションでは、現在の行番号も考慮する必要があります。

  パラメーターの配列の一部の要素のみが実行時データ パラメーターである場合、アプリケーションはすべてのパラメーターの要素を含む ParameterValuePtr 内の配列のアドレスを渡す必要があります。 この配列は、実行時データ パラメーターではないパラメーターに対して通常解釈されます。 実行時データ パラメーターの場合、SQLParamData がアプリケーションに提供する値 (通常は、この場合にドライバーが要求しているデータを識別するために使用できます) は、常に配列のアドレスです。