長い形式のデータの送信

DBMS は、254 文字など、特定のサイズの任意の文字またはバイナリ データとして 長いデータ を定義します。 長いデータの項目全体をメモリに格納できない場合があります。たとえば、項目が長いテキスト ドキュメントやビットマップを表している場合などです。 このようなデータは 1 つのバッファーに格納できないため、データ ソースはステートメントの実行時に SQLPutData の一部でドライバーに送信します。 実行時にデータが送信されるパラメーターは、実行時 のデータ パラメーターと呼ばれます。

注意

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

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

  1. バッファーのアドレスを渡すのではなく、SQLBindParameterParameterValuePtr 引数のパラメーターを識別する 32 ビット値を渡します。 この値は、ドライバーによって分析されません。 これは後でアプリケーションに返されるため、アプリケーションに何かを意味する必要があります。 たとえば、パラメーターの数や、データを含むファイルのハンドルなどです。

  2. SQLBindParameterStrLen_or_IndPtr引数に長さ/インジケーター バッファーのアドレスを渡します。

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

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

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

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

  7. SQLParamData をもう一度呼び出して、パラメーターのすべてのデータが送信されたことを示します。 データが送信されていない実行時のデータ パラメーターがある場合、ドライバーはSQL_NEED_DATAと次のパラメーターを識別する値を返します。アプリケーションが手順 6 に戻ります。 実行中のすべてのデータ パラメーターに対してデータが送信された場合、ステートメントが実行されます。 SQLParamData は、SQL_SUCCESSまたはSQL_SUCCESS_WITH_INFOを返し、 SQLExecute または SQLExecDirect が返すことができる任意の戻り値または診断を返すことができます。

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

実行時にデータを送信する例については、 SQLPutData 関数の説明を参照してください。