| 1 |
<!-- |
| 2 |
doc/src/sgml/ref/create_conversion.sgml |
| 3 |
PostgreSQL documentation |
| 4 |
--> |
| 5 |
|
| 6 |
<refentry id="sql-createconversion"> |
| 7 |
<indexterm zone="sql-createconversion"> |
| 8 |
<primary>CREATE CONVERSION</primary> |
| 9 |
</indexterm> |
| 10 |
|
| 11 |
<refmeta> |
| 12 |
<refentrytitle>CREATE CONVERSION</refentrytitle> |
| 13 |
<manvolnum>7</manvolnum> |
| 14 |
<refmiscinfo>SQL - Language Statements</refmiscinfo> |
| 15 |
</refmeta> |
| 16 |
|
| 17 |
<refnamediv> |
| 18 |
<refname>CREATE CONVERSION</refname> |
| 19 |
<refpurpose>define a new encoding conversion</refpurpose> |
| 20 |
</refnamediv> |
| 21 |
|
| 22 |
<refsynopsisdiv> |
| 23 |
<synopsis> |
| 24 |
CREATE [ DEFAULT ] CONVERSION <replaceable>name</replaceable> |
| 25 |
FOR <replaceable>source_encoding</replaceable> TO <replaceable>dest_encoding</replaceable> FROM <replaceable>function_name</replaceable> |
| 26 |
</synopsis> |
| 27 |
</refsynopsisdiv> |
| 28 |
|
| 29 |
<refsect1 id="sql-createconversion-description"> |
| 30 |
<title>Description</title> |
| 31 |
|
| 32 |
<para> |
| 33 |
<command>CREATE CONVERSION</command> defines a new conversion between |
| 34 |
two character set encodings. |
| 35 |
</para> |
| 36 |
|
| 37 |
<para> |
| 38 |
Conversions that are marked <literal>DEFAULT</literal> can be used for |
| 39 |
automatic encoding conversion between client and server. To support that |
| 40 |
usage, two conversions, from encoding A to B <emphasis>and</emphasis> |
| 41 |
from encoding B to A, must be defined. |
| 42 |
</para> |
| 43 |
|
| 44 |
<para> |
| 45 |
To be able to create a conversion, you must have <literal>EXECUTE</literal> privilege |
| 46 |
on the function and <literal>CREATE</literal> privilege on the destination schema. |
| 47 |
</para> |
| 48 |
</refsect1> |
| 49 |
|
| 50 |
|
| 51 |
<refsect1> |
| 52 |
<title>Parameters</title> |
| 53 |
|
| 54 |
<variablelist> |
| 55 |
<varlistentry> |
| 56 |
<term><literal>DEFAULT</literal></term> |
| 57 |
|
| 58 |
<listitem> |
| 59 |
<para> |
| 60 |
The <literal>DEFAULT</literal> clause indicates that this conversion |
| 61 |
is the default for this particular source to destination |
| 62 |
encoding. There should be only one default encoding in a schema |
| 63 |
for the encoding pair. |
| 64 |
</para> |
| 65 |
</listitem> |
| 66 |
</varlistentry> |
| 67 |
|
| 68 |
<varlistentry> |
| 69 |
<term><replaceable>name</replaceable></term> |
| 70 |
|
| 71 |
<listitem> |
| 72 |
<para> |
| 73 |
The name of the conversion. The conversion name can be |
| 74 |
schema-qualified. If it is not, the conversion is defined in the |
| 75 |
current schema. The conversion name must be unique within a |
| 76 |
schema. |
| 77 |
</para> |
| 78 |
</listitem> |
| 79 |
</varlistentry> |
| 80 |
|
| 81 |
<varlistentry> |
| 82 |
<term><replaceable>source_encoding</replaceable></term> |
| 83 |
|
| 84 |
<listitem> |
| 85 |
<para> |
| 86 |
The source encoding name. |
| 87 |
</para> |
| 88 |
</listitem> |
| 89 |
</varlistentry> |
| 90 |
|
| 91 |
<varlistentry> |
| 92 |
<term><replaceable>dest_encoding</replaceable></term> |
| 93 |
|
| 94 |
<listitem> |
| 95 |
<para> |
| 96 |
The destination encoding name. |
| 97 |
</para> |
| 98 |
</listitem> |
| 99 |
</varlistentry> |
| 100 |
|
| 101 |
<varlistentry> |
| 102 |
<term><replaceable>function_name</replaceable></term> |
| 103 |
|
| 104 |
<listitem> |
| 105 |
<para> |
| 106 |
The function used to perform the conversion. The function name can |
| 107 |
be schema-qualified. If it is not, the function will be looked |
| 108 |
up in the path. |
| 109 |
</para> |
| 110 |
|
| 111 |
<para> |
| 112 |
The function must have the following signature: |
| 113 |
|
| 114 |
<programlisting> |
| 115 |
conv_proc( |
| 116 |
integer, -- source encoding ID |
| 117 |
integer, -- destination encoding ID |
| 118 |
cstring, -- source string (null terminated C string) |
| 119 |
internal, -- destination (fill with a null terminated C string) |
| 120 |
integer, -- source string length |
| 121 |
boolean -- if true, don't throw an error if conversion fails |
| 122 |
) RETURNS integer; |
| 123 |
</programlisting> |
| 124 |
The return value is the number of source bytes that were successfully |
| 125 |
converted. If the last argument is false, the function must throw an |
| 126 |
error on invalid input, and the return value is always equal to the |
| 127 |
source string length. |
| 128 |
</para> |
| 129 |
</listitem> |
| 130 |
</varlistentry> |
| 131 |
</variablelist> |
| 132 |
</refsect1> |
| 133 |
|
| 134 |
<refsect1 id="sql-createconversion-notes"> |
| 135 |
<title>Notes</title> |
| 136 |
|
| 137 |
<para> |
| 138 |
Neither the source nor the destination encoding can |
| 139 |
be <literal>SQL_ASCII</literal>, as the server's behavior for cases |
| 140 |
involving the <literal>SQL_ASCII</literal> <quote>encoding</quote> is |
| 141 |
hard-wired. |
| 142 |
</para> |
| 143 |
|
| 144 |
<para> |
| 145 |
Use <command>DROP CONVERSION</command> to remove user-defined conversions. |
| 146 |
</para> |
| 147 |
|
| 148 |
<para> |
| 149 |
The privileges required to create a conversion might be changed in a future |
| 150 |
release. |
| 151 |
</para> |
| 152 |
</refsect1> |
| 153 |
|
| 154 |
<refsect1 id="sql-createconversion-examples"> |
| 155 |
<title>Examples</title> |
| 156 |
|
| 157 |
<para> |
| 158 |
To create a conversion from encoding <literal>UTF8</literal> to |
| 159 |
<literal>LATIN1</literal> using <function>myfunc</function>: |
| 160 |
<programlisting> |
| 161 |
CREATE CONVERSION myconv FOR 'UTF8' TO 'LATIN1' FROM myfunc; |
| 162 |
</programlisting></para> |
| 163 |
</refsect1> |
| 164 |
|
| 165 |
|
| 166 |
<refsect1 id="sql-createconversion-compat"> |
| 167 |
<title>Compatibility</title> |
| 168 |
|
| 169 |
<para> |
| 170 |
<command>CREATE CONVERSION</command> |
| 171 |
is a <productname>PostgreSQL</productname> extension. |
| 172 |
There is no <command>CREATE CONVERSION</command> |
| 173 |
statement in the SQL standard, but a <command>CREATE TRANSLATION</command> |
| 174 |
statement that is very similar in purpose and syntax. |
| 175 |
</para> |
| 176 |
</refsect1> |
| 177 |
|
| 178 |
|
| 179 |
<refsect1 id="sql-createconversion-seealso"> |
| 180 |
<title>See Also</title> |
| 181 |
|
| 182 |
<simplelist type="inline"> |
| 183 |
<member><xref linkend="sql-alterconversion"/></member> |
| 184 |
<member><xref linkend="sql-createfunction"/></member> |
| 185 |
<member><xref linkend="sql-dropconversion"/></member> |
| 186 |
</simplelist> |
| 187 |
</refsect1> |
| 188 |
|
| 189 |
</refentry> |