162 lines
5.4 KiB
Plaintext
162 lines
5.4 KiB
Plaintext
.\" This is -*-nroff-*-
|
|
.\" XXX standard disclaimer belongs here....
|
|
.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_type.l,v 1.1.1.1 1996/08/18 22:14:22 scrappy Exp $
|
|
.TH "CREATE TYPE" SQL 11/05/95 Postgres95 Postgres95
|
|
.SH NAME
|
|
create type \(em define a new base data type
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fBcreate type\fP typename \fB(\fR\fBinternallength\fR = (number | \fBvariable\fR),
|
|
[ \fBexternallength\fR = (number | \fBvariable\fR)\fB,\fR ]
|
|
\fBinput\fR = input_function,
|
|
\fBoutput\fR = output_function
|
|
[\fB,\fR \fBelement\fR = typename]
|
|
[\fB,\fR \fBdelimiter\fR = <character>]
|
|
[\fB,\fR \fBdefault\fR = "string" ]
|
|
[\fB,\fR \fBsend\fR = send_function ]
|
|
[\fB,\fR \fBreceive\fR = receive_function ]
|
|
[\fB,\fR \fBpassedbyvalue\fR]\fB)\fR
|
|
.fi
|
|
.\" \fBcreate type\fP typename as sql_commands
|
|
.SH DESCRIPTION
|
|
.BR "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.
|
|
.IR Typename
|
|
is the name of the new type and must be unique within the types
|
|
defined for this database.
|
|
.PP
|
|
.BR "Create type"
|
|
requires the registration of two functions (using
|
|
.IR "create function" (l))
|
|
before defining the type. The representation of a new base type is
|
|
determined by
|
|
.IR input_function ,
|
|
which converts the type's external representation to an internal
|
|
representation usable by the operators and functions defined for the
|
|
type. Naturally,
|
|
.IR "output_function"
|
|
performs the reverse transformation. Both the input and output
|
|
functions must be declared to take one or two arguments of type
|
|
\*(lqopaque\*(rq.
|
|
.PP
|
|
New base data types can be fixed length, in which case
|
|
.BR "internallength"
|
|
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,
|
|
\*(lqtext\*(rq. To indicate that a type is variable-length, set
|
|
.BR "internallength"
|
|
to
|
|
.IR "variable" .
|
|
The external representation is similarly specified using the
|
|
.IR "externallength"
|
|
keyword.
|
|
.PP
|
|
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
|
|
.BR "element"
|
|
keyword. For example, to define an array of 4 byte integers
|
|
(\*(lqint4\*(rq), specify
|
|
.nf
|
|
element = int4
|
|
.fi
|
|
.PP
|
|
To indicate the delimiter to be used on arrays of this type,
|
|
.BR "delimiter"
|
|
can be set to a specific character. The default delimiter is the
|
|
comma (\*(lq,\*(rq) character.
|
|
.PP
|
|
A
|
|
.BR "default"
|
|
value is optionally available in case a user wants some specific bit
|
|
pattern to mean \*(lqdata not present.\*(rq
|
|
.PP
|
|
The optional functions
|
|
.IR "send_function"
|
|
and
|
|
.IR "receive_function"
|
|
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 different format for the data type than used on
|
|
the remote machine. In this case it is appropriate to convert data
|
|
items to a standard form when
|
|
.BR send ing
|
|
from the server to the client and converting from the standard format
|
|
to the machine specific format when the server
|
|
.BR receive s
|
|
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.
|
|
.PP
|
|
The optional
|
|
.BR "passedbyvalue"
|
|
flag indicates that operators and functions which use this data type
|
|
should be passed an argument by value rather than by reference. Note
|
|
that only types whose internal representation is at most four bytes
|
|
may be passed by value.
|
|
.PP
|
|
For new base types, a user can define operators, functions and
|
|
aggregates using the appropriate facilities described in this section.
|
|
.SH "ARRAY TYPES"
|
|
Two generalized built-in functions,
|
|
.BR array_in
|
|
and
|
|
.BR array_out,
|
|
exist for quick creation of variable-length array types. These
|
|
functions operate on arrays of any existing Postgres type.
|
|
.SH "LARGE OBJECT TYPES"
|
|
A \*(lqregular\*(rq 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 Section 7, the
|
|
large object interface. The length of all large object types
|
|
is always
|
|
.IR variable,
|
|
meaning the
|
|
.BR internallength
|
|
for large objects is always -1.
|
|
.SH EXAMPLES
|
|
.nf
|
|
--
|
|
--This command creates the box data type and then uses the
|
|
--type in a class definition
|
|
--
|
|
create type box (internallength = 8,
|
|
input = my_procedure_1, output = my_procedure_2)
|
|
|
|
create table MYBOXES (id = int4, description = box)
|
|
.fi
|
|
.nf
|
|
--
|
|
--This command creates a variable length array type with
|
|
--integer elements.
|
|
--
|
|
create type int4array
|
|
(input = array_in, output = array_out,
|
|
internallength = variable, element = int4)
|
|
|
|
create table MYARRAYS (id = int4, numbers = int4array)
|
|
.fi
|
|
.nf
|
|
--
|
|
--This command creates a large object type and uses it in
|
|
--a class definition.
|
|
--
|
|
create type bigobj
|
|
(input = lo_filein, output = lo_fileout,
|
|
internallength = variable)
|
|
|
|
create table BIG_OBJS (id = int4, obj = bigobj)
|
|
.fi
|
|
.SH "RESTRICTIONS"
|
|
Type names cannot begin with the underscore character (\*(lq_\*(rq)
|
|
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.
|
|
.SH "SEE ALSO"
|
|
create function(l),
|
|
create operator(l),
|
|
drop type(l),
|
|
introduction(large objects).
|