diff options
Diffstat (limited to 'doc/man/create_type.l')
| -rw-r--r-- | doc/man/create_type.l | 161 |
1 files changed, 161 insertions, 0 deletions
diff --git a/doc/man/create_type.l b/doc/man/create_type.l new file mode 100644 index 00000000000..42f1e677654 --- /dev/null +++ b/doc/man/create_type.l @@ -0,0 +1,161 @@ +.\" 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). |