438 lines
12 KiB
Plaintext
438 lines
12 KiB
Plaintext
|
<REFENTRY ID="SQL-CREATETYPE-1">
|
||
|
|
<REFMETA>
|
||
|
|
<REFENTRYTITLE>
|
||
|
|
CREATE TYPE
|
||
|
|
</REFENTRYTITLE>
|
||
|
|
<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
|
||
|
|
</REFMETA>
|
||
|
|
<REFNAMEDIV>
|
||
|
|
<REFNAME>
|
||
|
|
CREATE TYPE
|
||
|
|
</REFNAME>
|
||
|
|
<REFPURPOSE>
|
||
|
|
CREATE TYPE - defines a new base data type.
|
||
|
|
</REFPURPOSE>
|
||
|
|
<REFSYNOPSISDIV>
|
||
|
|
<REFSYNOPSISDIVINFO>
|
||
|
|
<DATE>1998-04-15</DATE>
|
||
|
|
</REFSYNOPSISDIVINFO>
|
||
|
|
<SYNOPSIS>
|
||
|
|
CREATE TYPE <replaceable class="parameter">typename</replaceable> (
|
||
|
|
INTERNALLENGTH = (<replaceable class="parameter">internallength</replaceable> | VARIABLE)
|
||
|
|
[, EXTERNALLENGTH = (<replaceable class="parameter">externallength</replaceable> | VARIABLE) ]
|
||
|
|
<comment>
|
||
|
|
Why are parentheses required around the length parameters?
|
||
|
|
</comment>
|
||
|
|
, INPUT = <replaceable class="parameter">input_function</replaceable>
|
||
|
|
, OUTPUT = <replaceable class="parameter">output_function</replaceable>
|
||
|
|
[, ELEMENT = <replaceable class="parameter">element</replaceable>]
|
||
|
|
[, DELIMITER = <replaceable class="parameter">delimiter</replaceable>]
|
||
|
|
[, DEFAULT = "<replaceable class="parameter">default</replaceable>" ]
|
||
|
|
[, SEND = <replaceable class="parameter">send_function</replaceable> ]
|
||
|
|
[, RECEIVE = <replaceable class="parameter">receive_function</replaceable> ]
|
||
|
|
[, PASSEDBYVALUE])
|
||
|
|
</SYNOPSIS>
|
||
|
|
|
||
|
|
<REFSECT2 ID="R2-SQL-CREATETYPE-1">
|
||
|
|
<REFSECT2INFO>
|
||
|
|
<DATE>1998-04-15</DATE>
|
||
|
|
</REFSECT2INFO>
|
||
|
|
<TITLE>
|
||
|
|
Inputs
|
||
|
|
</TITLE>
|
||
|
|
<PARA>
|
||
|
|
</PARA>
|
||
|
|
<VARIABLELIST>
|
||
|
|
<VARLISTENTRY>
|
||
|
|
<TERM>
|
||
|
|
</TERM>
|
||
|
|
<LISTITEM>
|
||
|
|
<PARA>
|
||
|
|
<VARIABLELIST>
|
||
|
|
<VARLISTENTRY>
|
||
|
|
<TERM>
|
||
|
|
<ReturnValue>
|
||
|
|
<replaceable class="parameter">typename</replaceable>
|
||
|
|
</ReturnValue>
|
||
|
|
</TERM>
|
||
|
|
<LISTITEM>
|
||
|
|
<PARA>
|
||
|
|
The name of a type to be created.
|
||
|
|
</PARA>
|
||
|
|
</LISTITEM>
|
||
|
|
</VARLISTENTRY>
|
||
|
|
<VARLISTENTRY>
|
||
|
|
<TERM>
|
||
|
|
<ReturnValue>
|
||
|
|
<replaceable class="parameter">internallength</replaceable>
|
||
|
|
</ReturnValue>
|
||
|
|
</TERM>
|
||
|
|
<LISTITEM>
|
||
|
|
<PARA>
|
||
|
|
A literal value, which specifies the internal length of
|
||
|
|
the new type.
|
||
|
|
</PARA>
|
||
|
|
</LISTITEM>
|
||
|
|
</VARLISTENTRY>
|
||
|
|
<VARLISTENTRY>
|
||
|
|
<TERM>
|
||
|
|
<ReturnValue>
|
||
|
|
<replaceable class="parameter">externallength</replaceable>
|
||
|
|
</ReturnValue>
|
||
|
|
</TERM>
|
||
|
|
<LISTITEM>
|
||
|
|
<PARA>
|
||
|
|
A literal value, which specifies the external length of
|
||
|
|
the new type.
|
||
|
|
</PARA>
|
||
|
|
</LISTITEM>
|
||
|
|
</VARLISTENTRY>
|
||
|
|
<VARLISTENTRY>
|
||
|
|
<TERM>
|
||
|
|
<ReturnValue>
|
||
|
|
<replaceable class="parameter">input_function</replaceable>
|
||
|
|
</ReturnValue>
|
||
|
|
</TERM>
|
||
|
|
<LISTITEM>
|
||
|
|
<PARA>
|
||
|
|
The name of a function, created by CREATE FUNCTION, which
|
||
|
|
converts data from its external form to the type's
|
||
|
|
internal form.
|
||
|
|
</PARA>
|
||
|
|
</LISTITEM>
|
||
|
|
</VARLISTENTRY>
|
||
|
|
<VARLISTENTRY>
|
||
|
|
<TERM>
|
||
|
|
<ReturnValue>
|
||
|
|
<replaceable class="parameter">output_function</replaceable>
|
||
|
|
</ReturnValue>
|
||
|
|
</TERM>
|
||
|
|
<LISTITEM>
|
||
|
|
<PARA>
|
||
|
|
The name of a function, created by CREATE FUNCTION, which
|
||
|
|
converts data from its internal form to a form suitable
|
||
|
|
for display.
|
||
|
|
</PARA>
|
||
|
|
</LISTITEM>
|
||
|
|
</VARLISTENTRY>
|
||
|
|
<VARLISTENTRY>
|
||
|
|
<TERM>
|
||
|
|
<ReturnValue>
|
||
|
|
<replaceable class="parameter">element</replaceable>
|
||
|
|
</ReturnValue>
|
||
|
|
</TERM>
|
||
|
|
<LISTITEM>
|
||
|
|
<PARA>
|
||
|
|
The type being created is an array; this specifies
|
||
|
|
the type of the array elements.
|
||
|
|
</PARA>
|
||
|
|
</LISTITEM>
|
||
|
|
</VARLISTENTRY>
|
||
|
|
<VARLISTENTRY>
|
||
|
|
<TERM>
|
||
|
|
<ReturnValue>
|
||
|
|
<replaceable class="parameter">delimiter</replaceable>
|
||
|
|
</ReturnValue>
|
||
|
|
</TERM>
|
||
|
|
<LISTITEM>
|
||
|
|
<PARA>
|
||
|
|
The delimiter character for the array.
|
||
|
|
</PARA>
|
||
|
|
</LISTITEM>
|
||
|
|
</VARLISTENTRY>
|
||
|
|
<VARLISTENTRY>
|
||
|
|
<TERM>
|
||
|
|
<ReturnValue>
|
||
|
|
<replaceable class="parameter">default</replaceable
|
||
|
|
></ReturnValue>
|
||
|
|
</TERM>
|
||
|
|
<LISTITEM>
|
||
|
|
<PARA>
|
||
|
|
The default text to be displayed to indicate "data
|
||
|
|
not present"
|
||
|
|
</PARA>
|
||
|
|
</LISTITEM>
|
||
|
|
</VARLISTENTRY>
|
||
|
|
<VARLISTENTRY>
|
||
|
|
<TERM>
|
||
|
|
<ReturnValue>
|
||
|
|
<replaceable class="parameter">send_function</replaceable>
|
||
|
|
</ReturnValue>
|
||
|
|
</TERM>
|
||
|
|
<LISTITEM>
|
||
|
|
<PARA>
|
||
|
|
The name of a function, created by CREATE FUNCTION, which
|
||
|
|
converts data of this type into a form suitable for
|
||
|
|
transmission to another machine.
|
||
|
|
<comment>Is this right?</comment>
|
||
|
|
</PARA>
|
||
|
|
</LISTITEM>
|
||
|
|
</VARLISTENTRY>
|
||
|
|
<VARLISTENTRY>
|
||
|
|
<TERM>
|
||
|
|
<ReturnValue>
|
||
|
|
<replaceable class="parameter">receive_function</replaceable>
|
||
|
|
</ReturnValue>
|
||
|
|
</TERM>
|
||
|
|
<LISTITEM>
|
||
|
|
<PARA>
|
||
|
|
The name of a function, created by CREATE FUNCTION, which
|
||
|
|
converts data of this type from a form suitable for
|
||
|
|
transmission from another machine to internal form.
|
||
|
|
<comment>Is this right?</comment>
|
||
|
|
</PARA>
|
||
|
|
</LISTITEM>
|
||
|
|
</VARLISTENTRY>
|
||
|
|
</variablelist>
|
||
|
|
</LISTITEM>
|
||
|
|
</VARLISTENTRY>
|
||
|
|
</VARIABLELIST>
|
||
|
|
</REFSECT2>
|
||
|
|
|
||
|
|
<REFSECT2 ID="R2-SQL-CREATETYPE-2">
|
||
|
|
<REFSECT2INFO>
|
||
|
|
<DATE>1998-04-15</DATE>
|
||
|
|
</REFSECT2INFO>
|
||
|
|
<TITLE>
|
||
|
|
Outputs
|
||
|
|
</TITLE>
|
||
|
|
<PARA>
|
||
|
|
</PARA>
|
||
|
|
<VARIABLELIST>
|
||
|
|
<VARLISTENTRY>
|
||
|
|
<TERM>
|
||
|
|
</TERM>
|
||
|
|
<LISTITEM>
|
||
|
|
<PARA>
|
||
|
|
<VARIABLELIST>
|
||
|
|
<VARLISTENTRY>
|
||
|
|
<TERM>
|
||
|
|
<ReturnValue>CREATE</ReturnValue>
|
||
|
|
</TERM>
|
||
|
|
<LISTITEM>
|
||
|
|
<PARA>
|
||
|
|
Message returned if the type is successfully created.
|
||
|
|
</PARA>
|
||
|
|
</LISTITEM>
|
||
|
|
</VARLISTENTRY>
|
||
|
|
</variablelist>
|
||
|
|
</LISTITEM>
|
||
|
|
</VARLISTENTRY>
|
||
|
|
</VARIABLELIST>
|
||
|
|
|
||
|
|
</REFSECT2>
|
||
|
|
</REFSYNOPSISDIV>
|
||
|
|
|
||
|
|
<REFSECT1 ID="R1-SQL-CREATETYPE-1">
|
||
|
|
<REFSECT1INFO>
|
||
|
|
<DATE>1998-04-15</DATE>
|
||
|
|
</REFSECT1INFO>
|
||
|
|
<TITLE>
|
||
|
|
Description
|
||
|
|
</TITLE>
|
||
|
|
<PARA>
|
||
|
|
CREATE TYPE allows the user to register a new user data
|
||
|
|
type with Postgres for use in the current data base. The
|
||
|
|
user who defines a type becomes its owner.
|
||
|
|
<replaceable class="parameter">Typename</replaceable> is
|
||
|
|
the name of the new type and must be unique within the
|
||
|
|
types defined for this database.
|
||
|
|
</para>
|
||
|
|
<PARA>
|
||
|
|
CREATE TYPE requires the registration of two functions
|
||
|
|
(using create function) before defining the type. The
|
||
|
|
representation of a new base type is determined by
|
||
|
|
<replaceable class="parameter">input_function</replaceable>, which
|
||
|
|
converts the type's external representation to an internal
|
||
|
|
representation usable by the
|
||
|
|
operators and functions defined for the type. Naturally,
|
||
|
|
<replaceable class="parameter">output_function</replaceable>
|
||
|
|
performs the reverse transformation. Both
|
||
|
|
the input and output functions must be declared to take
|
||
|
|
one or two arguments of type "<literal>opaque</literal>".
|
||
|
|
</para>
|
||
|
|
<PARA>
|
||
|
|
New base data types can be fixed length, in which case
|
||
|
|
<replaceable class="parameter">internallength</replaceable> is a
|
||
|
|
positive integer, or variable length,
|
||
|
|
in which case Postgres assumes that the new type has the
|
||
|
|
same format
|
||
|
|
as the Postgres-supplied data type, "<literal>text</literal>".
|
||
|
|
To indicate that a type is variable-length, set
|
||
|
|
<replaceable class="parameter">internallength</replaceable>
|
||
|
|
to VARIABLE.
|
||
|
|
The external representation is similarly specified using the
|
||
|
|
<replaceable class="parameter">externallength</replaceable>
|
||
|
|
keyword.
|
||
|
|
</para>
|
||
|
|
<PARA>
|
||
|
|
To indicate that a type is an array and to indicate that a
|
||
|
|
type has array elements, indicate the type of the array
|
||
|
|
element using the element keyword. For example, to define
|
||
|
|
an array of 4 byte integers ("int4"), specify
|
||
|
|
<programlisting>ELEMENT = int4</programlisting>
|
||
|
|
</para>
|
||
|
|
<PARA>
|
||
|
|
To indicate the delimiter to be used on arrays of this
|
||
|
|
type, <replaceable class="parameter">delimiter</replaceable>
|
||
|
|
can be
|
||
|
|
set to a specific character. The default delimiter is the comma
|
||
|
|
("<literal>,</literal>").
|
||
|
|
</para>
|
||
|
|
<PARA>
|
||
|
|
A default value is optionally available in case a user
|
||
|
|
wants some specific bit pattern to mean "data not present."
|
||
|
|
Specify the default with the DEFAULT keyword.
|
||
|
|
<comment>How does the user specify that bit pattern and associate
|
||
|
|
it with the fact that the data is not present></comment>
|
||
|
|
</para>
|
||
|
|
<PARA>
|
||
|
|
The optional functions
|
||
|
|
<replaceable class="parameter">send_function</replaceable> and
|
||
|
|
<replaceable class="parameter">receive_function</replaceable>
|
||
|
|
are used when the application program requesting Postgres
|
||
|
|
services resides on a different machine. In this case,
|
||
|
|
the machine on which Postgres runs may use a format for the data
|
||
|
|
type different from that used on the remote machine.
|
||
|
|
In this case it is appropriate to convert data items to a
|
||
|
|
standard form when sending from the server to the client
|
||
|
|
and converting from the standard format to the machine
|
||
|
|
specific format when the server receives the data from the
|
||
|
|
client. If these functions are not specified, then it is
|
||
|
|
assumed that the internal format of the type is acceptable
|
||
|
|
on all relevant machine architectures. For example, single
|
||
|
|
characters do not have to be converted if passed from
|
||
|
|
a Sun-4 to a DECstation, but many other types do.
|
||
|
|
</para>
|
||
|
|
<PARA>
|
||
|
|
The optional flag, PASSEDBYVALUE, indicates that operators
|
||
|
|
and functions which use this data type should be passed an
|
||
|
|
argument by value rather than by reference. Note that you
|
||
|
|
may not pass by value types whose internal representation is
|
||
|
|
more than four bytes.
|
||
|
|
</para>
|
||
|
|
<PARA>
|
||
|
|
For new base types, a user can define operators, functions
|
||
|
|
and aggregates using the appropriate facilities described
|
||
|
|
in this section.
|
||
|
|
</para>
|
||
|
|
<refsect2>
|
||
|
|
<title>Array Types</title>
|
||
|
|
<para>
|
||
|
|
Two generalized built-in functions, array_in and
|
||
|
|
array_out, exist for quick creation of variable-length
|
||
|
|
array types. These functions operate on arrays of any
|
||
|
|
existing Postgres type.</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
|
||
|
|
<comment>This section reference needs replacing</comment>
|
||
|
|
Section 7, the large object interface. The
|
||
|
|
length of all large object types is always VARIABLE.
|
||
|
|
</refsect2>
|
||
|
|
</refsect1>
|
||
|
|
<refsect1>
|
||
|
|
<title>Examples</title>
|
||
|
|
<para>
|
||
|
|
This command creates the box data type and then uses the
|
||
|
|
type in a class definition:
|
||
|
|
</para>
|
||
|
|
<programlisting>
|
||
|
|
CREATE TYPE box (INTERNALLENGTH = 8,
|
||
|
|
INPUT = my_procedure_1, OUTPUT = my_procedure_2)
|
||
|
|
|
||
|
|
CREATE TABLE myboxes (id INT4, description box)
|
||
|
|
</programlisting>
|
||
|
|
<para>
|
||
|
|
This command creates a variable length array type with
|
||
|
|
integer elements.
|
||
|
|
</para>
|
||
|
|
<programlisting>
|
||
|
|
CREATE TYPE int4array
|
||
|
|
(INPUT = array_in, OUTPUT = array_out,
|
||
|
|
INTERNALLENGTH = VARIABLE, ELEMENT = int4)
|
||
|
|
|
||
|
|
CREATE TABLE myarrays (id int4, numbers int4array)
|
||
|
|
</programlisting>
|
||
|
|
<para>
|
||
|
|
This command creates a large object type and uses it in
|
||
|
|
a class definition.
|
||
|
|
</para>
|
||
|
|
<programlisting>
|
||
|
|
CREATE TYPE bigobj
|
||
|
|
(INPUT = lo_filein, OUTPUT = lo_fileout,
|
||
|
|
INTERNALLENGTH = VARIABLE)
|
||
|
|
|
||
|
|
CREATE TABLE big_objs (id int4, obj bigobj)
|
||
|
|
</programlisting>
|
||
|
|
<refsect2>
|
||
|
|
<title>Restrictions</title>
|
||
|
|
<para>
|
||
|
|
Type names cannot begin with the underscore character
|
||
|
|
("_") and can only be 15 characters long. This is because
|
||
|
|
Postgres silently creates an array type for each base type
|
||
|
|
with a name consisting of the base type's name prepended
|
||
|
|
with an underscore.
|
||
|
|
</para>
|
||
|
|
</refsect2>
|
||
|
|
<REFSECT2 ID="R2-SQL-CREATETYPE-3">
|
||
|
|
<REFSECT2INFO>
|
||
|
|
<DATE>1998-04-15</DATE>
|
||
|
|
</REFSECT2INFO>
|
||
|
|
<TITLE>
|
||
|
|
Notes
|
||
|
|
</TITLE>
|
||
|
|
<PARA>
|
||
|
|
Refer to DROP TYPE statement to drop types.
|
||
|
|
</PARA>
|
||
|
|
<PARA>
|
||
|
|
See also CREATE FUNCTION, CREATE OPERATOR and large_objects.</para>
|
||
|
|
</REFSECT2>
|
||
|
|
</refsect1>
|
||
|
|
|
||
|
|
|
||
|
|
<REFSECT1 ID="R1-SQL-CREATETYPE-3">
|
||
|
|
<TITLE>
|
||
|
|
Compatibility
|
||
|
|
</TITLE>
|
||
|
|
<PARA>
|
||
|
|
CREATE TYPE statement is a PostgreSQL language extension.
|
||
|
|
</PARA>
|
||
|
|
|
||
|
|
<REFSECT2 ID="R2-SQL-CREATETYPE-4">
|
||
|
|
<REFSECT2INFO>
|
||
|
|
<DATE>1998-04-15</DATE>
|
||
|
|
</REFSECT2INFO>
|
||
|
|
<TITLE>
|
||
|
|
SQL3
|
||
|
|
</TITLE>
|
||
|
|
<PARA>
|
||
|
|
CREATE TYPE is a SQL3 statement.
|
||
|
|
</PARA>
|
||
|
|
|
||
|
|
</REFSECT2>
|
||
|
|
</REFENTRY>
|
||
|
|
|
||
|
|
|
||
|
|
<!-- Keep this comment at the end of the file
|
||
|
|
Local variables:
|
||
|
|
mode: sgml
|
||
|
|
sgml-omittag:t
|
||
|
|
sgml-shorttag:t
|
||
|
|
sgml-minimize-attributes:nil
|
||
|
|
sgml-always-quote-attributes:t
|
||
|
|
sgml-indent-step:1
|
||
|
|
sgml-indent-data:t
|
||
|
|
sgml-parent-document:nil
|
||
|
|
sgml-default-dtd-file:"../reference.ced"
|
||
|
|
sgml-exposed-tags:nil
|
||
|
|
sgml-local-catalogs:"/usr/lib/sgml/catalog"
|
||
|
|
sgml-local-ecat-files:nil
|
||
|
|
End:
|
||
|
|
-->
|