データの行のフェッチ

データ行をフェッチするために、アプリケーションは SQLFetch を呼び出します。 SQLFetch はどのような種類のカーソルでも呼び出すことができますが、行セット カーソルは順方向にのみ移動します。 SQLFetch は、カーソルを次の行に進め、SQLBindCol の呼び出しでバインドされたすべての列のデータを返します。 カーソルが結果セットの末尾に達すると、SQLFetch は SQL_NO_DATA を返します。 SQLFetch の呼び出しの例については、「SQLBindCol の使用」を参照してください。

SQLFetch の実装方法は正確にはドライバー固有ですが、一般的なパターンは、ドライバーがデータ ソースからバインドされた列のデータを取得し、バインドされた変数の型に従ってそのデータを変換して、変換したデータをそれらの変数に配置することです。 ドライバーがデータを変換できない場合、SQLFetch はエラーを返します。 アプリケーションは行のフェッチを続行できますが、現在の行のデータは失われます。 バインドされていない列のデータがどうなるかはドライバーによって異なりますが、ほとんどのドライバーは、データを取得して破棄するか、まったく取得しません。

ドライバーは、バインドされている長さ/インジケーター バッファーの値も設定します。 列のデータ値が NULL の場合、ドライバーは対応する長さ/インジケーター バッファーを SQL_NULL_DATA に設定します。 データ値が NULL でない場合、ドライバーは、長さ/インジケーター バッファーを変換後のデータのバイト長に設定します。 複数の関数呼び出しによって長いデータを取得したときに発生することがあるように、この長さを特定できない場合、ドライバーは長さ/インジケーター バッファーを SQL_NO_TOTAL に設定します。 整数や日付構造体などの固定長データ型の場合、バイト長はデータ型のサイズです。

文字データやバイナリ データなど可変長データの場合、ドライバーは、変換されたデータのバイト長を、列にバインドされたバッファーのバイト長と照合します。バッファーの長さは、SQLBindCol の BufferLength 引数で指定されます。 変換されたデータのバイト長がバッファーのバイト長を超える場合、ドライバーはバッファーに収まるようにデータを切り詰め、長さ/インジケーター バッファーの切り詰められていない長さを返し、さらに SQL_SUCCESS_WITH_INFO を返して、診断に SQLSTATE 01004 (データの切り詰め) を表示します。 唯一の例外は、SQLFetch でよって返されるときに可変長ブックマークが切り詰められ、SQLSTATE 22001 (文字列データ、右側の切り詰め) が返される場合です。

固定長データは切り詰められません。ドライバーは、バインドされたバッファーのサイズがデータ型のサイズであると見なすためです。 通常、アプリケーションはデータ値全体を保持するのに十分な大きさのバッファーをバインドするため、データの切り詰めはめったに行われません。メタデータから必要なサイズが決定されます。 ただし、バッファーが小さすぎることがわかっている場合は、アプリケーションが明示的にバッファーをバインドすることがあります。 たとえば、パーツの説明の最初の 20 文字または長いテキスト列の最初の 100 文字を取得して表示できます。

文字データは、切り詰められている場合でも、アプリケーションに返される前に、ドライバーによって null 終端されている必要があります。 null 終端文字は、返されるバイト長には含まれませんが、バインドされたバッファーにスペースが必要です。 たとえば、アプリケーションが ASCII 文字セット内の文字データで構成される文字列を使用し、ドライバーが返すデータが 50 文字で、アプリケーションのバッファーの長さが 25 バイトであるとします。 アプリケーションのバッファーでは、ドライバーは最初の 24 文字の後に null 終端文字を返します。 長さ/インジケーター バッファーでは、バイト長 50 が返されます。

アプリケーションは、結果セットを作成するステートメントを実行する前に、SQL_ATTR_MAX_ROWS ステートメント属性を設定することで、結果セット内の行数を制限できます。 たとえば、レポートの書式設定に使用するアプリケーションのプレビュー モードで必要なのは、レポートの最初のページを表示するのに十分なデータだけです。 結果セットのサイズを制限することで、このような機能の実行速度が速くなります。 このステートメント属性は、ネットワーク トラフィックを減らすことを目的としており、すべてのドライバーでサポートされているとは限りません。