diff options
Diffstat (limited to 'doc/src/sgml/man7/CREATE_CONVERSION.7')
| -rw-r--r-- | doc/src/sgml/man7/CREATE_CONVERSION.7 | 145 |
1 files changed, 145 insertions, 0 deletions
diff --git a/doc/src/sgml/man7/CREATE_CONVERSION.7 b/doc/src/sgml/man7/CREATE_CONVERSION.7 new file mode 100644 index 0000000..3bbb34c --- /dev/null +++ b/doc/src/sgml/man7/CREATE_CONVERSION.7 @@ -0,0 +1,145 @@ +'\" t +.\" Title: CREATE CONVERSION +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "CREATE CONVERSION" "7" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_CONVERSION \- define a new encoding conversion +.SH "SYNOPSIS" +.sp +.nf +CREATE [ DEFAULT ] CONVERSION \fIname\fR + FOR \fIsource_encoding\fR TO \fIdest_encoding\fR FROM \fIfunction_name\fR +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE CONVERSION\fR +defines a new conversion between two character set encodings\&. +.PP +Conversions that are marked +DEFAULT +can be used for automatic encoding conversion between client and server\&. To support that usage, two conversions, from encoding A to B +\fIand\fR +from encoding B to A, must be defined\&. +.PP +To be able to create a conversion, you must have +EXECUTE +privilege on the function and +CREATE +privilege on the destination schema\&. +.SH "PARAMETERS" +.PP +DEFAULT +.RS 4 +The +DEFAULT +clause indicates that this conversion is the default for this particular source to destination encoding\&. There should be only one default encoding in a schema for the encoding pair\&. +.RE +.PP +\fIname\fR +.RS 4 +The name of the conversion\&. The conversion name can be schema\-qualified\&. If it is not, the conversion is defined in the current schema\&. The conversion name must be unique within a schema\&. +.RE +.PP +\fIsource_encoding\fR +.RS 4 +The source encoding name\&. +.RE +.PP +\fIdest_encoding\fR +.RS 4 +The destination encoding name\&. +.RE +.PP +\fIfunction_name\fR +.RS 4 +The function used to perform the conversion\&. The function name can be schema\-qualified\&. If it is not, the function will be looked up in the path\&. +.sp +The function must have the following signature: +.sp +.if n \{\ +.RS 4 +.\} +.nf +conv_proc( + integer, \-\- source encoding ID + integer, \-\- destination encoding ID + cstring, \-\- source string (null terminated C string) + internal, \-\- destination (fill with a null terminated C string) + integer, \-\- source string length + boolean \-\- if true, don\*(Aqt throw an error if conversion fails +) RETURNS integer; +.fi +.if n \{\ +.RE +.\} +.sp +The return value is the number of source bytes that were successfully converted\&. If the last argument is false, the function must throw an error on invalid input, and the return value is always equal to the source string length\&. +.RE +.SH "NOTES" +.PP +Neither the source nor the destination encoding can be +SQL_ASCII, as the server\*(Aqs behavior for cases involving the +SQL_ASCII +\(lqencoding\(rq +is hard\-wired\&. +.PP +Use +\fBDROP CONVERSION\fR +to remove user\-defined conversions\&. +.PP +The privileges required to create a conversion might be changed in a future release\&. +.SH "EXAMPLES" +.PP +To create a conversion from encoding +UTF8 +to +LATIN1 +using +\fBmyfunc\fR: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE CONVERSION myconv FOR \*(AqUTF8\*(Aq TO \*(AqLATIN1\*(Aq FROM myfunc; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBCREATE CONVERSION\fR +is a +PostgreSQL +extension\&. There is no +\fBCREATE CONVERSION\fR +statement in the SQL standard, but a +\fBCREATE TRANSLATION\fR +statement that is very similar in purpose and syntax\&. +.SH "SEE ALSO" +ALTER CONVERSION (\fBALTER_CONVERSION\fR(7)), CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7)), DROP CONVERSION (\fBDROP_CONVERSION\fR(7)) |