| <!-- $PostgreSQL: pgsql/doc/src/sgml/ref/create_conversion.sgml,v 1.18 2006/09/16 00:30:17 momjian Exp $ --> |
| |
| <refentry id="SQL-CREATECONVERSION"> |
| <refmeta> |
| <refentrytitle id="SQL-CREATECONVERSION-TITLE">CREATE CONVERSION</refentrytitle> |
| <refmiscinfo>SQL - Language Statements</refmiscinfo> |
| </refmeta> |
| |
| <refnamediv> |
| <refname>CREATE CONVERSION</refname> |
| <refpurpose>define a new encoding conversion</refpurpose> |
| </refnamediv> |
| |
| <indexterm zone="sql-createconversion"> |
| <primary>CREATE CONVERSION</primary> |
| </indexterm> |
| |
| <refsynopsisdiv> |
| <synopsis> |
| CREATE [ DEFAULT ] CONVERSION <replaceable>name</replaceable> |
| FOR <replaceable>source_encoding</replaceable> TO <replaceable>dest_encoding</replaceable> FROM <replaceable>funcname</replaceable> |
| </synopsis> |
| </refsynopsisdiv> |
| |
| <refsect1 id="sql-createconversion-description"> |
| <title>Description</title> |
| |
| <para> |
| <command>CREATE CONVERSION</command> defines a new conversion between |
| character set encodings. Conversion names may be used in the |
| <function>convert</function> function |
| to specify a particular encoding conversion. Also, conversions that |
| are marked <literal>DEFAULT</> can be used for automatic encoding |
| conversion between |
| client and server. For this purpose, two conversions, from encoding A to |
| B <emphasis>and</emphasis> from encoding B to A, must be defined. |
| </para> |
| |
| <para> |
| 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. |
| </para> |
| </refsect1> |
| |
| |
| <refsect1> |
| <title>Parameters</title> |
| |
| <variablelist> |
| <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 |
| for the encoding pair. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><replaceable>name</replaceable></term> |
| |
| <listitem> |
| <para> |
| The name of the conversion. The conversion name may be |
| schema-qualified. If it is not, the conversion is defined in the |
| current schema. The conversion name must be unique within a |
| schema. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><replaceable>source_encoding</replaceable></term> |
| |
| <listitem> |
| <para> |
| The source encoding name. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><replaceable>dest_encoding</replaceable></term> |
| |
| <listitem> |
| <para> |
| The destination encoding name. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><replaceable>funcname</replaceable></term> |
| |
| <listitem> |
| <para> |
| The function used to perform the conversion. The function name may |
| be schema-qualified. If it is not, the function will be looked |
| up in the path. |
| </para> |
| |
| <para> |
| The function must have the following signature: |
| |
| <programlisting> |
| 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 |
| ) RETURNS void; |
| </programlisting> |
| </para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </refsect1> |
| |
| <refsect1 id="sql-createconversion-notes"> |
| <title>Notes</title> |
| |
| <para> |
| Use <command>DROP CONVERSION</command> to remove user-defined conversions. |
| </para> |
| |
| <para> |
| The privileges required to create a conversion may be changed in a future |
| release. |
| </para> |
| </refsect1> |
| |
| <refsect1 id="sql-createconversion-examples"> |
| <title>Examples</title> |
| |
| <para> |
| To create a conversion from encoding <literal>UTF8</literal> to |
| <literal>LATIN1</literal> using <function>myfunc</>: |
| <programlisting> |
| CREATE CONVERSION myconv FOR 'UTF8' TO 'LATIN1' FROM myfunc; |
| </programlisting> |
| </para> |
| </refsect1> |
| |
| |
| <refsect1 id="sql-createconversion-compat"> |
| <title>Compatibility</title> |
| |
| <para> |
| <command>CREATE CONVERSION</command> |
| is a <productname>PostgreSQL</productname> extension. |
| There is no <command>CREATE CONVERSION</command> |
| statement in the SQL standard. |
| </para> |
| </refsect1> |
| |
| |
| <refsect1 id="sql-createconversion-seealso"> |
| <title>See Also</title> |
| |
| <simplelist type="inline"> |
| <member><xref linkend="sql-alterconversion" endterm="sql-alterconversion-title"></member> |
| <member><xref linkend="sql-createfunction" endterm="sql-createfunction-title"></member> |
| <member><xref linkend="sql-dropconversion" endterm="sql-dropconversion-title"></member> |
| </simplelist> |
| </refsect1> |
| |
| </refentry> |