Add CREATE CONVERSION/DROP CONVERSOION reference manual

4 files changed, 319 insertions, 2 deletions

diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml
index 55b4fc5c9f0..a37d58ab7d9 100644
--- a/doc/src/sgml/ref/allfiles.sgml
+++ b/doc/src/sgml/ref/allfiles.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.41 2002/07/18 23:11:27 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.42 2002/07/22 08:57:15 ishii Exp $
 PostgreSQL documentation
 Complete list of usable sgml source files in this directory.
 -->
@@ -53,6 +53,7 @@ Complete list of usable sgml source files in this directory.
 <!entity createAggregate    system "create_aggregate.sgml">
 <!entity createCast         system "create_cast.sgml">
 <!entity createConstraint   system "create_constraint.sgml">
+<!entity createConversion   system "create_conversion.sgml">
 <!entity createDatabase     system "create_database.sgml">
 <!entity createDomain       system "create_domain.sgml">
 <!entity createFunction     system "create_function.sgml">
@@ -73,6 +74,7 @@ Complete list of usable sgml source files in this directory.
 <!entity delete             system "delete.sgml">
 <!entity dropAggregate      system "drop_aggregate.sgml">
 <!entity dropCast           system "drop_cast.sgml">
+<!entity dropConversion     system "drop_conversion.sgml">
 <!entity dropDatabase       system "drop_database.sgml">
 <!entity dropDomain         system "drop_domain.sgml">
 <!entity dropFunction       system "drop_function.sgml">
diff --git a/doc/src/sgml/ref/create_conversion.sgml b/doc/src/sgml/ref/create_conversion.sgml
new file mode 100644
index 00000000000..1edc5d2f933
--- /dev/null
+++ b/doc/src/sgml/ref/create_conversion.sgml
@@ -0,0 +1,189 @@
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/create_conversion.sgml,v 1.1 2002/07/22 08:57:15 ishii 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 user-defined conversion</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+CREATE [DEFAULT] CONVERSION <replaceable>conversion_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 encoding
+   conversion. There are two kinds of conversions. A default
+   conversion is used for an automatic encoding conversion between
+   frontend and backend. There should be only one default conversion
+   for source/destination encodings pair in a schema. None default
+   conversion never be used for the automatic conversion. Instead it
+   can be used for CONVERT() function.
+ </para>
+
+  <para>
+   To be able to create a conversion, you must have the execute right
+   on the function and the usage right on the schema the function
+   belongs to.
+  </para>
+
+   <variablelist>
+    <title>Parameters</title>
+
+    <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. A default encoding can be used for not
+       only CONVERT() function, but also for the automatic encoding
+       conversion between frontend and backend. For this purpose, two
+       conversions, from encoding A to B AND encoding B to A, must be
+       defined.
+      </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry>
+     <term><replaceable>conversion_name</replaceable></term>
+
+     <listitem>
+      <para>
+       The name of the conversion. The conversion name may be
+       schema-qualified. If it is not, a conversion is defined in the
+       current schema. The conversion name must be unique with in a
+       schema.
+      </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry>
+     <term><replaceable>source_encoding</replaceable></term>
+
+     <listitem>
+      <para>
+       The source encoding name.
+      </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry>
+     <term><replaceable>source_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 following signature:
+
+       <programlisting>
+	conv_proc(
+	INTEGER,	-- source encoding id
+	INTEGER,	-- destination encoding id
+	OPAQUE,		-- source string (null terminated C string)
+	OPAQUE,		-- destination string (null terminated C string)
+	INTEGER		-- source string length
+	) returns INTEGER;	-- dummy. returns nothing, actually.
+       </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 UNICODE to LATIN1 using myfunc:
+<programlisting>
+CREATE CONVERSION myconv FOR 'UNICODE' 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 OPERATOR</command>
+    statement in <acronym>SQL99</acronym>.
+  </para>
+ </refsect1>
+
+
+ <refsect1 id="sql-createconversion-seealso">
+  <title>See Also</title>
+
+  <para>
+   <xref linkend="sql-createfunction" endterm="sql-createfunction-title">,
+   <xref linkend="sql-dropconversion" endterm="sql-dropconversion-title">,
+   <citetitle>PostgreSQL Programmer's Guide</citetitle>
+  </para>
+ </refsect1>
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode:sgml
+sgml-omittag:nil
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"../reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:("/usr/lib/sgml/catalog")
+sgml-local-ecat-files:nil
+End:
+-->
diff --git a/doc/src/sgml/ref/drop_conversion.sgml b/doc/src/sgml/ref/drop_conversion.sgml
new file mode 100644
index 00000000000..00d2804b51f
--- /dev/null
+++ b/doc/src/sgml/ref/drop_conversion.sgml
@@ -0,0 +1,124 @@
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_conversion.sgml,v 1.1 2002/07/22 08:57:15 ishii Exp $ -->
+
+<refentry id="SQL-DROPCONVERSION">
+ <refmeta>
+  <refentrytitle id="SQL-DROPCONVERSION-TITLE">DROP CONVERSION</refentrytitle>
+  <refmiscinfo>SQL - Language Statements</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+  <refname>DROP CONVERSION</refname>
+  <refpurpose>remove a user-defined conversion</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+DROP CONVERSION <replaceable>conversion_name</replaceable>
+    [ CASCADE | RESTRICT ]
+</synopsis>
+ </refsynopsisdiv>
+  
+ <refsect1 id="sql-dropconversion-description">
+  <title>Description</title>
+
+  <para>
+   <command>DROP CONVERSION</command> removes a previously defined conversion.
+  </para>
+
+  <para>
+   To be able to drop a conversion, you must own the conversion.
+  </para>
+
+   <variablelist>
+    <title>Parameters</title>
+
+    <varlistentry>
+     <term><replaceable>conversion_name</replaceable></term>
+
+     <listitem>
+      <para>
+       The name of the conversion. The conversion name may be
+       schema-qualified.
+      </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry>
+     <term><literal>CASCADE</literal></term>
+     <term><literal>RESTRICT</literal></term>
+
+     <listitem>
+      <para>
+       These key words do not have any effect, since there are no
+       dependencies on conversions.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+
+ </refsect1>
+
+ <refsect1 id="sql-dropconversion-notes">
+  <title>Notes</title>
+
+  <para>
+   Use <command>CREATE CONVERSION</command> to create user-defined conversions.
+  </para>
+
+  <para>
+   The privileges required to drop a conversion may be changed in a future
+   release.
+  </para>
+ </refsect1>
+
+
+ <refsect1 id="sql-dropconversion-examples">
+  <title>Examples</title>
+
+  <para>
+   To drop the conversion named myname:
+<programlisting>
+DROP CONVERSION myname;
+</programlisting>
+  </para>
+ </refsect1>
+
+ 
+ <refsect1 id="sql-dropconversion-compat">
+  <title>Compatibility</title>
+
+  <para>
+    <command>DROP CONVERSION</command>
+    is a <productname>PostgreSQL</productname> extension.
+    There is no <command>DROP OPERATOR</command>
+    statement in <acronym>SQL99</acronym>.
+  </para>
+ </refsect1>
+
+
+ <refsect1 id="sql-dropconversion-seealso">
+  <title>See Also</title>
+
+  <para>
+   <xref linkend="sql-createconversion" endterm="sql-createconversion-title">
+  </para>
+ </refsect1>
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode:sgml
+sgml-omittag:nil
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"../reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:("/usr/lib/sgml/catalog")
+sgml-local-ecat-files:nil
+End:
+-->
diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml
index 39fec262dd0..e2491f54082 100644
--- a/doc/src/sgml/reference.sgml
+++ b/doc/src/sgml/reference.sgml
@@ -1,5 +1,5 @@
 <!-- reference.sgml
-$Header: /cvsroot/pgsql/doc/src/sgml/reference.sgml,v 1.30 2002/07/18 23:11:27 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/reference.sgml,v 1.31 2002/07/22 08:57:15 ishii Exp $
 
 PostgreSQL Reference Manual
 -->
@@ -62,6 +62,7 @@ PostgreSQL Reference Manual
    &createAggregate;
    &createCast;
    &createConstraint;
+   &createConversion;
    &createDatabase;
    &createDomain;
    &createFunction;
@@ -82,6 +83,7 @@ PostgreSQL Reference Manual
    &delete;
    &dropAggregate;
    &dropCast;
+   &dropConversion;
    &dropDatabase;
    &dropDomain;
    &dropFunction;