データの長さ、バッファー長、および切り捨て

データ長は、データ ソースに格納されるのではなく、アプリケーションのデータ バッファーに格納されるデータのバイト長です。 多くの場合、データはデータ バッファー内のデータ ソースとは異なる型に格納されるため、この区別は重要になります。 したがって、データ ソースに送信されるデータの場合、これはデータ ソースの型に変換される前のデータのバイト長になります。 データ ソースから取得されるデータの場合、これは、データ バッファーの型への変換後、および切り捨てが行われる前のデータのバイト長です。

整数や日付構造などの固定長データの場合、データのバイト長は常にデータ型のサイズになります。 一般には、アプリケーションはデータ型のサイズであるデータ バッファーを割り当てます。 アプリケーションがより小さいバッファーを割り当てる場合、データ バッファーがデータ型のサイズであるとドライバーが想定し、小さなバッファーに収まるようにデータを切り捨てないため、結果は未定義になります。 アプリケーションがより大きなバッファを割り当てた場合、余分なスペースは使用されません。

文字データやバイナリ データなどの可変長データの場合、データのバイト長はバッファーのバイト長とは別であり、多くの場合に異なっていることを認識することが重要です。 これら 2 つの長さの関係については、「バッファー」セクションで説明します。 データのバイト長がバッファーのバイト長を超える場合、ドライバーはフェッチされたデータをバッファーのバイト長まで切り捨て、SQLSTATE 01004 (データ切り捨て) で SQL_SUCCESS_WITH_INFO を返します。 ただし、返されるバイト長は、未使用のデータの長さです。

たとえば、アプリケーションがバイナリ データ バッファーに 50 バイトを割り当てるとします。 ドライバーが返すバイナリ データの 10 バイトがある場合は、バッファー内のそれらの 10 バイトを返します。 データのバイト長は 10 で、バッファーのバイト長は 50 です。 ドライバーが返すバイナリ データの 60 バイトがある場合は、データを 50 バイトに切り捨て、バッファー内のそれらのバイトを返し、SQL_SUCCESS_WITH_INFO を返します。 データのバイト長は 60 (切り捨て前の長さ) であり、バッファーのバイト長は 50 のままです。

切り捨てられた列ごとに診断レコードが作成されます。 ドライバーがこれらのレコードを作成し、アプリケーションがそれらのレコードを処理するには時間がかかるため、切り捨てによってパフォーマンスが低下する可能性があります。 通常、アプリケーションでは十分な大きさのバッファーを割り当てることでこの問題を回避できますが、長いデータを操作する場合は不可能な場合があります。 データの切り捨てが発生すると、アプリケーションは大きなバッファーを割り当ててデータを再フェッチすることがありますが、れはすべてのケースで当てはまるわけではありません。 SQLGetData の呼び出しでデータを取得中に切り捨てが発生した場合、アプリケーションは既に返されたデータに対して SQLGetData を呼び出す必要はありません。詳細については、「Long データの取得」を参照してください。