CLI の手引きおよび解説書

SQLExtendedFetch - 拡張取り出し (行の配列の取り出し)

DB2 CLI バージョン 5 以降におけるこの関数の状況
注:

ODBC バージョン 3 では、SQLExtendedFetch() は使用すべきではありません。代わりに、SQLFetchScroll() に置き換えられています。詳細については、SQLFetchScroll - バインド列すべての行セットを取り出し、データを返すを参照してください。

このバージョンの DB2 CLI でも引き続き SQLExtendedFetch() をサポートはしていますが、 SQLFetchScroll() の使用を DB2 CLI プログラムから開始するなら最新の規格に適合できるため、この方法をお勧めします。

上記の関数と、その他の使用すべきでない関数の詳細については、 バージョン 5 で使用すべきでない DB2 CLI 関数を参照してください。

目的
仕様: DB2 CLI 2.1 ODBC 1.0  

SQLExtendedFetch() は、バインドされた列ごとの配列の形式で、複数行を含むデータのブロック (行セット という) を返すことにより、 SQLFetch() の機能を拡張します。行セットのサイズは、SQLSetStmtAttr() 呼び出しの SQL_ROWSET_SIZE 属性で判別されます。

データ行を一度に 1 行ずつ取り出すには、アプリケーションは SQLFetch() を呼び出す必要があります。

ブロックまたは配列検索の詳細については、配列への結果セットの取り出しを参照してください。

構文

SQLRETURN   SQLExtendedFetch (
                SQLHSTMT          StatementHandle,   /* hstmt */
                SQLUSMALLINT      FetchOrientation,  /* fFetchType */
                SQLINTEGER        FetchOffset,       /* irow */
                SQLUINTEGER  *FAR RowCountPtr,       /* pcrow */
                SQLUSMALLINT *FAR RowStatusArray);   /* rgfRowStatus */

関数引き数


表 63. SQLExtendedFetch 引き数
データ・タイプ 引き数 使用法 説明
SQLHSTMT StatementHandle 入力 ステートメント・ハンドル。
SQLUSMALLINT FetchOrientation 入力 取り出しの方向とタイプ。 DB2 CLI は、取り出し方向 SQL_FETCH_NEXT だけ、つまり順方向のみのカーソル方向をサポートします。次のデータ配列 (行セット) が取り出されます。
SQLINTEGER FetchOffset 入力 将来の利用のために予約済み。
SQLUINTEGER * RowCountPtr 出力 実際に取り出された行数。処理中にエラーが発生した場合、 RowCountPtr はエラーが発生した行の前の行 (行セット内) の順位を指定します。取り出し中にエラーが発生した場合、最初の行 RowCountPtr は値 0 を指します。
SQLUSMALLINT * RowStatusArray 出力 状況値の配列。要素数は、行セット内の行数 (SQL_ROWSET_SIZE 属性で定義される) と等しくなければなりません。行取り出しのたびに状況値が返されます。
  • SQL_ROW_SUCCESS

取り出された行数が状況配列内の要素数より小さい (つまり、行セットのサイズより小さい) 場合、残りの状況要素は SQL_ROW_NOROW に設定されます。

DB2 CLI は、取り出しの開始以降に行が更新または削除されたかどうかを検出できません。そのため、以下の ODBC 定義の状況値は報告されません。

  • SQL_ROW_DELETED
  • SQL_ROW_UPDATED

使用法

行の集まりの配列取り出しを実行するには、SQLExtendedFetch() を使用します。アプリケーションは、SQL_ROWSET_SIZE オプションを指定して SQLSetStmtAttr() を呼び出し、配列のサイズを指定します。

最初に SQLExtendedFetch() を呼び出す前に、カーソルを最初の行に置いてください。 SQLExtendedFetch() を呼び出した後、ちょうど検索された行セットの最後の行要素に対応する、結果セット内の行に、カーソルが置かれます。

SQLBindCol() または SQLBindFileToCol() 関数によってバインドされた結果セット内の列について、 DB2 CLI は必要に応じてバインドされた列のデータを変換し、これらの列にバインドされた場所にそのデータを保管します。 配列への結果セットの取り出しの節に記述されているように、列方向または行方向に結果セットをバインドすることができます。

ファイル参照の行方向バインドはサポートされていません。

SQLExtendedFetch() が行セット全体に適用されるエラーを戻すと、 SQL_ERROR 関数戻りコードが該当する SQLSTATE とともに報告されます。行セット・バッファーの内容は定義されず、カーソル位置は変更されません。

単一行に適用するエラーが発生する場合:

RowStatusArray 配列に SQL_ROW_ERROR が返された場合にのみ、対応する要素のあるエラーが発生したことを示しています。これは、生成された SQLSTATE の数を示してはいません。それで、SQLSTATE 01S01 は、各行の SQLSTATE の結果における区切り記号として使用されます。 DB2 CLI は行セットから残りの行の取り出しを継続し、関数戻りコードとして SQL_SUCCESS_WITH_INFO を戻します。 SQLExtendedFetch() が返された後、エラーが発生している各行について、 01S01 の SQLSTATE および現在行のエラーを示すゼロまたは複数の追加 SQLSTATE が存在します。これは SQLError() を介して取り出すことができます。特定の行にあてはまっている個々のエラーは、カーソルに影響を及ぼして先に進めなくなることはありません。

RowStatusArray 配列出力バッファー内の要素数は、行セット内の行数 (SQL_ROWSET_SIZE ステートメント属性で定義される) と等しくなければなりません。取り出された行数が状況配列内の要素数より小さい場合、残りの状況要素は SQL_ROW_NOROW に設定されます。

アプリケーションは、 SQLExtendedFetch() 呼び出しと SQLFetch() 呼び出しを混合できません。

戻りコード

診断


表 64. SQLExtendedFetch SQLSTATE
SQLSTATE 説明 解説
01004 データが切り捨てられました。 1 つまたは複数の 列について返されたデータが切り捨てられました。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。)
01S01 行の中にエラーがあります。 1つ以上の行をフェッチ中にエラーが起きました。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。)
07002 列が多すぎます。 バインド中に指定された 1 つまたは複数の列の列番号が、結果セット内の列数より大きい値でした。
07006 変換が無効です。 データ値を、SQLBindCol()fCType で指定されたデータ・タイプに有意義な方法で変換できませんでした。
22002 無効な出力または標識バッファーが指定されました。 SQLBindCol() の引き数 pcbValue に指定されたポインター値はヌル・ポインターでしたが、対応する列の値はヌルです。 SQL_NULL_DATA を報告する手段はありません。

SQLBindFileToCol() の引き数 IndicatorValue に指定されたポインターはヌル・ポインターでしたが、対応する LOB 列は NULL です。 SQL_NULL_DATA を報告する手段はありません。

22003 数値が範囲外です。 1 つまたは複数の列の数値を (数値またはストリングとして) 返したため、割り当て時または中間結果の計算時に数値の整数部分が切り捨てられたと考えられます。

ゼロでの除算が行われた算術式からの値が返されました。

注:このエラーが DB2 ユニバーサル・データベースによって検出された場合、関連するカーソルは未定義です。エラーが DB2 CLI または他の IBM RDBMS によって検出された場合、カーソルはオープンされたままとなり、後続のフェッチ呼び出しに進みます。

22005 割り当てにエラーがありました。 返された値は、バインドされた列のデータ・タイプと互換性がありませんでした。

返された LOB ロケーター値は、バインドされた列のデータ・タイプと互換性がありませんでした。

22007 日時形式が無効です。 文字ストリングから日時形式への変換が指定されましたが、無効なストリング表示または値が指定されたか、あるいは値が無効な日付になっています。

日付、時刻、またはタイム・スタンプの値が、指定された日付タイプの構文に従っていません。

22008 日時フィールドがオーバーフローしました。 日時フィールドのオーバーフローが発生しました。たとえば、日付またはタイム・スタンプに関する算術演算で有効な日付の範囲内にない結果になるか、あるいは、バインドされた変数が小さすぎて、その変数に日時値を割り当てることができません。
22012 ゼロによる割算は無効です。 ゼロでの除算が行われた算術式からの値が返されました。
24000 カーソル状態が無効です。 ステートメント・ハンドルで実行された直前の SQL ステートメントは照会ではありませんでした。
40003 08S01 通信リンクに障害が起きました。 アプリケーションとデータ・ソースとの間の通信リンクが、関数の完了する前に失敗しました。
428A1 ホスト・ファイル変数で参照されるファイルにアクセスできません。 これは、次のシナリオで生ずる可能性があります。テキスト内で関連付けられた理由コードは、特定のエラーを表します。
  • 01 - ファイル名の長さが無効か、またはファイル名とパスのいずれか、または両方の形式が無効です。
  • 02 - ファイル・オプションが無効です。ファイル・オプションには、以下のいずれかの値が指定されなければなりません。

     
    SQL_FILE_READ      -既存ファイルからの読み取り
    SQL_FILE_CREATE    -書き込みのための新規ファイルの
                        作成
    SQL_FILE_OVERWRITE -既存ファイルの上書き
                        ファイルが存在しない場合は
                        ファイルを作成
    SQL_FILE_APPEND    -既存ファイルの付加
                        ファイルが存在しない場合は
                        ファイルを作成
    
  • 03 - ファイルが見つかりませんでした。
  • 04 - SQL_FILE_CREATE オプションが、既存のファイルと同じ名前を持つファイルに指定されました。
  • 05 - ファイルへのアクセスが拒否されました。ユーザーが、ファイルをオープンするための許可を持っていません。
  • 06 - ファイルへのアクセスが拒否されました。ファイルが非互換モードで使用中です。書き込まれるファイルが、排他モードでオープンされています。
  • 07 - ファイルへの書き込み中に、ディスクがいっぱいになりました。
  • 08 - ファイルの読み取り中に、予期しないファイル終わりが見つかりました。
  • 09 - ファイルのアクセス中に、媒体エラーが起きました。
54028 並行 LOB ハンドルが最大数に達しました。 割り当てられた最大 LOB ロケーター。

並行 LOB ロケーターの最大数に達しました。新しいロケーターを割り当てることができません。

56084 DRDA では、LOB データはサポートされていません。 LOBが DRDA でサポートされていません。

DRDA サーバーに接続 (DB2 コネクトを使用して行う) しているときには、 LOB 列の選択や更新を行うことができません。

58004 予期しないシステム障害です。 回復不能システム・エラー。
HY001 メモリーの割り振り失敗です。 DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY010 関数の順序エラーです。 SQLFetch() を呼び出した後、 SQL_CLOSE オプションを指定して SQLFreeStmt() を呼び出す前に、 StatementHandle のために SQLExtendedFetch() を呼び出しました。

StatementHandleSQLPrepare() または SQLExecDirect() を呼び出す前に、この関数を呼び出しました。

実行時データ (SQLParamData()SQLPutData()) 操作中に、関数が呼び出されました。

BEGIN COMPOUND と END COMPOUND SQL の操作中に、関数が呼び出されました。

HY013 予期しないメモリーのハンドル・エラーが起きました。 DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを使用することができませんでした。
HY092 オプション・タイプが範囲外です。 直前の SQLBindFileToCol() 操作の FileOptions 引き数が無効でした。
HY106 フェッチ・タイプが範囲外です。 引き数 FetchOrientation に指定された値は、認識されませんでした。
HYC00 ドライバーが機能していません。 DB2 CLI またはデータ・ソースは、 SQLBindCol() または SQLBindFileToCol()fCType および対応する列の SQL データ・タイプの組み合わせによって指定された変換をサポートしません。

DB2 CLI によってサポートされていない列データ・タイプに対して、 SQLBindCol() 呼び出しが行われました。

指定された取り出しタイプは認識されますが、サポートされません。

HYT00 タイムアウトになりました。 データ・ソースが結果セットを返す前に、タイムアウト期間が満了しました。タイムアウトは、 Windows 3.1 や Macintosh System 7 のようなマルチタスクではないシステム上でのみサポートされています。タイムアウト期間は、 SQLSetConnectAttr() の SQL_ATTR_QUERY_TIMEOUT 属性を使用して設定することができます。

制約

なし。

SQLFetchScroll - バインド列すべての行セットを取り出し、データを返すを参照してください。

参照


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