2010-04-03 09:23:02 +02:00
|
|
|
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/create_conversion.sgml,v 1.23 2010/04/03 07:22:58 petere Exp $ -->
|
2002-07-22 10:57:15 +02:00
|
|
|
|
|
|
|
<refentry id="SQL-CREATECONVERSION">
|
|
|
|
<refmeta>
|
2010-04-03 09:23:02 +02:00
|
|
|
<refentrytitle>CREATE CONVERSION</refentrytitle>
|
2008-11-14 11:22:48 +01:00
|
|
|
<manvolnum>7</manvolnum>
|
2002-07-22 10:57:15 +02:00
|
|
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
|
|
|
</refmeta>
|
|
|
|
|
|
|
|
<refnamediv>
|
|
|
|
<refname>CREATE CONVERSION</refname>
|
2005-05-03 21:17:59 +02:00
|
|
|
<refpurpose>define a new encoding conversion</refpurpose>
|
2002-07-22 10:57:15 +02:00
|
|
|
</refnamediv>
|
|
|
|
|
2003-08-31 19:32:24 +02:00
|
|
|
<indexterm zone="sql-createconversion">
|
|
|
|
<primary>CREATE CONVERSION</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
2002-07-22 10:57:15 +02:00
|
|
|
<refsynopsisdiv>
|
|
|
|
<synopsis>
|
2006-01-11 23:16:39 +01:00
|
|
|
CREATE [ DEFAULT ] CONVERSION <replaceable>name</replaceable>
|
2009-09-19 12:23:27 +02:00
|
|
|
FOR <replaceable>source_encoding</replaceable> TO <replaceable>dest_encoding</replaceable> FROM <replaceable>function_name</replaceable>
|
2002-07-22 10:57:15 +02:00
|
|
|
</synopsis>
|
|
|
|
</refsynopsisdiv>
|
|
|
|
|
|
|
|
<refsect1 id="sql-createconversion-description">
|
|
|
|
<title>Description</title>
|
|
|
|
|
|
|
|
<para>
|
2005-05-03 21:17:59 +02:00
|
|
|
<command>CREATE CONVERSION</command> defines a new conversion between
|
2007-09-24 03:29:30 +02:00
|
|
|
character set encodings. Also, conversions that
|
2005-05-03 21:17:59 +02:00
|
|
|
are marked <literal>DEFAULT</> can be used for automatic encoding
|
|
|
|
conversion between
|
2003-04-22 12:08:08 +02:00
|
|
|
client and server. For this purpose, two conversions, from encoding A to
|
|
|
|
B <emphasis>and</emphasis> from encoding B to A, must be defined.
|
2002-07-22 10:57:15 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2003-04-22 12:08:08 +02:00
|
|
|
To be able to create a conversion, you must have <literal>EXECUTE</literal> privilege
|
|
|
|
on the function and <literal>CREATE</literal> privilege on the destination schema.
|
2002-07-22 10:57:15 +02:00
|
|
|
</para>
|
2003-04-22 12:08:08 +02:00
|
|
|
</refsect1>
|
2002-07-22 10:57:15 +02:00
|
|
|
|
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Parameters</title>
|
|
|
|
|
|
|
|
<variablelist>
|
2002-07-22 10:57:15 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><literal>DEFAULT</literal></term>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The <literal>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
|
2002-11-02 03:33:03 +01:00
|
|
|
for the encoding pair.
|
2002-07-22 10:57:15 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2003-06-25 01:29:25 +02:00
|
|
|
<term><replaceable>name</replaceable></term>
|
2002-07-22 10:57:15 +02:00
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
Update reference documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
|
|
|
The name of the conversion. The conversion name can be
|
2002-11-02 03:33:03 +01:00
|
|
|
schema-qualified. If it is not, the conversion is defined in the
|
|
|
|
current schema. The conversion name must be unique within a
|
2002-07-22 10:57:15 +02:00
|
|
|
schema.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable>source_encoding</replaceable></term>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The source encoding name.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2003-04-22 12:08:08 +02:00
|
|
|
<term><replaceable>dest_encoding</replaceable></term>
|
2002-07-22 10:57:15 +02:00
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The destination encoding name.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2009-09-19 12:23:27 +02:00
|
|
|
<term><replaceable>function_name</replaceable></term>
|
2002-07-22 10:57:15 +02:00
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
Update reference documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
|
|
|
The function used to perform the conversion. The function name can
|
2002-07-22 10:57:15 +02:00
|
|
|
be schema-qualified. If it is not, the function will be looked
|
|
|
|
up in the path.
|
2003-04-22 12:08:08 +02:00
|
|
|
</para>
|
2002-07-22 10:57:15 +02:00
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<para>
|
2002-11-02 03:33:03 +01:00
|
|
|
The function must have the following signature:
|
2002-07-22 10:57:15 +02:00
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<programlisting>
|
|
|
|
conv_proc(
|
|
|
|
integer, -- source encoding ID
|
|
|
|
integer, -- destination encoding ID
|
|
|
|
cstring, -- source string (null terminated C string)
|
2005-05-03 21:17:59 +02:00
|
|
|
internal, -- destination (fill with a null terminated C string)
|
2003-04-22 12:08:08 +02:00
|
|
|
integer -- source string length
|
|
|
|
) RETURNS void;
|
|
|
|
</programlisting>
|
2002-07-22 10:57:15 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
2003-04-22 12:08:08 +02:00
|
|
|
</refsect1>
|
2002-07-22 10:57:15 +02:00
|
|
|
|
|
|
|
<refsect1 id="sql-createconversion-notes">
|
|
|
|
<title>Notes</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Use <command>DROP CONVERSION</command> to remove user-defined conversions.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
Update reference documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
|
|
|
The privileges required to create a conversion might be changed in a future
|
2002-07-22 10:57:15 +02:00
|
|
|
release.
|
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1 id="sql-createconversion-examples">
|
|
|
|
<title>Examples</title>
|
|
|
|
|
|
|
|
<para>
|
2005-03-07 05:30:55 +01:00
|
|
|
To create a conversion from encoding <literal>UTF8</literal> to
|
2003-04-22 12:08:08 +02:00
|
|
|
<literal>LATIN1</literal> using <function>myfunc</>:
|
2002-07-22 10:57:15 +02:00
|
|
|
<programlisting>
|
2005-03-07 05:30:55 +01:00
|
|
|
CREATE CONVERSION myconv FOR 'UTF8' TO 'LATIN1' FROM myfunc;
|
2002-07-22 10:57:15 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
|
|
|
|
<refsect1 id="sql-createconversion-compat">
|
|
|
|
<title>Compatibility</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<command>CREATE CONVERSION</command>
|
|
|
|
is a <productname>PostgreSQL</productname> extension.
|
2002-07-22 15:00:00 +02:00
|
|
|
There is no <command>CREATE CONVERSION</command>
|
2003-04-22 12:08:08 +02:00
|
|
|
statement in the SQL standard.
|
2002-07-22 10:57:15 +02:00
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
|
|
|
|
<refsect1 id="sql-createconversion-seealso">
|
|
|
|
<title>See Also</title>
|
|
|
|
|
2003-06-27 16:45:32 +02:00
|
|
|
<simplelist type="inline">
|
2010-04-03 09:23:02 +02:00
|
|
|
<member><xref linkend="sql-alterconversion"></member>
|
|
|
|
<member><xref linkend="sql-createfunction"></member>
|
|
|
|
<member><xref linkend="sql-dropconversion"></member>
|
2003-06-27 16:45:32 +02:00
|
|
|
</simplelist>
|
2002-07-22 10:57:15 +02:00
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
</refentry>
|