Documentation updates to reflect TOAST and new-style fmgr.

doc/src/sgml/array.sgml

@@ -130,10 +130,12 @@ UPDATE sal_emp SET pay_by_quarter[1:2] = '{27000,27000}'
 </Para>
 
 <Para>
-     It is not currently possible to resize an array value except by
-     complete replacement; for example, we couldn't change a four-
-     element array value to a five-element value with a single
-     assignment to array[5].
+     An array can be enlarged by assigning to an element adjacent to
+     those already present, or by assigning to a slice that is adjacent
+     to or overlaps the data already present.  Currently, this is only
+     allowed for one-dimensional arrays, not multidimensional arrays.
+     For example, if an array value currently has 4 elements, it will
+     have five elements after an update that assigns to array[5].
 </Para>
 
 <Para>

doc/src/sgml/datatype.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.33 2000/08/23 05:59:01 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.34 2000/08/24 23:36:28 tgl Exp $
 -->
 
  <chapter id="datatype">
@@ -42,7 +42,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.33 2000/08/23 05:59:01 th
      <thead>
       <row>
        <entry><productname>Postgres</productname> Type</entry>
-       <entry><acronym>SQL92</acronym> or <acronym>SQL3</acronym> Type</entry>
+       <entry><acronym>SQL92</acronym> or <acronym>SQL99</acronym> Type</entry>
        <entry>Description</entry>
       </row>
      </thead>
@@ -80,7 +80,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.33 2000/08/23 05:59:01 th
       <row>
        <entry>decimal</entry>
        <entry>decimal(p,s)</entry>
-       <entry>exact numeric for p <= 9, s = 0</entry>
+       <entry>exact numeric with selectable precision</entry>
       </row>
       <row>
        <entry>float4</entry>
@@ -135,7 +135,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.33 2000/08/23 05:59:01 th
       <row>
        <entry>numeric</entry>
        <entry>numeric(p,s)</entry>
-       <entry>exact numeric for p == 9, s = 0</entry>
+       <entry>exact numeric with selectable precision</entry>
       </row>
       <row>
        <entry>path</entry>
@@ -157,6 +157,11 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.33 2000/08/23 05:59:01 th
        <entry></entry>
        <entry>unique id for indexing and cross-reference</entry>
       </row>
+      <row>
+       <entry>text</entry>
+       <entry></entry>
+       <entry>variable-length character string</entry>
+      </row>
       <row>
        <entry>time</entry>
        <entry>time [ without time zone ]</entry>
@@ -234,7 +239,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.33 2000/08/23 05:59:01 th
   <para>
    <productname>Postgres</productname> has features at the forefront of 
    <acronym>ORDBMS</acronym> development. In addition to
-   <acronym>SQL3</acronym> conformance, substantial portions 
+   <acronym>SQL99</acronym> conformance, substantial portions 
    of <acronym>SQL92</acronym> are also supported.
    Although we strive for <acronym>SQL92</acronym> compliance, 
    there are some aspects of the standard
@@ -275,7 +280,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.33 2000/08/23 05:59:01 th
    <title>Numeric Types</title>
 
    <para>
-    Numeric types consist of two- and four-byte integers, four- and eight-byte
+    Numeric types consist of two-, four-, and eight-byte integers,
+    four- and eight-byte
     floating point numbers and fixed-precision decimals.
    </para>
 
@@ -297,7 +303,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.33 2000/08/23 05:59:01 th
 	<entry>decimal</entry>
 	<entry>variable</entry>
 	<entry>User-specified precision</entry>
-	<entry>~8000 digits</entry>
+	<entry>no limit</entry>
        </row>
        <row>
 	<entry>float4</entry>
@@ -327,7 +333,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.33 2000/08/23 05:59:01 th
 	<entry>int8</entry>
 	<entry>8 bytes</entry>
 	<entry>Very large range fixed-precision</entry>
-	<entry>+/- &gt; 18 decimal places</entry>
+	<entry>~18 decimal places</entry>
        </row>
        <row>
 	<entry>numeric</entry>
@@ -354,7 +360,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.33 2000/08/23 05:59:01 th
 
    <para>
     The <type>int8</type> type may not be available on all platforms since
-    it relies on compiler support for this.
+    it relies on compiler support for eight-byte integers.
    </para>
 
    <sect2>
@@ -483,7 +489,7 @@ CREATE TABLE <replaceable class="parameter">tablename</replaceable> (<replaceabl
       </thead>
       <tbody>
        <row>
-	<entry>char</entry>
+	<entry>"char"</entry>
 	<entry>1 byte</entry>
 	<entry><acronym>SQL92</acronym>-compatible</entry>
 	<entry>Single character</entry>
@@ -502,7 +508,7 @@ CREATE TABLE <replaceable class="parameter">tablename</replaceable> (<replaceabl
        </row>
        <row>
 	<entry>varchar(n)</entry>
-	<entry>(4+n) bytes</entry>
+	<entry>(4+x) bytes</entry>
 	<entry><acronym>SQL92</acronym>-compatible</entry>
 	<entry>Variable-length with limit</entry>
        </row>
@@ -1359,10 +1365,10 @@ January 8 04:05:06 1999 PST
 
    <para>
     <productname>Postgres</productname> supports <type>bool</type> as
-    the <acronym>SQL3</acronym> boolean type.
+    the <acronym>SQL99</acronym> boolean type.
     <type>bool</type> can have one of only two states: 'true' or 'false'. 
     A third state, 'unknown', is not
-    implemented and is not suggested in <acronym>SQL3</acronym>; 
+    implemented and is not suggested in <acronym>SQL99</acronym>; 
     <acronym>NULL</acronym> is an
     effective substitute. <type>bool</type> can be used in any boolean expression, 
     and boolean expressions

doc/src/sgml/ref/create_function.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.15 2000/07/22 04:30:27 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.16 2000/08/24 23:36:29 tgl Exp $
 Postgres documentation
 -->
 
@@ -31,7 +31,7 @@ CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceab
 CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">ftype</replaceable> [, ...] ] )
     RETURNS <replaceable class="parameter">rtype</replaceable>
     AS <replaceable class="parameter">obj_file</replaceable> , <replaceable class="parameter">link_symbol</replaceable>  
-    LANGUAGE 'C'
+    LANGUAGE 'langname'
     [ WITH ( <replaceable class="parameter">attribute</replaceable> [, ...] ) ]
   </synopsis>
   
@@ -57,11 +57,11 @@ CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceab
       <term><replaceable class="parameter">ftype</replaceable></term>
       <listitem>
        <para>
-	The data type of function arguments.
+	The data type(s) of the function's arguments, if any.
 	The input types may be base or complex types, or
 	<firstterm>opaque</firstterm>.
 	<literal>opaque</literal> indicates that the function
-	accepts arguments of an invalid type such as <type>char *</type>.
+	accepts arguments of a non-SQL type such as <type>char *</type>.
        </para>
       </listitem>
      </varlistentry>
@@ -84,14 +84,7 @@ CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceab
       <listitem>
        <para>
         An optional piece of information about the function, used for
-	optimization.  The only attribute currently supported is
-	<literal>iscachable</literal>.
-	<literal>iscachable</literal> indicates that the function always
-	returns the same result when given the same input values (i.e.,
-	it does not do database lookups or otherwise use information not
-	directly present in its parameter list).  The optimizer uses
-	<literal>iscachable</literal> to know whether it is safe to
-	pre-evaluate a call of the function.
+	optimization.  See below for details.
        </para>
       </listitem>
      </varlistentry>
@@ -115,8 +108,8 @@ CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceab
 	function. The string <replaceable
 	class="parameter">obj_file</replaceable> is the name of the file
 	containing the dynamically loadable object, and <replaceable
-	class="parameter">link_symbol</replaceable>, is the object's link
-	symbol which is the same as the name of the function in the C
+	class="parameter">link_symbol</replaceable> is the object's link
+	symbol, that is the name of the function in the C
 	language source code.
        </para>
       </listitem>
@@ -125,8 +118,9 @@ CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceab
       <term><replaceable class="parameter">langname</replaceable></term>
       <listitem>
        <para>
-	may be '<literal>C</literal>', '<literal>sql</literal>',
-	'<literal>internal</literal>'
+	may be '<literal>sql</literal>',
+	'<literal>C</literal>', '<literal>newC</literal>',
+	'<literal>internal</literal>', '<literal>newinternal</literal>',
 	or '<replaceable class="parameter">plname</replaceable>',
 	where '<replaceable class="parameter">plname</replaceable>'
 	is the name of a created procedural language. See
@@ -175,11 +169,57 @@ CREATE
    <command>CREATE FUNCTION</command> allows a
    <productname>Postgres</productname> user
    to register a function
-   with a database. Subsequently, this user is considered the
+   with the database. Subsequently, this user is considered the
    owner of the function.
   </para>
-  
+
   <refsect2 id="R2-SQL-CREATEFUNCTION-3">
+   <refsect2info>
+    <date>2000-08-24</date>
+   </refsect2info>
+   <title>
+    Function Attributes
+   </title>
+
+   <para>
+    The following items may appear in the WITH clause:
+
+    <variablelist>
+     <varlistentry>
+      <literal>iscachable</literal>
+      <listitem>
+       <para>
+	<literal>iscachable</literal> indicates that the function always
+	returns the same result when given the same argument values (i.e.,
+	it does not do database lookups or otherwise use information not
+	directly present in its parameter list).  The optimizer uses
+	<literal>iscachable</literal> to know whether it is safe to
+	pre-evaluate a call of the function.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <literal>isstrict</literal>
+      <listitem>
+       <para>
+	<literal>isstrict</literal> indicates that the function always
+	returns NULL whenever any of its arguments are NULL.  If this
+	attribute is specified, the function is not executed when there
+	are NULL arguments; instead a NULL result is assumed automatically.
+	When <literal>isstrict</literal> is not specified, the function will
+	be called for NULL inputs.  It is then the function author's
+	responsibility to check for NULLs if necessary and respond
+	appropriately.
+       </para>
+      </listitem>
+     </varlistentry>
+    </variablelist>
+   </para>
+
+  </refsect2>
+
+  <refsect2 id="R2-SQL-CREATEFUNCTION-4">
    <refsect2info>
     <date>2000-03-25</date>
    </refsect2info>
@@ -200,26 +240,25 @@ CREATE
     to remove user-defined functions.
    </para>
 
-   <para>
-    <productname>Postgres</productname> allows function "overloading";
-    that is, the same name can be used for several different functions
-    so long as they have distinct argument types.  This facility must
-    be used with caution for <literal>internal</literal> and
-    C-language functions, however.    
-   </para>
-
    <para>
     The full <acronym>SQL92</acronym> type syntax is allowed for
     input arguments and return value. However, some details of the
     type specification (e.g. the precision field for
     <type>numeric</type> types) are the responsibility of the
     underlying function implementation and are silently swallowed
-    (e.g. not recognized or
+    (i.e., not recognized or
     enforced) by the <command>CREATE FUNCTION</command> command.
    </para>
 
    <para>
-    Two <literal>internal</literal>
+    <productname>Postgres</productname> allows function "overloading";
+    that is, the same name can be used for several different functions
+    so long as they have distinct argument types.  This facility must
+    be used with caution for internal and C-language functions, however.    
+   </para>
+
+   <para>
+    Two <literal>internal</literal> or <literal>newinternal</literal>
     functions cannot have the same C name without causing
     errors at link time.  To get around that, give them different C names
     (for example, use the argument types as part of the C names), then
@@ -229,18 +268,14 @@ CREATE
    </para>
 
    <para>
-    When overloading SQL functions with C-language functions, give
-    each C-language instance of the function a distinct name, and use
+    Similarly, when overloading SQL function names with multiple C-language
+    functions, give
+    each C-language instance of the function a distinct name, then use
     the alternative form of the <command>AS</command> clause in the
-    <command>CREATE FUNCTION</command> syntax to ensure that
-    overloaded SQL functions names are resolved to the correct
-    dynamically linked objects.
+    <command>CREATE FUNCTION</command> syntax to select the appropriate
+    C-language implementation of each overloaded SQL function.
    </para>
 
-
-   <para>
-    A C function cannot return a set of values.
-   </para>
   </refsect2>
  </refsect1>
   
@@ -291,7 +326,7 @@ CREATE TABLE product (
    function is implemented by a dynamically loaded object that was
    compiled from C source. For <productname>Postgres</productname> to
    find a type conversion function automatically, the sql function has
-   to have the same name as the return type, and overloading is
+   to have the same name as the return type, and so overloading is
    unavoidable.  The function name is overloaded by using the second
    form of the <command>AS</command> clause in the SQL definition:
   </para>
@@ -324,7 +359,7 @@ Point * complex_to_point (Complex *z)
    Compatibility
   </title>
 
-  <refsect2 id="R2-SQL-CREATEFUNCTION-4">
+  <refsect2 id="R2-SQL-CREATEFUNCTION-5">
    <refsect2info>
     <date>2000-03-25</date>
    </refsect2info>
@@ -338,7 +373,7 @@ Point * complex_to_point (Complex *z)
    </para>
   </refsect2>
 
-  <refsect2 id="R2-SQL-CREATEFUNCTION-5">
+  <refsect2 id="R2-SQL-CREATEFUNCTION-6">
    <refsect2info>
     <date>2000-03-25</date>
    </refsect2info>

doc/src/sgml/ref/create_language.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_language.sgml,v 1.10 2000/05/29 01:59:06 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_language.sgml,v 1.11 2000/08/24 23:36:29 tgl Exp $
 Postgres documentation
 -->
 
@@ -48,8 +48,7 @@ CREATE [ TRUSTED ] PROCEDURAL LANGUAGE '<replaceable class="parameter">langname<
 	this keyword is omitted when registering the language,
 	only users with the <productname>Postgres</productname>
 	superuser privilege can use
-	this language to create new functions
-	(like the 'C' language).  
+	this language to create new functions.
        </para>
       </listitem>
      </varlistentry>
@@ -222,6 +221,11 @@ ERROR:  PL handler function <replaceable class="parameter">funcname</replaceable
     must be careful that <literal>flinfo-&gt;fn_extra</literal> is made to
     point at memory that will live at least until the end of the current
     query, since an FmgrInfo data structure could be kept that long.
+    One way to do this is to allocate the extra data in the memory context
+    specified by <literal>flinfo-&gt;fn_mcxt</literal>; such data will
+    normally have the same lifespan as the FmgrInfo itself.  But the handler
+    could also choose to use a longer-lived context so that it can cache
+    function definition information across queries.
    </para>
 
    <para>
@@ -262,20 +266,21 @@ ERROR:  PL handler function <replaceable class="parameter">funcname</replaceable
  lanplcallfoid | oid     |
  lancompiler   | text    |
 
- lanname  | lanispl | lanpltrusted | lanplcallfoid | lancompiler
-----------+---------+--------------+---------------+-------------
- internal | f       | f            |             0 | n/a
- C        | f       | f            |             0 | /bin/cc
- sql      | f       | f            |             0 | postgres
+   lanname   | lanispl | lanpltrusted | lanplcallfoid | lancompiler
+-------------+---------+--------------+---------------+-------------
+ internal    | f       | f            |             0 | n/a
+ newinternal | f       | f            |             0 | n/a
+ C           | f       | f            |             0 | /bin/cc
+ newC        | f       | f            |             0 | /bin/cc
+ sql         | f       | f            |             0 | postgres
 </computeroutput>
 </programlisting>
    </para>
 
    <para>
-    Since the call handler for a procedural language must be
-    registered with <productname>Postgres</productname> in the 'C' language,
-    it inherits
-    all the capabilities and restrictions of 'C' functions.
+    The call handler for a procedural language must normally be written
+    in C and registered as 'newinternal' or 'newC' language, depending
+    on whether it is linked into the backend or dynamically loaded.
    </para>
 
    <para> 

doc/src/sgml/ref/create_table.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_table.sgml,v 1.33 2000/07/22 04:30:27 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_table.sgml,v 1.34 2000/08/24 23:36:29 tgl Exp $
 Postgres documentation
 -->
 
@@ -248,11 +248,9 @@ ERROR:  DEFAULT: type mismatched
 
   <para>
    The new table is created as a heap with no initial data.
-   A table can have no more than 1600 columns (realistically,
-   this is limited by the fact that tuple sizes must
-   be less than 8192 bytes), but this limit may be configured
-   lower at some sites. A table cannot have the same name as
-   a system catalog table.
+   A table can have no more than 1600 columns (in practice, the
+   effective limit is lower because of tuple-length constraints).
+   A table cannot have the same name as a system catalog table.
   </para>
  </refsect1>
 

doc/src/sgml/ref/create_type.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_type.sgml,v 1.12 2000/03/27 17:14:42 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_type.sgml,v 1.13 2000/08/24 23:36:29 tgl Exp $
 Postgres documentation
 -->
 
@@ -24,11 +24,16 @@ Postgres documentation
   </refsynopsisdivinfo>
   <synopsis>
 CREATE TYPE <replaceable class="parameter">typename</replaceable> ( INPUT = <replaceable class="parameter">input_function</replaceable>, OUTPUT = <replaceable class="parameter">output_function</replaceable>
-      , INTERNALLENGTH = { <replaceable class="parameter">internallength</replaceable> | VARIABLE } [ , EXTERNALLENGTH = { <replaceable class="parameter">externallength</replaceable> | VARIABLE } ]
+      , INTERNALLENGTH = { <replaceable
+      class="parameter">internallength</replaceable> | VARIABLE }
+    [ , EXTERNALLENGTH = { <replaceable class="parameter">externallength</replaceable> | VARIABLE } ]
     [ , DEFAULT = "<replaceable class="parameter">default</replaceable>" ]
     [ , ELEMENT = <replaceable class="parameter">element</replaceable> ] [ , DELIMITER = <replaceable class="parameter">delimiter</replaceable> ]
     [ , SEND = <replaceable class="parameter">send_function</replaceable> ] [ , RECEIVE = <replaceable class="parameter">receive_function</replaceable> ]
-    [ , PASSEDBYVALUE ] )
+    [ , PASSEDBYVALUE ]
+    [ , ALIGNMENT = <replaceable class="parameter">alignment</replaceable> ]
+    [ , STORAGE = <replaceable class="parameter">storage</replaceable> ]
+)
   </synopsis>
   
   <refsect2 id="R2-SQL-CREATETYPE-1">
@@ -64,7 +69,7 @@ CREATE TYPE <replaceable class="parameter">typename</replaceable> ( INPUT = <rep
       <term><replaceable class="parameter">externallength</replaceable></term>
       <listitem>
        <para>
-	A literal value, which specifies the external length of
+	A literal value, which specifies the external (displayed) length of
 	the new type.
        </para>
       </listitem>
@@ -86,7 +91,8 @@ CREATE TYPE <replaceable class="parameter">typename</replaceable> ( INPUT = <rep
       <term><replaceable class="parameter">output_function</replaceable></term>
       <listitem>
        <para>
-	The name of a function, created by CREATE FUNCTION, which
+	The name of a function, created by
+	<command>CREATE FUNCTION</command>, which
 	converts data from its internal form to a form suitable
 	for display.
        </para>
@@ -107,7 +113,7 @@ CREATE TYPE <replaceable class="parameter">typename</replaceable> ( INPUT = <rep
       <term><replaceable class="parameter">delimiter</replaceable></term>
       <listitem>
        <para>
-	The delimiter character for the array.
+	The delimiter character for the array elements.
        </para>
       </listitem>
      </varlistentry>
@@ -116,8 +122,8 @@ CREATE TYPE <replaceable class="parameter">typename</replaceable> ( INPUT = <rep
       <term><replaceable class="parameter">default</replaceable></term>
       <listitem>
        <para>
-	The default text to be displayed to indicate "data
-	not present"
+	The default value for the datatype.  Usually this is omitted,
+	so that the default is NULL.
        </para>
       </listitem>
      </varlistentry>
@@ -141,6 +147,29 @@ CREATE TYPE <replaceable class="parameter">typename</replaceable> ( INPUT = <rep
        </para>
       </listitem>
      </varlistentry>
+
+     <varlistentry>
+      <term><replaceable class="parameter">alignment</replaceable></term>
+      <listitem>
+       <para>
+        Storage alignment requirement of the datatype.  If specified, must
+	be '<literal>int4</literal>' or '<literal>double</literal>';
+	the default is '<literal>int4</literal>'.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><replaceable class="parameter">storage</replaceable></term>
+      <listitem>
+       <para>
+        Storage technique for the datatype.  If specified, must
+	be '<literal>plain</literal>', '<literal>external</literal>',
+	'<literal>extended</literal>', or '<literal>main</literal>';
+	the default is '<literal>plain</literal>'.
+       </para>
+      </listitem>
+     </varlistentry>
     </variablelist>
    </para>
   </refsect2>
@@ -267,6 +296,24 @@ CREATE
    more than four bytes.
   </para>
 
+  <para>
+   The <replaceable class="parameter">storage</replaceable> keyword
+   allows selection of TOAST storage method for variable-length datatypes
+   (only <literal>plain</literal> is allowed for fixed-length types).
+   <literal>plain</literal> disables TOAST for the datatype: it will always
+   be stored in-line and not compressed.
+   <literal>extended</literal> is full TOAST capability: the system will
+   first try to compress a long data value, and will move the value out of
+   the main table row if it's still too long.
+   <literal>external</literal> allows the value to be moved out of the main
+   table, but the system will not try to compress it.
+   <literal>main</literal> allows compression, but discourages moving the
+   value out of the main table.  (Data items with this storage method may
+   still be moved out of the main table if there is no other way to make
+   a row fit, but they will be kept in the main table preferentially over
+   <literal>extended</literal> and <literal>external</literal> items.)
+  </para>
+
   <para>
    For new base types, a user can define operators, functions
    and aggregates using the appropriate facilities  described
@@ -283,17 +330,6 @@ CREATE
    </para>
   </refsect2>
 
-  <refsect2>
-   <title>Large Object Types</title>
-   <para>
-    A "regular" Postgres  type  can  only  be  8192  bytes  in
-    length.  If you need a larger type you must create a Large
-    Object type.  The interface for these types  is  discussed
-    at  length  in the
-    <citetitle>PostgreSQL Programmer's Guide</citetitle>.
-    The length of all large object types is always VARIABLE.
-   </para>
-  </refsect2>
  </refsect1>
 
  <refsect1>