CLI の手引きおよび解説書

SQLFetchScroll - バインド列すべての行セットを取り出し、データを返す

目的


仕様: DB2 CLI 5.0 ODBC 3.0 ISO CLI

SQLFetchScroll() は、結果セットからデータの指定された行セットを取り出し、すべてのバインドされた列にデータを返します。行セットは、絶対位置または相対位置で指定するか、またはブックマークを使用して指定できます。

構文

SQLRETURN   SQLFetchScroll   (SQLHSTMT          StatementHandle,
                              SQLSMALLINT       FetchOrientation,
                              SQLINTEGER        FetchOffset);

関数引き数

表 70. SQLFetchScroll 引き数
データ・タイプ 引き数 使用法 説明
SQLHSTMT StatementHandle 入力 ステートメント・ハンドル。
SQLUSMALLINT FetchOrientation 入力 取り出しのタイプ。以下のいずれかです。
  • SQL_FETCH_NEXT
  • SQL_FETCH_PRIOR
  • SQL_FETCH_FIRST
  • SQL_FETCH_LAST
  • SQL_FETCH_ABSOLUTE
  • SQL_FETCH_RELATIVE
  • SQL_FETCH_BOOKMARK
詳細については、『カーソルの位置決め』を参照してください。
SQLINTEGER FetchOffset 入力 取り出しを行う行の数。この引き数の解釈は、FetchOrientation 引き数の値によって異なります。詳細については、『カーソルの位置決め』を参照してください。

使用法

概説

SQLFetchScroll() は、結果セットから指定した行セットを返します。行セットは、絶対位置または相対位置で指定するか、またはブックマークを使用して指定できます。 SQLFetchScroll() を呼び出すことができるのは、結果セットが存在するときだけです。つまり、結果セットを作成する呼び出しを行った後で、その結果セット上にあるカーソルをクローズする前です。列のどれかがバインドされている場合、これらの列にデータが返されます。アプリケーションが行状況配列にポインターを指定するか、または取り出されているいくつかの行を返す先のバッファーを指定している場合、 SQLFetchScroll() はこの情報も共に返します。 SQLFetchScroll() の呼び出しは、 SQLFetch() の呼び出しと混合できますが、 SQLExtendedFetch() の呼び出しと混合することはできません。

カーソルの位置決め

結果セットが作成されたら、カーソルは結果セットの先頭の前に置かれます。 SQLFetchScroll() は、次の表に示されているように、 FetchOrientationFetchOffset 引き数の値に基づいてブロック・カーソルの位置を決めます。新しい行セットの開始を決定するための正確な規則は、次のセクションで示されています。

FetchOrientation
意味

SQL_FETCH_NEXT
次の行セットを返します。これは、SQLFetch() の呼び出しと同等です。 SQLFetchScroll() は、FetchOffset の値を無視します。

SQL_FETCH_PRIOR
直前の行セットを返します。 SQLFetchScroll() は、FetchOffset の値を無視します。

SQL_FETCH_RELATIVE
行セット FetchOffset を現在の行セットの開始から返します。

SQL_FETCH_ABSOLUTE
FetchOffset から始まる行セットを返します。

SQL_FETCH_FIRST
結果セットにある最初の行セットを返します。 SQLFetchScroll() は、FetchOffset の値を無視します。

SQL_FETCH_LAST
結果セットにある最後に完了した行セットを返します。 SQLFetchScroll() は、FetchOffset の値を無視します。

SQL_FETCH_BOOKMARK
SQL_ATTR_FETCH_BOOKMARK_PTR ステートメント属性によって指定したブックマークから、行セット FetchOffset の行を返します。

SQL_ATTR_ROW_ARRAY_SIZE ステートメント属性は、行セット内の行数を指定します。 SQLFetchScroll() によって取り出されている行セットが結果セットの最後とオーバーラップする場合は、 SQLFetchScroll() は行セットの一部を返します。つまり、S + R-1 が L より大きい場合、(この S は取り出されている行セットの開始行、 R は行セット・サイズ、L は結果セットの最後の行)、行セットの最初の L-S+1 行のみが有効になります。残りの行は空であり、状況は SQL_ROW_NOROW になります。

SQLFetchScroll() が返ったら、行セット・カーソルは結果セットの最初の行に置かれます。

カーソル位置の規則

次のセクションでは、FetchOrientation の各値の正確な規則について説明します。これらの規則には、以下の表記を使用します。

FetchOrientation
意味

開始前
ブロック・カーソルが結果セットの先頭の前に置かれています。新しい行セットの最初の行が結果セットの先頭の前に置かれている場合、 SQLFetchScroll() は SQL_NO_DATA を返します。

終了後
ブロック・カーソルが結果セットの末尾の後ろに置かれています。新しい行セットの最初の行が結果セットの末尾の後ろに置かれている場合、 SQLFetchScroll() は SQL_NO_DATA を返します。

CurrRowsetStart
現在の行セット内の最初の行の番号。

LastResultRow
結果セットにある最後の行の番号。

RowsetSize
行セットのサイズ。

FetchOffset
FetchOffset 引き数の値。

BookmarkRow
SQL_ATTR_FETCH_BOOKMARK_PTR ステートメント属性によって指定したブックマークに対応する行。

SQL_FETCH_NEXT 規則は以下のとおりです。

表 71. SQL_FETCH_NEXT 規則
条件 新しい行セットの最初の行
開始前 1
CurrRowsetStart + RowsetSize <= LastResultRow CurrRowsetStart + RowsetSize
CurrRowsetStart + RowsetSize > LastResultRow 終了後
終了後 終了後

SQL_FETCH_PRIOR 規則は以下のとおりです。

表 72. SQL_FETCH_PRIOR 規則
条件 新しい行セットの最初の行
開始前 開始前
CurrRowsetStart = 1 開始前
1 < CurrRowsetStart <= RowsetSize 1 a
CurrRowsetStart > RowsetSize CurrRowsetStart - RowsetSize
終了後、かつ LastResultRow < RowsetSize 1 a
終了後、かつ LastResultRow >= RowsetSize LastResultRow - RowsetSize + 1

a SQLFetchScroll() は SQLSTATE 01S06 (結果セットが最初の行設定を戻す前に取り出そうとしています。) と SQL_SUCCESS_WITH_INFO を返します。

SQL_FETCH_RELATIVE 規則は以下のとおりです。

表 73. 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 終了後

a SQLFetchScroll() は、 FetchOrientation セットを使用して呼び出されたときと同じ行セットを SQL_FETCH_ABSOLUTE に返します。詳細については、"SQL_FETCH_ABSOLUTE" の項を参照してください。
b SQLFetchScroll() は SQLSTATE 01S06 (結果セットが最初の行設定を戻す前に取り出そうとしています。) と SQL_SUCCESS_WITH_INFO を返します。

SQL_FETCH_ABSOLUTE 規則は以下のとおりです。

表 74. 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 終了後

a SQLFetchScroll() は SQLSTATE 01S06 (結果セットが最初の行設定を戻す前に取り出そうとしています。) と SQL_SUCCESS_WITH_INFO を返します。

SQL_FETCH_FIRST 規則は以下のとおりです。

表 75. SQL_FETCH_FIRST 規則
条件 新しい行セットの最初の行
任意 1

SQL_FETCH_LAST 規則は以下のとおりです。

表 76. SQL_FETCH_LAST 規則
条件 新しい行セットの最初の行
RowsetSize <= LastResultRow LastResultRow - RowsetSize + 1
RowsetSize > LastResultRow 1

SQL_FETCH_BOOKMARK 規則は以下のとおりです。

表 77. 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 を返さない場合には定義されません。

以下の値が行状況配列に返されます。

行状況配列の値
説明

SQL_ROW_SUCCESS
行が正常に取り出されました。

SQL_ROW_SUCCESS_WITH_INFO
行が正常に取り出されました。しかし、行に関する警告が返されました。

SQL_ROW_ERROR
行を取り出し中にエラーが発生しました。

SQL_ROW_ADDED
この行は、SQLBulkOperations() に挿入されました。この行がもう一度フェッチされたり、SQLSetPos() によって更新されたりすると、状況は SQL_ROW_SUCCESS になります。

この値は、SQLFetch() または SQLFetchScroll() によっては設定されません。

SQL_ROW_UPDATED
行は正常にフェッチされ、この結果セットから取り出された最後のフェッチ以降に更新されています。この行がこの結果セットからもう一度フェッチされたり、 SQLSetPos() によって更新されたりすると、その行の状況は新しい状況に変更されます。

SQL_ROW_DELETED
この行は、この結果セットからの最後のフェッチ以降に削除されています。

SQL_ROW_NOROW
行セットが結果セットの終了行と重なり合いました。行状況配列のこの要素に対応した行が返されていません。

行フェッチ・バッファー

行フェッチ・バッファーは、取り出した行の数を返すために使用します。これには、取り出しを行っているときにエラーが生じたためにデータが返されなかった行も含まれます。言い換えると、行状況配列の値が 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() を呼び出し、その列を含む行を判別できます。


表 78. SQLFetchScroll SQLSTATE
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 データ・タイプの組み合わせによって指定されている変換はサポートされていません。

制約

なし。

CLI サンプル tbread.c

(ここで完全サンプル 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]]);
        }	
    }
 
 

参照


[ ページのトップ | 前ページ | 次ページ | 目次 | 索引 ]