aboutsummaryrefslogtreecommitdiff
path: root/doc/src
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src')
-rw-r--r--doc/src/sgml/ref/create_type.sgml52
-rw-r--r--doc/src/sgml/xtypes.sgml21
2 files changed, 49 insertions, 24 deletions
diff --git a/doc/src/sgml/ref/create_type.sgml b/doc/src/sgml/ref/create_type.sgml
index a39c244c6c7..9382395182a 100644
--- a/doc/src/sgml/ref/create_type.sgml
+++ b/doc/src/sgml/ref/create_type.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_type.sgml,v 1.60 2006/01/13 18:06:45 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_type.sgml,v 1.61 2006/02/28 22:37:25 tgl Exp $
PostgreSQL documentation
-->
@@ -37,6 +37,8 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> (
[ , ELEMENT = <replaceable class="parameter">element</replaceable> ]
[ , DELIMITER = <replaceable class="parameter">delimiter</replaceable> ]
)
+
+CREATE TYPE <replaceable class="parameter">name</replaceable>
</synopsis>
</refsynopsisdiv>
@@ -142,17 +144,16 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> (
<para>
You should at this point be wondering how the input and output functions
- can be declared to have results or arguments of the new type, when they have
- to be created before the new type can be created. The answer is that the
- input function must be created first, then the output function (and
- the binary I/O functions if wanted), and finally the data type.
- <productname>PostgreSQL</productname> will first see the name of the new
- data type as the return type of the input function. It will create a
- <quote>shell</> type, which is simply a placeholder entry in
- the system catalog, and link the input function definition to the shell
- type. Similarly the other functions will be linked to the (now already
- existing) shell type. Finally, <command>CREATE TYPE</> replaces the
- shell entry with a complete type definition, and the new type can be used.
+ can be declared to have results or arguments of the new type, when they
+ have to be created before the new type can be created. The answer is that
+ the type should first be defined as a <firstterm>shell type</>, which is a
+ placeholder type that has no properties except a name and an owner. This
+ is done by issuing the command <literal>CREATE TYPE
+ <replaceable>name</></literal>, with no additional parameters. Then the
+ I/O functions can be defined referencing the shell type. Finally,
+ <command>CREATE TYPE</> with a full definition replaces the shell entry
+ with a complete, valid type definition, after which the new type can be
+ used normally.
</para>
<para>
@@ -458,16 +459,32 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> (
</para>
<para>
+ Before <productname>PostgreSQL</productname> version 8.2, the syntax
+ <literal>CREATE TYPE <replaceable>name</></literal> did not exist.
+ The way to create a new base type was to create its input function first.
+ In this approach, <productname>PostgreSQL</productname> will first see
+ the name of the new data type as the return type of the input function.
+ The shell type is implicitly created in this situation, and then it
+ can be referenced in the definitions of the remaining I/O functions.
+ This approach still works, but is deprecated and may be disallowed in
+ some future release. Also, to avoid accidentally cluttering
+ the catalogs with shell types as a result of simple typos in function
+ definitions, a shell type will only be made this way when the input
+ function is written in C.
+ </para>
+
+ <para>
In <productname>PostgreSQL</productname> versions before 7.3, it
- was customary to avoid creating a shell type by replacing the
+ was customary to avoid creating a shell type at all, by replacing the
functions' forward references to the type name with the placeholder
pseudotype <type>opaque</>. The <type>cstring</> arguments and
results also had to be declared as <type>opaque</> before 7.3. To
support loading of old dump files, <command>CREATE TYPE</> will
- accept functions declared using <type>opaque</>, but it will issue
- a notice and change the function's declaration to use the correct
+ accept I/O functions declared using <type>opaque</>, but it will issue
+ a notice and change the function declarations to use the correct
types.
</para>
+
</refsect1>
<refsect1>
@@ -489,6 +506,11 @@ $$ LANGUAGE SQL;
This example creates the base data type <type>box</type> and then uses the
type in a table definition:
<programlisting>
+CREATE TYPE box;
+
+CREATE FUNCTION my_box_in_function(cstring) RETURNS box AS ... ;
+CREATE FUNCTION my_box_out_function(box) RETURNS cstring AS ... ;
+
CREATE TYPE box (
INTERNALLENGTH = 16,
INPUT = my_box_in_function,
diff --git a/doc/src/sgml/xtypes.sgml b/doc/src/sgml/xtypes.sgml
index 22d11a6300b..95723360e70 100644
--- a/doc/src/sgml/xtypes.sgml
+++ b/doc/src/sgml/xtypes.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/xtypes.sgml,v 1.25 2005/01/10 00:04:38 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/xtypes.sgml,v 1.26 2006/02/28 22:37:25 tgl Exp $
-->
<sect1 id="xtypes">
@@ -168,8 +168,16 @@ complex_send(PG_FUNCTION_ARGS)
</para>
<para>
- To define the <type>complex</type> type, we need to create the
- user-defined I/O functions before creating the type:
+ Once we have written the I/O functions and compiled them into a shared
+ library, we can define the <type>complex</type> type in SQL.
+ First we declare it as a shell type:
+
+<programlisting>
+CREATE TYPE complex;
+</programlisting>
+
+ This serves as a placeholder that allows us to reference the type while
+ defining its I/O functions. Now we can define the I/O functions:
<programlisting>
CREATE FUNCTION complex_in(cstring)
@@ -192,15 +200,10 @@ CREATE FUNCTION complex_send(complex)
AS '<replaceable>filename</replaceable>'
LANGUAGE C IMMUTABLE STRICT;
</programlisting>
-
- Notice that the declarations of the input and output functions must
- reference the not-yet-defined type. This is allowed, but will draw
- warning messages that may be ignored. The input function must
- appear first.
</para>
<para>
- Finally, we can declare the data type:
+ Finally, we can provide the full definition of the data type:
<programlisting>
CREATE TYPE complex (
internallength = 16,