diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/ref/create_type.sgml | 52 | ||||
| -rw-r--r-- | doc/src/sgml/xtypes.sgml | 21 |
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, |