MySQL Lists are EOL. Please join:

List:Commits« Previous MessageNext Message »
From:john.russell Date:June 11 2010 7:38pm
Subject:svn commit - mysqldoc@docsrva: r21188 - trunk/refman-5.5
View as plain text  
Author: jrussell
Date: 2010-06-11 21:38:31 +0200 (Fri, 11 Jun 2010)
New Revision: 21188

Log:
Initial edits to the stored routine restrictions section for wording and structure.
Added some bridgeheads to clarify the relationships, rearranged order to make related things be adjacent.


Modified:
   trunk/refman-5.5/restrictions.xml


Modified: trunk/refman-5.5/restrictions.xml
===================================================================
--- trunk/refman-5.5/restrictions.xml	2010-06-11 18:19:13 UTC (rev 21187)
+++ trunk/refman-5.5/restrictions.xml	2010-06-11 19:38:31 UTC (rev 21188)
Changed blocks: 15, Lines Added: 130, Lines Deleted: 97; 14293 bytes

@@ -48,22 +48,29 @@
 
     <para>
       Some of the restrictions noted here apply to all stored routines;
-      that is, both to stored procedures and stored functions. Some of
-      these restrictions apply to stored functions but not to stored
-      procedures.
+      that is, both to stored procedures and stored functions. There are
+      also some
+      <link linkend="stored-routines-function-restrictions">restrictions
+      specific to stored functions</link> but not to stored procedures.
     </para>
 
     <para>
       The restrictions for stored functions also apply to triggers.
-      There are also some restrictions specific to triggers.
+      There are also some
+      <link linkend="stored-routines-trigger-restrictions">restrictions
+      specific to triggers</link>.
     </para>
 
     <para>
       The restrictions for stored procedures also apply to the
       <literal role="stmt">DO</literal> clause of Event Scheduler event
-      definitions. There are also some restrictions specific to events.
+      definitions. There are also some
+      <link linkend="stored-routines-event-restrictions">restrictions
+      specific to events</link>.
     </para>
 
+    <bridgehead id="stored-routine-sql-restrictions">SQL Statements Not Allowed in Stored Routines</bridgehead>
+
     <para>
       Stored routines cannot contain arbitrary SQL statements. The
       following statements are disallowed:

@@ -100,18 +107,19 @@
           <literal role="stmt">EXECUTE</literal>,
           <literal role="stmt">DEALLOCATE PREPARE</literal>) can be used
           in stored procedures, but not stored functions or triggers.
-          Implication: You cannot use dynamic SQL within stored
-          functions or triggers (where you construct dynamically
-          statements as strings and then execute them).
+          Thus, stored functions and triggers cannot use dynamic SQL
+          (where you construct statements as strings and then execute
+          them).
         </para>
+      </listitem>
 
+      <listitem>
         <para>
-          In addition, SQL statements that are not permitted within
-          prepared statements are also not permitted in stored routines.
-          See <xref linkend="sql-syntax-prepared-statements"/>, for a
-          list of statements supported as prepared statements.
-          Statements not listed there are not supported for SQL prepared
-          statements and thus are also not supported for stored routines
+          SQL statements that are not permitted within prepared
+          statements are also not permitted in stored routines. See
+          <xref linkend="sql-syntax-prepared-statements"/>, for a list
+          of statements supported as prepared statements. Only the
+          statements listed there are supported for stored routines,
           unless noted otherwise in <xref linkend="stored-routines"/>.
         </para>
       </listitem>

@@ -119,7 +127,7 @@
       <listitem>
         <para>
           Inserts cannot be delayed. <literal role="stmt">INSERT
-          DELAYED</literal> syntax is accepted but the statement is
+          DELAYED</literal> syntax is accepted, but the statement is
           handled as a normal <literal role="stmt">INSERT</literal>.
         </para>
       </listitem>

@@ -139,9 +147,16 @@
 
     </itemizedlist>
 
+    <bridgehead id="stored-routines-function-restrictions">Restrictions for Stored Functions</bridgehead>
+
     <para>
-      For stored functions (but not stored procedures), the following
-      additional statements or operations are disallowed:
+      The following additional statements or operations are not allowed
+      within stored functions. They are allowed within stored
+      procedures, except stored procedures that are invoked from within
+      a stored function or trigger. For example, if you use
+      <literal role="stmt">FLUSH</literal> in a stored procedure, that
+      stored procedure cannot be called from a stored function or
+      trigger.
     </para>
 
     <itemizedlist>

@@ -185,10 +200,9 @@
 
       <listitem>
         <para>
-          Within a stored function or trigger, it is not permitted to
-          modify a table that is already being used (for reading or
-          writing) by the statement that invoked the function or
-          trigger.
+          A stored function or trigger cannot modify a table that is
+          already being used (for reading or writing) by the statement
+          that invoked the function or trigger.
         </para>
       </listitem>
 

@@ -222,20 +236,64 @@
 
     </itemizedlist>
 
+    <bridgehead id="stored-routines-trigger-restrictions">Restrictions for Triggers</bridgehead>
+
     <para>
-      Although some restrictions normally apply to stored functions and
-      triggers but not to stored procedures, those restrictions do apply
-      to stored procedures if they are invoked from within a stored
-      function or trigger. For example, if you use
-      <literal role="stmt">FLUSH</literal> in a stored procedure, that
-      stored procedure cannot be called from a stored function or
-      trigger.
+      For triggers, the following additional restrictions apply:
     </para>
 
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          Triggers currently are not activated by foreign key actions.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          When using row-based replication, triggers on the slave are
+          not activated by statements originating on the master. The
+          triggers on the slave are activated when using statement-based
+          replication. For more information, see
+          <xref linkend="replication-features-triggers"/>.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          The <literal role="stmt">RETURN</literal> statement is
+          disallowed in triggers, which cannot return a value. To exit a
+          trigger immediately, use the
+          <literal role="stmt" condition="leave-statement">LEAVE</literal>
+          statement.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Triggers are not allowed on tables in the
+          <literal>mysql</literal> database.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          The trigger cache does not detect when metadata of the
+          underlying objects has changed. If a trigger uses a table and
+          the table has changed since the trigger was loaded into the
+          cache, the trigger operates using the outdated metadata.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <bridgehead id="stored-routine-name-conflicts">Name Conflicts within Stored Routines</bridgehead>
+
     <para>
-      It is possible for the same identifier to be used for a routine
-      parameter, a local variable, and a table column. Also, the same
-      local variable name can be used in nested blocks. For example:
+      The same identifier might be used for a routine parameter, a local
+      variable, and a table column. Also, the same local variable name
+      can be used in nested blocks. For example:
     </para>
 
 <programlisting>

@@ -251,7 +309,7 @@
 </programlisting>
 
     <para>
-      In such cases the identifier is ambiguous and the following
+      In such cases, the identifier is ambiguous and the following
       precedence rules apply:
     </para>
 

@@ -260,20 +318,20 @@
       <listitem>
         <para>
           A local variable takes precedence over a routine parameter or
-          table column
+          table column.
         </para>
       </listitem>
 
       <listitem>
         <para>
-          A routine parameter takes precedence over a table column
+          A routine parameter takes precedence over a table column.
         </para>
       </listitem>
 
       <listitem>
         <para>
           A local variable in an inner block takes precedence over a
-          local variable in an outer block
+          local variable in an outer block.
         </para>
       </listitem>
 

@@ -284,6 +342,8 @@
       nonstandard.
     </para>
 
+    <bridgehead id="stored-routines-replication-restrictions">Replication Considerations</bridgehead>
+
     <para>
       Use of stored routines can cause replication problems. This issue
       is discussed further in <xref linkend="stored-programs-logging"/>.

@@ -298,78 +358,50 @@
       <option>--replicate-*-db</option> options.
     </para>
 
+    <bridgehead id="stored-routines-debugging-restrictions">Debugging Considerations</bridgehead>
+
     <para>
       There are no stored routine debugging facilities.
     </para>
 
-    <para>
-      <literal>UNDO</literal> handlers are not supported.
-    </para>
+    <bridgehead id="stored-routines-standard-restrictions">Unsupported Syntax from the SQL:2003 Standard</bridgehead>
 
     <para>
-      <literal>FOR</literal> loops are not supported.
+      The MySQL stored routine syntax is based on the SQL:2003 standard.
+      The following items from that standard are not currently
+      supported:
     </para>
 
-    <para>
-      To prevent problems of interaction between server threads, when a
-      client issues a statement, the server uses a snapshot of routines
-      and triggers available for execution of the statement. That is,
-      the server calculates a list of procedures, functions, and
-      triggers that may be used during execution of the statement, loads
-      them, and then proceeds to execute the statement. This means that
-      while the statement executes, it will not see changes to routines
-      performed by other threads.
-    </para>
-
-    <para>
-      For triggers, the following additional restrictions apply:
-    </para>
-
     <itemizedlist>
 
       <listitem>
         <para>
-          Triggers currently are not activated by foreign key actions.
+          <literal>UNDO</literal> handlers are not supported.
         </para>
       </listitem>
 
       <listitem>
         <para>
-          When using row-based replication, triggers on the slave are
-          not activated by statements originating on the master. This
-          does not apply when using statement-based replication. For
-          more information, see
-          <xref linkend="replication-features-triggers"/>.
+          <literal>FOR</literal> loops are not supported.
         </para>
       </listitem>
 
-      <listitem>
-        <para>
-          The <literal role="stmt">RETURN</literal> statement is
-          disallowed in triggers, which cannot return a value. To exit a
-          trigger immediately, use the
-          <literal role="stmt" condition="leave-statement">LEAVE</literal>
-          statement.
-        </para>
-      </listitem>
+    </itemizedlist>
 
-      <listitem>
-        <para>
-          Triggers are not allowed on tables in the
-          <literal>mysql</literal> database.
-        </para>
-      </listitem>
+    <bridgehead>Concurrency Considerations</bridgehead>
 
-      <listitem>
-        <para>
-          The trigger cache does not detect when metadata of the
-          underlying objects has changed. If a trigger uses a table and
-          the table has changed since the trigger was loaded into the
-          cache, the trigger operates using the outdated metadata.
-        </para>
-      </listitem>
+    <para>
+      To prevent problems of interaction between sessions, when a client
+      issues a statement, the server uses a snapshot of routines and
+      triggers available for execution of the statement. That is, the
+      server calculates a list of procedures, functions, and triggers
+      that may be used during execution of the statement, loads them,
+      and then proceeds to execute the statement. While the statement
+      executes, it does not see changes to routines performed by other
+      sessions.
+    </para>
 
-    </itemizedlist>
+    <bridgehead id="stored-routines-event-restrictions">Event Scheduler Restrictions</bridgehead>
 
     <para>
       The following limitations are specific to the Event Scheduler:

@@ -380,8 +412,8 @@
       <listitem>
         <para>
           Event names are handled in case-insensitive fashion. For
-          example, this means that you cannot have two events in the
-          same database with the names <literal>anEvent</literal> and
+          example, you cannot have two events in the same database with
+          the names <literal>anEvent</literal> and
           <literal>AnEvent</literal>.
         </para>
       </listitem>

@@ -452,7 +484,7 @@
 
       <listitem>
         <para>
-          Generally speaking, statements which are not permitted in
+          Generally speaking, statements that are not permitted in
           stored routines or in SQL prepared statements are also not
           allowed in the body of an event. For more information, see
           <xref linkend="sql-syntax-prepared-statements"/>.

@@ -742,11 +774,11 @@
 </programlisting>
 
         <para>
-          Here the result from the
-          subquery in the <literal>FROM</literal> clause is stored as a
-          temporary table, so the relevant rows in <literal>t</literal>
-          have already been selected by the time the update to
-          <literal>t</literal> takes place.
+          Here the result from the subquery in the
+          <literal>FROM</literal> clause is stored as a temporary table,
+          so the relevant rows in <literal>t</literal> have already been
+          selected by the time the update to <literal>t</literal> takes
+          place.
         </para>
       </listitem>
 

@@ -818,10 +850,11 @@
         </para>
       </listitem>
 
-        <listitem>
-          <para>
-            MySQL does not support <literal>LIMIT</literal> in subqueries for certain subquery operators:
-          </para>
+      <listitem>
+        <para>
+          MySQL does not support <literal>LIMIT</literal> in subqueries
+          for certain subquery operators:
+        </para>
 
 <programlisting>
 mysql&gt; <userinput>SELECT * FROM t1</userinput>

@@ -829,7 +862,7 @@
 ERROR 1235 (42000): This version of MySQL doesn't yet support
  'LIMIT &amp; IN/ALL/ANY/SOME subquery'
 </programlisting>
-        </listitem>
+      </listitem>
 
       <listitem>
         <para>


Thread
svn commit - mysqldoc@docsrva: r21188 - trunk/refman-5.5john.russell11 Jun