begriffs open source - ai-pg/blob - full-docs/src/sgml/html/libpq-copy.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>32.10. Functions Associated with the COPY Command</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-notify.html" title="32.9. Asynchronous Notification" /><link rel="next" href="libpq-control.html" title="32.11. Control Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">32.10. Functions Associated with the <code class="command">COPY</code> Command</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-notify.html" title="32.9. Asynchronous Notification">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 32. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 32. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-control.html" title="32.11. Control Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-COPY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">32.10. Functions Associated with the <code class="command">COPY</code> Command <a href="#LIBPQ-COPY" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="libpq-copy.html#LIBPQ-COPY-SEND">32.10.1. Functions for Sending <code class="command">COPY</code> Data</a></span></dt><dt><span class="sect2"><a href="libpq-copy.html#LIBPQ-COPY-RECEIVE">32.10.2. Functions for Receiving <code class="command">COPY</code> Data</a></span></dt><dt><span class="sect2"><a href="libpq-copy.html#LIBPQ-COPY-DEPRECATED">32.10.3. Obsolete Functions for <code class="command">COPY</code></a></span></dt></dl></div><a id="id-1.7.3.17.2" class="indexterm"></a><p>
   3    The <code class="command">COPY</code> command in
   4    <span class="productname">PostgreSQL</span> has options to read from or write
   5    to the network connection used by <span class="application">libpq</span>.
   6    The functions described in this section allow applications to take
   7    advantage of this capability by supplying or consuming copied data.
   8   </p><p>
   9    The overall process is that the application first issues the SQL
  10    <code class="command">COPY</code> command via <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> or one
  11    of the equivalent functions.  The response to this (if there is no
  12    error in the command) will be a <code class="structname">PGresult</code> object bearing
  13    a status code of <code class="literal">PGRES_COPY_OUT</code> or
  14    <code class="literal">PGRES_COPY_IN</code> (depending on the specified copy
  15    direction).  The application should then use the functions of this
  16    section to receive or transmit data rows.  When the data transfer is
  17    complete, another <code class="structname">PGresult</code> object is returned to indicate
  18    success or failure of the transfer.  Its status will be
  19    <code class="literal">PGRES_COMMAND_OK</code> for success or
  20    <code class="literal">PGRES_FATAL_ERROR</code> if some problem was encountered.
  21    At this point further SQL commands can be issued via
  22    <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a>.  (It is not possible to execute other SQL
  23    commands using the same connection while the <code class="command">COPY</code>
  24    operation is in progress.)
  25   </p><p>
  26    If a <code class="command">COPY</code> command is issued via
  27    <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> in a string that could contain additional
  28    commands, the application must continue fetching results via
  29    <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> after completing the <code class="command">COPY</code>
  30    sequence.  Only when <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> returns
  31    <code class="symbol">NULL</code> is it certain that the <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a>
  32    command string is done and it is safe to issue more commands.
  33   </p><p>
  34    The functions of this section should be executed only after obtaining
  35    a result status of <code class="literal">PGRES_COPY_OUT</code> or
  36    <code class="literal">PGRES_COPY_IN</code> from <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> or
  37    <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>.
  38   </p><p>
  39    A <code class="structname">PGresult</code> object bearing one of these status values
  40    carries some additional data about the <code class="command">COPY</code> operation
  41    that is starting.  This additional data is available using functions
  42    that are also used in connection with query results:
  43
  44    </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQNFIELDS-1"><span class="term"><code class="function">PQnfields</code><a id="id-1.7.3.17.7.3.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQNFIELDS-1" class="id_link">#</a></dt><dd><p>
  45        Returns the number of columns (fields) to be copied.
  46       </p></dd><dt id="LIBPQ-PQBINARYTUPLES-1"><span class="term"><code class="function">PQbinaryTuples</code><a id="id-1.7.3.17.7.3.2.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQBINARYTUPLES-1" class="id_link">#</a></dt><dd><p>
  47        0 indicates the overall copy format is textual (rows separated by
  48        newlines, columns separated by separator characters, etc.).  1
  49        indicates the overall copy format is binary.  See <a class="xref" href="sql-copy.html" title="COPY"><span class="refentrytitle">COPY</span></a> for more information.
  50       </p></dd><dt id="LIBPQ-PQFFORMAT-1"><span class="term"><code class="function">PQfformat</code><a id="id-1.7.3.17.7.3.3.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQFFORMAT-1" class="id_link">#</a></dt><dd><p>
  51        Returns the format code (0 for text, 1 for binary) associated with
  52        each column of the copy operation.  The per-column format codes
  53        will always be zero when the overall copy format is textual, but
  54        the binary format can support both text and binary columns.
  55        (However, as of the current implementation of <code class="command">COPY</code>,
  56        only binary columns appear in a binary copy; so the per-column
  57        formats always match the overall format at present.)
  58       </p></dd></dl></div><p>
  59   </p><div class="sect2" id="LIBPQ-COPY-SEND"><div class="titlepage"><div><div><h3 class="title">32.10.1. Functions for Sending <code class="command">COPY</code> Data <a href="#LIBPQ-COPY-SEND" class="id_link">#</a></h3></div></div></div><p>
  60     These functions are used to send data during <code class="literal">COPY FROM
  61     STDIN</code>.  They will fail if called when the connection is not in
  62     <code class="literal">COPY_IN</code> state.
  63    </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQPUTCOPYDATA"><span class="term"><code class="function">PQputCopyData</code><a id="id-1.7.3.17.8.3.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQPUTCOPYDATA" class="id_link">#</a></dt><dd><p>
  64        Sends data to the server during <code class="literal">COPY_IN</code> state.
  65 </p><pre class="synopsis">
  66 int PQputCopyData(PGconn *conn,
  67                   const char *buffer,
  68                   int nbytes);
  69 </pre><p>
  70       </p><p>
  71        Transmits the <code class="command">COPY</code> data in the specified
  72        <em class="parameter"><code>buffer</code></em>, of length <em class="parameter"><code>nbytes</code></em>, to the server.
  73        The result is 1 if the data was queued, zero if it was not queued
  74        because of full buffers (this will only happen in nonblocking mode),
  75        or -1 if an error occurred.
  76        (Use <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE">
  77       <code class="function">PQerrorMessage</code>
  78
  79      </a> to retrieve details if
  80        the return value is -1.  If the value is zero, wait for write-ready
  81        and try again.)
  82       </p><p>
  83        The application can divide the <code class="command">COPY</code> data stream
  84        into buffer loads of any convenient size.  Buffer-load boundaries
  85        have no semantic significance when sending.  The contents of the
  86        data stream must match the data format expected by the
  87        <code class="command">COPY</code> command; see <a class="xref" href="sql-copy.html" title="COPY"><span class="refentrytitle">COPY</span></a> for details.
  88       </p></dd><dt id="LIBPQ-PQPUTCOPYEND"><span class="term"><code class="function">PQputCopyEnd</code><a id="id-1.7.3.17.8.3.2.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQPUTCOPYEND" class="id_link">#</a></dt><dd><p>
  89        Sends end-of-data indication to the server during <code class="literal">COPY_IN</code> state.
  90 </p><pre class="synopsis">
  91 int PQputCopyEnd(PGconn *conn,
  92                  const char *errormsg);
  93 </pre><p>
  94       </p><p>
  95        Ends the <code class="literal">COPY_IN</code> operation successfully if
  96        <em class="parameter"><code>errormsg</code></em> is <code class="symbol">NULL</code>.  If
  97        <em class="parameter"><code>errormsg</code></em> is not <code class="symbol">NULL</code> then the
  98        <code class="command">COPY</code> is forced to fail, with the string pointed to by
  99        <em class="parameter"><code>errormsg</code></em> used as the error message.  (One should not
 100        assume that this exact error message will come back from the server,
 101        however, as the server might have already failed the
 102        <code class="command">COPY</code> for its own reasons.)
 103       </p><p>
 104        The result is 1 if the termination message was sent; or in
 105        nonblocking mode, this may only indicate that the termination
 106        message was successfully queued.  (In nonblocking mode, to be
 107        certain that the data has been sent, you should next wait for
 108        write-ready and call <a class="xref" href="libpq-async.html#LIBPQ-PQFLUSH"><code class="function">PQflush</code></a>, repeating until it
 109        returns zero.)  Zero indicates that the function could not queue
 110        the termination message because of full buffers; this will only
 111        happen in nonblocking mode.  (In this case, wait for
 112        write-ready and try the <a class="xref" href="libpq-copy.html#LIBPQ-PQPUTCOPYEND"><code class="function">PQputCopyEnd</code></a> call
 113        again.)  If a hard error occurs, -1 is returned; you can use
 114        <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE">
 115       <code class="function">PQerrorMessage</code>
 116
 117      </a> to retrieve details.
 118       </p><p>
 119        After successfully calling <a class="xref" href="libpq-copy.html#LIBPQ-PQPUTCOPYEND"><code class="function">PQputCopyEnd</code></a>, call
 120        <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> to obtain the final result status of the
 121        <code class="command">COPY</code> command.  One can wait for this result to be
 122        available in the usual way.  Then return to normal operation.
 123       </p></dd></dl></div></div><div class="sect2" id="LIBPQ-COPY-RECEIVE"><div class="titlepage"><div><div><h3 class="title">32.10.2. Functions for Receiving <code class="command">COPY</code> Data <a href="#LIBPQ-COPY-RECEIVE" class="id_link">#</a></h3></div></div></div><p>
 124     These functions are used to receive data during <code class="literal">COPY TO
 125     STDOUT</code>.  They will fail if called when the connection is not in
 126     <code class="literal">COPY_OUT</code> state.
 127    </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQGETCOPYDATA"><span class="term"><code class="function">PQgetCopyData</code><a id="id-1.7.3.17.9.3.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQGETCOPYDATA" class="id_link">#</a></dt><dd><p>
 128        Receives data from the server during <code class="literal">COPY_OUT</code> state.
 129 </p><pre class="synopsis">
 130 int PQgetCopyData(PGconn *conn,
 131                   char **buffer,
 132                   int async);
 133 </pre><p>
 134       </p><p>
 135        Attempts to obtain another row of data from the server during a
 136        <code class="command">COPY</code>.  Data is always returned one data row at
 137        a time; if only a partial row is available, it is not returned.
 138        Successful return of a data row involves allocating a chunk of
 139        memory to hold the data.  The <em class="parameter"><code>buffer</code></em> parameter must
 140        be non-<code class="symbol">NULL</code>.  <em class="parameter"><code>*buffer</code></em> is set to
 141        point to the allocated memory, or to <code class="symbol">NULL</code> in cases
 142        where no buffer is returned.  A non-<code class="symbol">NULL</code> result
 143        buffer should be freed using <a class="xref" href="libpq-misc.html#LIBPQ-PQFREEMEM"><code class="function">PQfreemem</code></a> when no longer
 144        needed.
 145       </p><p>
 146        When a row is successfully returned, the return value is the number
 147        of data bytes in the row (this will always be greater than zero).
 148        The returned string is always null-terminated, though this is
 149        probably only useful for textual <code class="command">COPY</code>.  A result
 150        of zero indicates that the <code class="command">COPY</code> is still in
 151        progress, but no row is yet available (this is only possible when
 152        <em class="parameter"><code>async</code></em> is true).  A result of -1 indicates that the
 153        <code class="command">COPY</code> is done.  A result of -2 indicates that an
 154        error occurred (consult <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE">
 155       <code class="function">PQerrorMessage</code>
 156
 157      </a> for the reason).
 158       </p><p>
 159        When <em class="parameter"><code>async</code></em> is true (not zero),
 160        <a class="xref" href="libpq-copy.html#LIBPQ-PQGETCOPYDATA"><code class="function">PQgetCopyData</code></a> will not block waiting for input; it
 161        will return zero if the <code class="command">COPY</code> is still in progress
 162        but no complete row is available.  (In this case wait for read-ready
 163        and then call <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>
 164      </a> before calling
 165        <a class="xref" href="libpq-copy.html#LIBPQ-PQGETCOPYDATA"><code class="function">PQgetCopyData</code></a> again.)  When <em class="parameter"><code>async</code></em> is
 166        false (zero), <a class="xref" href="libpq-copy.html#LIBPQ-PQGETCOPYDATA"><code class="function">PQgetCopyData</code></a> will block until data is
 167        available or the operation completes.
 168       </p><p>
 169        After <a class="xref" href="libpq-copy.html#LIBPQ-PQGETCOPYDATA"><code class="function">PQgetCopyData</code></a> returns -1, call
 170        <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> to obtain the final result status of the
 171        <code class="command">COPY</code> command.  One can wait for this result to be
 172        available in the usual way.  Then return to normal operation.
 173       </p></dd></dl></div></div><div class="sect2" id="LIBPQ-COPY-DEPRECATED"><div class="titlepage"><div><div><h3 class="title">32.10.3. Obsolete Functions for <code class="command">COPY</code> <a href="#LIBPQ-COPY-DEPRECATED" class="id_link">#</a></h3></div></div></div><p>
 174     These functions represent older methods of handling <code class="command">COPY</code>.
 175     Although they still work, they are deprecated due to poor error handling,
 176     inconvenient methods of detecting end-of-data, and lack of support for binary
 177     or nonblocking transfers.
 178    </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQGETLINE"><span class="term"><code class="function">PQgetline</code><a id="id-1.7.3.17.10.3.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQGETLINE" class="id_link">#</a></dt><dd><p>
 179        Reads  a  newline-terminated  line  of  characters (transmitted
 180        by the server) into a buffer string of size <em class="parameter"><code>length</code></em>.
 181 </p><pre class="synopsis">
 182 int PQgetline(PGconn *conn,
 183               char *buffer,
 184               int length);
 185 </pre><p>
 186       </p><p>
 187        This function copies up to <em class="parameter"><code>length</code></em>-1 characters into
 188        the buffer and converts the terminating newline into a zero byte.
 189        <a class="xref" href="libpq-copy.html#LIBPQ-PQGETLINE"><code class="function">PQgetline</code></a> returns <code class="symbol">EOF</code> at the
 190        end of input, 0 if the entire line has been read, and 1 if the
 191        buffer is full but the terminating newline has not yet been read.
 192        </p><p>
 193        Note that the application must check to see if a new line consists
 194        of  the  two characters  <code class="literal">\.</code>, which  indicates
 195        that the server has finished sending the results  of  the
 196        <code class="command">COPY</code> command.  If  the  application might receive
 197        lines that are more than <em class="parameter"><code>length</code></em>-1  characters  long,
 198        care is needed to be sure it recognizes the <code class="literal">\.</code>
 199        line correctly (and does not, for example, mistake the end of a
 200        long data line for a terminator line).
 201       </p></dd><dt id="LIBPQ-PQGETLINEASYNC"><span class="term"><code class="function">PQgetlineAsync</code><a id="id-1.7.3.17.10.3.2.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQGETLINEASYNC" class="id_link">#</a></dt><dd><p>
 202        Reads a row of <code class="command">COPY</code> data (transmitted  by the
 203        server) into a buffer without blocking.
 204 </p><pre class="synopsis">
 205 int PQgetlineAsync(PGconn *conn,
 206                    char *buffer,
 207                    int bufsize);
 208 </pre><p>
 209       </p><p>
 210        This function is similar to <a class="xref" href="libpq-copy.html#LIBPQ-PQGETLINE"><code class="function">PQgetline</code></a>, but it can be used
 211        by applications
 212        that must read <code class="command">COPY</code> data asynchronously, that is, without blocking.
 213        Having issued the <code class="command">COPY</code> command and gotten a <code class="literal">PGRES_COPY_OUT</code>
 214        response, the
 215        application should call <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>
 216      </a> and
 217        <a class="xref" href="libpq-copy.html#LIBPQ-PQGETLINEASYNC"><code class="function">PQgetlineAsync</code></a> until the
 218        end-of-data signal is detected.
 219        </p><p>
 220        Unlike <a class="xref" href="libpq-copy.html#LIBPQ-PQGETLINE"><code class="function">PQgetline</code></a>, this function takes
 221        responsibility for detecting end-of-data.
 222       </p><p>
 223        On each call, <a class="xref" href="libpq-copy.html#LIBPQ-PQGETLINEASYNC"><code class="function">PQgetlineAsync</code></a> will return data if a
 224        complete data row is available in <span class="application">libpq</span>'s input buffer.
 225        Otherwise, no data is returned until the rest of the row arrives.
 226        The function returns -1 if the end-of-copy-data marker has been recognized,
 227        or 0 if no data is available, or a positive number giving the number of
 228        bytes of data returned.  If -1 is returned, the caller must next call
 229        <a class="xref" href="libpq-copy.html#LIBPQ-PQENDCOPY"><code class="function">PQendcopy</code></a>, and then return to normal processing.
 230       </p><p>
 231        The data returned will not extend beyond a data-row boundary.  If possible
 232        a whole row will be returned at one time.  But if the buffer offered by
 233        the caller is too small to hold a row sent by the server, then a partial
 234        data row will be returned.  With textual data this can be detected by testing
 235        whether the last returned byte is <code class="literal">\n</code> or not.  (In a binary
 236        <code class="command">COPY</code>, actual parsing of the <code class="command">COPY</code> data format will be needed to make the
 237        equivalent determination.)
 238        The returned string is not null-terminated.  (If you want to add a
 239        terminating null, be sure to pass a <em class="parameter"><code>bufsize</code></em> one smaller
 240        than the room actually available.)
 241       </p></dd><dt id="LIBPQ-PQPUTLINE"><span class="term"><code class="function">PQputline</code><a id="id-1.7.3.17.10.3.3.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQPUTLINE" class="id_link">#</a></dt><dd><p>
 242        Sends  a  null-terminated  string  to  the server.  Returns 0 if
 243        OK and <code class="symbol">EOF</code> if unable to send the string.
 244 </p><pre class="synopsis">
 245 int PQputline(PGconn *conn,
 246               const char *string);
 247 </pre><p>
 248       </p><p>
 249        The <code class="command">COPY</code> data stream sent by a series of calls
 250        to <a class="xref" href="libpq-copy.html#LIBPQ-PQPUTLINE"><code class="function">PQputline</code></a> has the same format as that
 251        returned by <a class="xref" href="libpq-copy.html#LIBPQ-PQGETLINEASYNC"><code class="function">PQgetlineAsync</code></a>, except that
 252        applications are not obliged to send exactly one data row per
 253        <a class="xref" href="libpq-copy.html#LIBPQ-PQPUTLINE"><code class="function">PQputline</code></a> call; it is okay to send a partial
 254        line or multiple lines per call.
 255       </p><div class="note"><h3 class="title">Note</h3><p>
 256         Before <span class="productname">PostgreSQL</span> protocol 3.0, it was necessary
 257         for the application to explicitly send the two characters
 258         <code class="literal">\.</code> as a final line to indicate to the server that it had
 259         finished sending <code class="command">COPY</code> data.  While this still works, it is deprecated and the
 260         special meaning of <code class="literal">\.</code> can be expected to be removed in a
 261         future release.  (It already will misbehave in <code class="literal">CSV</code>
 262         mode.)  It is sufficient to call <a class="xref" href="libpq-copy.html#LIBPQ-PQENDCOPY"><code class="function">PQendcopy</code></a>
 263         after having sent the actual data.
 264        </p></div></dd><dt id="LIBPQ-PQPUTNBYTES"><span class="term"><code class="function">PQputnbytes</code><a id="id-1.7.3.17.10.3.4.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQPUTNBYTES" class="id_link">#</a></dt><dd><p>
 265        Sends  a  non-null-terminated  string  to  the server.  Returns
 266        0 if OK and <code class="symbol">EOF</code> if unable to send the string.
 267 </p><pre class="synopsis">
 268 int PQputnbytes(PGconn *conn,
 269                 const char *buffer,
 270                 int nbytes);
 271 </pre><p>
 272       </p><p>
 273        This is exactly like <a class="xref" href="libpq-copy.html#LIBPQ-PQPUTLINE"><code class="function">PQputline</code></a>, except that the data
 274        buffer need not be null-terminated since the number of bytes to send is
 275        specified directly.  Use this procedure when sending binary data.
 276       </p></dd><dt id="LIBPQ-PQENDCOPY"><span class="term"><code class="function">PQendcopy</code><a id="id-1.7.3.17.10.3.5.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQENDCOPY" class="id_link">#</a></dt><dd><p>
 277        Synchronizes with the server.
 278 </p><pre class="synopsis">
 279 int PQendcopy(PGconn *conn);
 280 </pre><p>
 281        This function waits until the  server  has  finished  the copying.
 282        It should either be issued when the  last  string  has  been sent
 283        to  the  server using <a class="xref" href="libpq-copy.html#LIBPQ-PQPUTLINE"><code class="function">PQputline</code></a> or when the
 284        last string has been  received  from  the  server using
 285        <code class="function">PQgetline</code>.  It must be issued or the server
 286        will get <span class="quote">“<span class="quote">out of sync</span>”</span> with  the client.   Upon return
 287        from this function, the server is ready to receive the next SQL
 288        command.  The return value is 0  on  successful  completion,
 289        nonzero otherwise.  (Use <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE">
 290       <code class="function">PQerrorMessage</code>
 291
 292      </a> to
 293        retrieve details if the return value is nonzero.)
 294       </p><p>
 295        When using <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>, the application should
 296        respond to a <code class="literal">PGRES_COPY_OUT</code> result by executing
 297        <a class="xref" href="libpq-copy.html#LIBPQ-PQGETLINE"><code class="function">PQgetline</code></a> repeatedly, followed by
 298        <a class="xref" href="libpq-copy.html#LIBPQ-PQENDCOPY"><code class="function">PQendcopy</code></a> after the terminator line is seen.
 299        It should then return to the <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> loop
 300        until <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> returns a null pointer.
 301        Similarly a <code class="literal">PGRES_COPY_IN</code> result is processed
 302        by a series of <a class="xref" href="libpq-copy.html#LIBPQ-PQPUTLINE"><code class="function">PQputline</code></a> calls followed by
 303        <a class="xref" href="libpq-copy.html#LIBPQ-PQENDCOPY"><code class="function">PQendcopy</code></a>, then return to the
 304        <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> loop.  This arrangement will
 305        ensure that a <code class="command">COPY</code> command embedded in a series
 306        of <acronym class="acronym">SQL</acronym> commands will be executed correctly.
 307       </p><p>
 308        Older applications are likely to submit a <code class="command">COPY</code>
 309        via <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> and assume that the transaction
 310        is done after <a class="xref" href="libpq-copy.html#LIBPQ-PQENDCOPY"><code class="function">PQendcopy</code></a>.  This will work
 311        correctly only if the <code class="command">COPY</code> is the only
 312        <acronym class="acronym">SQL</acronym> command in the command string.
 313       </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-notify.html" title="32.9. Asynchronous Notification">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 32. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-control.html" title="32.11. Control Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">32.9. Asynchronous Notification </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 32.11. Control Functions</td></tr></table></div></body></html>