SQLFetch() - 次の行をフェッチする
SQLFetch() は、カーソルを結果セットの次の行へ進めて、バインドされた列を取り出します。列は、アプリケーション・ストレージまたは LOB ロケーターのいずれかにバインドできます。
SQLFetch() の ODBC 仕様
| ODBC 仕様レベル | X/Open CLI CAE 仕様 | ISO CLI 仕様 |
|---|---|---|
| 1.0 | あり | あり |
構文
SQLRETURN SQLFetch (SQLHSTMT hstmt);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLHSTMT | hstmt | 入力 | データをフェッチするステートメント・ハンドルを指定します。 |
使用法
SQLFetch() を呼び出すと、Db2® ODBC は、適切なデータ転送を行い、列をバインドしたときに指示されていればデータ変換も一緒に行います。SQLGetData() を呼び出して、列をフェッチした 後、個々に受け取ることができます。
- 照会の実行
- 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() 呼び出しの 両方を使用することはできません。
戻りコード
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
- SQL_NO_DATA_FOUND
結果セットに行がない場合、または直前の SQLFetch() 呼び出しで結果セットの全行の フェッチが完了した場合、SQL_NO_DATA_FOUND が戻されます。すべての行がフェッチされてしまうと、カーソルは結果セットの末尾の後ろに位置されます。
診断
次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。
| SQLSTATE | 説明 | 説明 |
|---|---|---|
| 01004 | データが切り捨てられました。 | 1 つ以上の列に戻されたデータが切り捨てられました。 ストリング値または数値は、右側が切り捨てられます。 (SQLFetch() は、この SQLSTATE で SQL_SUCCESS_WITH_INFO を戻します。) |
| 07002 | 列が多すぎます。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
| 07006 | 変換が無効です。 | データ値は、SQLBindCol() の引数 fCType が指定するデータ・タイプに、意味のある方法では変換できませんでした。 |
| 08S01 | 通信リンクに障害が起きました。 | 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。 |
| 22002 | 無効な出力または標識バッファーが指定されました。 | SQLBindCol() の pcbValue 引数が NULL ポインターを指定し、対応する列の値が NULL です。この関数は、SQL_NULL_DATA を報告できません。 |
| 22008 | 日時形式が無効または日時フィールドがオーバーフローしました。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
| 22012 | ゼロによる除算は無効です。 | 除数ゼロでの割り算となる算術式からの値が戻されました。 |
| 22018 | 割り当てにエラーがありました。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
| 24000 | カーソル状態が無効です。 | ステートメント・ハンドルで実行された直前の SQL ステートメントは 照会でありません。 |
| 54028 | 最大 LOB ロケーターが割り当てられました。 | 同時 LOB ロケーターの最大数に達しました。 新規のロケーターを割り当てることはできません。 |
| 58004 | 予期しないシステム障害です。 | リカバリー不能なシステム・エラーです。 |
| HY001 | メモリーの割り振りに失敗しました。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
| HY002 | 列番号が無効です。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
| HY010 | 関数シーケンス・エラーが発生しました。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
| HY013 | 予期しないメモリー処理エラーです。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーにアクセスできません。 |
| HY019 | 数値が範囲外です。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
重要: このエラーを Db2 for z/OS® が検出した場合、関連するカーソルは不確定です。 エラーが Db2 for Linux, UNIX, and Windows または他の IBM® リレーショナル・データベース管理システムによって検出された場合、 カーソルはオープンされたままとなり、後続のフェッチ呼び出しに進みます。 |
| HYC00 | ドライバーは使用できません。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
例
以下の例は、SQLFetch() を使用して、結果セットのバインドされた列からデータを取り出すアプリケーションを示しています。
/* ... */
/*******************************************************************
** 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 */
/* ... */