doc/src/sgml/ref/create_conversion.sgml

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