1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/create_conversion.sgml,v 1.14.4.1 2005-05-03 19:18:15 tgl Exp $ -->
3
<refentry id="SQL-CREATECONVERSION">
5
<refentrytitle id="SQL-CREATECONVERSION-TITLE">CREATE CONVERSION</refentrytitle>
6
<refmiscinfo>SQL - Language Statements</refmiscinfo>
10
<refname>CREATE CONVERSION</refname>
11
<refpurpose>define a new encoding conversion</refpurpose>
14
<indexterm zone="sql-createconversion">
15
<primary>CREATE CONVERSION</primary>
20
CREATE [DEFAULT] CONVERSION <replaceable>name</replaceable>
21
FOR <replaceable>source_encoding</replaceable> TO <replaceable>dest_encoding</replaceable> FROM <replaceable>funcname</replaceable>
25
<refsect1 id="sql-createconversion-description">
26
<title>Description</title>
29
<command>CREATE CONVERSION</command> defines a new conversion between
30
character set encodings. Conversion names may be used in the
31
<function>convert</function> function
32
to specify a particular encoding conversion. Also, conversions that
33
are marked <literal>DEFAULT</> can be used for automatic encoding
35
client and server. For this purpose, two conversions, from encoding A to
36
B <emphasis>and</emphasis> from encoding B to A, must be defined.
40
To be able to create a conversion, you must have <literal>EXECUTE</literal> privilege
41
on the function and <literal>CREATE</literal> privilege on the destination schema.
47
<title>Parameters</title>
51
<term><literal>DEFAULT</literal></term>
55
The <literal>DEFAULT</> clause indicates that this conversion
56
is the default for this particular source to destination
57
encoding. There should be only one default encoding in a schema
58
for the encoding pair.
64
<term><replaceable>name</replaceable></term>
68
The name of the conversion. The conversion name may be
69
schema-qualified. If it is not, the conversion is defined in the
70
current schema. The conversion name must be unique within a
77
<term><replaceable>source_encoding</replaceable></term>
81
The source encoding name.
87
<term><replaceable>dest_encoding</replaceable></term>
91
The destination encoding name.
97
<term><replaceable>funcname</replaceable></term>
101
The function used to perform the conversion. The function name may
102
be schema-qualified. If it is not, the function will be looked
107
The function must have the following signature:
111
integer, -- source encoding ID
112
integer, -- destination encoding ID
113
cstring, -- source string (null terminated C string)
114
internal, -- destination (fill with a null terminated C string)
115
integer -- source string length
124
<refsect1 id="sql-createconversion-notes">
128
Use <command>DROP CONVERSION</command> to remove user-defined conversions.
132
The privileges required to create a conversion may be changed in a future
137
<refsect1 id="sql-createconversion-examples">
138
<title>Examples</title>
141
To create a conversion from encoding <literal>UNICODE</literal> to
142
<literal>LATIN1</literal> using <function>myfunc</>:
144
CREATE CONVERSION myconv FOR 'UNICODE' TO 'LATIN1' FROM myfunc;
150
<refsect1 id="sql-createconversion-compat">
151
<title>Compatibility</title>
154
<command>CREATE CONVERSION</command>
155
is a <productname>PostgreSQL</productname> extension.
156
There is no <command>CREATE CONVERSION</command>
157
statement in the SQL standard.
162
<refsect1 id="sql-createconversion-seealso">
163
<title>See Also</title>
165
<simplelist type="inline">
166
<member><xref linkend="sql-alterconversion" endterm="sql-alterconversion-title"></member>
167
<member><xref linkend="sql-createfunction" endterm="sql-createfunction-title"></member>
168
<member><xref linkend="sql-dropconversion" endterm="sql-dropconversion-title"></member>
174
<!-- Keep this comment at the end of the file
179
sgml-minimize-attributes:nil
180
sgml-always-quote-attributes:t
183
sgml-parent-document:nil
184
sgml-default-dtd-file:"../reference.ced"
185
sgml-exposed-tags:nil
186
sgml-local-catalogs:("/usr/lib/sgml/catalog")
187
sgml-local-ecat-files:nil