mirror of
https://github.com/postgres/postgres.git
synced 2025-12-21 05:21:08 +03:00
Add a bunch of pseudo-types to replace the behavior formerly associated
with OPAQUE, as per recent pghackers discussion. I still want to do some more work on the 'cstring' pseudo-type, but I'm going to commit the bulk of the changes now before the tree starts shifting under me ...
This commit is contained in:
Tom Lane
@@ -1,4 +1,4 @@
|
||||
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/create_conversion.sgml,v 1.2 2002/07/22 13:00:00 ishii Exp $ -->
|
||||
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/create_conversion.sgml,v 1.3 2002/08/22 00:01:40 tgl Exp $ -->
|
||||
|
||||
<refentry id="SQL-CREATECONVERSION">
|
||||
<refmeta>
|
||||
@@ -108,10 +108,10 @@ CREATE [DEFAULT] CONVERSION <replaceable>conversion_name</replaceable>
|
||||
conv_proc(
|
||||
INTEGER, -- source encoding id
|
||||
INTEGER, -- destination encoding id
|
||||
OPAQUE, -- source string (null terminated C string)
|
||||
OPAQUE, -- destination string (null terminated C string)
|
||||
CSTRING, -- source string (null terminated C string)
|
||||
CSTRING, -- destination string (null terminated C string)
|
||||
INTEGER -- source string length
|
||||
) returns INTEGER; -- dummy. returns nothing, actually.
|
||||
) returns VOID;
|
||||
</programlisting>
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.41 2002/07/24 19:11:07 petere Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.42 2002/08/22 00:01:40 tgl Exp $
|
||||
-->
|
||||
|
||||
<refentry id="SQL-CREATEFUNCTION">
|
||||
@@ -67,16 +67,17 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
|
||||
<listitem>
|
||||
<para>
|
||||
The data type(s) of the function's arguments, if any. The
|
||||
input types may be base or complex types,
|
||||
<literal>opaque</literal>, or the same as the type of an
|
||||
existing column. <literal>Opaque</literal> indicates
|
||||
that the function accepts arguments of a non-SQL type such as
|
||||
<type>char *</type>.
|
||||
The type of a column is indicated using <replaceable
|
||||
input types may be base, complex, or domain types,
|
||||
or the same as the type of an existing column.
|
||||
The type of a column is referenced by writing <replaceable
|
||||
class="parameter">tablename</replaceable>.<replaceable
|
||||
class="parameter">columnname</replaceable><literal>%TYPE</literal>;
|
||||
using this can sometimes help make a function independent from
|
||||
changes to the definition of a table.
|
||||
Depending on the implementation language it may also be allowed
|
||||
to specify <quote>pseudo-types</> such as <type>cstring</>.
|
||||
Pseudo-types indicate that the actual argument type is either
|
||||
incompletely specified, or outside the set of ordinary SQL datatypes.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
@@ -87,15 +88,13 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
|
||||
<listitem>
|
||||
<para>
|
||||
The return data type. The return type may be specified as a
|
||||
base type, complex type, <literal>setof</literal> type,
|
||||
<literal>opaque</literal>, or the same as the type of an
|
||||
base, complex, or domain type, or the same as the type of an
|
||||
existing column.
|
||||
Depending on the implementation language it may also be allowed
|
||||
to specify <quote>pseudo-types</> such as <type>cstring</>.
|
||||
The <literal>setof</literal>
|
||||
modifier indicates that the function will return a set of
|
||||
items, rather than a single item. Functions with a declared
|
||||
return type of <literal>opaque</literal> do not return a value.
|
||||
These cannot be called directly; trigger functions make use of
|
||||
this feature.
|
||||
items, rather than a single item.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_language.sgml,v 1.26 2002/07/24 19:11:07 petere Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_language.sgml,v 1.27 2002/08/22 00:01:40 tgl Exp $
|
||||
PostgreSQL documentation
|
||||
-->
|
||||
|
||||
@@ -108,8 +108,8 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">langna
|
||||
language such as C with version 1 call convention and
|
||||
registered with <productname>PostgreSQL</productname> as a
|
||||
function taking no arguments and returning the
|
||||
<type>opaque</type> type, a placeholder for unspecified or
|
||||
undefined types.
|
||||
<type>language_handler</type> type, a placeholder type that is
|
||||
simply used to identify the function as a call handler.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
@@ -122,11 +122,13 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">langna
|
||||
<replaceable class="parameter">valfunction</replaceable> is the
|
||||
name of a previously registered function that will be called
|
||||
when a new function in the language is created, to validate the
|
||||
new function. The validator function must take one argument of
|
||||
type <type>oid</type>, which will be the OID of the
|
||||
to-be-created function, and can have any return type. If no
|
||||
new function.
|
||||
If no
|
||||
validator function is specified, then a new function will not
|
||||
be checked when it is created.
|
||||
The validator function must take one argument of
|
||||
type <type>oid</type>, which will be the OID of the
|
||||
to-be-created function, and will typically return <type>void</>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@@ -251,7 +253,7 @@ ERROR: PL handler function <replaceable class="parameter">funcname</replaceable
|
||||
The following two commands executed in sequence will register a new
|
||||
procedural language and the associated call handler.
|
||||
<programlisting>
|
||||
CREATE FUNCTION plsample_call_handler () RETURNS opaque
|
||||
CREATE FUNCTION plsample_call_handler () RETURNS language_handler
|
||||
AS '$libdir/plsample'
|
||||
LANGUAGE C;
|
||||
CREATE LANGUAGE plsample
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_opclass.sgml,v 1.1 2002/07/29 22:14:10 tgl Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_opclass.sgml,v 1.2 2002/08/22 00:01:40 tgl Exp $
|
||||
PostgreSQL documentation
|
||||
-->
|
||||
|
||||
@@ -260,13 +260,13 @@ CREATE OPERATOR CLASS gist__int_ops
|
||||
OPERATOR 7 @,
|
||||
OPERATOR 8 ~,
|
||||
OPERATOR 20 @@ (_int4, query_int),
|
||||
FUNCTION 1 g_int_consistent (opaque, _int4, int4),
|
||||
FUNCTION 2 g_int_union (bytea, opaque),
|
||||
FUNCTION 3 g_int_compress (opaque),
|
||||
FUNCTION 4 g_int_decompress (opaque),
|
||||
FUNCTION 5 g_int_penalty (opaque, opaque, opaque),
|
||||
FUNCTION 6 g_int_picksplit (opaque, opaque),
|
||||
FUNCTION 7 g_int_same (_int4, _int4, opaque);
|
||||
FUNCTION 1 g_int_consistent (internal, _int4, int4),
|
||||
FUNCTION 2 g_int_union (bytea, internal),
|
||||
FUNCTION 3 g_int_compress (internal),
|
||||
FUNCTION 4 g_int_decompress (internal),
|
||||
FUNCTION 5 g_int_penalty (internal, internal, internal),
|
||||
FUNCTION 6 g_int_picksplit (internal, internal),
|
||||
FUNCTION 7 g_int_same (_int4, _int4, internal);
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_trigger.sgml,v 1.26 2002/05/18 15:44:47 petere Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_trigger.sgml,v 1.27 2002/08/22 00:01:40 tgl Exp $
|
||||
PostgreSQL documentation
|
||||
-->
|
||||
|
||||
@@ -66,7 +66,7 @@ CREATE TRIGGER <replaceable class="PARAMETER">name</replaceable> { BEFORE | AFTE
|
||||
<listitem>
|
||||
<para>
|
||||
A user-supplied function that is declared as taking no arguments
|
||||
and returning type <literal>opaque</>.
|
||||
and returning type <literal>trigger</>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
@@ -167,6 +167,14 @@ CREATE TRIGGER
|
||||
<literal>TRIGGER</literal> privilege on the table.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
In <productname>PostgreSQL</productname> versions before 7.3, it was
|
||||
necessary to declare trigger functions as returning the placeholder
|
||||
type <type>opaque</>, rather than <type>trigger</>. This is still
|
||||
supported, but is deprecated because it is obscure and causes loss of
|
||||
type safety.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
As of the current release, <literal>STATEMENT</literal> triggers are not implemented.
|
||||
</para>
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_type.sgml,v 1.31 2002/08/15 16:36:00 momjian Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_type.sgml,v 1.32 2002/08/22 00:01:40 tgl Exp $
|
||||
PostgreSQL documentation
|
||||
-->
|
||||
|
||||
@@ -226,22 +226,47 @@ CREATE TYPE
|
||||
operators and functions defined for the type. Naturally,
|
||||
<replaceable class="parameter">output_function</replaceable>
|
||||
performs the reverse transformation. The input function may be
|
||||
declared as taking one argument of type <type>opaque</type>,
|
||||
declared as taking one argument of type <type>cstring</type>,
|
||||
or as taking three arguments of types
|
||||
<type>opaque</type>, <type>OID</type>, <type>int4</type>.
|
||||
<type>cstring</type>, <type>OID</type>, <type>int4</type>.
|
||||
(The first argument is the input text as a C string, the second
|
||||
argument is the element type in case this is an array type,
|
||||
and the third is the typmod of the destination column, if known.)
|
||||
It should return a value of the datatype itself.
|
||||
The output function may be
|
||||
declared as taking one argument of type <type>opaque</type>,
|
||||
or as taking two arguments of types
|
||||
<type>opaque</type>, <type>OID</type>.
|
||||
(The first argument is actually of the data type itself, but since the
|
||||
output function must be declared first, it's easier to declare it as
|
||||
accepting type <type>opaque</type>. The second argument is again
|
||||
the array element type for array types.)
|
||||
declared as taking one argument of the new datatype, or as taking
|
||||
two arguments of which the second is type <type>OID</type>.
|
||||
(The second argument is again the array element type for array types.)
|
||||
The output function should return type <type>cstring</type>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You should at this point be wondering how the input and output functions
|
||||
can be declared to have results or inputs 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, then the
|
||||
datatype.
|
||||
<productname>PostgreSQL</productname> will first see the name of the new
|
||||
datatype as the return type of the input function. It will create a
|
||||
<quote>shell</> type, which is simply a placeholder entry in
|
||||
<literal>pg_type</>, and link the input function definition to the shell
|
||||
type. Similarly the output function 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.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
In <productname>PostgreSQL</productname> versions before 7.3, it was
|
||||
customary to avoid creating a shell type by replacing the functions'
|
||||
forward references to the type name with the placeholder pseudo-type
|
||||
<type>OPAQUE</>. The <type>cstring</> inputs and
|
||||
results also had to be declared as <type>OPAQUE</> before 7.3.
|
||||
Use of <type>OPAQUE</> for this purpose is still supported, but it is
|
||||
deprecated because it causes loss of type safety.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<para>
|
||||
New base data types can be fixed length, in which case
|
||||
<replaceable class="parameter">internallength</replaceable> is a
|
||||
|
||||
Reference in New Issue
Block a user