granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/create_conversion.sgml

   1 <!-- doc/src/sgml/ref/create_conversion.sgml -->
   2
   3 <refentry id="SQL-CREATECONVERSION">
   4  <refmeta>
   5   <refentrytitle>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>function_name</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>function_name</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></para>
 117      </listitem>
 118     </varlistentry>
 119    </variablelist>
 120  </refsect1>
 121
 122  <refsect1 id="sql-createconversion-notes">
 123   <title>Notes</title>
 124
 125   <para>
 126    Use <command>DROP CONVERSION</command> to remove user-defined conversions.
 127   </para>
 128
 129   <para>
 130    The privileges required to create a conversion might be changed in a future
 131    release.
 132   </para>
 133  </refsect1>
 134
 135  <refsect1 id="sql-createconversion-examples">
 136   <title>Examples</title>
 137
 138   <para>
 139    To create a conversion from encoding <literal>UTF8</literal> to
 140    <literal>LATIN1</literal> using <function>myfunc</>:
 141 <programlisting>
 142 CREATE CONVERSION myconv FOR 'UTF8' TO 'LATIN1' FROM myfunc;
 143 </programlisting></para>
 144  </refsect1>
 145
 146
 147  <refsect1 id="sql-createconversion-compat">
 148   <title>Compatibility</title>
 149
 150   <para>
 151     <command>CREATE CONVERSION</command>
 152     is a <productname>PostgreSQL</productname> extension.
 153     There is no <command>CREATE CONVERSION</command>
 154     statement in the SQL standard, but a <command>CREATE TRANSLATION</command>
 155     statement that is very similar in purpose and syntax.
 156   </para>
 157  </refsect1>
 158
 159
 160  <refsect1 id="sql-createconversion-seealso">
 161   <title>See Also</title>
 162
 163   <simplelist type="inline">
 164    <member><xref linkend="sql-alterconversion"></member>
 165    <member><xref linkend="sql-createfunction"></member>
 166    <member><xref linkend="sql-dropconversion"></member>
 167   </simplelist>
 168  </refsect1>
 169
 170 </refentry>