31.9. COPYコマンド関連関数

COPY_IN状態の間、サーバにデータを送信します。

int PQputCopyData(PGconn *conn,
                  const char *buffer,
                  int nbytes);

指定したbufferにあるCOPYデータをnbytes長分、サーバに送信します。 データが送信された場合、この結果は1になります。 送信試行がブロックされたために送信できなかった場合はゼロになります。 （これは、接続が非ブロックモードの場合にのみ起こります。） エラーが発生した場合は-1になります。 （戻り値が-1の場合、詳細を取り出すためにはPQerrorMessageを使用してください。 戻り値がゼロの場合は書き込み準備が整うまで待ち、再実行してください。）

アプリケーションはCOPYデータストリームを使いやすい大きさのバッファに分けて読み込むことができます。 送信時の読み込みバッファの境界には意味的な重要性はありません。 データストリームの内容は、COPYコマンドで想定しているデータ書式に一致している必要があります。 詳細はCOPYを参照してください。

COPY_IN状態の間に、サーバにデータ終了指示を送信します。

int PQputCopyEnd(PGconn *conn,
                 const char *errormsg);

errormsgがNULLの場合は、COPY_IN操作の終了に成功しました。 errormsgがNULLでない場合は、COPYは強制的に失敗されました。 errormsgが指し示す文字列はエラーメッセージとして使用されます。 （しかし、このエラーメッセージが正しくサーバから返ったものであるとは仮定すべきではありません。 サーバは既に別の原因でCOPYに失敗していた可能性があります。 また、この強制的な失敗は3.0より前のプロトコルの接続を使用している場合は動作しません。）

終端データが送信された場合は結果は1になります。 送信試行がブロックされたため送信できなかった場合はゼロになります。 （これは、接続が非ブロックモードの場合にのみ起こります。） エラーが発生した場合は-1になります。 （戻り値が-1の場合、詳細を取り出すためにはPQerrorMessageを使用してください。 戻り値がゼロの場合は書き込み準備が整うまで待ち、再実行してください。）

PQputCopyEndの呼び出しに成功した後、PQgetResultを呼び出してCOPYコマンドの最終的な結果状態を取り出してください。 通常の方法でこの結果が使用できるようになるまで待機しても構いません。 そして、通常の操作に戻ってください。

COPY_OUT状態時にサーバからデータを受信します。

int PQgetCopyData(PGconn *conn,
                  char **buffer,
                  int async);

COPY期間中、サーバから別の行データの入手を試みます。 常に1度に1つの行データが返されます。 部分的な行のみが利用可能な場合は返されません。 行データの取得に成功することは、そのデータを保持するためのメモリチャンクの割り当てを意味します。 bufferパラメータは非NULLでなければなりません。 *bufferは割り当てられたメモリへのポインタに、バッファが返されなかった場合はNULLに設定されます。 非NULLの結果バッファは、不要になったらPQfreememを使用して解放しなければなりません。

行の取り込みに成功した時、戻り値は行内のデータのバイト数になります。 (これは常に0より大きくなります。) 返された文字列は常にヌル終端ですが、おそらくテキストCOPYでのみ有用になるでしょう。 ゼロという結果は、COPYが進行中で、行がまだ利用できない状態であることを示します。 (asyncが真の場合にのみ発生することがあります。) -1という結果は、COPYが完了したことを示します。 -2という結果はエラーが発生したことを示します。 (その理由についてはPQerrorMessageを参照してください。)

asyncが真(非0)の場合、PQgetCopyDataは入力待ちのためのブロックを行いません。 COPY実行中で完全な行を取り出せない場合PQgetCopyDataは0を返します。 (この場合、再試行の前に読み込み準備が整うまで待機してください。 PQconsumeInputを呼び出したかどうかは関係ありません。) asyncが偽(0)の場合、PQgetCopyDataはデータが利用できるようになるまで、もしくは、操作が完了するまでブロックします。

PQgetCopyDataが-1を返した後、PQgetResultを呼び出して、COPYコマンドの最終結果状態を取り出してください。 通常の方法で結果が利用できるようになるまで待機しても構いません。 そして、通常の操作に戻ってください。

改行で終端する文字列（サーバから送信されたもの）を長さlengthのバッファ用文字列に読み込みます。

int PQgetline(PGconn *conn,
              char *buffer,
              int length);

この関数はバッファにlength-1個までの文字をコピーし、終端の改行を1バイトのゼロに置き換えます。 PQgetlineは、入力の終端ではEOFを、行全体が読み込まれれば0を返します。 そしてまだ終端の改行が読み込まれていないうちにバッファがいっぱいになってしまった場合は1を返します。

アプリケーションは新しく読み込んだ行が、\.という2文字であるかどうか確認しなければいけません。 この2文字は、COPYコマンドの結果をサーバが送信し終えたことを示すものです。 アプリケーションには、仮にlength-1文字より長い行を受け取るようなことがあっても、間違いなく\.行を認識するような配慮が必要です （また例えば長いデータの行の終端を、最終行と取り違えないようにもしてください）。

COPYデータ行（サーバから送信されたもの）を、ブロッキングなしでバッファに読み込みます。

int PQgetlineAsync(PGconn *conn,
                   char *buffer,
                   int bufsize);

PQgetlineと似ていますが、COPYのデータを非同期的に、つまりブロッキングなしで読み出さなければならないアプリケーションで使用することができます。 COPYコマンドを発行し、そしてPGRES_COPY_OUT応答を受け取ったら、アプリケーションはデータ終了の合図を受け取るまでPQconsumeInputとPQgetlineAsyncを呼び出します。

PQgetlineと違い、この関数はデータ終了の検出に対して責任を持ちます。

PQgetlineAsyncの個々の呼び出しでは、libpqの入力バッファ内で完全な行データが利用できる場合にデータを返します。 さもなければ、行の残りが届くまでデータは返されません。 この関数は、コピーデータの終端を示す符号を認識すると-1を、また何もデータがなければ0を、そしてデータを返す場合はそのバイト数を正の値で返します。 もし-1が返されたら、呼び出し側は次にPQendcopyを呼び出さなければいけません。 それから通常の処理に戻ります。

返されるデータは行データの境界を越えて拡張されることはありません。 可能であれば行全体を一度に返します。 しかし呼び出し側が準備したバッファが少なすぎ、サーバから送られてくる行を保持しておくことができない場合には、分割された行データを返します。 テキストデータでは、これは最後の1バイトが\nかどうかを確認すれば検出できます。 （バイナリCOPYの場合に同様の検出を行うためには、実際にCOPYデータの書式を解析しなければなりません。） なお、返される文字列はヌル終端ではありません。 （ヌル終端を後から付け加えるのであれば、実際に確保するバッファサイズ-1をbufsizeとして渡すようにしてください。）

サーバにヌル終端の文字列を送信します。 問題なければ0を返します。 文字列の送信ができなかった場合はEOFを返します。

int PQputline(PGconn *conn,
              const char *string);

PQputlineの呼び出しによって送信されるCOPYデータストリームは、PQgetlineAsyncで返される書式と同じ書式を持ちます。 ただし、アプリケーションは、PQputline毎に正確に1つのデータ行を送信するように強制されていません。 呼び出し毎に行の一部や複数の行を送信しても問題ありません。

ヌル終端ではない文字列をサーバに送信します。 問題なければ0を返します。 文字列の送信ができなかった場合はEOFを返します。

int PQputnbytes(PGconn *conn,
                const char *buffer,
                int nbytes);

これはまさにPQputlineと同様です。 ただし、直接送信バイト数を指定するため、ヌル終端である必要がありません。 バイナリデータを送信する時はこのプロシージャを使用してください。

サーバと同期します。

int PQendcopy(PGconn *conn);

この関数はサーバがコピーを完了するのを待ちます。 この関数は、PQputlineを使ったサーバへの文字列送信が完了した時点、あるいはPGgetlineを使ったサーバからの文字列受信が完了した時点のいずれでも呼び出さなければなりません。 これを発行しないと、サーバはクライアントとの"同期がずれた"状態になってしまいます。 この関数から戻った時点で、サーバは次のSQLコマンドを受ける準備が整います。 正常に終了した場合、返り値は0です。 さもなくば、非ゼロです。 （戻り値が非ゼロの場合、PQerrorMessageを使用して詳細を取り出してください。）

PQgetResultを使う場合、アプリケーションはPQgetlineを繰り返し呼び出してPGRES_COPY_OUTに応答し、終端行を見つけたら続いてPQendcopyを呼び出さなければなりません。 それから、PQgetResultがヌルポインタを返すまで、PQgetResultのループに戻らなければなりません。 同じように PGRES_COPY_INは連続したPQputlineで処理し、それからPQendcopyで締めくくった後にPQgetResultのループに戻ります。 このようにすることで、一連のSQLコマンド群に含めたCOPYコマンドを確実に、また正しく実行できるはずです。

比較的古いアプリケーションでは、COPYをPQexecで実行し、PQendcopyの実行でトランザクションは完了する、と想定していることがよくあります。 これはコマンド文字列中のSQLがCOPYだけであった時にのみ正しく動作します。