svn commit - mysqldoc@docsrva: r1437 - in trunk: . internals

[paul]

Author: paul
Date: 2006-02-24 04:45:41 +0100 (Fri, 24 Feb 2006)
New Revision: 1437

Log:
 r8120@frost:  paul | 2006-02-23 21:43:50 -0600
 Add mysqltest notes.


Modified:
   trunk/
   trunk/internals/mysqltest.xml


Property changes on: trunk
___________________________________________________________________
Name: svk:merge
   - b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:8117
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:3548
   + b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:8120
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:3548

Modified: trunk/internals/mysqltest.xml
===================================================================
--- trunk/internals/mysqltest.xml	2006-02-24 03:45:26 UTC (rev 1436)
+++ trunk/internals/mysqltest.xml	2006-02-24 03:45:41 UTC (rev 1437)
@@ -485,9 +485,14 @@
             <option>--record</option>, <option>-r</option>
           </para>
 
+          <remark role="todo">
+            What happens if no --result-file option is given?
+          </remark>
+
           <para>
-            Record the output from running the test file into the file
-            named by the <option>--result-file</option> option.
+            Record the output that results from running the test file
+            into the file named by the <option>--result-file</option>
+            option.
           </para>
         </listitem>
 
@@ -513,20 +518,9 @@
           </remark>
 
           <para>
-            Read results from this file. In addition, if the
-
-            <indexterm>
-              <primary>mysqltest</primary>
-              <secondary>record option</secondary>
-            </indexterm>
-
-            <indexterm>
-              <primary>record option</primary>
-              <secondary>mysqltest</secondary>
-            </indexterm>
-
-            <option>--record</option> option is given, write results to
-            this file.
+            Read expected results from this file. In addition, if the
+            <option>--record</option> option is given, write actual
+            results to this file.
           </para>
         </listitem>
 
@@ -677,7 +671,7 @@
           </para>
 
           <para>
-            Read the test from this file. The default is to read from
+            Read test input from this file. The default is to read from
             the standard input.
           </para>
         </listitem>
@@ -698,6 +692,10 @@
             <option>-m
<replaceable>file_name</replaceable></option>
           </para>
 
+          <remark role="todo">
+            This is an input file? Output file?
+          </remark>
+
           <para>
             The file where the timing in microseconds is stored.
           </para>
@@ -719,6 +717,10 @@
             <option>-t
<replaceable>dir_name</replaceable></option>
           </para>
 
+          <remark role="todo">
+            "put" = "created"?
+          </remark>
+
           <para>
             The temporary directory where sockets are put.
           </para>
@@ -792,7 +794,7 @@
 
     <refsection id="mysqltest-commands">
 
-      <title>Command Language</title>
+      <title>Test File Command Language</title>
 
       <para>
         This section describes the test language implemented by
@@ -812,10 +814,73 @@
         <command>mysqltest</command> supports the following commands:
       </para>
 
+      <para>
+        General input conventions:
+      </para>
+
       <itemizedlist>
 
         <listitem>
           <para>
+            A line that begins with a
&lsquo;<literal>#</literal>&rsquo;
+            character is treated as a comment that extends to the end of
+            the line and is ignored.
+          </para>
+
+          <para>
+            Must the <literal>#</literal> occur in column 1 only, or can
+            it be the first non-whitespace character on the line?
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            A line that begins with
&lsquo;<literal>--</literal>&rsquo;
+            also is treated as a comment that extends to the end of the
+            line. However, if the first word of the comment is a valid
+            <command>mysqltest</command> command, the comment is
+            executed. This can be useful for writing commands that
+            contain embedded instances of the command delimiter.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Other input is taken as containing commands to be sent to
+            the server. These commands are delimited by instances of the
+            delimiter. Such input can contain multiple commands per
+            line, and a given command can span multiple lines. Consider
+            the following two input lines:
+          </para>
+
+<programlisting>
+select 1; select 'hello'; select
+'goodbye';
+</programlisting>
+
+          <para>
+            Three commands result from that input:
+          </para>
+
+<programlisting>
+select 1;
+select 'hello';
+select 'goodbye';
+</programlisting>
+
+          <para>
+            The default delimiter is the semicolon character
+            (&lsquo;<literal>;</literal>&rsquo;). It can be changed
with
+            the <literal>delimiter</literal> command.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
             <literal>character_set</literal>
           </para>
         </listitem>
@@ -844,8 +909,15 @@
 
         <listitem>
           <para>
-            <literal>delimiter</literal>
+            <literal>delimiter
<replaceable>str</replaceable></literal>
           </para>
+
+          <para>
+            Set the command delimiter to <replaceable>str</replaceable>,
+            which may consist of one or more characters. The default
+            delimiter is the semicolon character
+            (&lsquo;<literal>;</literal>&rsquo;).
+          </para>
         </listitem>
 
         <listitem>
@@ -1012,8 +1084,26 @@
 
         <listitem>
           <para>
-            <literal>error</literal>
+            <literal>error {<replaceable>error_num</replaceable> |
+            <replaceable>sqlstate_code</replaceable>}</literal>
           </para>
+
+          <para>
+            Specify an error value that the next command is expected to
+            return. The argument can be either a MySQL-specific error
+            number or a SQLSTATE value. (These are the kinds of values
+            returned by the <literal>mysql_errno()</literal> and
+            <literal>mysql_sqlstate()</literal> C API functions.) If you
+            specify a SQLSTATE value, it should begin with an
+            <literal>S</literal> to enable
<command>mysqltest</command>
+            to distinguish it from a MySQL error number. For example, to
+            specify the SQLSTATE value <literal>42000</literal>, write
+            it as <literal>S42000</literal>:
+          </para>
+
+<programlisting>
+--error S42000
+</programlisting>
         </listitem>
 
         <listitem>
@@ -1141,11 +1231,10 @@
           <para>
             Replace strings that match the pattern
             <replaceable>pattern</replaceable> with
-            <replaceable>replacment</replaceable>. The
-            <literal>i</literal> modifier, if given, causes
-            case-insensitive pattern matching. Each instance of the
-            pattern on the line is replaced. Multiple
-            pattern/replacement pairs may be given.
+            <replaceable>replacment</replaceable>. Each instance of the
+            pattern on the line is replaced. The <literal>i</literal>
+            modifier, if given, causes case-insensitive pattern
+            matching.
           </para>
 
           <para>
@@ -1156,12 +1245,36 @@
             <literal>\<replaceable>N</replaceable></literal> in
the
             replacement string cause insertion of the
             <replaceable>N</replaceable>-th substring matched by the
-            pattern.
+            pattern. For example, the following command will match
+            <literal>strawberry</literal> and replace it with
+            <literal>raspbetter strawberry</literal>
           </para>
 
+<programlisting>
+--replace_regex /(strawberry)/raspberry and \1/
+</programlisting>
+
           <para>
-            This command was added in MySQL 5.1.6.
+            Multiple pattern/replacement pairs may be given. The
+            following command replaces instances of <literal>A</literal>
+            with <literal>C</literal> (the first pattern replaces
+            <literal>A</literal> with <literal>B</literal>, the
second
+            replaces <literal>B</literal> with
<literal>C</literal>):
           </para>
+
+<programlisting>
+--replace_regex /A/B/ /B/C/
+</programlisting>
+
+          <para>
+            If a pattern is not found, no error occurs and the input is
+            unchanged.
+          </para>
+
+          <para>
+            The <literal>replace_regex</literal> command was added in
+            MySQL 5.1.6.
+          </para>
         </listitem>
 
         <listitem>
@@ -1226,8 +1339,12 @@
 
         <listitem>
           <para>
-            <literal>source</literal>
+            <literal>source
<filename>file_name</filename></literal>
           </para>
+
+          <para>
+            Reads test input from the named file.
+          </para>
         </listitem>
 
         <listitem>
@@ -1289,6 +1406,27 @@
 
       </itemizedlist>
 
+      <para>
+        <literal>$mysql_errno</literal> is a built-in variable that
+        contains the numeric error returned by the most recent command
+        sent to the server, or 0 if the command executes successfully.
+        <literal>$mysql_errno</literal> has a value of &minus;1 if no
+        command has yet been sent.
+      </para>
+
+      <para>
+        If an expected error is specified and that error occurs,
+        <command>mysqltest</command> continues reading input. If the
+        command is successful or a different error occurs,
+        <command>mysqltest</command> aborts.
+      </para>
+
+      <para>
+        If no expected error is specified, <command>mysqltest</command>
+        aborts unless the command is successful. (It is implicit that
+        you expect <literal>$mysql_errno</literal> to be 0.)
+      </para>
+
     </refsection>
 
   </refentry>