長い形式のデータの送信

  • [アーティクル]

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

Note

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

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

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

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

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

  4. SQLExecute または SQLExecDirect を呼び出します。 ドライバーは、長さ/インジケーター バッファーに SQL_DATA_AT_EXEC 値または SQL_LEN_DATA_AT_EXEC(長さ) マクロの結果が含まれていることを検出し、関数の戻り値として 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 状態になります。 ステートメントがデータが必要な状態にある間、アプリケーションは SQLPutData、SQLParamData、SQLCancel、SQLGetDiagField、または SQLGetDiagRec のみを呼び出すことができます。他のすべての関数は SQLSTATE HY010 (関数シーケンス エラー) を返します。 SQLCancel を呼び出すと、ステートメントの実行が取り消され、以前の状態に戻されます。 詳細については、「付録 B: ODBC 状態遷移テーブル」を参照してください。

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