他のバージョンの文書10 | 9.6 | 9.5 | 9.4 | 9.3 | 9.2 | 9.1 | 9.0 | 8.4 | 8.3 | 8.2 | 8.1 | 8.0 | 7.4 | 7.3 | 7.2

31.5. 1行1行問い合わせ結果を受け取る

通常、libpqはSQLコマンドの結果全体を収集し、それを1つのPGresultとしてアプリケーションに返します。 これは、多くの行数を返すコマンドでは動作しなくなるかもしれません。 こうした場合、アプリケーションはPQsendQueryPQgetResult単一行モードで使用することができます。 このモードでは、結果行は、サーバから受け取ったかのように、アプリケーションに1度に1行返されます。

単一行モードに入るためには、PQsendQuery(または同系列の関数)の呼び出しに成功した直後にPQsetSingleRowModeを呼び出してください。 このモード選択は、現在実行中の問い合わせに対してのみ有効です。 その後、項31.4の説明通りに、ヌルを返すようになるまでPQgetResultを繰り返し呼び出してください。 問い合わせが何らかの行を返す場合、PGRES_TUPLES_OKではなくPGRES_SINGLE_TUPLE状態コードを持つ以外通常の問い合わせ結果と同じように見える、個々のPGresultオブジェクトを返します。 最後の行の後、または問い合わせがゼロ行を返す場合は即座に、PGRES_TUPLES_OK状態のゼロ行のオブジェクトが返されます。 これはもう行が届かないことを通知するものです。 (しかしヌルが返るまでPQgetResultを呼び出さなければならないことに注意してください。) PGresultオブジェクトのすべては、その問い合わせに対する通常のPGresultと同一の行説明データ(列名、型など)を持ちます。 各オブジェクトは通常通りPQclearで解放しなければなりません。

PQsetSingleRowMode

現在実行中の問い合わせについて単一行モードを選択します。

int PQsetSingleRowMode(PGconn *conn);

この関数はPQsendQueryまたはその系列の関数のいずれかの後即座に、PQconsumeInputPQgetResultなど接続に対する何らかの他の操作を行う前のみに呼び出すことができます。 正しい時点で呼び出された場合、この関数は現在の問い合わせに対して単一行モードを有効にし、1を返します。 この他の場合、モードは変更されず、関数はゼロを返します。 いずれの場合でも、現在の問い合わせが完了した後に通常モードに戻ります。

注意

問い合わせを処理している間、サーバはいくつか行を返した後にエラーになり、問い合わせがアボートする可能性があります。 通常のlibpqでは、こうした行を破棄しエラーのみを報告します。 しかし単一行モードでは、これらの行はすでにアプリケーションに返されています。 このためアプリケーションはPGRES_SINGLE_TUPLE状態のPGresultオブジェクトをいくつか見た後にPGRES_FATAL_ERRORオブジェクトを見るかもしれません。 適切な振る舞いのトランザクションのために、最終的に問い合わせが失敗した場合、アプリケーションはこれまで処理した行を破棄するまたは取り消すように設計しなければなりません。