SQLFetch - 次のデータ行の取り出し

SQLFetch() は、結果セットの次の行にカーソルを進め、バインド列を検索します。

SQLFetch() を使って、 SQLBindCol() で指定した変数内にデータを直接受信することができますが、 SQLGetData() を呼び出して、取り出し後の列を 1 つずつ受信することもできます。また、列バインド時に変換が指示されている場合は、 SQLFetch() の呼び出し時にデータ変換も実行されます。

構文

SQLRETURN SQLFetch (SQLHSTMT    hstmt);

関数引数

表 1. SQLFetch の引数
データ・タイプ	argument	Use	説明
SQLHSTMT	hstmt (hstmt)	入力	ステートメント・ハンドル

使用法

SQLFetch() を呼び出せるのは、hstmt で処理された最新のステートメントが SELECT の場合のみです。

SQLBindCol() でバインドされたアプリケーション変数の数が、結果セットの列の数より多いと、SQLFetch() が失敗します。

列バインド時に SQLBindCol() が呼び出されないと、 SQLFetch() を実行してもデータはアプリケーション・プログラムに戻されず、カーソルが次の行に進むだけになります。この場合は、SQLGetData() を呼び出して、すべての列を個々に得ることができます。アンバインドされた列のデータは、 SQLFetch() によりカーソルが次の行に進められた時点で廃棄されます。

バインド変数が小さくて SQLFetch() の戻りデータが入らない場合、データは切り捨てられます。文字データが切り捨てられた場合、SQLSetEnvAttr() の属性 SQL_ATTR_TRUNCATION_RTNC が SQL_TRUE に設定されていると、CLI 戻りコード SQL_SUCCESS_WITH_INFO が、切り捨てを示す SQLSTATE とともに戻されます。 SQL_ATTR_TRUNCATION_RTNC のデフォルトは SQL_FALSE なので注意してください。また、文字データ切り捨ての場合は、SQLBindCol() の遅延出力引数 pcbValue には、データ・ソースで検索される列データの実際の長さが指定されます。アプリケーションは出力の長さと入力の長さ(pcbValueとcbValueMaxのSQLBindCol()からの引数)を比較して、どの文字列が切り捨てられたかを判断しなければなりません。

10 進小数点の右側の桁が切り捨てられた場合、数値データ・タイプの切り捨ては報告されません。 10 進小数点の左側の桁が切り捨てられると、エラーが戻されます (診断の項を参照)。

図形データ・タイプの切り捨ては、文字データ・タイプと同じ方法で処理されます。ただし、rgbValueバッファは、SQLBindCol()で指定されたcbValueMax以下の2バイトの倍数まで満たされる。 Db2 for i CLIとアプリケーションの間で転送されるグラフィックデータは、決してヌル終端ではありません。

結果セットのすべての行の検索が完了したか、またはその他の行の検索が必要ない場合は、 SQLFreeStmt() を呼び出してカーソルをクローズし、その他のデータと関連リソースを廃棄してください。

戻りコード

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE
SQL_NO_DATA_FOUND

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

診断

表 2. SQLFetch SQLSTATE
SQLSTATE	説明	説明
01004	データは切り捨てられる	戻された 1 つ以上の列のデータが切り捨てられています。ストリング値の右桁が切り捨てられます。 (エラーが発生しなければ SQL_SUCCESS_WITH_INFO が戻されます。)
HY001	メモリーの割り振りの失敗	ドライバーは、関数の処理または完了をサポートするのに必要なメモリーを割り振ることができません。
HY010 年	関数シーケンス・エラー	指定された hstmt が処理済み状態になっていません。先に SQLExecute または SQLExecDirect を呼び出さないで、この関数が呼び出されています。
HY 013 *	メモリー管理の問題	ドライバーは、関数の処理または完了をサポートするのに必要なメモリーにアクセスできません。
HY021	内部記述子が無効	内部記述子がアドレッシングできない、割り振れない、または無効な値を持っています。

例

注: コード例を使用すると、コード・ライセンスおよび特記事項の条件に同意したことになります。

/*************************************************************************
** file = fetch.c
**
** Example of executing an SQL statement.
** SQLBindCol & SQLFetch is used to retrieve data from the result set
** directly into application storage.
**
** Functions used:
**
**        SQLAllocConnect      SQLFreeConnect
**        SQLAllocEnv          SQLFreeEnv
**        SQLAllocStmt         SQLFreeStmt
**        SQLConnect           SQLDisconnect
**
**        SQLBindCol           SQLFetch
**        SQLTransact          SQLExecDirect
**        SQLError
**
**************************************************************************/
 
#include <stdio.h>
#include <string.h>
#include "sqlcli.h"
 
#define MAX_STMT_LEN 255
 
int initialize(SQLHENV *henv,
              SQLHDBC *hdbc);
 
int terminate(SQLHENV henv,
              SQLHDBC hdbc);
 
int print_error (SQLHENV    henv,
                 SQLHDBC    hdbc,
                 SQLHSTMT   hstmt);
 
int check_error (SQLHENV    henv,
                 SQLHDBC    hdbc,
                 SQLHSTMT   hstmt,
                 SQLRETURN  frc);
 
/*******************************************************************
** main
** - initialize
** - terminate
*******************************************************************/
int main()
{
    SQLHENV     henv;
    SQLHDBC     hdbc;
    SQLCHAR     sqlstmt[MAX_STMT_LEN + 1]="";
    SQLRETURN   rc;
 
    rc = initialize(&henv, &hdbc);
    if (rc == SQL_ERROR) return(terminate(henv, hdbc));
 
 
    {SQLHSTMT   hstmt;
     SQLCHAR    sqlstmt[]="SELECT deptname, location from org where division = 'Eastern'";
     SQLCHAR    deptname[15],
                location[14];
     SQLINTEGER rlength;
 
        rc = SQLAllocStmt(hdbc, &hstmt);
        if (rc != SQL_SUCCESS )
           check_error (henv, hdbc, SQL_NULL_HSTMT, rc);
 
        rc = SQLExecDirect(hstmt, sqlstmt, SQL_NTS);
        if (rc != SQL_SUCCESS )
            check_error (henv, hdbc, hstmt, rc);
 
        rc = SQLBindCol(hstmt, 1, SQL_CHAR, (SQLPOINTER) deptname, 15,
                         &rlength);
        if (rc != SQL_SUCCESS )
            check_error (henv, hdbc, hstmt, rc);
        rc = SQLBindCol(hstmt, 2, SQL_CHAR, (SQLPOINTER) location, 14,
                         &rlength);
        if (rc != SQL_SUCCESS )
            check_error (henv, hdbc, hstmt, rc);
 
        printf("Departments in Eastern division:\n");
        printf("DEPTNAME       Location\n");
        printf("-------------- -------------\n");
 
        while ((rc = SQLFetch(hstmt)) == SQL_SUCCESS)
        {
            printf("%-14.14s %-13.13s \n", deptname, location);
        }
        if (rc != SQL_NO_DATA_FOUND )
           check_error (henv, hdbc, hstmt, rc);
 
        rc = SQLFreeStmt(hstmt, SQL_DROP);
        if (rc != SQL_SUCCESS )
            check_error (henv, hdbc, SQL_NULL_HSTMT, rc);
    }
 
 
    rc = SQLTransact(henv, hdbc, SQL_COMMIT);
    if (rc != SQL_SUCCESS )
        check_error (henv, hdbc, SQL_NULL_HSTMT, rc);
 
    terminate(henv, hdbc);
    return (0);
}/* end main */
 
/*******************************************************************
** initialize
**  - allocate environment handle
**  - allocate connection handle
**  - prompt for server, user id, & password
**  - connect to server
*******************************************************************/
 
int initialize(SQLHENV *henv,
              SQLHDBC *hdbc)
{
SQLCHAR     server[SQL_MAX_DSN_LENGTH],
            uid[30],
            pwd[30];
SQLRETURN   rc;
 
    rc = SQLAllocEnv (henv);         /* allocate an environment handle    */
    if (rc != SQL_SUCCESS )
        check_error (*henv, *hdbc, SQL_NULL_HSTMT, rc);
 
    rc = SQLAllocConnect (*henv, hdbc);  /* allocate a connection handle   */
    if (rc != SQL_SUCCESS )
        check_error (*henv, *hdbc, SQL_NULL_HSTMT, rc);
 
    printf("Enter Server Name:\n");
    gets(server);
    printf("Enter User Name:\n");
    gets(uid);
    printf("Enter Password Name:\n");
    gets(pwd);
 
    if (uid[0] == '\0')
    {   rc = SQLConnect (*hdbc, server, SQL_NTS, NULL, SQL_NTS, NULL, SQL_NTS);
        if (rc != SQL_SUCCESS )
            check_error (*henv, *hdbc, SQL_NULL_HSTMT, rc);
    }
    else
    {   rc = SQLConnect (*hdbc, server, SQL_NTS, uid, SQL_NTS, pwd, SQL_NTS);
        if (rc != SQL_SUCCESS )
            check_error (*henv, *hdbc, SQL_NULL_HSTMT, rc);
    }
 
    return(SQL_SUCCESS);
}/* end initialize */
 
/*******************************************************************
** terminate
**  - disconnect
**  - free connection handle
**  - free environment handle
*******************************************************************/
int terminate(SQLHENV henv,
              SQLHDBC hdbc)
{
SQLRETURN   rc;
 
    rc = SQLDisconnect (hdbc);               /* disconnect from database  */
    if (rc != SQL_SUCCESS )
        print_error (henv, hdbc, SQL_NULL_HSTMT);
    rc = SQLFreeConnect (hdbc);              /* free connection handle    */
    if (rc != SQL_SUCCESS )
        print_error (henv, hdbc, SQL_NULL_HSTMT);
    rc = SQLFreeEnv (henv);                  /* free environment handle   */
    if (rc != SQL_SUCCESS )
        print_error (henv, hdbc, SQL_NULL_HSTMT);
 
    return(rc);
}/* end terminate */
 
/*******************************************************************
**  - print_error   - call SQLError(), display SQLSTATE and message
*******************************************************************/
 
int print_error (SQLHENV    henv,
                 SQLHDBC    hdbc,
                 SQLHSTMT   hstmt)
{
SQLCHAR     buffer[SQL_MAX_MESSAGE_LENGTH + 1];
SQLCHAR     sqlstate[SQL_SQLSTATE_SIZE + 1];
SQLINTEGER  sqlcode;
SQLSMALLINT length;
 
 
    while ( SQLError(henv, hdbc, hstmt, sqlstate, &sqlcode, buffer,
                     SQL_MAX_MESSAGE_LENGTH + 1, &length) == SQL_SUCCESS )
    {
        printf("\n **** ERROR *****\n");
        printf("         SQLSTATE: %s\n", sqlstate);
        printf("Native Error Code: %ld\n", sqlcode);
        printf("%s \n", buffer);
    };
 
    return ( SQL_ERROR);
} /* end print_error */
 
/*******************************************************************
**  - check_error   - call print_error(), checks severity of return code
*******************************************************************/
int check_error (SQLHENV    henv,
                 SQLHDBC    hdbc,
                 SQLHSTMT   hstmt,
                 SQLRETURN  frc)
{
SQLRETURN   rc;
 
    print_error(henv, hdbc, hstmt);
 
    switch (frc){
    case SQL_SUCCESS : break;
    case SQL_ERROR :
    case SQL_INVALID_HANDLE:
        printf("\n ** FATAL ERROR, Attempting to rollback transaction **\n");
        rc = SQLTransact(henv, hdbc, SQL_ROLLBACK);
        if (rc != SQL_SUCCESS)
            printf("Rollback Failed, Exiting application\n");
        else
            printf("Rollback Successful, Exiting application\n");
        terminate(henv, hdbc);
        exit(frc);
        break;
    case SQL_SUCCESS_WITH_INFO :
        printf("\n ** Warning Message, application continuing\n");
        break;
    case SQL_NO_DATA_FOUND :
        printf("\n ** No Data Found ** \n");
        break;
    default :
        printf("\n ** Invalid Return Code ** \n");
        printf(" ** Attempting to rollback transaction **\n");
        SQLTransact(henv, hdbc, SQL_ROLLBACK);
        terminate(henv, hdbc);
        exit(frc);
        break;
    }
    return(SQL_SUCCESS);
 
} /* end check_error */