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

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

Note

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

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

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

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

2. 長さ/インジケーター バッファーの値を、SQL_LEN_DATA_AT_EXEC(length) マクロの結果に設定します。 この値は、パラメーターのデータが SQLPutData で送信されることをドライバーに示します。 length 値は、データ ソースに長いデータを送信する場合に、領域を事前に割り当てることができるように長いデータのバイト数を把握する必要があるときに使用されます。 データ ソースにこの値が必要かどうかを判断するために、アプリケーションは 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 状態になります。 この状態では、アプリケーションは SQLPutData、SQLParamData、SQLCancel、SQLGetDiagField、または SQLGetDiagRec のみを呼び出すことができます。他のすべての関数は SQLSTATE HY010 (関数シーケンス エラー) を返します。 SQLCancel を呼び出すと、ステートメントの実行が取り消され、以前の状態に戻されます。 詳細については、「付録 B: ODBC 状態遷移テーブル」を参照してください。