Author: paul
Date: 2006-12-06 18:26:41 +0100 (Wed, 06 Dec 2006)
New Revision: 4133
Log:
r16768@polar: paul | 2006-12-06 11:13:30 -0600
Add new section describing the name-resolution rules for
built-in, UDF, and stored functions. Add cross-references
from other relevant sections.
(Bug#22619)
Modified:
trunk/refman-4.1/extending-mysql.xml
trunk/refman-4.1/functions.xml
trunk/refman-4.1/language-structure.xml
trunk/refman-5.0/extending-mysql.xml
trunk/refman-5.0/functions.xml
trunk/refman-5.0/language-structure.xml
trunk/refman-5.0/stored-procedures.xml
trunk/refman-5.1/extending-mysql.xml
trunk/refman-5.1/functions.xml
trunk/refman-5.1/language-structure.xml
trunk/refman-5.1/news-5.1.xml
trunk/refman-5.1/stored-procedures.xml
Property changes on: trunk
___________________________________________________________________
Name: svk:merge
- 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:16763
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:13158
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:12611
+ 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:16768
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:13158
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:12611
Modified: trunk/refman-4.1/extending-mysql.xml
===================================================================
--- trunk/refman-4.1/extending-mysql.xml 2006-12-06 17:25:22 UTC (rev 4132)
+++ trunk/refman-4.1/extending-mysql.xml 2006-12-06 17:26:41 UTC (rev 4133)
Changed blocks: 1, Lines Added: 6, Lines Deleted: 0; 689 bytes
@@ -344,6 +344,12 @@
</para>
<para>
+ See <xref linkend="function-resolution"/>, for the rules
+ describing how the server interprets references to different kinds
+ of functions.
+ </para>
+
+ <para>
The following sections describe features of the UDF interface,
provide instructions for writing UDFs, discuss security
precautions that MySQL takes to prevent UDF misuse, and describe
Modified: trunk/refman-4.1/functions.xml
===================================================================
--- trunk/refman-4.1/functions.xml 2006-12-06 17:25:22 UTC (rev 4132)
+++ trunk/refman-4.1/functions.xml 2006-12-06 17:26:41 UTC (rev 4133)
Changed blocks: 3, Lines Added: 9, Lines Deleted: 5; 1859 bytes
@@ -39,7 +39,9 @@
built-in functions, user-defined functions, and operators. This
chapter describes the functions and operators that are allowed for
writing expressions in MySQL. Instructions for writing user-defined
- functions are given in <xref linkend="adding-functions"/>.
+ functions are given in <xref linkend="adding-functions"/>. See
+ <xref linkend="function-resolution"/>, for the rules describing how
+ the server interprets references to different kinds of functions.
</para>
<para>
@@ -3509,14 +3511,15 @@
alphabetic characters outside the A-Z range are treated as
vowels.
</para>
-
+
<para>
<emphasis role="bold">Important</emphasis>: When using
<literal>SOUNDEX()</literal>, you should be aware of the
following limitations:
</para>
-
+
<itemizedlist>
+
<listitem>
<para>
This function, as currently implemented, is intended to
@@ -3525,19 +3528,20 @@
results.
</para>
</listitem>
-
+
<listitem>
<para>
This function is not guaranteed to provide consistent
results with strings that use multi-byte character sets,
including <literal>utf-8</literal>.
</para>
-
+
<para>
We hope to remove these limitations in a future release.
See Bug #22638 for more information.
</para>
</listitem>
+
</itemizedlist>
<remark role="help-description-end"/>
Modified: trunk/refman-4.1/language-structure.xml
===================================================================
--- trunk/refman-4.1/language-structure.xml 2006-12-06 17:25:22 UTC (rev 4132)
+++ trunk/refman-4.1/language-structure.xml 2006-12-06 17:26:41 UTC (rev 4133)
Changed blocks: 1, Lines Added: 30, Lines Deleted: 0; 1676 bytes
@@ -1341,6 +1341,36 @@
</section>
+ <section id="function-resolution">
+
+ <title>Function Name Resolution</title>
+
+ <para>
+ MySQL ¤t-series; supports built-in (native) functions and
+ user-defined functions (UDFs). The server resolves references to
+ function names for function creation and invocation as follows:
+ A UDF can be created with the same name as a built-in function
+ but the UDF cannot be invoked because the parser resolves
+ invocations of the function to refer to the built-in function.
+ For example, if you create a UDF named <literal>ABS</literal>,
+ references to <literal>ABS()</literal> invoke the built-in
+ function.
+ </para>
+
+ <para>
+ The preceding function name resolution rules have implications
+ for upgrading to versions of MySQL that implement new built-in
+ functions. If you have already created a user-defined function
+ with a given name and upgrade MySQL to a version that implements
+ a new built-in function with the same name, the UDF becomes
+ inaccessible. To correct this, use <literal>DROP
+ FUNCTION</literal> to drop the UDF, and then use <literal>CREATE
+ FUNCTION</literal> to re-create the UDF with a different
+ non-conflicting name.
+ </para>
+
+ </section>
+
</section>
<section id="user-variables">
Modified: trunk/refman-5.0/extending-mysql.xml
===================================================================
--- trunk/refman-5.0/extending-mysql.xml 2006-12-06 17:25:22 UTC (rev 4132)
+++ trunk/refman-5.0/extending-mysql.xml 2006-12-06 17:26:41 UTC (rev 4133)
Changed blocks: 1, Lines Added: 6, Lines Deleted: 0; 689 bytes
@@ -340,6 +340,12 @@
</para>
<para>
+ See <xref linkend="function-resolution"/>, for the rules
+ describing how the server interprets references to different kinds
+ of functions.
+ </para>
+
+ <para>
The following sections describe features of the UDF interface,
provide instructions for writing UDFs, discuss security
precautions that MySQL takes to prevent UDF misuse, and describe
Modified: trunk/refman-5.0/functions.xml
===================================================================
--- trunk/refman-5.0/functions.xml 2006-12-06 17:25:22 UTC (rev 4132)
+++ trunk/refman-5.0/functions.xml 2006-12-06 17:26:41 UTC (rev 4133)
Changed blocks: 3, Lines Added: 9, Lines Deleted: 5; 1783 bytes
@@ -49,7 +49,9 @@
are allowed for writing expressions in MySQL. Instructions for
writing stored functions and user-defined functions are given in
<xref linkend="stored-procedures"/>, and
- <xref linkend="adding-functions"/>.
+ <xref linkend="adding-functions"/>. See
+ <xref linkend="function-resolution"/>, for the rules describing how
+ the server interprets references to different kinds of functions.
</para>
<para>
@@ -3601,14 +3603,15 @@
alphabetic characters outside the A-Z range are treated as
vowels.
</para>
-
+
<para>
<emphasis role="bold">Important</emphasis>: When using
<literal>SOUNDEX()</literal>, you should be aware of the
following limitations:
</para>
-
+
<itemizedlist>
+
<listitem>
<para>
This function, as currently implemented, is intended to
@@ -3617,19 +3620,20 @@
results.
</para>
</listitem>
-
+
<listitem>
<para>
This function is not guaranteed to provide consistent
results with strings that use multi-byte character sets,
including <literal>utf-8</literal>.
</para>
-
+
<para>
We hope to remove these limitations in a future release.
See Bug #22638 for more information.
</para>
</listitem>
+
</itemizedlist>
<remark role="help-description-end"/>
Modified: trunk/refman-5.0/language-structure.xml
===================================================================
--- trunk/refman-5.0/language-structure.xml 2006-12-06 17:25:22 UTC (rev 4132)
+++ trunk/refman-5.0/language-structure.xml 2006-12-06 17:26:41 UTC (rev 4133)
Changed blocks: 1, Lines Added: 75, Lines Deleted: 0; 3132 bytes
@@ -1331,6 +1331,81 @@
</section>
+ <section id="function-resolution">
+
+ <title>Function Name Resolution</title>
+
+ <para>
+ MySQL ¤t-series; supports built-in (native) functions,
+ user-defined functions (UDFs), and stored functions. The
+ following rules describe how the server resolves references to
+ function names for function creation and invocation:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Built-in functions and user-defined functions
+ </para>
+
+ <para>
+ A UDF can be created with the same name as a built-in
+ function but the UDF cannot be invoked because the parser
+ resolves invocations of the function to refer to the
+ built-in function. For example, if you create a UDF named
+ <literal>ABS</literal>, references to
+ <literal>ABS()</literal> invoke the built-in function.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Built-in functions and stored functions
+ </para>
+
+ <para>
+ It is possible to create a stored function with the same
+ name as a built-in function, but to invoke the stored
+ function it is necessary to qualify it with a database name.
+ For example, if you create a stored function named
+ <literal>PI</literal> in the <literal>test</literal>
+ database, you invoke it as <literal>test.PI()</literal>
+ because the server resolves <literal>PI()</literal> as a
+ reference to the built-in function.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ User-defined functions and stored functions
+ </para>
+
+ <para>
+ User-defined functions and stored functions share the same
+ namespace, so you cannot create a UDF and a stored function
+ with the same name.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ The preceding function name resolution rules have implications
+ for upgrading to versions of MySQL that implement new built-in
+ functions. If you have already created a user-defined function
+ with a given name and upgrade MySQL to a version that implements
+ a new built-in function with the same name, the UDF becomes
+ inaccessible. To correct this, use <literal>DROP
+ FUNCTION</literal> to drop the UDF, and then use <literal>CREATE
+ FUNCTION</literal> to re-create the UDF with a different
+ non-conflicting name. The same is true if the new version of
+ MySQL implements a built-in function with the same name as an
+ existing stored function.
+ </para>
+
+ </section>
+
</section>
<section id="user-variables">
Modified: trunk/refman-5.0/stored-procedures.xml
===================================================================
--- trunk/refman-5.0/stored-procedures.xml 2006-12-06 17:25:22 UTC (rev 4132)
+++ trunk/refman-5.0/stored-procedures.xml 2006-12-06 17:26:41 UTC (rev 4133)
Changed blocks: 1, Lines Added: 3, Lines Deleted: 1; 732 bytes
@@ -440,7 +440,9 @@
continue to be supported, even with the existence of stored
functions. A UDF can be regarded as an external stored function.
However, do note that stored functions share their namespace
- with UDFs.
+ with UDFs. See <xref linkend="function-resolution"/>, for the
+ rules describing how the server interprets references to
+ different kinds of functions.
</para>
<remark role="note">
Modified: trunk/refman-5.1/extending-mysql.xml
===================================================================
--- trunk/refman-5.1/extending-mysql.xml 2006-12-06 17:25:22 UTC (rev 4132)
+++ trunk/refman-5.1/extending-mysql.xml 2006-12-06 17:26:41 UTC (rev 4133)
Changed blocks: 1, Lines Added: 6, Lines Deleted: 0; 691 bytes
@@ -2497,6 +2497,12 @@
</para>
<para>
+ See <xref linkend="function-resolution"/>, for the rules
+ describing how the server interprets references to different kinds
+ of functions.
+ </para>
+
+ <para>
The following sections describe features of the UDF interface,
provide instructions for writing UDFs, discuss security
precautions that MySQL takes to prevent UDF misuse, and describe
Modified: trunk/refman-5.1/functions.xml
===================================================================
--- trunk/refman-5.1/functions.xml 2006-12-06 17:25:22 UTC (rev 4132)
+++ trunk/refman-5.1/functions.xml 2006-12-06 17:26:41 UTC (rev 4133)
Changed blocks: 3, Lines Added: 11, Lines Deleted: 7; 1987 bytes
@@ -49,7 +49,9 @@
are allowed for writing expressions in MySQL. Instructions for
writing stored functions and user-defined functions are given in
<xref linkend="stored-procedures"/>, and
- <xref linkend="adding-functions"/>.
+ <xref linkend="adding-functions"/>. See
+ <xref linkend="function-resolution"/>, for the rules describing how
+ the server interprets references to different kinds of functions.
</para>
<para>
@@ -3570,16 +3572,17 @@
soundex string. All non-alphabetic characters in
<replaceable>str</replaceable> are ignored. All international
alphabetic characters outside the A-Z range are treated as
- vowels.
+ vowels.
</para>
-
+
<para>
<emphasis role="bold">Important</emphasis>: When using
<literal>SOUNDEX()</literal>, you should be aware of the
following limitations:
</para>
-
+
<itemizedlist>
+
<listitem>
<para>
This function, as currently implemented, is intended to
@@ -3588,21 +3591,22 @@
results.
</para>
</listitem>
-
+
<listitem>
<para>
This function is not guaranteed to provide consistent
results with strings that use multi-byte character sets,
including <literal>utf-8</literal>.
</para>
-
+
<para>
We hope to remove these limitations in a future release.
See Bug #22638 for more information.
</para>
</listitem>
+
</itemizedlist>
-
+
<remark role="help-description-end"/>
<remark role="help-example"/>
Modified: trunk/refman-5.1/language-structure.xml
===================================================================
--- trunk/refman-5.1/language-structure.xml 2006-12-06 17:25:22 UTC (rev 4132)
+++ trunk/refman-5.1/language-structure.xml 2006-12-06 17:26:41 UTC (rev 4133)
Changed blocks: 1, Lines Added: 80, Lines Deleted: 0; 3488 bytes
@@ -1526,6 +1526,86 @@
</section>
+ <section id="function-resolution">
+
+ <title>Function Name Resolution</title>
+
+ <para>
+ MySQL ¤t-series; supports built-in (native) functions,
+ user-defined functions (UDFs), and stored functions. The
+ following rules describe how the server resolves references to
+ function names for function creation and invocation:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Built-in functions and user-defined functions
+ </para>
+
+ <para>
+ As of MySQL 5.1.14, an error occurs if you try to create a
+ UDF with the same name as a built-in function. Before
+ 5.1.14, a UDF can be created with the same name as a
+ built-in function but the UDF cannot be invoked because the
+ parser resolves invocations of the function to refer to the
+ built-in function. For example, if you create a UDF named
+ <literal>ABS</literal>, references to
+ <literal>ABS()</literal> invoke the built-in function.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Built-in functions and stored functions
+ </para>
+
+ <para>
+ It is possible to create a stored function with the same
+ name as a built-in function, but to invoke the stored
+ function it is necessary to qualify it with a schema name.
+ For example, if you create a stored function named
+ <literal>PI</literal> in the <literal>test</literal> schema,
+ you invoke it as <literal>test.PI()</literal> because the
+ server resolves <literal>PI()</literal> as a reference to
+ the built-in function. As of 5.1.14, the server creates a
+ warning if the stored function name collides with a built-in
+ function name. The warning can be displayed with
+ <literal>SHOW WARNINGS</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ User-defined functions and stored functions
+ </para>
+
+ <para>
+ User-defined functions and stored functions share the same
+ namespace, so you cannot create a UDF and a stored function
+ with the same name.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ The preceding function name resolution rules have implications
+ for upgrading to versions of MySQL that implement new built-in
+ functions. If you have already created a user-defined function
+ with a given name and upgrade MySQL to a version that implements
+ a new built-in function with the same name, the UDF becomes
+ inaccessible. To correct this, use <literal>DROP
+ FUNCTION</literal> to drop the UDF, and then use <literal>CREATE
+ FUNCTION</literal> to re-create the UDF with a different
+ non-conflicting name. The same is true if the new version of
+ MySQL implements a built-in function with the same name as an
+ existing stored function.
+ </para>
+
+ </section>
+
</section>
<section id="user-variables">
Modified: trunk/refman-5.1/news-5.1.xml
===================================================================
--- trunk/refman-5.1/news-5.1.xml 2006-12-06 17:25:22 UTC (rev 4132)
+++ trunk/refman-5.1/news-5.1.xml 2006-12-06 17:26:41 UTC (rev 4133)
Changed blocks: 16, Lines Added: 53, Lines Deleted: 30; 7304 bytes
@@ -82,14 +82,37 @@
</para>
<itemizedlist>
-
+
<listitem>
<para>
+ <emphasis role="bold">Incompatible change</emphasis>:
+ Previously, you could create a user-defined function (UDF) or
+ stored function with the same name as a built-in function, but
+ could not invoke the UDF. Now an error occurs if you try to
+ create such a UDF. The server also now generates a warning if
+ you create a stored function with the same name as a built-in
+ function. It is not considered an error to create a stored
+ function with the same name as a built-in function because you
+ can invoke the function using
+ <literal><replaceable>db_name</replaceable>.<replaceable>func_name</replaceable>()</literal>
+ syntax. However, the server now generates a warning in this
+ case. (Bug #22619)
+ </para>
+
+ <para>
+ See <xref linkend="function-resolution"/>, for the rules
+ describing how the server interprets references to different
+ kinds of functions.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
<literal>NDB Cluster</literal>: Backup messages are now
printed to the Cluster log. (Bug #24544)
</para>
</listitem>
-
+
<listitem>
<para>
<literal>NDB Cluster</literal>: The error message
@@ -98,7 +121,7 @@
indicating when the error took place. (Bug #21519)
</para>
</listitem>
-
+
<listitem>
<para>
<literal>NDB Cluster</literal> (Disk Data): The output of
@@ -106,7 +129,7 @@
tablespace and logfile group definitions used by any tables or
databases that are dumped. (Bug #20839)
</para>
-
+
<para>
<emphasis role="bold">Note</emphasis>: The working of the
<option>--all-tablespaces</option> or <option>-Y</option>
@@ -143,7 +166,7 @@
</para>
<itemizedlist>
-
+
<listitem>
<para>
<literal>NDB Cluster</literal>: The failure of a data node
@@ -151,7 +174,7 @@
node failures. (Bug #24752)
</para>
</listitem>
-
+
<listitem>
<para>
<literal>NDB Cluster</literal>: A committed read could be
@@ -159,7 +182,7 @@
timeout error. (Bug #24717)
</para>
</listitem>
-
+
<listitem>
<para>
<literal>NDB Cluster</literal>: The simultaneous shutdown of
@@ -167,7 +190,7 @@
processes caused unnecessary locking. (Bug #24655)
</para>
</listitem>
-
+
<listitem>
<para>
<literal>NDB Cluster</literal>: The failure of the master node
@@ -175,7 +198,7 @@
<command>ndb_mgmd</command> to hang. (Bug #24543)
</para>
</listitem>
-
+
<listitem>
<para>
<literal>NDB Cluster</literal>: In certain rare cases, a data
@@ -183,7 +206,7 @@
Cluster source code. (Bug #24476)
</para>
</listitem>
-
+
<listitem>
<para>
<literal>NDB Cluster</literal>: Creating a new tables
@@ -192,18 +215,18 @@
#24470)
</para>
</listitem>
-
+
<listitem>
<para>
<literal>NDB Cluster</literal>: Any statement following the
execution of <literal>CREATE TABLE ... LIKE
- <replaceable>ndb_table</replaceable></literal> (where
+ <replaceable>ndb_table</replaceable></literal> (where
<replaceable>ndb_table</replaceable> was a table using the
<literal>NDB</literal> storage engine), would cause the
- <command>mysql</command> client to hang. (Bug #24301)
+ <command>mysql</command> client to hang. (Bug #24301)
</para>
</listitem>
-
+
<listitem>
<para>
<literal>NDB Cluster</literal>: When the management client
@@ -212,7 +235,7 @@
were shut down. (Bug #24105)
</para>
</listitem>
-
+
<listitem>
<para>
<literal>NDB Cluster</literal>: A query using an index scan
@@ -220,17 +243,17 @@
cause one or more data nodes to crash. (Bug #24039)
</para>
</listitem>
-
+
<listitem>
<para>
<literal>NDB Cluster</literal> (Cluster APIs): Some MGM API
function calls could yield incorrect return values in certain
cases where the cluster was operating under a very high load,
or experienced timeouts in inter-node communications. (Bug
- #24011)
+ #24011)
</para>
</listitem>
-
+
<listitem>
<para>
<literal>NDB Cluster</literal>: It was possible for the sum of
@@ -244,26 +267,26 @@
messages provided. (Bug #22548)
</para>
</listitem>
-
+
<listitem>
<para>
<literal>NDB Cluster</literal>: Given a table
<literal>mytbl</literal> in a database <literal>mydb</literal>
on a MySQL Server acting as an SQL node in a MySQL Cluster,
then, following multiple <literal>ALTER TABLE mytbl
- ENGINE=<replaceable>engine</replaceable></literal>
- statements — first, to change the storage engine used
- for a table to <literal>NDB</literal>, and then again to
- change the table to use a non-<literal>NDB</literal> storage
- engine — a <literal>DROP DATABASE mydb</literal>
- statement executed on any SQL node in the cluster would cause
+ ENGINE=<replaceable>engine</replaceable></literal> statements
+ — first, to change the storage engine used for a table
+ to <literal>NDB</literal>, and then again to change the table
+ to use a non-<literal>NDB</literal> storage engine — a
+ <literal>DROP DATABASE mydb</literal> statement executed on
+ any SQL node in the cluster would cause
<literal>mydb</literal> to be dropped on
<emphasis>all</emphasis> SQL nodes in the cluster, even if
<literal>mydb</literal> contained non-<literal>NDB</literal>
- tables. (Bug #21495)
+ tables. (Bug #21495)
</para>
</listitem>
-
+
<listitem>
<para>
<literal>NDB Cluster</literal>: An incorrect error message was
@@ -272,7 +295,7 @@
low. (Bug #20065)
</para>
</listitem>
-
+
<listitem>
<para>
<literal>NDB Cluster</literal>: An incorrect error message was
@@ -281,7 +304,7 @@
the amount of data to be stored by the cluster. (Bug #19808)
</para>
</listitem>
-
+
<listitem>
<para>
<literal>NDB Cluster</literal>: A unique constraint violation
@@ -1713,7 +1736,7 @@
be specified for processing binary log files. (Bug #18351)
</para>
</listitem>
-
+
<listitem>
<para>
<literal>NDB Cluster</literal>: Backup messages are no longer
Modified: trunk/refman-5.1/stored-procedures.xml
===================================================================
--- trunk/refman-5.1/stored-procedures.xml 2006-12-06 17:25:22 UTC (rev 4132)
+++ trunk/refman-5.1/stored-procedures.xml 2006-12-06 17:26:41 UTC (rev 4133)
Changed blocks: 1, Lines Added: 3, Lines Deleted: 1; 732 bytes
@@ -431,7 +431,9 @@
continue to be supported, even with the existence of stored
functions. A UDF can be regarded as an external stored function.
However, do note that stored functions share their namespace
- with UDFs.
+ with UDFs. See <xref linkend="function-resolution"/>, for the
+ rules describing how the server interprets references to
+ different kinds of functions.
</para>
<remark role="note">
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r4133 - in trunk: . refman-4.1 refman-5.0 refman-5.1 | paul | 6 Dec |
