SQLMoreResults() - さらに結果セットがあるかどうかを判別する

SQLMoreResults() は、ステートメント・ハンドルの追加の情報を 返します。この情報は、通常、照会における入力パラメーター値の配列、 または結果セットを返すストアード・プロシージャーと関係があります。

SQLMoreResults() の ODBC 仕様

表 1. SQLMoreResults() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
1.0 なし なし

構文

SQLRETURN   SQLMoreResults   (SQLHSTMT          hstmt);

関数の引数

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

表 2. SQLMoreResults() の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT hstmt 入力 結果が戻されるステートメント・ハンドルを指定します。

使用法

次のいずれかのアクションを実行した後、この関数を使用して結果セットのシーケンスを戻します。
  • SQLSetStmtAttr または SQLBindParameter() が指定する入力パラメーター値の配列を用いたパラメーター化照会
  • 生成した結果セット上でカーソルをオープン状態のままにしておく SQL 照会が含まれた ストアード・プロシージャー (ストアード・プロシージャーの実行終了時に、このような結果セット でカーソルがオープンのままになっている場合、結果セットはアクセス可能)

1 つの結果セットを完全に処理した後、SQLMoreResults() を呼び出して、別の結果セットが使用可能かどうかを判別します。SQLMoreResults() を呼び出すと、この関数はカーソルをクローズすることによって、現行の結果セットでフェッチされなかった行を廃棄します。別の結果セットが使用可能な場合は、SQLMoreResults() は SQL_SUCCESS を戻します。

すべての結果セットが既に処理済みだった場合は、SQLMoreResults() は SQL_NO_DATA_FOUND を戻します。

引数 fOption を設定して SQL_CLOSE にした SQLFreeStmt() を呼び出した場合、 あるいは引数 HandleType を設定して SQL_HANDLE_STMT にした SQLFreeHandle() が呼び出された場合、 これらの関数は、ステートメント・ハンドルに対するペンディング結果セットをすべて廃棄します。

戻りコード

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

診断

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

表 3. SQLMoreResults() の SQLSTATE
SQLSTATE 説明 説明
08S01 通信リンクに障害が起きました。 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。
58004 予期しないシステム障害です。 リカバリー不能なシステム・エラーです。
HY001 メモリーの割り振りに失敗しました。 Db2® ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY010 関数シーケンス・エラーが発生しました。 この関数は、実行時データの操作時に呼び出されました。(すなわち、SQLParamData() または SQLPutData() 関数を使用するプロシージャー実行中に関数が呼び出されました。)
HY013 予期しないメモリー処理エラーです。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーにアクセスできません。

そのほか、SQLMoreResults() は、HY009、HY014、 および HY090 を除く、SQLExecDirect() に関連したすべての SQLSTATE を 戻すことができます。

制約事項

SQLMoreResults() の ODBC 仕様によって、入力パラメーター値の配列を用いて パラメーター化された INSERT、UPDATE、および DELETE ステートメントの実行に 関連した行カウントを戻すことができます。 ただし、Db2 ODBC では、このカウント情報の戻しをサポートしていません。

例

以下の例 は、SQLMoreResults() を使用して 結果セットの追加をチェックするアプリケーションを示しています。
図 1. 結果セットの追加をチェックするアプリケーション
/* ... */
#define NUM_CUSTOMERS 25
    SQLCHAR         stmt[] =
    {  "WITH "  /* Common Table expression (or Define Inline View) */
         "order (ord_num, cust_num, prod_num, quantity, amount) AS "
         "( "
         "SELECT c.ord_num, c.cust_num, l.prod_num, l.quantity,  "
                 "price(char(p.price, '.'), p.units, char(l.quantity, '.')) "
            "FROM ord_cust c, ord_line l, product p  "
            "WHERE c.ord_num = l.ord_num AND l.prod_num = p.prod_num  "
             "AND cust_num = CNUM(cast (? as integer)) "
         "), "
         "totals (ord_num, total) AS "
         "( "
          "SELECT ord_num, sum(decimal(amount, 10, 2))  "
          "FROM order GROUP BY ord_num "
         ") "
       /* The 'actual' SELECT from the inline view */
       "SELECT order.ord_num, cust_num, prod_num, quantity,  "
              "DECIMAL(amount,10,2) amount, total "
        "FROM order, totals  "
        "WHERE order.ord_num = totals.ord_num "
     };
    /* Array of customers to get list of all orders for */
    SQLINTEGER     Cust[]=
    {
        10, 20, 30, 40, 50, 60, 70, 80, 90, 100,
        110, 120, 130, 140, 150, 160, 170, 180, 190, 200,
        210, 220, 230, 240, 250
    };
#define  NUM_CUSTOMERS sizeof(Cust)/sizeof(SQLINTEGER)
    /* Row-wise (Includes buffer for both column data and length) */
    struct {
        SQLINTEGER      Ord_Num_L;
        SQLINTEGER      Ord_Num;
        SQLINTEGER      Cust_Num_L;
        SQLINTEGER      Cust_Num;
        SQLINTEGER      Prod_Num_L;
        SQLINTEGER      Prod_Num;
        SQLINTEGER      Quant_L;
        SQLDOUBLE       Quant;
        SQLINTEGER      Amount_L;
        SQLDOUBLE       Amount;
        SQLINTEGER      Total_L;
        SQLDOUBLE       Total;
    }               Ord[ROWSET_SIZE];
    SQLUINTEGER     pirow = 0;
    SQLUINTEGER     pcrow;
    SQLINTEGER      i;
    SQLINTEGER      j;
/* ... */
    /* Get details and total for each order row-wise */
    rc = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
    rc = SQLParamOptions(hstmt, NUM_CUSTOMERS, &pirow);
    rc = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_LONG, SQL_INTEGER,
                          0, 0, Cust, 0, NULL);
    rc = SQLExecDirect(hstmt, stmt, SQL_NTS);
    /* SQL_ROWSET_SIZE sets the max number of result rows to fetch each time */
    rc = SQLSetStmtAttr(hstmt, SQL_ATTR_ROWSET_SIZE, ROWSET_SIZE, 0);
    /* Set size of one row, used for row-wise binding only */
    rc = SQLSetStmtAttr(hstmt, SQL_ATTR_BIND_TYPE, (void*)sizeof(Ord)/ROW_SIZE, 0);
    /* Bind column 1 to the Ord_num Field of the first row in the array*/
    rc = SQLBindCol(hstmt, 1, SQL_C_LONG, (SQLPOINTER) &Ord[0].Ord_Num, 0,
                    &Ord[0].Ord_Num_L);
    /* Bind remaining columns ... */
/* ... */
    /* NOTE: This sample assumes that an order never has more
             rows than ROWSET_SIZE.  A check should be added below to call
             SQLExtendedFetch multiple times for each result set.
    */
    do  /* for each result set .... */
    { rc = SQLExtendedFetch(hstmt, SQL_FETCH_NEXT, 0, &pcrow, NULL);
      if (pcrow > 0) /* if 1 or more rows in the result set */
      {
        i = j = 0;
        printf("**************************************¥n");
        printf("Orders for Customer: 0].Cust_Num);
        printf("**************************************¥n");
        while (i < pcrow)
        {   printf("¥nOrder #: i].Ord_Num);
            printf("     Product  Quantity         Price¥n");
            printf("     -------- ---------------- ------------¥n");
            j = i;
            while (Ord[j].Ord_Num == Ord[i].Ord_Num)
            {   printf("    %8ld %16.7lf %12.2lf¥n",
                       Ord[i].Prod_Num, Ord[i].Quant, Ord[i].Amount);
                i++;
            }
            printf("                               ============¥n");
            printf("                              j].Total);
        } /* end while */
      } /* end if */
    }
    while ( SQLMoreResults(hstmt) == SQL_SUCCESS);
/* ... */