SQL ステートメントのパラメーターの場合と同様に、 SQLBulkOperations または SQLSetPos で行を更新するとき、または SQLBulkOperations で行を挿入するときに、長いデータを送信できます。 データは、 SQLPutData を複数回呼び出して、一部で送信されます。 実行時にデータが送信される列は、実行時 データ列と呼ばれます。
注
アプリケーションは実際には SQLPutData を使用して実行時に任意の種類のデータを送信できますが、一部で送信できるのは文字データとバイナリ データのみです。 ただし、データが 1 つのバッファーに収まるほど小さい場合、一般に SQLPutData を使用する理由はありません。 バッファーをバインドし、ドライバーがバッファーからデータを取得できるようにする方がはるかに簡単です。
通常、長いデータ列はバインドされないため、アプリケーションは SQLBulkOperations または SQLSetPos を呼び出す前に列をバインドし、 SQLBulkOperations または SQLSetPos を呼び出した後にバインドを解除する必要があります。 SQLBulkOperations または SQLSetPos はバインドされた列でのみ動作し、SQLGetData を使用して列からデータを取得できるようにバインドされていない必要があるため、列をバインドする必要があります。
実行時にデータを送信するために、アプリケーションは次の処理を行います。
データ値の代わりに行セット バッファーに 32 ビット値を配置します。 この値は後でアプリケーションに返されるため、アプリケーションでは、列の数やデータを含むファイルのハンドルなどの意味のある値に設定する必要があります。
長さ/インジケーター バッファーの値を SQL_LEN_DATA_AT_EXEC(length) マクロの結果に設定します。 この値は、パラメーターのデータが SQLPutData で送信されることをドライバーに示します。 長さの値は、長いデータのバイト数を知る必要があるデータ ソースに長いデータを送信するときに使用され、領域を事前に割り当てることができるようにします。 データ ソースにこの値が必要かどうかを判断するために、アプリケーションは SQL_NEED_LONG_DATA_LEN オプションを使用して SQLGetInfo を呼び出します。 すべてのドライバーは、このマクロをサポートする必要があります。データ ソースがバイト長を必要としない場合、ドライバーはそれを無視できます。
SQLBulkOperations または SQLSetPos を呼び出します。 ドライバーは、長さ/インジケーター バッファーに SQL_LEN_DATA_AT_EXEC(length) マクロの結果が含まれていることを検出し、関数の戻り値としてSQL_NEED_DATAを返します。
SQL_NEED_DATA戻り値に応答して SQLParamData を呼び出します。 長いデータを送信する必要がある場合、 SQLParamData は SQL_NEED_DATAを返します。 ValuePtrPtr 引数が指すバッファーでは、ドライバーは、アプリケーションが行セット バッファーに配置した一意の値を返します。 複数の実行時データ列がある場合、アプリケーションはこの値を使用して、データを送信する列を決定します。ドライバーは、実行時データ列のデータを特定の順序で要求する必要はありません。
SQLPutData を呼び出して、列データをドライバーに送信します。 長いデータの場合と同様に、列データが 1 つのバッファーに収まらない場合、アプリケーションは SQLPutData を 繰り返し呼び出してデータを一部で送信します。データを再構築するのはドライバーとデータ ソースです。 アプリケーションが null で終了した文字列データを渡す場合、ドライバーまたはデータ ソースは、再構築プロセスの一部として null 終端文字を削除する必要があります。
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 状態遷移テーブル」を参照してください。