通常、libpqはSQLコマンドの結果全体を収集し、それを1つのPGresult
としてアプリケーションに返します。
これは、多くの行数を返すコマンドでは動作しなくなるかもしれません。
こうした場合、アプリケーションはPQsendQuery
とPQgetResult
を単一行モードで使用することができます。
このモードでは、結果行は、サーバから受け取ったかのように、アプリケーションに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
またはその系列の関数のいずれかの後即座に、PQconsumeInput
やPQgetResult
など接続に対する何らかの他の操作を行う前のみに呼び出すことができます。
正しい時点で呼び出された場合、この関数は現在の問い合わせに対して単一行モードを有効にし、1を返します。
この他の場合、モードは変更されず、関数はゼロを返します。
いずれの場合でも、現在の問い合わせが完了した後に通常モードに戻ります。
問い合わせを処理している間、サーバはいくつか行を返した後にエラーになり、問い合わせがアボートする可能性があります。
通常のlibpqでは、こうした行を破棄しエラーのみを報告します。
しかし単一行モードでは、これらの行はすでにアプリケーションに返されています。
このためアプリケーションはPGRES_SINGLE_TUPLE
状態のPGresult
オブジェクトをいくつか見た後にPGRES_FATAL_ERROR
オブジェクトを見るかもしれません。
適切な振る舞いのトランザクションのために、最終的に問い合わせが失敗した場合、アプリケーションはこれまで処理した行を破棄するまたは取り消すように設計しなければなりません。