Merge

1 files changed, 147 insertions, 66 deletions

diff --git a/Docs/manual.texi b/Docs/manual.texi
index 0ca3734d052..f63e2c17ff8 100644
--- a/Docs/manual.texi
+++ b/Docs/manual.texi
@@ -539,7 +539,7 @@ InnoDB Tables
 
 * InnoDB overview::             InnoDB tables overview
 * InnoDB start::                InnoDB startup options
-* Creating an InnoDB database:: Creating an InnoDB database.
+* InnoDB init::                 Creating InnoDB table space.
 * Using InnoDB tables::         Creating InnoDB tables
 * Adding and removing::         Adding and removing InnoDB data and log files
 * Backing up::                  Backing up and recovering an InnoDB database
@@ -552,7 +552,7 @@ InnoDB Tables
 * InnoDB restrictions::         Some restrictions on InnoDB tables
 * InnoDB contact information::  InnoDB contact information. 
 
-Creating an InnoDB database
+Creating InnoDB table space
 
 * Error creating InnoDB::      
 
@@ -942,6 +942,12 @@ MySQL Internals
 * MySQL threads::               MySQL threads
 * MySQL test suite::            MySQL test suite
 
+MySQL Test Suite
+
+* running mysqltest::           
+* extending mysqltest::         
+* Reporting mysqltest bugs::    
+
 Credits
 
 * Developers::                  
@@ -9203,9 +9209,10 @@ You should now have an ODBC connection to @strong{MySQL}, encrypted using SSH.
 @node Windows symbolic links, Windows compiling, Windows and SSH, Windows
 @subsection Splitting Data Across Different Disks on Windows
 
-Beginning with @strong{MySQL} Version 3.23.16, the @strong{MySQL}
-distribution is compiled with the @code{-DUSE_SYMDIR} option.  This allows
-you to put a database on different disk by adding a symbolic link to it
+Beginning with @strong{MySQL} Version 3.23.16, the @code{mysqld-max}
+and @code{mysql-max-nt} servers in the @strong{MySQL} distribution are
+compiled with the @code{-DUSE_SYMDIR} option.  This allows you to put a
+database on different disk by adding a symbolic link to it
 (in a manner similar to the way that symbolic links work on Unix).
 
 On Windows, you make a symbolic link to a database by creating a file
@@ -10372,7 +10379,7 @@ feature).
 Ignore the @code{delay_key_write} option for all tables.
 @xref{Server parameters}.
 
-@item -Sg, --skip-grant-tables
+@item --skip-grant-tables
 This option causes the server not to use the privilege system at all.  This
 gives everyone @emph{full access} to all databases!  (You can tell a running
 server to start using the grant tables again by executing @code{mysqladmin
@@ -24716,7 +24723,7 @@ NuSphere is working on removing these limitations.
 @menu
 * InnoDB overview::             InnoDB tables overview
 * InnoDB start::                InnoDB startup options
-* Creating an InnoDB database:: Creating an InnoDB database.
+* InnoDB init::                 Creating InnoDB table space.
 * Using InnoDB tables::         Creating InnoDB tables
 * Adding and removing::         Adding and removing InnoDB data and log files
 * Backing up::                  Backing up and recovering an InnoDB database
@@ -24771,7 +24778,7 @@ may consist of several files. This is different from, for example,
 InnoDB is distributed under the GNU GPL License Version 2 (of June 1991).
 In the source distribution of @strong{MySQL}, InnoDB appears as a subdirectory.
 
-@node InnoDB start, Creating an InnoDB database, InnoDB overview, InnoDB
+@node InnoDB start, InnoDB init, InnoDB overview, InnoDB
 @subsection InnoDB startup options
 
 Beginning from @strong{MySQL}-3.23.37 the prefix of the options is changed
@@ -24913,8 +24920,8 @@ InnoDB cannot notice. In cases like this the timeout is useful to
 resolve the situation.
 @end multitable
  
-@node Creating an InnoDB database, Using InnoDB tables, InnoDB start, InnoDB
-@subsection Creating an InnoDB database
+@node InnoDB init, Using InnoDB tables, InnoDB start, InnoDB
+@subsection Creating InnoDB table space
 
 Suppose you have installed @strong{MySQL} and have edited @file{my.cnf} so that
 it contains the necessary InnoDB configuration parameters.
@@ -24975,7 +24982,7 @@ mysqld: ready for connections
 * Error creating InnoDB::      
 @end menu
 
-@node Error creating InnoDB,  , Creating an InnoDB database, Creating an InnoDB database
+@node Error creating InnoDB,  , InnoDB init, InnoDB init
 @subsubsection If something goes wrong in database creation
 
 If something goes wrong in an InnoDB database creation, you should
@@ -24985,7 +24992,7 @@ create some InnoDB tables, delete also the corresponding @file{.frm}
 files for these tables from the @strong{MySQL} database
 directories. Then you can try the InnoDB database creation again.
 
-@node Using InnoDB tables, Adding and removing, Creating an InnoDB database, InnoDB
+@node Using InnoDB tables, Adding and removing, InnoDB init, InnoDB
 @subsection Creating InnoDB tables
 
 Suppose you have started the @strong{MySQL} client with the command
@@ -26221,6 +26228,12 @@ The menagerie database will be simple (deliberately), but it is not difficult
 to think of real-world situations in which a similar type of database might
 be used.  For example, a database like this could be used by a farmer to keep
 track of livestock, or by a veterinarian to keep track of patient records.
+A menagerie distribution containing some of the queries and sample data used
+in the following sections can be obtained from the @strong{MySQL} Web site.
+It's available in either
+@uref{http://www.mysql.com/Downloads/Contrib/Examples/menagerie.tar.gz,compressed @code{tar} format}
+or
+@uref{http://www.mysql.com/Downloads/Contrib/Examples/menagerie.zip,Zip format}.
 
 Use the @code{SHOW} statement to find out what databases currently exist
 on the server:
@@ -35429,12 +35442,20 @@ To add a new native @strong{MySQL} function, follow these steps:
 Add one line to @file{lex.h} that defines the function name in the
 @code{sql_functions[]} array.
 @item
-Add two lines to @file{sql_yacc.yy}. One indicates the preprocessor
-symbol that @code{yacc} should define (this should be added at the
-beginning of the file). Then define the function parameters and add an
-``item'' with these parameters to the @code{simple_expr} parsing rule.
-For an example, check all occurrences of @code{SOUNDEX} in
-@file{sql_yacc.yy} to see how this is done.
+If the function prototype is simple (just takes zero, one, two or three
+arguments), you should in lex.h specify SYM(FUNC_ARG#) (where # is the
+number of arguments) as the second argument in the
+@code{sql_functions[]} array and add a function that creates a function
+object in @file{item_create.cc}.  Take a look at @code{"ABS"} and
+@code{create_funcs_abs()} for an example of this.
+
+If the function prototype is complicated (for example takes a variable number
+of arguments), you should add two lines to @file{sql_yacc.yy}. One
+indicates the preprocessor symbol that @code{yacc} should define (this
+should be added at the beginning of the file). Then define the function
+parameters and add an ``item'' with these parameters to the
+@code{simple_expr} parsing rule.  For an example, check all occurrences
+of @code{ATAN} in @file{sql_yacc.yy} to see how this is done.
 @item
 In @file{item_func.h}, declare a class inheriting from @code{Item_num_func} or
 @code{Item_str_func}, depending on whether your function returns a number or a
@@ -35447,28 +35468,45 @@ double   Item_func_newname::val()
 longlong Item_func_newname::val_int()
 String  *Item_func_newname::Str(String *str)
 @end example
+
+If you inherit your object from any of the standard items (like
+@code{Item_num_func} you probably only have to define one of the above
+functions and let the parent object take care of the other functions.
+For example, the @code{Item_str_func} class defines a @code{val()} function
+that executes @code{atof()} on the value returned by @code{::str()}.
+
 @item
-You should probably also define the following function:
+You should probably also define the following object function:
 @example
 void Item_func_newname::fix_length_and_dec()
 @end example
 This function should at least calculate @code{max_length} based on the
 given arguments. @code{max_length} is the maximum number of characters
-the function may return.  This function should also set @code{maybe_null = 0}
-if the main function can't return a @code{NULL} value.  The function can check
-if any of the function arguments can return @code{NULL} by checking the
-arguments @code{maybe_null} variable.
+the function may return.  This function should also set @code{maybe_null
+= 0} if the main function can't return a @code{NULL} value.  The
+function can check if any of the function arguments can return
+@code{NULL} by checking the arguments @code{maybe_null} variable. You
+can take a look at @code{Item_func_mod::fix_length_and_dec} for a
+typical example of how to do this.
 @end enumerate
 
-All functions must be thread safe.
+All functions must be thread safe (In other words, don't use any global or
+static variables in the functions without protecting them with mutexes).
+
+If you want to return @code{NULL}, from @code{::val()}, @code{::val_int()}
+or @code{::str()} you should set @code{null_value} to 1 and return 0.
+
+For @code{::str()} object functions, there are some additional
+considerations to be aware of:
 
-For string functions, there are some additional considerations to be aware of:
 @itemize @bullet
 @item
-The @code{String *str} argument provides a string
-buffer that may be used to hold the result.
+The @code{String *str} argument provides a string buffer that may be
+used to hold the result. (For more information about the @code{String} type,
+take a look at the @file{sql_string.h} file.)
 @item
-The function should return the string that holds the result.
+The @code{::str()} function should return the string that holds the result or
+@code{(char*) 0} if the result is @code{NULL}.
 @item
 All current string functions try to avoid allocating any memory unless
 absolutely necessary!
@@ -42486,16 +42524,35 @@ as well developers, to do regression tests on the @strong{MySQL} code. To
 address this problem, we have created a new test system that is included in
 the source and binary distributions starting in Version 3.23.29.
 
-The test system consist of a test language interpreter (@code{mysqltest}),
-a shell script to run all tests(@code{mysql-test-run}), the actual test cases
-written in a special test language, and their expected results.  To run the
-test suite on your system after a build, type @code{mysql-test/mysql-test-run}
-from the source root.  If you have installed a binary distribution, @code{cd}
-to the install root (eg. @code{/usr/local/mysql}), and do
-@code{scripts/mysql-test-run}.  All tests should succeed.  If they do not,
-use @code{mysqlbug} to send a bug report to @email{bugs@@lists.mysql.com}.
-Make sure to include the output of @code{mysql-test-run}, as well as
-contents of all @code{.reject} files in @code{mysql-test/r} directory.
+The current set of test cases doesn't test everything in MySQL but, it
+should catch most obvious bugs in the SQL processing code, OS/library
+issues, and is quite thorough in testing replication.  Our eventual goal
+is to have the tests cover 100% of the code.  We welcome contributions
+to our test suite.  You may especially want to contribute tests that
+examine the functionality critical to your system, as this will ensure
+that all future @strong{MySQL} releases will work well with your
+applications.
+
+@menu
+* running mysqltest::           
+* extending mysqltest::         
+* Reporting mysqltest bugs::    
+@end menu
+
+@node running mysqltest, extending mysqltest, MySQL test suite, MySQL test suite
+@subsection Running the MySQL Test Suite
+
+The test system consist of a test language interpreter
+(@code{mysqltest}), a shell script to run all
+tests(@code{mysql-test-run}), the actual test cases written in a special
+test language, and their expected results.  To run the test suite on
+your system after a build, type @code{make test} or
+@code{mysql-test/mysql-test-run} from the source root.  If you have
+installed a binary distribution, @code{cd} to the install root
+(eg. @code{/usr/local/mysql}), and do @code{scripts/mysql-test-run}.
+All tests should succeed.  If not, you should try to find out why and
+report the problem if this is a bug in @strong{MySQL}.
+@xref{Reporting mysqltest bugs}.
 
 If you have a copy of @code{mysqld} running on the machine where you want to
 run the test suite you do not have to stop it, as long as it is not using
@@ -42503,14 +42560,14 @@ ports @code{9306} and @code{9307}.  If one of those ports is taken, you should
 edit @code{mysql-test-run} and change the values of the master and/or slave
 port to one that is available.
 
-The current set of test cases is far from comprehensive, as we have not yet
-converted all of our private tests to the new format.  However, it should 
-already catch most obvious bugs in the SQL processing code, OS/library issues,
-and is quite thorough in testing replication.  Our eventual goal is to have 
-the tests cover 100% of the code.  We welcome contributions to our test suite.
-You may especially want to contribute tests that examine the functionality 
-critical to your system, as this will ensure that all future @strong{MySQL} 
-releases will work well with your applications.
+You can run one individual test case with
+@code{mysql-test/mysql-test-run test_name}.
+
+If one test fails, you should test running @code{mysql-test-run} with
+the @code{--force} option to check if any other tests fails.
+
+@node extending mysqltest, Reporting mysqltest bugs, running mysqltest, MySQL test suite
+@subsection Extending the MySQL Test Suite
 
 You can use the @code{mysqltest} language to write your own test cases.
 Unfortunately, we have not yet written full documentation for it - we plan to
@@ -42518,16 +42575,10 @@ do this shortly.  You can, however, look at our current test cases and use
 them as an example.  The following points should help you get started:
 
 @itemize
-
 @item
 The tests are located in @code{mysql-test/t/*.test}
 
 @item
-You can run one individual test case with
-@code{mysql-test/mysql-test-run test_name}
-removing @code{.test} extension from the file name
-
-@item
 A test case consists of @code{;} terminated statements and is similar to the
 input of @code{mysql} command line client.  A statement by default is a query
 to be sent to @strong{MySQL} server, unless it is recognized as internal
@@ -42555,15 +42606,9 @@ test produces more than one result, you should use @code{test_name.a.result},
 @code{test_name.b.result}, etc.
 
 @item
-Failed test results are put in a file with the same base name as the
-result file with the @code{.reject} extension.  If your test case is
-failing, you should do a diff on the two files.  If you cannot see how
-they are different, examine both with @code{od -c} and also check their
-lengths.
-
-@item
-You can prefix a query with @code{!} if the test can continue after that query
-returns an error.
+If a statement returns an error, you should on the line before the statement
+specify with the @code{--error error-number}.  The error number can be
+a list of possible error numbers separated with @code{','}.
 
 @item
 If you are writing a replication test case, you should on the first line of
@@ -42602,6 +42647,9 @@ attachments, you should ftp all the relevant files to:
 
 @end itemize
 
+@node Reporting mysqltest bugs,  , extending mysqltest, MySQL test suite
+@subsection Extending the MySQL Test Suite
+
 If your @strong{MySQL} version doesn't pass the test suite you should
 do the following:
 
@@ -42612,6 +42660,26 @@ what when wrong!  When you do it, please use the @code{mysqlbug} script
 so that we can get information about your system and @code{MySQL}
 version. @xref{Bug reports}.
 @item
+Make sure to include the output of @code{mysql-test-run}, as well as
+contents of all @code{.reject} files in @code{mysql-test/r} directory.
+@item
+If a test in the test suite fails, check if the test fails also when run
+by its own:
+
+@example
+cd mysql-test
+mysql-test-run --local test-name
+@end example
+
+If this fails, then you should configure @strong{MySQL} with
+@code{--with-debug} and run @code{mysql-test-run} with the
+@code{--debug} option. If this also fails send the trace file
+@file{var/tmp/master.trace} to ftp://support.mysql.com/pub/mysql/secret
+so that we can examine it. Please remember to also include a full
+description of your system, the version of the mysqld binary and how you
+compiled it.
+
+@item
 If you have compiled @strong{MySQL} yourself, check our manual for how
 to compile @strong{MySQL} on your platform or, preferable, use one of
 the binaries we have compiled for you at
@@ -42622,10 +42690,14 @@ pass the test suite !
 If you get an error, like @code{Result length mismatch} or @code{Result
 content mismatch} it means that the output of the test didn't match
 exactly the expected output. This could be a bug in @strong{MySQL} or
-that your @code{mysqld} version produces slightly different results under some
-circumstances. In this case, you should compare the @file{.test}
-and @file{.reject} file in the @file{mysql-test/r} sub directory to
-see if this is something to worry about.
+that your mysqld version produces slight different results under some
+circumstances.
+
+Failed test results are put in a file with the same base name as the
+result file with the @code{.reject} extension.  If your test case is
+failing, you should do a diff on the two files.  If you cannot see how
+they are different, examine both with @code{od -c} and also check their
+lengths.
 
 @item
 If a test fails totally, you should check the logs file in the
@@ -42633,7 +42705,8 @@ If a test fails totally, you should check the logs file in the
 
 @item
 If you have compiled @strong{MySQL} with debugging you can try to debug this
-with the @code{--gdb} and @code{--debug} options to @code{mysql-test-run}.
+by running @code{mysql-test-run} with the @code{--gdb} and/or @code{--debug}
+options.
 @xref{Making trace files}.
 
 If you have not compiled @strong{MySQL} for debugging you should probably
@@ -43459,6 +43532,11 @@ these tables directly without ODBC-driver.
 Windows GUI (binary only) to administrate a database, by David B. Mansel,
 @email{david@@zhadum.org}.
 
+
+@item @uref{http://members.xoom.com/_opex_/mysqlmanager/index.html, MySQL Manager}
+a graphical MySQL server manager for MySQL server written in Java, for Windows
+
+
 @item @uref{http://www.mysql.com/Downloads/Win32/netadmin.zip, netadmin.zip}
 An administrator tool for @strong{MySQL} on Windows 95/98 and Windows NT
 4.0. Only tested with @strong{MySQL} Versions 3.23.5 - 3.23.7. Written
@@ -44553,6 +44631,9 @@ not yet 100% confident in this code.
 @appendixsubsec Changes in release 3.23.39
 @itemize @bullet
 @item
+Fixed that date-part extract functions works with dates where day
+and/or month is 0.
+@item
 Extended argument length in option files from 256 to 512 chars.
 @item
 Fixed problem with shutdown when @code{INSERT DELAYED} was waiting for