Another round of protocol changes. Backend-to-frontend messages now all

have length words.  COPY OUT reimplemented per new protocol: it doesn't
need \. anymore, thank goodness.  COPY BINARY to/from frontend works,
at least as far as the backend is concerned --- libpq's PQgetline API
is not up to snuff, and will have to be replaced with something that is
null-safe.  libpq uses message length words for performance improvement
(no cycles wasted rescanning long messages), but not yet for error
recovery.

2 files changed, 76 insertions, 36 deletions

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 7a7bb48ff39..5ba7e6468c3 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.119 2003/04/19 00:02:29 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.120 2003/04/22 00:08:06 tgl Exp $
 -->
 
  <chapter id="libpq">
@@ -175,7 +175,8 @@ PGconn *PQconnectdb(const char *conninfo);
      <term><literal>connect_timeout</literal></term>
      <listitem>
      <para>
-      Time space in seconds given to connection function. Zero or not set means infinite.
+      Maximum wait for connection, in seconds (write as a decimal integer
+      string). Zero or not specified means infinite.
      </para>
      </listitem>
     </varlistentry>
@@ -184,7 +185,7 @@ PGconn *PQconnectdb(const char *conninfo);
      <term><literal>options</literal></term>
      <listitem>
       <para>
-       Configuration options to be sent to the server.
+       Command-line options to be sent to the server.
       </para>
      </listitem>
     </varlistentry>
@@ -252,8 +253,9 @@ PGconn *PQsetdbLogin(const char *pghost,
 </para>
 
 <para>
-   This is the predecessor of <function>PQconnectdb</function> with a fixed number
-   of parameters but the same functionality.   
+   This is the predecessor of <function>PQconnectdb</function> with a fixed
+   number of parameters.  It has the same functionality except that the
+   missing parameters cannot be specified in the call.
    </para>
   </listitem>
  </varlistentry>
@@ -274,8 +276,8 @@ PGconn *PQsetdb(char *pghost,
 
 <para>
    This is a macro that calls <function>PQsetdbLogin</function> with null pointers
-   for the <parameter>login</> and <parameter>pwd</> parameters.  It is provided primarily
-   for backward compatibility with old programs.
+   for the <parameter>login</> and <parameter>pwd</> parameters.  It is provided
+   for backward compatibility with very old programs.
    </para>
   </listitem>
  </varlistentry>
@@ -454,7 +456,7 @@ switch(PQstatus(conn))
   </para>
 
   <para>
-   Finally, these functions leave the socket in a nonblocking state as if 
+   Finally, these functions leave the connection in a nonblocking state as if 
    <function>PQsetnonblocking</function> had been called.
   </para>
   </listitem>
@@ -486,8 +488,6 @@ typedef struct
 </para>
 
 <para>
-   converts an escaped string representation of binary data into binary
-   data --- the reverse of <function>PQescapeBytea</function>.
    Returns a connection options array.  This may
    be used to determine all possible <function>PQconnectdb</function> options and their
    current default values.  The return value points to an array of
@@ -683,7 +683,7 @@ char *PQtty(const PGconn *conn);
 <term><function>PQoptions</function></term>
 <listitem>
 <para>
-       Returns the configuration options passed in the connection request.
+       Returns the command-line options passed in the connection request.
 <synopsis>
 char *PQoptions(const PGconn *conn);
 </synopsis>
@@ -2047,13 +2047,13 @@ contains example functions that correctly handle the <command>COPY</command> pro
 <term><function>PQgetlineAsync</function></term>
 <listitem>
 <para>
-          Reads  a  newline-terminated  line  of  characters
+          Reads a row of COPY data
           (transmitted  by the server) into a buffer
           without blocking.
 <synopsis>
 int PQgetlineAsync(PGconn *conn,
                    char *buffer,
-                   int length);
+                   int bufsize);
 </synopsis>
 </para>
 
@@ -2070,24 +2070,27 @@ end-of-data signal is detected.
 <para>
 Unlike <function>PQgetline</function>, this function takes
 responsibility for detecting end-of-data.
-On each call, <function>PQgetlineAsync</function> will return data if a complete newline-
-terminated data line is available in <application>libpq</>'s input buffer, or if the
-incoming data line is too long to fit in the buffer offered by the caller.
-Otherwise, no data is returned until the rest of the line arrives.
+</para>
+<para>
+On each call, <function>PQgetlineAsync</function> will return data if a
+complete data row is available in <application>libpq</>'s input buffer.
+Otherwise, no data is returned until the rest of the row arrives.
 The function returns -1 if the end-of-copy-data marker has been recognized,
 or 0 if no data is available, or a positive number giving the number of
 bytes of data returned.  If -1 is returned, the caller must next call
 <function>PQendcopy</function>, and then return to normal processing.
 </para>
 <para>
-The data returned will not extend beyond a newline character.  If possible
-a whole line will be returned at one time.  But if the buffer offered by
-the caller is too small to hold a line sent by the server, then a partial
-data line will be returned.  This can be detected by testing whether the
-last returned byte is <literal>\n</literal> or not.
+The data returned will not extend beyond a data-row boundary.  If possible
+a whole row will be returned at one time.  But if the buffer offered by
+the caller is too small to hold a row sent by the server, then a partial
+data row will be returned.  With textual data this can be detected by testing
+whether the last returned byte is <literal>\n</literal> or not.  (In a binary
+COPY, actual parsing of the COPY data format will be needed to make the
+equivalent determination.)
 The returned string is not null-terminated.  (If you want to add a
-terminating null, be sure to pass a <parameter>length</parameter> one smaller than the room
-actually available.)
+terminating null, be sure to pass a <parameter>bufsize</parameter> one smaller
+than the room actually available.)
 </para>
 </listitem>
 </varlistentry>
@@ -2105,10 +2108,24 @@ int PQputline(PGconn *conn,
 </para>
 
 <para>
-Note the application must explicitly  send  the  two
-characters  <literal>\.</literal> on a final line  to indicate to
-the server that it has finished sending its data.
+The COPY datastream sent by a series of calls to
+<function>PQputline</function> has the same format as that returned by
+<function>PQgetlineAsync</function>, except that applications are not
+obliged to send exactly one data row per <function>PQputline</function>
+call; it is okay to send a partial line or multiple lines per call.
 </para>
+
+<note>
+<para>
+Before <productname>PostgreSQL</productname> 7.4, it was necessary for the
+application to explicitly send the two characters <literal>\.</literal> as a
+final line to indicate to the server that it had finished sending COPY data.
+While this still works, it is deprecated and the special meaning of
+<literal>\.</literal> can be expected to be removed in a future release.
+It is sufficient to call <function>PQendcopy</function> after having sent the
+actual data.
+</para>
+</note>
 </listitem>
 </varlistentry>
 
@@ -2126,9 +2143,9 @@ int PQputnbytes(PGconn *conn,
 </para>
 
 <para>
-This is exactly like <function>PQputline</function>, except that the data buffer need
-not be null-terminated since the number of bytes to send is
-specified directly.
+This is exactly like <function>PQputline</function>, except that the data
+buffer need not be null-terminated since the number of bytes to send is
+specified directly.  Use this procedure when sending binary data.
 </para>
 </listitem>
 </varlistentry>
@@ -2147,11 +2164,12 @@ int PQendcopy(PGconn *conn);
  sent  to  the  server using <function>PQputline</function> or when the
  last string has been  received  from  the  server
  using <function>PGgetline</function>.  It must be issued or the server
- may get <quote>out of sync</quote> with  the client.   Upon
+ will get <quote>out of sync</quote> with  the client.   Upon
  return from this function, the server is ready to
  receive the next SQL command.
  The return value is 0  on  successful  completion,
- nonzero otherwise.
+ nonzero otherwise.  (Use <function>PQerrorMessage</function> to retrieve
+ details if the return value is nonzero.)
 </para>
 
 <para>
@@ -2187,7 +2205,6 @@ PQexec(conn, "COPY foo FROM STDIN;");
 PQputline(conn, "3\thello world\t4.5\n");
 PQputline(conn, "4\tgoodbye world\t7.11\n");
 ...
-PQputline(conn, "\\.\n");
 PQendcopy(conn);
 </programlisting>
 </para>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 529baa1f31b..52d2a60c3b2 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/protocol.sgml,v 1.28 2003/04/19 00:02:29 tgl Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/protocol.sgml,v 1.29 2003/04/22 00:08:06 tgl Exp $ -->
 
 <chapter id="protocol">
  <title>Frontend/Backend Protocol</title>
@@ -3691,7 +3691,8 @@ Terminate (F)
 <para>
 This section describes the fields that may appear in ErrorResponse and
 NoticeResponse messages.  Each field type has a single-byte identification
-token.
+token.  Note that any given field type should appear at most once per
+message.
 </para>
 
 <VariableList>
@@ -3863,7 +3864,29 @@ PasswordMessage now has a type byte.
 
 <para>
 COPY data is now encapsulated into CopyData and CopyDone messages.  There
-is a well-defined way to recover from errors during COPY.
+is a well-defined way to recover from errors during COPY.  The special
+<quote><literal>\.</></quote> last line is not needed anymore, and is not sent
+during COPY OUT.
+(It is still recognized as a terminator during COPY IN, but its use is
+deprecated and will eventually be removed.)  Binary COPY is supported.
+The CopyInResponse and CopyOutResponse messages carry a field indicating
+whether the COPY operation is text or binary.
+</para>
+
+<para>
+The CursorResponse ('<literal>P</>') message is no longer generated by
+the backend.
+</para>
+
+<para>
+The NotificationResponse ('<literal>A</>') message has an additional string
+field, which is presently empty but may someday carry additional data passed
+from the NOTIFY event sender.
+</para>
+
+<para>
+The EmptyQueryResponse ('<literal>I</>') message used to include an empty
+string parameter; this has been removed.
 </para>
 
 <note>