SQLFetch() - 次の行をフェッチする

SQLFetch() は、カーソルを結果セットの次の行へ進めて、バインドされた列を取り出します。列は、アプリケーション・ストレージまたは LOB ロケーターのいずれかにバインドできます。

SQLFetch() の ODBC 仕様

表 1. SQLFetch() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
1.0 あり あり

構文

SQLRETURN   SQLFetch         (SQLHSTMT          hstmt);

関数の引数

次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。

表 2. SQLFetch() の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT hstmt 入力 データをフェッチするステートメント・ハンドルを指定します。

使用法

SQLFetch() を呼び出すと、Db2® ODBC は、適切なデータ転送を行い、列をバインドしたときに指示されていればデータ変換も一緒に行います。SQLGetData() を呼び出して、列をフェッチした 後、個々に受け取ることができます。

SQLFetch() を呼び出すことができるのは、結果セットを生成した後だけです。 以下のいずれのアクションでも、結果セットが生成されます。
  • 照会の実行
  • SQLGetTypeInfo() の呼び出し
  • カタログ関数の呼び出し

一度に複数の行を取り出すには、SQLExtendedFetch() を使用します。

SQLFetch() を呼び出して、その結果を取り出してバインドされたアプリケーション変数に入れ、 結果セットの中でカーソル位置を進めます。SQLFetch() を呼び出せるのは、結果セットがステートメント・ハンドルで生成された後だけです。SQLFetch() を初めて呼び出す前に、カーソルを結果セットの 先頭の前に置きます。

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

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

どの列をバインドするためにも SQLBindCol() を呼び出さなかった場合、SQLFetch() はアプリケーション にデータを戻さず、単にカーソルだけを進めます。この場合、SQLGetData() を呼び出して、 すべての列を個々に取得することができます。SQLFetch() がカーソルを次の行に進めると、 バインドされていない列のデータが廃棄されます。 固定長データ・タイプまたは短い可変長データ・タイプの場合、 列をバインドした方が、SQLGetData() を使用するよりもパフォーマンスは向上します。

複数の列をバインドしてアプリケーション・ストレージに入れることができます。 あるいは LOB ロケーターを使用できます。

アプリケーション・ストレージへのフェッチ: SQLBindCol() は、アプリケーション・ストレージをバインドして列に入れることができ ます。SQLFetch() を呼び出すと、データはサーバーからアプリケーションへ転送されます。また、戻すのに使用可能なデータ長も設定されます。

LOB 値が大きすぎて 1 回のフェッチで取り出せない場合には、これらの LOB 値を分けて取り出します。 これを行うには、SQLGetData() (これはどの列タイプでも使用可能) を使用するか、あるいは LOB ロケーターをバインドして SQLGetSubString() を使用します。

LOB ロケーターへのフェッチ: SQLBindCol() を使用して、LOB ロケーターをバインドして列に入れます。フェッチする時には、LOB ロケーター (4 バイト) のみがサーバーからアプリケーションへ転送されます。

アプリケーションは、ロケーターを受け取ると、そのロケーター を、SQLGetSubString()、SQLGetPosition()、または SQLGetLength() で使用するか、 あるいは別の SQL ステートメントのパラメーター・マーカーの値として使用することができ ます。SQLGetSubString() は、別ロケーターを戻すか、またはデータそのものを戻すことができます。 すべてのロケーターは、ロケーターが作成されたトランザクションの終了まで (たとえカーソルが 別の行に移った場合でも)、あるいはロケーターが FREE LOCATOR ステートメントを使用して 解放されるまで、有効な状態にあります。

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

切り捨てが小数点の右側の桁数に関係している場合、 数値データ・タイプの切り捨ては警告として報告されます。 切り捨てが小数点の左側で行われた場合には、 エラーが戻されます (診断を参照)。

グラフィック・データ・タイプの切り捨てが行われた場合は、文字データ・タイプと同じ方法で処理され ますが、SQLBindCol() の引数 rgbValue で指定したバッファーの場合はその限りではありません。このバッファーは、SQLBindCol() の引数 cbValueMax で指定した値以下で、 最も近い 2 バイトの倍数まで埋められます。Db2 ODBC とアプリケーション間で転送された グラフィック (DBCS) データは、C バッファー・タイプが SQL_C_CHAR の場合には NUL 終了しません。バッファー・タイプが SQL_C_DBCHAR の場合は、グラフィック・データは NUL 終了します。

データ切り捨て時の警告を出力しないようにするには、SQL_ATTR_MAX_LENGTH 属性を最大長の値 に設定して SQLSetStmtAttr() を呼び出します。その後、引数 rgbValue でバッファーを割り振ります。 これは、SQL_ATTR_MAX_LENGTH で指定した値と同じバイト数 (NUL 終止符をプラス) です。SQL_ATTR_MAX_LENGTH で指定した最大長よりも列データの方が大きい場合は、SQL_SUCCESS が 戻されます。最大長を指定する場合は、実際の長さではなく指定した長さが、引数 pcbValue に 戻されます。

一度に複数の行を取り出すには、SQLExtendedFetch() を使用します。 同じステートメント・ハンドルで、SQLFetch() 呼び出しと SQLExtendedFetch() 呼び出しの 両方を使用することはできません。

戻りコード

SQLFetch() は、呼び出された後、次のいずれかの値を戻します。
  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE
  • SQL_NO_DATA_FOUND

結果セットに行がない場合、または直前の SQLFetch() 呼び出しで結果セットの全行の フェッチが完了した場合、SQL_NO_DATA_FOUND が戻されます。すべての行がフェッチされてしまうと、カーソルは結果セットの末尾の後ろに位置されます。

診断

次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。

表 3. SQLFetch() の SQLSTATE
SQLSTATE 説明 説明
01004 データが切り捨てられました。 1 つ以上の列に戻されたデータが切り捨てられました。 ストリング値または数値は、右側が切り捨てられます。 (SQLFetch() は、この SQLSTATE で SQL_SUCCESS_WITH_INFO を戻します。)
07002 列が多すぎます。 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
  • 1 つ以上の列のバインドで指定された列番号が、結果セットの列数より大きい値です。
  • アプリケーションが SQLSetColAttributes() を使用して、Db2 ODBC に 結果セットの記述子情報を通知しましたが、その結果セットにあるすべての列には この情報を提供していません。
07006 変換が無効です。 データ値は、SQLBindCol() の引数 fCType が指定するデータ・タイプに、意味のある方法では変換できませんでした。
08S01 通信リンクに障害が起きました。 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。
22002 無効な出力または標識バッファーが指定されました。 SQLBindCol() の pcbValue 引数が NULL ポインターを指定し、対応する列の値が NULL です。この関数は、SQL_NULL_DATA を報告できません。
22008 日時形式が無効または日時フィールドがオーバーフローしました。 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
  • 文字ストリングから日時形式への変換が指示されましたが、 指定されたストリング表示または値が無効であるか、あるいは日付の値が無効です。
  • 日付、時刻、またはタイム・スタンプの値が、指定されたデータ・タイプ の構文に準拠していません。
  • 日時フィールドでオーバーフローが起こりました。

    例: 日付またはタイム・スタンプの算術計算の結果が日付の有効範囲から外れているか、 あるいは、バインドされた変数が小さすぎて日付/時刻値を割り当てることができません。

22012 ゼロによる除算は無効です。 除数ゼロでの割り算となる算術式からの値が戻されました。
22018 割り当てにエラーがありました。 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
  • 戻された値は、バインドのデータ・タイプと互換性がありません。
  • 戻された LOB ロケーターは、バインドされた列のデータ・タイプと互換性がありません。
24000 カーソル状態が無効です。 ステートメント・ハンドルで実行された直前の SQL ステートメントは 照会でありません。
54028 最大 LOB ロケーターが割り当てられました。

同時 LOB ロケーターの最大数に達しました。 新規のロケーターを割り当てることはできません。

58004 予期しないシステム障害です。 リカバリー不能なシステム・エラーです。
HY001 メモリーの割り振りに失敗しました。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY002 列番号が無効です。 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
  • 指定された列は、0 より小さいか、結果の列数より大きい値です。
  • 指定された列は 0 ですが、Db2 ODBC は ODBC ブックマーク (icol = 0) を サポートしていません。
  • SQLExtendedFetch() がこの結果セットに対して呼び出されました。
HY010 関数シーケンス・エラーが発生しました。 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
  • SQLFetch() が SQLExtendedFetch() の後、かつ SQLCloseCursor() の前に、ステートメント・ハンドルに対して呼び出されました。
  • この関数は、SQLPrepare() または SQLExecDirect() の前に呼び出されました。
  • この関数は、実行時データの操作時に呼び出されました。(すなわち、SQLParamData() または SQLPutData() 関数を使用するプロシージャー実行中に関数が呼び出されました。)
HY013 予期しないメモリー処理エラーです。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーにアクセスできません。
HY019 数値が範囲外です。 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
  • 1 つ以上の列の数値を (数値またはストリングとして) 戻す場合、 割り当て時または中間結果算出時に、数値の整数部分が切り捨てられています。
  • 除数ゼロでの割り算となる算術式からの値が戻されました。

重要: このエラーを Db2 for z/OS® が検出した場合、関連するカーソルは不確定です。 エラーが Db2 for Linux, UNIX, and Windows または他の IBM® リレーショナル・データベース管理システムによって検出された場合、 カーソルはオープンされたままとなり、後続のフェッチ呼び出しに進みます。

HYC00 ドライバーは使用できません。 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
  • Db2 ODBC またはデータ・ソースは、SQLBindCol() の引数 fCType、および 対応する列の SQL データ・タイプが必要とする変換をサポートしていません。
  • Db2 ODBC によってサポートされていない列データ・タイプに対して、SQLBindCol() 呼び出し が行われました。

例

以下の例は、SQLFetch() を使用して、結果セットのバインドされた列からデータを取り出すアプリケーションを示しています。

図 1. バインドされた列からデータを取り出すアプリケーション
/* ... */
/*******************************************************************
** main
*******************************************************************/
int
main( int argc, char * argv[] )
{
    SQLHENV         henv;
    SQLHDBC         hdbc;
    SQLHSTMT        hstmt;
    SQLRETURN       rc;
    SQLCHAR         sqlstmt[] = "SELECT deptname, location from org where
                                        division = 'Eastern'";
    struct { SQLINTEGER ind;
             SQLCHAR  s[15];
           } deptname, location;
  /* Macro to initialize server, uid and pwd */
    INIT_UID_PWD;
    /* Allocate an environment handle    */
    rc = SQLAllocHandle( SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);    
    if (rc != SQL_SUCCESS)
        return (terminate(henv, rc));
    rc = DBconnect(henv, &hdbc);/* allocate a connect handle, and connect */
    if (rc != SQL_SUCCESS)
        return (terminate(henv, rc));
    rc = SQLAllocHandle( SQL_HANDLE_STMT, hdbc, &hstmt);
    rc = SQLExecDirect(hstmt, sqlstmt, SQL_NTS);
    rc = SQLBindCol(hstmt, 1, SQL_C_CHAR, (SQLPOINTER) deptname.s, 15,
                    &deptname.ind);
    rc = SQLBindCol(hstmt, 2, SQL_C_CHAR, (SQLPOINTER) location.s, 15,
                    &location.ind);
printf("Departments in Eastern division:¥n");
    printf("DEPTNAME       Location¥n");
    printf("-------------- -------------¥n");
    while ((rc = SQLFetch(hstmt)) == SQL_SUCCESS) {
        printf("
    }
    if (rc != SQL_NO_DATA_FOUND)
        CHECK_HANDLE (SQL_HANDLE_STMT, hstmt, RETCODE);
    rc = SQLFreeHandle (SQL_HANDLE_STMT, hstmt);
    rc = SQLEndTran(SQL_HANDLE_DBC, hdbc, SQL_COMMIT);
    printf("Disconnecting .....¥n");
    rc = SQLDisconnect(hdbc);
    rc = SQLFreeHandle (SQL_HANDLE_DBC, hdbc);
    rc = SQLFreeHandle (SQL_HANDLE_DBC, henv);
    if (rc != SQL_SUCCESS)
        return (terminate(henv, rc));
}                               /* end main */
/* ... */