長い形式のデータ、SQLSetPos および SQLBulkOperations

SQL ステートメントのパラメーターの場合と同様に、SQLBulkOperations または SQLSetPos で行を更新するとき、または SQLBulkOperations で行を挿入するときに、長いデータを送信できます。 データは一部で送信され、 SQLPutData への複数の呼び出しが行われます。 実行時にデータが送信される列は、実行時 データ列と呼ばれます。

注意

アプリケーションは実際には SQLPutData を使用して実行時に任意の種類のデータを送信できますが、一部で送信できるのは文字データとバイナリ データのみです。 ただし、データが 1 つのバッファーに収まるほど小さい場合、一般に SQLPutData を使用する理由はありません。 バッファーをバインドし、ドライバーがバッファーからデータを取得できるようにする方がはるかに簡単です。

通常、長いデータ列はバインドされないため、 SQLBulkOperations または SQLSetPos を呼び出す前にアプリケーションで列をバインドし、 SQLBulkOperations または SQLSetPos を呼び出した後でバインドを解除する必要があります。 SQLBulkOperations または SQLSetPos はバインドされた列でのみ動作し、SQLGetData を使用して列からデータを取得できるようにバインド解除する必要があるため、列をバインドする必要があります。

実行時にデータを送信するために、アプリケーションは次の処理を行います。

  1. データ値の代わりに行セット バッファーに 32 ビット値を配置します。 この値は後でアプリケーションに返されるため、アプリケーションは、列の数やデータを含むファイルのハンドルなどの意味のある値に設定する必要があります。

  2. 長さ/インジケーター バッファーの値を、SQL_LEN_DATA_AT_EXEC(length) マクロの結果に設定します。 この値は、パラメーターのデータが SQLPutData で送信されることをドライバーに示します。 長さの値は、領域を事前に割り当てることができるように送信される長いデータのバイト数を知る必要があるデータ ソースに長いデータを送信するときに使用されます。 データ ソースでこの値が必要かどうかを判断するために、アプリケーションは SQL_NEED_LONG_DATA_LEN オプションを使用して SQLGetInfo を呼び出します。 すべてのドライバーは、このマクロをサポートする必要があります。データ ソースがバイト長を必要としない場合、ドライバーはそれを無視できます。

  3. SQLBulkOperations または SQLSetPos を呼び出します。 ドライバーは、長さ/インジケーター バッファーに SQL_LEN_DATA_AT_EXEC(length) マクロの結果が含まれていることを検出し、関数の戻り値としてSQL_NEED_DATAを返します。

  4. SQL_NEED_DATA戻り値に応答して SQLParamData を呼び出します。 長いデータを送信する必要がある場合、 SQLParamData はSQL_NEED_DATAを返します。 ValuePtrPtr 引数が指すバッファーでは、ドライバーは、アプリケーションが行セット バッファーに配置した一意の値を返します。 実行中のデータ列が複数ある場合、アプリケーションはこの値を使用して、データを送信する列を決定します。ドライバーは、実行中のデータ列のデータを特定の順序で要求する必要はありません。

  5. SQLPutData を呼び出して、列データをドライバーに送信します。 列データが 1 つのバッファーに収まらない場合 (多くの場合、長いデータの場合と同様)、アプリケーションは SQLPutData を 繰り返し呼び出してデータを部分的に送信します。データを再構成するには、ドライバーとデータ ソースが必要です。 アプリケーションが null 終端文字列データを渡す場合、ドライバーまたはデータ ソースは、再構築プロセスの一環として null 終端文字を削除する必要があります。

  6. SQLParamData をもう一度呼び出して、列のすべてのデータが送信されたことを示します。 データが送信されていない実行中のデータ列がある場合、ドライバーは次の実行時データ列のSQL_NEED_DATAと一意の値を返します。アプリケーションが手順 5 に戻ります。 実行中のすべてのデータ列に対してデータが送信された場合、行のデータはデータ ソースに送信されます。 その後、SQLParamData はSQL_SUCCESSまたはSQL_SUCCESS_WITH_INFOを返し、 SQLBulkOperations または SQLSetPos が返すことができる任意の SQLSTATE を 返すことができます。

SQLBulkOperations または SQLSetPos がSQL_NEED_DATAを返した後、最後の実行時データ列のデータが完全に送信される前に、ステートメントは Need Data 状態になります。 この状態では、アプリケーションは SQLPutDataSQLParamDataSQLCancelSQLGetDiagField、または SQLGetDiagRec のみを呼び出すことができます。他のすべての関数は、SQLSTATE HY010 (関数シーケンス エラー) を返します。 SQLCancel を呼び出すと、ステートメントの実行が取り消され、前の状態に戻されます。 詳細については、「 付録 B: ODBC 状態遷移テーブル」を参照してください。