仕様: | DB2 CLI 5.0 | ODBC 3.0 | ISO CLI |
SQLFetchScroll() は、結果セットからデータの指定された行セットを取り出し、すべてのバインドされた列にデータを返します。行セットは、絶対位置または相対位置で指定するか、またはブックマークを使用して指定できます。
構文
SQLRETURN SQLFetchScroll (SQLHSTMT StatementHandle, SQLSMALLINT FetchOrientation, SQLINTEGER FetchOffset);
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLHSTMT | StatementHandle | 入力 | ステートメント・ハンドル。 |
SQLUSMALLINT | FetchOrientation | 入力 | 取り出しのタイプ。以下のいずれかです。
|
SQLINTEGER | FetchOffset | 入力 | 取り出しを行う行の数。この引き数の解釈は、FetchOrientation 引き数の値によって異なります。詳細については、『カーソルの位置決め』を参照してください。 |
使用法
概説
SQLFetchScroll() は、結果セットから指定した行セットを返します。行セットは、絶対位置または相対位置で指定するか、またはブックマークを使用して指定できます。 SQLFetchScroll() を呼び出すことができるのは、結果セットが存在するときだけです。つまり、結果セットを作成する呼び出しを行った後で、その結果セット上にあるカーソルをクローズする前です。列のどれかがバインドされている場合、これらの列にデータが返されます。アプリケーションが行状況配列にポインターを指定するか、または取り出されているいくつかの行を返す先のバッファーを指定している場合、 SQLFetchScroll() はこの情報も共に返します。 SQLFetchScroll() の呼び出しは、 SQLFetch() の呼び出しと混合できますが、 SQLExtendedFetch() の呼び出しと混合することはできません。
結果セットが作成されたら、カーソルは結果セットの先頭の前に置かれます。 SQLFetchScroll() は、次の表に示されているように、 FetchOrientation と FetchOffset 引き数の値に基づいてブロック・カーソルの位置を決めます。新しい行セットの開始を決定するための正確な規則は、次のセクションで示されています。
SQL_ATTR_ROW_ARRAY_SIZE ステートメント属性は、行セット内の行数を指定します。 SQLFetchScroll() によって取り出されている行セットが結果セットの最後とオーバーラップする場合は、 SQLFetchScroll() は行セットの一部を返します。つまり、S + R-1 が L より大きい場合、(この S は取り出されている行セットの開始行、 R は行セット・サイズ、L は結果セットの最後の行)、行セットの最初の L-S+1 行のみが有効になります。残りの行は空であり、状況は SQL_ROW_NOROW になります。
SQLFetchScroll() が返ったら、行セット・カーソルは結果セットの最初の行に置かれます。
次のセクションでは、FetchOrientation の各値の正確な規則について説明します。これらの規則には、以下の表記を使用します。
SQL_FETCH_NEXT 規則は以下のとおりです。
条件 | 新しい行セットの最初の行 |
---|---|
開始前 | 1 |
CurrRowsetStart + RowsetSize <= LastResultRow | CurrRowsetStart + RowsetSize |
CurrRowsetStart + RowsetSize > LastResultRow | 終了後 |
終了後 | 終了後 |
SQL_FETCH_PRIOR 規則は以下のとおりです。
条件 | 新しい行セットの最初の行 |
---|---|
開始前 | 開始前 |
CurrRowsetStart = 1 | 開始前 |
1 < CurrRowsetStart <= RowsetSize | 1 a |
CurrRowsetStart > RowsetSize | CurrRowsetStart - RowsetSize |
終了後、かつ LastResultRow < RowsetSize | 1 a |
終了後、かつ LastResultRow >= RowsetSize | LastResultRow - RowsetSize + 1 |
SQL_FETCH_RELATIVE 規則は以下のとおりです。
条件 | 新しい行セットの最初の行 |
---|---|
(開始前、かつ FetchOffset > 0) または (終了後、かつ FetchOffset < 0) | -- a |
開始前、かつ FetchOffset <= 0 | 開始前 |
CurrRowsetStart = 1 かつ FetchOffset < 0 | 開始前 |
CurrRowsetStart > 1 かつ CurrRowsetStart + FetchOffset < 1 AND |FetchOffset| > RowsetSize | 開始前 |
CurrRowsetStart > 1 かつ CurrRowsetStart + FetchOffset < 1 AND |FetchOffset| <= RowsetSize | 1 b |
1 <= CurrRowsetStart + FetchOffset <= LastResultRow | CurrRowsetStart + FetchOffset |
CurrRowsetStart + FetchOffset > LastResultRow | 終了後 |
終了後、かつ FetchOffset >= 0 | 終了後 |
SQL_FETCH_ABSOLUTE 規則は以下のとおりです。
条件 | 新しい行セットの最初の行 |
---|---|
FetchOffset < 0 AND |FetchOffset| <= LastResultRow | LastResultRow + FetchOffset + 1 |
FetchOffset < 0 AND |FetchOffset| > LastResultRow、かつ |FetchOffset| > RowsetSize | 開始前 |
FetchOffset < 0 AND |FetchOffset| > LastResultRow、かつ |FetchOffset| <= RowsetSize | 1 a |
FetchOffset = 0 | 開始前 |
1 <= FetchOffset <= LastResultRow | FetchOffset |
FetchOffset > LastResultRow | 終了後 |
SQL_FETCH_FIRST 規則は以下のとおりです。
条件 | 新しい行セットの最初の行 |
---|---|
任意 | 1 |
SQL_FETCH_LAST 規則は以下のとおりです。
条件 | 新しい行セットの最初の行 |
---|---|
RowsetSize <= LastResultRow | LastResultRow - RowsetSize + 1 |
RowsetSize > LastResultRow | 1 |
SQL_FETCH_BOOKMARK 規則は以下のとおりです。
条件 | 新しい行セットの最初の行 |
---|---|
BookmarkRow + FetchOffset < 1 | 開始前 |
1 <= BookmarkRow + FetchOffset <= LastResultRow | BookmarkRow + FetchOffset |
BookmarkRow + FetchOffset > LastResultRow | 終了後 |
バインドされた列にデータを返す
SQLFetchScroll() は、SQLFetch() と同様に、バインドされた列にデータを返します。詳細については、SQLFetch - 次の行の取り出しを参照してください。
バインドされた列がない場合、SQLFetchScroll() はデータを返しませんが、ブロック・カーソルを指定した位置にまで移動します。この場合、SQLFetch() のときと同じように SQLGetData() を使用して情報を検索できます。
バッファー・アドレス
SQLFetchScroll() は、データおよび長さ / 標識バッファーのアドレスを決定するために SQLFetch() と同じ公式を使用します。詳細については、SQLBindCol() の『バッファー・アドレス』を参照してください。
行状況配列は、行セットにある各行の状況を返すときに使用します。この配列のアドレスは、SQL_ATTR_ROW_STATUS_PTR ステートメント属性によって指定されます。配列は、アプリケーションによって割り当てられており、 SQL_ATTR_ROW_ARRAY_SIZE ステートメントによって指定されている数と同じ数の要素があるべきです。その値は、SQLFetch()、SQLFetchScroll()、 SQLSetPos() によって設定されています (カーソルが SQLExtendedFetch() によって配置された後にその値が呼び出された場合は例外です)。 SQL_ATTR_ROW_STATUS_PTR ステートメント属性の値がヌル・ポインターである場合、これらの機能は行状況を返しません。
行状況配列バッファーの内容は、SQLFetch() または SQLFetchScroll() が SQL_SUCCESS または SQL_SUCCESS_WITH_INFO を返さない場合には定義されません。
以下の値が行状況配列に返されます。
この値は、SQLFetch() または SQLFetchScroll() によっては設定されません。
行フェッチ・バッファーは、取り出した行の数を返すために使用します。これには、取り出しを行っているときにエラーが生じたためにデータが返されなかった行も含まれます。言い換えると、行状況配列の値が SQL_ROW_NOROW ではない行の数ということになります。このバッファーのアドレスは、SQL_ATTR_ROWS_FETCHED_PTR ステートメント属性によって指定されます。バッファーは、アプリケーションによって割り当てられます。これは SQLFetch() と SQLFetchScroll() によって設定されます。 SQL_ATTR_ROWS_FETCHED_PTR ステートメント属性の値がヌル・ポインターである場合、これらの関数は取り出した行の数を返しません。結果セットの現在行の数を判別するために、アプリケーションは SQL_ATTR_ROW_NUMBER 属性を使用して SQLGetStmtAttr() を呼び出すことができます。
行フェッチ・バッファーの内容は、SQLFetch() または SQLFetchScroll() が SQL_SUCCESS または SQL_SUCCESS_WITH_INFO を返さない場合には定義されません。ただし、SQL_NO_DATA が返された場合は例外です。この場合は、行フェッチ・バッファーの値は 0 に設定されます。
エラー処理
SQLFetchScroll() は SQLFetch() と同じ仕方でエラーと警告を返します。詳細については、SQLFetch()、『エラー処理』を参照してください。 SQLExtendedFetch() は、SQLFetch() と同じ仕方でエラーを返します。ただし、以下の場合は例外です。
記述子および SQLFetchScroll()
SQLFetchScroll() は、SQLFetch() と同じ仕方で記述子と対話します。詳細については、SQLFetch()、『記述子と SQLFetch』を参照してください。
戻りコード
診断
各 SQLSTATE 値に関連している戻りコードは、特に注記がない限り SQL_ERROR です。エラーが単一の列に生じる場合、 SQL_DIAG_COLUMN_NUMBER の DiagIdentifier を使用して SQLGetDiagField() を呼び出し、エラーが生じた列を判別できます。また、 SQL_DIAG_ROW_NUMBER の DiagIdentifier を使用して SQLGetDiagField() を呼び出し、その列を含む行を判別できます。
SQLSTATE | 説明 | 解説 |
---|---|---|
01000 | 警告。 | 通知メッセージ。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。) |
01004 | データが切り捨てられました。 | 非ブランク文字または非 NULL の 2 進データを切り捨てた結果として、ストリングまたは 2 進データが列に返されました。ストリング値は右方切り捨てされます。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。) |
01S01 | 行の中にエラーがあります。 | 1つ以上の行をフェッチ中にエラーが起きました。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。) (この SQLSTATE は、DB2 CLI v2 に接続したときのみに返されます。) |
01S06 | 結果セットが最初の行設定を戻す前に取り出そうとしています。 | 要求された行セットは、現行位置が最初の行を超えたときに結果セットの開始と重なり合いました。そして、FetchOrientation が SQL_PRIOR であるか、または FetchOrientation が SQL_RELATIVE でした。これは、絶対値が現行の SQL_ATTR_ROW_ARRAY_SIZE 以下である負の FetchOffset を伴います。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。) |
01S07 | 小数が切り捨てられました。 | 列に返されたデータが切り捨てられました。数値データ・タイプの場合、数の小数部分は切り捨てられます。時刻、タイム・スタンプ、およびインターバル・データ・タイプの場合、時刻の小数部分は切り捨てられます。 |
07002 | 列が多すぎます。 | バインド中に指定された 1 つまたは複数の列の列番号が、結果セット内の列数より大きい値でした。 |
07006 | 変換が無効です。 | 結果セットにある列のデータ値を、 SQLBindCol() の TargetType で指定された C データ・タイプに変換できませんでした。 |
07009 | 記述子索引が無効です。 | 列 0 がバインドされ、SQL_USE_BOOKMARKS ステートメント属性が SQL_UB_OFF に設定されました。 |
08S01 | 通信リンクに障害が起きました。 | 関数が処理を完了する前に、DB2 CLI とその接続先データ・ソースとの間の通信リンクが失敗しました。 |
22001 | ストリング・データの右側が切り捨てられました。 | 行に返された可変長ブックマークが切り捨てられました。 |
22002 | 無効な出力または標識バッファーが指定されました。 | NULL データが取り出され、 SQLBindCol() によって設定された StrLen_or_IndPtr (あるいは、 SQLSetDescField() または SQLSetDescRec() によって設定された SQL_DESC_INDICATOR_PTR) がヌル・ポインターである列に入れられました。 |
22003 | 数値が範囲外です。 | 1 つまたは複数のバインド済み列の数値を (数値またはストリングとして) 返したため、割り当て時または中間結果の計算時に数値の整数部分が切り捨てられたと考えられます。 |
22007 | 日時形式が無効です。 | 結果セットにある文字列が日付、時刻、またはタイム・スタンプ C 構造にバインドされ、列にある値はそれぞれ無効である日付、時刻、またはタイム・スタンプにバインドされました。 |
22012 | ゼロによる割算は無効です。 | ゼロでの除算が行われた算術式からの値が返されました。 |
22018 | キャスト仕様の文字値が無効です。 | 結果セットにある文字カラムが文字 C バッファーにバインドされ、その列には、バッファーの文字セットに表示のない文字が入っていました。結果セットにある文字カラムが近似の数値 C バッファーにバインドされ、その列にある値は有効で近似の数値にキャストできませんでした。結果セットにある文字カラムが正確な数値 C バッファーにバインドされ、その列にある値は有効で正確な数値にキャストできませんでした。結果セットにある文字カラムが日時または間隔 C バッファーにバインドされ、その列にある値は有効な日時またはインターバル値にキャストできませんでした。 |
24000 | カーソル状態が無効です。 | StatementHandle は実行状態にありましたが、 StatementHandle に関連する結果セットがありませんでした。 |
40001 | トランザクション・ロールバック。 | 取り出しが実行されたトランザクションは、デッドロックを避けるために終了しました。 |
HY000 | 一般的なエラーです。 | 特定の SQLSTATE がなかった場合のエラーが発生しました。 SQLGetDiagRec() により *MessageText バッファーに返されたエラー・メッセージに、そのエラーと原因が記述されています。 |
HY001 | メモリーの割り振り失敗です。 | DB2 CLI は、この関数の実行または完了をサポートするために必要なメモリーを割り当てられませんでした。 |
HY008 | 操作が取り消されました。 |
非同期処理が StatementHandle に対して使用可能になりました。関数が呼び出され、その実行が完了する前に、 SQLCancel() が StatementHandle で呼び出されました。そして、関数が再び StatementHandle で呼び出されました。 関数が呼び出され、その実行が完了する前に、
SQLCancel() が複数スレッドのアプリケーション内の別のスレッドから、
StatementHandle で呼び出されました。
|
HY010 | 関数の順序エラーです。 | 指定した StatementHandle が実行状態にありませんでした。関数は、最初に SQLExecDirect()、SQLExecute()、またはカタログ関数を呼び出さずに呼び出されました。
非同期実行関数 (この関数ではない) が StatementHandle で呼び出され、この関数は、呼び出し時に依然実行中でした。
StatementHandle のために SQLExecute() または SQLExecDirect() が呼び出され、 SQL_NEED_DATA が戻されました。データがすべての実行時データ・パラメーターまたは列用に送られる前に、この関数が呼び出されました。
SQLFetch() が呼び出され、DB2 v2 またはそれ以前のサーバーに接続された後、 SQL_CLOSE オプションを使用して SQLFreeStmt() を呼び出す前、または SQLMoreResults() を呼び出す前に、 SQLFetchScroll() が StatementHandle のために呼び出されました。
SQLExtendedFetch() を呼び出した後、 SQL_CLOSE オプションを指定して SQLFreeStmt() を呼び出す前に、 StatementHandle のために SQLFetchScroll() を呼び出しました。 |
HY106 | フェッチ・タイプが範囲外です。 | 引き数 FetchOrientation に指定された値は無効でした。
引き数 FetchOrientation が SQL_FETCH_BOOKMARK であり、 SQL_ATTR_USE_BOOKMARKS ステートメント属性が SQL_UB_OFF に設定されました。
SQL_CURSOR_TYPE ステートメント属性の値は SQL_CURSOR_FORWARD_ONLY であり、引き数 FetchOrientation の値は SQL_FETCH_NEXT ではありませんでした。 |
HY107 | 行の値が範囲外です。 | SQL_ATTR_CURSOR_TYPE ステートメント属性で指定した値は SQL_CURSOR_KEYSET_DRIVEN でしたが、 SQL_ATTR_KEYSET_SIZE ステートメント属性で指定した値は 0 より大きく、 SQL_ATTR_ROW_ARRAY_SIZE ステートメント属性で指定した値より小さいものでした。 |
HY111 | ブックマーク値が無効です。 | 引き数 FetchOrientation は SQL_FETCH_BOOKMARK であり、 SQL_ATTR_FETCH_BOOKMARK_PTR ステートメント属性で値によって指されているブックマークは無効であるかまたはヌル・ポインターでした。 |
HYC00 | ドライバーが機能していません。 | 指定された取り出しタイプは、サポートされません。
SQLBindCol() の TargetType と、対応する列の SQL データ・タイプの組み合わせによって指定されている変換はサポートされていません。 |
制約
なし。
(ここで完全サンプル tbread.c を使用することもできます 。)
/* From the CLI sample TBREAD.C */ /* ... */ /* select using SQLFetchScroll with column-wise binding */ rc = TbSelectUsingFetchScrollColWise( hdbc) ; /* ... */ sqlrc = SQLFetchScroll( hstmt, SQL_FETCH_ABSOLUTE, 15 ); STMT_HANDLE_CHECK( hstmt, sqlrc); if (sqlrc == SQL_NO_DATA_FOUND) { printf("\n Data not found.\n"); } for ( i = 0; i < rowsFetchedNb; i++) { printf(" %-14s%-14s\n", col1.val[i], col2.val[i]); } /* output the Row Status Array if the complete rowset was not returned. */ if ( rowsFetchedNb != ROWSET_SIZE) { printf(" Previous rowset was not full:\n"); for (i = 0; i < ROWSET_SIZE; i++) { printf(" Row Status Array[%i] = %s\n", i, ROWSTATVALUE[rowStatus[i]]); } }
参照