svn commit - mysqldoc@docsrva: r11433 - trunk/refman-common

[mcbrown]

Author: mcbrown
Date: 2008-07-30 12:00:38 +0200 (Wed, 30 Jul 2008)
New Revision: 11433

Log:
Documenting proxy.response and proxy.resultset (part of Docs Bug #37122)



Modified:
   trunk/refman-common/mysql-proxy-core.xml


Modified: trunk/refman-common/mysql-proxy-core.xml
===================================================================
--- trunk/refman-common/mysql-proxy-core.xml	2008-07-30 08:55:30 UTC (rev 11432)
+++ trunk/refman-common/mysql-proxy-core.xml	2008-07-30 10:00:38 UTC (rev 11433)
Changed blocks: 2, Lines Added: 179, Lines Deleted: 2; 8210 bytes

@@ -461,8 +461,8 @@
         <para>
           <literal>--proxy-read-only-backend-address=host:port</literal>
           &mdash; the listening hostname (or IP address) and port of the
-          proxy server for read-only connections. The default is
-          <literal>localhost:4042</literal>.
+          proxy server for read-only connections. The default is for
+          this information not to be set.
         </para>
       </listitem>
 

@@ -1076,6 +1076,183 @@
 
 <programlisting>proxy.queries:append(1,packet)</programlisting>
 
+      <para id="mysql-proxy-scripting-structures-response">
+        <emphasis
role="bold"><literal>proxy.response</literal></emphasis>
+      </para>
+
+      <para>
+        The <literal>proxy.response</literal> structure is used when you
+        want to return your own MySQL response, instead of forwarding a
+        packet that you have received a backend server. The structure
+        holds the response type information, an optional error message,
+        and the result set (rows/columns) that you want to return.
+      </para>
+
+      <informaltable>
+        <tgroup cols="2">
+          <colspec colwidth="30*"/>
+          <colspec colwidth="70*"/>
+          <thead>
+            <row>
+              <entry>Attribute</entry>
+              <entry>Description</entry>
+            </row>
+          </thead>
+          <tbody>
+            <row>
+              <entry><literal>type</literal></entry>
+              <entry>The type of the response. The type must be either
+                <literal>MYSQLD_PACKET_OK</literal> or
+                <literal>MYSQLD_PACKET_ERR</literal>. If the
+                <literal>MYSQLD_PACKET_ERR</literal>, then you should
+                set the value of the
+                <literal>mysql.response.errmsg</literal> with a suitable
+                error message.</entry>
+            </row>
+            <row>
+              <entry><literal>errmsg</literal></entry>
+              <entry>A string containing the error message that will be returned to
the
+                client.</entry>
+            </row>
+            <row>
+              <entry><literal>resultset</literal></entry>
+              <entry>A structure containing the result set information (columns and
rows),
+                identical to what would be returned when returning a
+                results from a <literal>SELECT</literal> query.</entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </informaltable>
+
+      <para>
+        When using <literal>proxy.response</literal> you either set
+        <literal>proxy.response.type</literal> to
+        <literal>proxy.MYSQLD_PACKET_OK</literal> and then build
+        <literal>resultset</literal> to contain the results that you
+        want to return, or set <literal>proxy.response.type</literal> to
+        <literal>proxy.MYSQLD_PACKET_ERR</literal> and set the
+        <literal>proxy.response.errmsg</literal> to a string with the
+        error message. To send the completed resultset or error message,
+        you should return the <literal>proxy.PROXY_SEND_RESULT</literal>
+        to trigger the return of the packet information.
+      </para>
+
+      <para>
+        An example of this can be seen in the
+        <filename>tutorial-resultset.lua</filename> script within the
+        MySQL Proxy package:
+      </para>
+
+<programlisting>if string.lower(command) == "show" and string.lower(option) ==
"querycounter" then
+        ---
+        -- proxy.PROXY_SEND_RESULT requires
+        --
+        -- proxy.response.type to be either
+        -- * proxy.MYSQLD_PACKET_OK or
+        -- * proxy.MYSQLD_PACKET_ERR
+        --
+        -- for proxy.MYSQLD_PACKET_OK you need a resultset
+        -- * fields
+        -- * rows
+        --
+        -- for proxy.MYSQLD_PACKET_ERR
+        -- * errmsg
+        proxy.response.type = proxy.MYSQLD_PACKET_OK
+        proxy.response.resultset = {
+                fields = {
+                        { type = proxy.MYSQL_TYPE_LONG, name = "global_query_counter", },
+                        { type = proxy.MYSQL_TYPE_LONG, name = "query_counter", },
+                },
+                rows = {
+                        { proxy.global.query_counter, query_counter }
+                }
+        }
+
+        -- we have our result, send it back
+        return proxy.PROXY_SEND_RESULT
+elseif string.lower(command) == "show" and string.lower(option) == "myerror" then
+        proxy.response.type = proxy.MYSQLD_PACKET_ERR
+        proxy.response.errmsg = "my first error"
+
+        return proxy.PROXY_SEND_RESULT
+</programlisting>
+
+      <para id="mysql-proxy-scripting-structures-resultset">
+        <emphasis
role="bold"><literal>proxy.response.resultset</literal></emphasis>
+      </para>
+
+      <para>
+        The <literal>proxy.response.resultset</literal> structure should
+        be populated with the rows and columns of data that you want to
+        return. The structure contains the information about the entire
+        result set, with the individual elements of the data shown in
+        the table below.
+      </para>
+
+      <informaltable>
+        <tgroup cols="2">
+          <colspec colwidth="30*"/>
+          <colspec colwidth="70*"/>
+          <thead>
+            <row>
+              <entry>Attribute</entry>
+              <entry>Description</entry>
+            </row>
+          </thead>
+          <tbody>
+            <row>
+              <entry><literal>fields</literal></entry>
+              <entry>The definition of the columns being returned. This should be a
+                dictionary structure with the <literal>type</literal>
+                specifying the MySQL data type, and the
+                <literal>name</literal> specifying the column name.
+                Columns should be listed in the the order of the column
+                data that will be returned.</entry>
+            </row>
+            <row>
+              <entry><literal>flags</literal></entry>
+              <entry>A number of flags related to the resultset. Valid flags
include
+                <literal>auto_commit</literal> (whether an automatic
+                commit was triggered),
+                <literal>no_good_index_used</literal> (the query
+                executed without using an appropriate index), and
+                <literal>no_index_used</literal> (the query executed
+                without using any index).</entry>
+            </row>
+            <row>
+              <entry><literal>rows</literal></entry>
+              <entry>The actual row data. The information should be returned as an
array of
+                arrays. Each inner array should contain the column data,
+                with the outer array making up the entire result set.</entry>
+            </row>
+            <row>
+              <entry><literal>warning_count</literal></entry>
+              <entry>The number of warnings for this result set.</entry>
+            </row>
+            <row>
+              <entry><literal>affected_rows</literal></entry>
+              <entry>The number of rows affected by the original
statement.</entry>
+            </row>
+            <row>
+              <entry><literal>insert_id</literal></entry>
+              <entry>The last insert ID for an auto-incremented column in a
table.</entry>
+            </row>
+            <row>
+              <entry><literal>query_status</literal></entry>
+              <entry>The status of the query operation. You can use the
+                <literal>MYSQLD_PACKET_OK</literal> or
+                <literal>MYSQLD_PACKET_ERR</literal> constants to
+                populate this parameter.</entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </informaltable>
+
+      <para>
+        For an example of the population of this table, see
+        <xref linkend="mysql-proxy-scripting-structures-response"/>.
+      </para>
+
       <para id="mysql-proxy-scripting-structures-return-states">
         <emphasis role="bold">Proxy Return State Constants</emphasis>
       </para>