通常、libpqはSQLコマンドの結果全体を収集し、それを1つのPGresult
としてアプリケーションに返します。
これは、多くの行数を返すコマンドでは動作しなくなるかもしれません。
このような場合、アプリケーションはPQsendQuery
とPQgetResult
で単一行モードまたはチャンクモードを使用することができます。
これらのモードでは、結果の行は、サーバから受信されると、一度に1行ずつ、またはチャンクでグループ化されてアプリケーションに返されます。
これらのモードのいずれかに入るには、PQsendQuery
(またはその兄弟関数)の呼び出し直後にPQsetSingleRowMode
またはPQsetChunkedRowsMode
を呼び出します。
このモード選択は、現在実行中の問い合わせに対してのみ有効です。
その後、32.4の説明通りに、NULLを返すようになるまでPQgetResult
を繰り返し呼び出してください。
問い合わせが何らかの行を返す場合、PGRES_TUPLES_OK
ではなくPGRES_SINGLE_TUPLE
である点を除けば、通常の問い合わせ結果と同じように見える、個々のPGresult
オブジェクトを返します。
問い合わせが何行かの行を返すと、それらは1つ以上のPGresult
オブジェクトとして返されます。
これらは通常の問い合わせ結果と同じように見えますが、PGRES_SINGLE_TUPLE
がシングル行モードの場合はPGRES_TUPLES_OK
ではなく、チャンクモードの場合はPGRES_TUPLES_CHUNK
が付きます。
各PGRES_SINGLE_TUPLE
オブジェクトには1行の結果がありますが、PGRES_TUPLES_CHUNK
オブジェクトには少なくとも1行、チャンクあたり指定された行数以下の結果があります。
最後の行の後、またはクエリがゼロ行を返す場合は直ちに、ステータスPGRES_TUPLES_OK
を持つゼロ行オブジェクトが返されます。これは、これ以上行が到着しないというシグナルです。
(ただし、NULL を返すまでは、PQgetResult
を呼び出し続ける必要があることに注意してください。)
これらのPGresult
オブジェクトはすべて、問い合わせの通常のPGresult
オブジェクトと同じ行記述データ(列名、型など)を含みます。
各オブジェクトは通常通りPQclear
で解放する必要があります。
パイプラインモードを使用する場合、単一行モードまたはチャンクモードは、PQgetResult
でその問い合わせの結果を取得する前に、パイプラインの各問い合わせに対してアクティブにする必要があります。
詳細は32.5を参照してください。
PQsetSingleRowMode
#現在実行中の問い合わせについて単一行モードを選択します。
int PQsetSingleRowMode(PGconn *conn);
この関数はPQsendQuery
またはその系列の関数のいずれかの後即座に、PQconsumeInput
やPQgetResult
など接続に対する何らかの他の操作を行う前のみに呼び出すことができます。
正しい時点で呼び出された場合、この関数は現在の問い合わせに対して単一行モードを有効にし、1を返します。
この他の場合、モードは変更されず、関数はゼロを返します。
いずれの場合でも、現在の問い合わせが完了した後に通常モードに戻ります。
PQsetChunkedRowsMode
#現在実行中の問い合わせに対してチャンクモードを選択します。
int PQsetChunkedRowsMode(PGconn *conn, int chunkSize);
この関数はPQsetSingleRowMode
と似ていますが、必ずしも1行だけではなく、PGresult
ごとに最大chunkSize
行を取得する点が異なります。
この関数は、PQsendQuery
またはその兄弟関数の直後、およびPQconsumeInput
やPQgetResult
などの接続上の他の操作の直前にのみ呼び出すことができます。
正しいタイミングで呼び出されると、この関数は現在の問い合わせに対してチャンクモードをアクティブにし、1を返します。
それ以外の場合、モードは変更されず、この関数は0を返します。
いずれの場合も、現在の問い合わせが完了すると、モードは通常に戻ります。
問い合わせを処理している間、サーバはいくつか行を返した後にエラーになり、問い合わせがアボートする可能性があります。
通常のlibpqでは、こうした行を破棄しエラーのみを報告します。
しかし単一行モードあるいはチャンクモードでは、これらの行はすでにアプリケーションに返されています。
このためアプリケーションはPGRES_SINGLE_TUPLE
あるいはPGRES_TUPLES_CHUNK
状態のPGresult
オブジェクトをいくつか見た後にPGRES_FATAL_ERROR
オブジェクトを見るかもしれません。
適切な振る舞いのトランザクションのために、最終的に問い合わせが失敗した場合、アプリケーションはこれまで処理した行を破棄するまたは取り消すように設計しなければなりません。