SQLFetch - 次の行の取り出し

目的

仕様:

DB2 CLI 1.1

ODBC 1.0

SQLFetch() はカーソルを結果セットの次の行に進めて、バインドされた列を取り出します。

列はアプリケーションのストレージにバインドすることができます。

SQLFetch() が呼び出されると、適切なデータ転送が行われます。列のバインド時に変換が指示されている場合は、データ変換も同時に行われます。 SQLGetData() を呼び出すことによって、取り出しの後に、列を個別に受け取ることもできます。

SQLFetch() は、照会の実行によって (同じステートメント・ハンドルを使用して) 結果セットを生成した後でのみ、呼び出すことができます。

構文

SQLRETURN   SQLFetch         (SQLHSTMT          StatementHandle);  /* hstmt */

関数の引き数

表 48. SQLFetch の引き数

データ・タイプ	引き数	用途	説明
SQLHSTMT	`StatementHandle`	入力	ステートメント・ハンドル。

使用法

SQLFetch() は、同じステートメント・ハンドル上で結果セットが生成された後でのみ、呼び出すことができます。最初に SQLFetch() を呼び出す前に、カーソルを結果セットの先頭の前に位置付けます。

SQLBindCol() にバインドされるアプリケーション変数の数は、結果セット内の列数を超えてはなりません。超えた場合、SQLFetch() は失敗します。

列のバインドのために SQLBindCol() が呼び出されていない場合、SQLFetch() はデータをアプリケーションに戻さないで、カーソルを進めるだけです。このような場合、すべての列を個別に入手するには、SQLGetData() を呼び出します。 SQLFetch() がカーソルを次の行に進めると、アンバインド列のデータは廃棄されます。

列はアプリケーションのストレージにバインドすることができます。アプリケーションのストレージを列にバインドするには、SQLBindCol() を使用します。データは取り出し時にデータベースからアプリケーションに転送されます。戻すことのできるデータの長さも設定されます。

バインド・ストレージ・バッファーの大きさが SQLFetch() によって戻されるデータを収容するのに十分でない場合、データは切り捨てられます。文字データが切り捨てられた場合 SQL_SUCCESS_WITH_INFO が戻され、切り捨てを示す SQLSTATE が生成されます。SQLBindCol() 据え置き出力引き数 pcbValue に、サーバーから取り出された列データの実際の長さが入ります。アプリケーションでは実際の出力の長さと入力バッファーの長さ (SQLBindCol() からの pcbValue と cbValueMax 引き数) を比較して、切り捨てられた文字列を判別する必要があります。

小数点の右側の数字を切り捨てた場合、数値データ・タイプの切り捨ては警告として報告されます。切り捨てが小数点の左側で発生した場合、エラーが戻されます (診断のセクションを参照してください)。

結果セットからすべての行を取り出す場合、または結果セットの残りの行が必要ない場合には、SQLFreeStmt() を呼び出してカーソルをクローズし、残りのデータおよび関連するリソースを廃棄します。

DB2 Everyplace は、行セットを使用する代わりに、一度に 1 行ずつ取り出します。DB2 Everyplace はステートメント記述子をサポートしません。

SQLFetch() は、アプリケーションが別々の長さバッファーと標識バッファーを指定しているかどうかを判別します。指定している場合、データが NULL でないときは、SQLFetch() は標識バッファーを 0 に設定し、長さを長さバッファーに戻します。データが NULL のときは、 SQLFetch() は標識バッファーを SQL_NULL_DATA に設定し、長さバッファーは変更しません。

カーソルの位置決め

結果セットが作成されると、カーソルは結果セットの先頭の前に位置付けされます。 SQLFetch() は次の行を取り出します。

戻りコード

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE
SQL_NO_DATA_FOUND

結果セットに行がないか、または前の SQLFetch() 呼び出しが結果セットからすべての行を取り出した場合には、SQL_NO_DATA_FOUND が戻されます。

すべての行が取り出されると、カーソルは結果セットの末尾の後に位置付けされます。

診断

表 49. SQLFetch の SQLSTATE

SQLSTATE	説明	解説
01004	データが切り捨てられた。	1 つ以上の列に対して戻されたデータが切り捨てられる。ストリング値または数値は右側が切り捨てられる。(エラーがない場合には、SQL_SUCCESS_WITH_INFO が戻される。)
07006	無効な変換。	`SQLBindCol()` の `fCType` により指定したデータ・タイプへのデータ値の変換が無意味である。
22002	無効な出力バッファーまたは標識バッファーの指定。	`SQLBindCol()` 内の引き数 `pcbValue` に指定したポインター値がヌル・ポインターで、対応する列の値がヌルである。 SQL_NULL_DATA を報告する方法がない。
58004	予期しないシステム障害。	回復不能なシステム・エラー。
HY001	メモリーの割り振りの失敗。	DB2 CLI が、関数の実行または完了のサポートに必要なメモリーを割り当てることができない。
HY010	関数のシーケンス・エラー。	`StatementHandle` に対して、`SQLPrepare()` または `SQLExecDirect()` が呼び出される前に関数が呼び出された。
HY013	予期しないメモリー処理エラー。	DB2 CLI が、関数の実行または完了のサポートに必要なメモリーにアクセスできない。

制約事項

なし。

関連した解説