bk commit - mysqldoc tree (paul:1.2651)

[paul]

Below is the list of changes that have just been committed into a local
mysqldoc repository of paul. When paul does a push these changes will
be propagated to the main repository and, within 24 hours after the
push, to the public repository.
For information on how to access the public repository
see http://www.mysql.com/doc/I/n/Installing_source_tree.html

ChangeSet
  1.2651 05/03/03 08:29:05 paul@stripped +1 -0
  Revise "installing server as Windows service" section:
  - Be more explicit about what options are allowed after service
    name.
  - Mention possibility of option other than --defaults-file. (Ugh.)
  - Mention --local-service option added in 5.0.1.

  Docs/manual.texi
    1.2467 05/03/03 08:29:00 paul@stripped +102 -62
    Revise "installing server as Windows service" section:
    - Be more explicit about what options are allowed after service
      name.
    - Mention possibility of option other than --defaults-file. (Ugh.)
    - Mention --local-service option added in 5.0.1.

# This is a BitKeeper patch.  What follows are the unified diffs for the
# set of deltas contained in the patch.  The rest of the patch, the part
# that BitKeeper cares about, is below these diffs.
# User:	paul
# Host:	frost.snake.net
# Root:	/Volumes/frost2/MySQL/bk/mysqldoc

--- 1.2466/Docs/manual.texi	2005-03-02 22:07:40 -06:00
+++ 1.2467/Docs/manual.texi	2005-03-03 08:29:00 -06:00
@@ -6102,7 +6102,8 @@
 
 On NT-based systems such as Windows NT, 2000, XP, or 2003, clients have two
 options. They can use TCP/IP, or they can use a named pipe if the server
-supports named pipe connections.
+supports named pipe connections.  To get MySQL to work with TCP/IP on
+Windows NT 4, you must install service pack 3 (or newer).
 
 In MySQL versions 4.1 and higher, Windows servers also support shared-memory
 connections if started with the @code{--shared-memory} option.  Clients can
@@ -6205,10 +6206,10 @@
 @end example
 
 This invokes the MySQL administrative utility @command{mysqladmin} to
-connect to the server and tell it to shut down. The command connects
-as @code{root}, which is the default administrative account in the
-MySQL grant system. Note that users in the MySQL grant system
-are wholly independent from any login users under Windows.
+connect to the server and tell it to shut down. The command connects as the
+MySQL @code{root} user, which is the default administrative account in the
+MySQL grant system. Note that users in the MySQL grant system are wholly
+independent from any login users under Windows.
 
 If @command{mysqld} doesn't start, check the error log to see whether the
 server wrote any messages there to indicate the cause of the problem.
@@ -6243,9 +6244,6 @@
 @code{Services} utility while performing server installation or removal
 operations from this command line.  This prevents some odd errors.
 
-To get MySQL to work with TCP/IP on Windows NT 4, you must install
-service pack 3 (or newer).
-
 Before installing MySQL as a Windows service, you should first stop
 the current server if it is running by using the following command:
 
@@ -6254,19 +6252,20 @@
 @end example
 
 This invokes the MySQL administrative utility @command{mysqladmin} to
-connect to the server and tell it to shut down. The command connects
-as @code{root}, which is the default administrative account in the
-MySQL grant system. Note that users in the MySQL grant system
-are wholly independent from any login users under Windows.
+connect to the server and tell it to shut down. The command connects as the
+MySQL @code{root} user, which is the default administrative account in the
+MySQL grant system. Note that users in the MySQL grant system are wholly
+independent from any login users under Windows.
 
-Install the server as a service:
+Install the server as a service using this command:
 
 @example
 C:\> mysqld --install
 @end example
 
 If you have problems installing @command{mysqld} as a
-service using just the server name, try installing it using its full pathname:
+service using just the server name, try installing it using its full pathname.
+For example:
 
 @example
 C:\> C:\mysql\bin\mysqld --install
@@ -6277,24 +6276,56 @@
 @c If that doesn't work, you can get @command{mysqld} to
 @c start properly by fixing the path in the registry!
 
-As of MySQL 4.0.2, you can specify a specific service name after the
-@code{--install} option.  As of MySQL 4.0.3, you can in addition specify a
-@code{--defaults-file} option after the service name to indicate where the
-server should obtain options when it starts. The rules that determine the
-service name and option files the server uses are as follows:
+The service-installation command does not start the server. Instructions for
+that are given later in this section.
+
+Before MySQL 4.0.2, no command-line arguments can be given following the
+@code{--install} option. MySQL 4.0.2 and up offer limited support for
+additional arguments:
 
 @itemize @bullet
 
 @item
-If you specify no service name or a name of @code{MySQL}, the server uses
-the default service name of @code{MySQL} and the reads options from
-the @code{[mysqld]} group in the standard option files.
+You can specify a service name immediately following the @code{--install}
+option. The default service name is @code{MySQL}.
 
 @item
-If you specify a service name other than @code{MySQL} after the
-@code{--install} option, the server reads options from the group that has
-the same name as the service.  The server reads options from the standard
-option files.
+As of MySQL 4.0.3, if a service name is given, it can be followed by a single
+option. By convention, this should be @code{--defaults-file=@var{file_name}}
+to specify the name of an option file from which the server should read
+options when it starts.
+
+It is possible to use a single option other than @code{--defaults-file}, but
+this is discouraged.  @code{--defaults-file} is more flexible because it
+enables you to specify multiple startup options for the server by placing
+them in the named option file. Also, in MySQL 5.0, use of an option
+different from @code{--defaults-file} is not supported until 5.0.3.
+
+@item
+As of MySQL 5.0.1, you can also specify a @code{--local-service} option
+following the service name. This causes the server to run using the
+@code{LocalService} Windows account that has limited system privileges.  If
+@code{--defaults-file} and @code{--local-service} both are given following
+the service name, they can be in any order.
+
+@end itemize
+
+For a MySQL server that is installed as a Windows service, the following
+rules determine the service name and option files that the server uses:
+
+@itemize @bullet
+
+@item
+If the service-installation command specifies no service name or the default
+service name (@code{MySQL}), the server uses the a service name of
+@code{MySQL} and the reads options from the @code{[mysqld]} group in the
+standard option files.
+
+@item
+If the service-installation command specifies a service name other than
+@code{MySQL} following the @code{--install} option, the server uses that
+service name. It reads options from the group that has the same name as the
+service, and reads options from the standard option files.
 
 As of MySQL 4.0.17, the server also reads options from the @code{[mysqld]}
 group from the standard option files.  This allows you to use the
@@ -6303,18 +6334,12 @@
 with that service name.
 
 @item
-If you specify a @code{--defaults-file} option after the service name,
-the server ignores the standard option files and reads options only from the
-@code{[mysqld]} group of the named file.
+If the service-installation command specifies a @code{--defaults-file}
+option after the service name, the server ignores the standard option files
+and reads options only from the @code{[mysqld]} group of the named file.
 
 @end itemize
 
-@strong{Note}: Prior to MySQL 4.0.17, a server installed as a Windows
-service has problems starting if its pathname or the service name contains
-spaces. For this reason, with older versions, avoid installing MySQL in a
-directory such as @file{C:\Program Files} or using a service name containing
-spaces.
-
 As a more complex example, consider the following command:
 
 @example
@@ -6331,24 +6356,30 @@
 You can also specify options as ``@code{Start parameters}'' in the
 Windows @code{Services} utility before you start the MySQL service.
 
-Once a MySQL server is installed as a service, Windows starts
+@strong{Note}: Prior to MySQL 4.0.17, a server installed as a Windows
+service has problems starting if its pathname or the service name contains
+spaces. For this reason, with older versions, avoid installing MySQL in a
+directory such as @file{C:\Program Files} or using a service name containing
+spaces.
+
+Once a MySQL server has been installed as a service, Windows starts
 the service automatically whenever Windows starts.  The service also
 can be started immediately from the @code{Services} utility, or by
 using the command @command{NET START MySQL}.  The @command{NET} command
 is not case sensitive.
 
-When run as a service, @command{mysqld} has no access
-to a console window, so no messages can be seen there.  If
-@command{mysqld} doesn't start, check the error log to see whether the
-server wrote any messages there to indicate the cause of the problem.
-The error log is located in the @file{C:\mysql\data} directory. It
-is the file with a suffix of @file{.err}.
-
-When @command{mysqld} is running as a service, it can be stopped by
-using the @code{Services} utility, the command @command{NET STOP
-MySQL}, or the command @command{mysqladmin shutdown}. If the service
-is running when Windows shuts down, Windows stops the server
-automatically.
+When run as a service, @command{mysqld} has no access to a console window,
+so no messages can be seen there.  If @command{mysqld} doesn't start, check
+the error log to see whether the server wrote any messages there to indicate
+the cause of the problem.  The error log is located in the MySQL data
+directory (for example, @file{C:\mysql\data}). It is the file with a suffix
+of @file{.err}.
+
+When a MySQL server has been installed as a service, and the service is
+running, Windows stops the service automatically when Windows shuts down.
+The server also can be stopped manually by using the @code{Services}
+utility, the command @command{NET STOP MySQL}, or the command
+@command{mysqladmin shutdown}.
 
 From MySQL 3.23.44 on, you have the choice of installing the
 server as a @code{Manual} service if you don't wish the service to
@@ -6372,7 +6403,7 @@
 seconds for the shutdown to complete, then killed the database
 server process if the time limit was exceeded. This had the potential
 to cause problems.  (For example, the @code{InnoDB} storage engine
-had to perform crash recovery at the next startup.) Starting from
+would have to perform crash recovery at the next startup.) Starting from
 MySQL 3.23.49, Windows waits longer for the MySQL server
 shutdown to complete. If you notice this still is not enough for
 your installation, it is safest not to run the MySQL server as a
@@ -6389,7 +6420,7 @@
 in the Registry tree. Specify the new larger value in milliseconds.
 For example, the value 120000 tells Windows NT to wait up to 120 seconds.
 
-If you don't want to start @command{mysqld} as a service, you can start it
+If @command{mysqld} is not running as a service, you can start it
 from the command line.  For instructions, see @ref{Windows start command
 line}.
 
@@ -6422,11 +6453,12 @@
 You can force a MySQL client to use a named pipe connection rather than
 TCP/IP by specifying the @code{--pipe} option or by specifying @code{.}
 (period) as the host name.  Use the @code{--socket} option to specify the
-name of the pipe.  As of MySQL 4.1, you should use the
-@code{--protocol=PIPE} option.
+name of the pipe.  As of MySQL 4.1, you can use the
+@code{--protocol=PIPE} option instead.
 
-There are two versions of the MySQL command-line tool:
-@multitable @columnfractions .20 .80
+There are two versions of the MySQL command-line tool on Windows:
+
+@multitable @columnfractions .15 .85
 @item @strong{Binary} @tab @strong{Description}
 @item @command{mysql} @tab Compiled on native Windows, offering limited
 text editing capabilities.
@@ -6442,15 +6474,12 @@
 @c suitable period of time has elapsed. Suggestion: Move this info to a
 @c separate 'legacy' page?
 
-If you want to use @command{mysqlc}, you must have a copy of the
-@file{cygwinb19.dll} library installed somewhere that @command{mysqlc}
-can find it. Current distributions of MySQL include this library
-in the same directory as @command{mysqlc} (the @file{bin} directory
-under the base directory of your MySQL installation). If your
+To use @command{mysqlc}, you must have a copy of the @file{cygwinb19.dll}
+library installed somewhere that @command{mysqlc} can find it.  If your
 distribution does not have the @code{cygwinb19.dll} library in the
-@file{bin} directory, look for it in the @code{lib} directory and
-copy it to your Windows system directory
-(@file{\Windows\system} or a similar place).
+@file{bin} directory under the base directory of your MySQL installation,
+look for it in the @code{lib} directory and copy it to your Windows system
+directory (@file{\Windows\system} or a similar place).
 
 @c TODO: check whether it needs to be in the *system* directory, or if
 @c it can be in the Windows directory.
@@ -96452,6 +96481,10 @@
 Functionality added or changed:
 @itemize @bullet
 @item
+Allow the service-installation command for Windows servers to specify a single
+option other than @code{--defaults-file} following the service name. This is
+for compatibility with MySQL 4.1. (Bug #7856)
+@item
 @code{InnoDB}: Commit after every 10,000 copied rows when executing
 @code{ALTER TABLE}, @code{CREATE INDEX} or @code{DROP INDEX}.  This makes it
 much faster to recover from an aborted operation.
@@ -97111,6 +97144,13 @@
 
 Functionality added or changed:
 @itemize @bullet
+@item
+When installing a MySQL server as a Windows service, the installation
+command can include a @code{--local-service} option following the service
+name to cause the server to run using the @code{LocalService} Windows
+account that has limited privileges.  This is in addition to the
+@code{--defaults-file} option that also can be given following the service
+name.
 @item
 Added support for read-only and updatable views based on a single table or
 other updatable views. View use requires that you upgrade your grant tables