Mark server_encoding and integer_datetimes as GUC_REPORT, per previous

proposals by Oliver Jowett.  Update documentation.

3 files changed, 97 insertions, 25 deletions

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 402f77bd7d4..af9a35a620d 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.158 2004/08/11 18:06:00 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.159 2004/08/16 02:12:29 tgl Exp $
 -->
 
  <chapter id="libpq">
@@ -848,28 +848,45 @@ const char *PQparameterStatus(const PGconn *conn, const char *paramName);
 Certain parameter values are reported by the server automatically at
 connection startup or whenever their values change.
 <function>PQparameterStatus</> can be used to interrogate these settings.
-It returns the current value of a parameter if known, or <symbol>NULL</symbol> if the parameter
-is not known.
+It returns the current value of a parameter if known, or <symbol>NULL</symbol>
+if the parameter is not known.
 </para>
 
 <para>
 Parameters reported as of the current release include
-<literal>server_version</> (cannot change after startup);
+<literal>server_version</>,
+<literal>server_encoding</>,
 <literal>client_encoding</>,
 <literal>is_superuser</>,
-<literal>session_authorization</literal>, and
-<literal>DateStyle</>.
+<literal>session_authorization</>,
+<literal>DateStyle</>, and
+<literal>integer_datetimes</>.
+(<literal>server_encoding</> and <literal>integer_datetimes</> were not
+reported by releases before 8.0.)
+Note that
+<literal>server_version</>,
+<literal>server_encoding</> and
+<literal>integer_datetimes</>
+cannot change after startup.
 </para>
 
 <para>
 Pre-3.0-protocol servers do not report parameter settings, but
 <application>libpq</> includes logic to obtain values for
-<literal>server_version</>, and <literal>client_encoding</>.
+<literal>server_version</> and <literal>client_encoding</> anyway.
 Applications are encouraged to use <function>PQparameterStatus</>
 rather than ad-hoc code to determine these values.  (Beware however
 that on a pre-3.0 connection, changing <literal>client_encoding</> via
 <command>SET</> after connection startup will not be reflected by
-<function>PQparameterStatus</>.)
+<function>PQparameterStatus</>.)  For <literal>server_version</>,
+see also <function>PQserverVersion</>, which returns the information
+in a numeric form that is much easier to compare against.
+</para>
+
+<para>
+Although the returned pointer is declared <literal>const</>, it in fact
+points to mutable storage associated with the <literal>PGconn</> structure.
+It is unwise to assume the pointer will remain valid across queries.
 </para>
 </listitem>
 </varlistentry>
@@ -904,10 +921,10 @@ int PQserverVersion(const PGconn *conn);
 </synopsis>
 Applications may use this to determine the version of the database server they
 are connected to. The number is formed by converting the major, minor, and
-revision numbers into two digit numbers and appending them together. For
-example, version 7.4.2 will be returned as 70402, and version 8.1 will be
-returned as 80100 (leading zeroes are not shown).  Zero is returned if the
-connection is bad.
+revision numbers into two-decimal-digit numbers and appending them
+together. For example, version 7.4.2 will be returned as 70402, and version
+8.1 will be returned as 80100 (leading zeroes are not shown).  Zero is
+returned if the connection is bad.
 </para>
 </listitem>
 </varlistentry>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index a88bca30026..f2f0fddabf7 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/protocol.sgml,v 1.52 2004/06/11 01:08:33 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/protocol.sgml,v 1.53 2004/08/16 02:12:29 tgl Exp $ -->
 
 <chapter id="protocol">
  <title>Frontend/Backend Protocol</title>
@@ -1046,12 +1046,20 @@
    <para>
     At present there is a hard-wired set of parameters for which
     ParameterStatus will be generated: they are
-    <literal>server_version</> (a pseudo-parameter that cannot change after
-    startup);
+    <literal>server_version</>,
+    <literal>server_encoding</>,
     <literal>client_encoding</>,
     <literal>is_superuser</>,
-    <literal>session_authorization</literal>, and
-    <literal>DateStyle</>.
+    <literal>session_authorization</>,
+    <literal>DateStyle</>, and
+    <literal>integer_datetimes</>.
+    (<literal>server_encoding</> and <literal>integer_datetimes</> were not
+    reported by releases before 8.0.)
+    Note that
+    <literal>server_version</>,
+    <literal>server_encoding</> and
+    <literal>integer_datetimes</>
+    are pseudo-parameters that cannot change after startup.
     This set might change in the future, or even become configurable.
     Accordingly, a frontend should simply ignore ParameterStatus for
     parameters that it does not understand or care about.
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index c1a3fa225bd..9cca707519e 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.277 2004/08/13 16:29:55 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.278 2004/08/16 02:12:29 tgl Exp $
 -->
 
 <Chapter Id="runtime">
@@ -2675,8 +2675,8 @@ archive_command = 'copy "%p" /mnt/server/archivedir/"%f"'  # Win32
 
      <variablelist>
 
-     <varlistentry id="guc-datestyle" xreflabel="datestyle">
-      <term><varname>datestyle</varname> (<type>string</type>)</term>
+     <varlistentry id="guc-datestyle" xreflabel="DateStyle">
+      <term><varname>DateStyle</varname> (<type>string</type>)</term>
       <indexterm><primary>date style</></>
       <listitem>
        <para>
@@ -3091,13 +3091,13 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
     </sect3>
    </sect2>
 
-   <sect2 id="runtime-config-compiler">
-    <title>Compiled-in Options</title>
+   <sect2 id="runtime-config-preset">
+    <title>Preset Options</title>
 
     <para>
      The following <quote>parameters</> are read-only, and are determined
-     when <productname>PostgreSQL</productname> is compiled. As such,
-     they have been excluded from the sample
+     when <productname>PostgreSQL</productname> is compiled or when it is
+     installed. As such, they have been excluded from the sample
      <filename>postgresql.conf</> file.  These options determine
      various aspects of <productname>PostgreSQL</productname> behavior
      that may be of interest to certain applications, particularly
@@ -3125,7 +3125,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
       <listitem>
        <para>
         Shows whether <productname>PostgreSQL</productname> was built
-        with support for 64-bit integer dates and times.  It is set by
+        with support for 64-bit-integer dates and times.  It is set by
         configuring with <literal>--enable-integer-datetimes</literal>
         when building <productname>PostgreSQL</productname>.  The
         default value is <literal>off</literal>.
@@ -3133,6 +3133,30 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
       </listitem>
      </varlistentry>
 
+     <varlistentry id="guc-lc-collate" xreflabel="lc_collate">
+      <term><varname>lc_collate</varname> (<type>string</type>)</term>
+      <listitem>
+       <para>
+        Shows the locale in which sorting of textual data is done.
+	See <xref linkend="locale"> for more information.
+	The value is determined when the database cluster is initialized.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry id="guc-lc-ctype" xreflabel="lc_ctype">
+      <term><varname>lc_ctype</varname> (<type>string</type>)</term>
+      <listitem>
+       <para>
+        Shows the locale that determines character classifications.
+	See <xref linkend="locale"> for more information.
+	The value is determined when the database cluster is initialized.
+	Ordinarily this will be the same as <varname>lc_collate</varname>,
+	but for special applications it might be set differently.
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry id="guc-max-function-args" xreflabel="max_function_args">
       <term><varname>max_function_args</varname> (<type>integer</type>)</term>
       <listitem>
@@ -3168,6 +3192,29 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
       </listitem>
      </varlistentry>
 
+     <varlistentry id="guc-server-encoding" xreflabel="server_encoding">
+      <term><varname>server_encoding</varname> (<type>string</type>)</term>
+      <indexterm><primary>character set</></>
+      <listitem>
+       <para>
+        Shows the database encoding (character set).
+        It is determined when the database is created.  Ordinarily,
+        clients need only be concerned with the value of <xref
+        linkend="guc-client-encoding">.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry id="guc-server-version" xreflabel="server_version">
+      <term><varname>server_version</varname> (<type>string</type>)</term>
+      <listitem>
+       <para>
+        Shows the version number of the server. It is determined by the
+        value of <literal>PG_VERSION</> when building the server.
+       </para>
+      </listitem>
+     </varlistentry>
+
     </variablelist>
    </sect2>