bk commit - mysqldoc tree (paul:1.2907)

[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.2907 05/04/27 10:30:17 paul@stripped +1 -0
  manual.texi:
    Describe effect of new system variable more explicitly,
    including a non-intuitive behavior.

  Docs/manual.texi
    1.2760 05/04/27 10:29:44 paul@stripped +52 -9
    Describe effect of new system variable more explicitly,
    including a non-intuitive behavior.

# 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:	kite-hub.kitebird.com
# Root:	/src/extern/MySQL/bk/mysqldoc

--- 1.2759/Docs/manual.texi	2005-04-26 20:48:51 -05:00
+++ 1.2760/Docs/manual.texi	2005-04-27 10:29:44 -05:00
@@ -11040,12 +11040,15 @@
 @item
 @strong{Incompatible change:}
 @code{TIMESTAMP} is returned as a string in @code{'YYYY-MM-DD HH:MM:SS'}
-format (from 4.0.12 the @code{--new} option can be used to make a
-4.0 server behave as 4.1 in this respect).
+format.
 @xref{TIMESTAMP 4.1,  , @code{TIMESTAMP} 4.1}.
-
-If you want to have the value returned as a number (as MySQL 4.0 does) you
-should add @code{+0} to @code{TIMESTAMP} columns when you retrieve them:
+From 4.0.12 on, the @code{--new} option can be used to make a 4.0 server
+behave as 4.1 in this respect.  The effect of this option is described in
+@ref{TIMESTAMP pre-4.1,  , @code{TIMESTAMP} pre-4.1}.
+
+When running the server with @code{--new}, if you want to have a
+@code{TIMESTAMP} column returned as a number (as MySQL 4.0 does by default),
+you should add @code{+0} when you retrieve it:
 
 @example
 mysql> SELECT ts_col + 0 FROM @var{tbl_name};
@@ -46311,8 +46314,8 @@
 
 @end itemize
 
-@code{TIMESTAMP} columns other than the first can also be set to the current
-date and time.  Just set the column to @code{NULL} or to any function that
+A @code{TIMESTAMP} column other than the first also can be assigned the
+current date and time by setting it to @code{NULL} or to any function that
 produces the current date and time (@code{NOW()}, @code{CURRENT_TIMESTAMP}).
 
 You can set any @code{TIMESTAMP} column to a value different from the current
@@ -46342,7 +46345,7 @@
 
 Another way to maintain a column that records row-creation time is to use
 a @code{DATETIME} column that you initialize to @code{NOW()} when the row
-is created and leave alone for subsequent updates.
+is created and do not modify for subsequent updates.
 
 @code{TIMESTAMP} values may range from the beginning of 1970 to partway
 through the year 2037, with a resolution of one second.  Values are displayed
@@ -46421,6 +46424,44 @@
 produces a meaningless result.
 @end itemize
 
+In MySQL 4.1, @code{TIMESTAMP} display format changes to be the same as
+@code{DATETIME}, that is, as a string in @code{'YYYY-MM-DD HH:MM:SS'} format
+rather than as a number in @code{YYYYMMDDHHMMSS} format. To test applications
+written for MySQL 4.0 for compatibility with this change, you can set the
+@code{new} system variable to 1.  This variable is available beginning with
+MySQL 4.0.12. It can be set at server startup by specifying the @code{--new}
+option to @command{mysqld}. At runtime, a user who has the @code{SUPER}
+privilege can set the global value with a @code{SET} statement:
+
+@example
+mysql> SET GLOBAL new = 1;
+@end example
+
+Any client can set its session value of @code{new} as follows:
+
+@example
+mysql> SET new = 1;
+@end example
+
+The general effect of setting @code{new} to 1 is that values for a
+@code{TIMESTAMP} column display as strings rather than as numbers.  Also,
+@code{DESCRIBE} displays the column definition as @code{timestamp(19)},
+rather than as @code{timestamp(14)}.
+
+However, the effect differs somewhat for @code{TIMESTAMP} columns that are
+created while @code{new} is set to 1.  In this case, column values display
+as strings and @code{DESCRIBE} shows the definition as @code{timestamp(19)},
+regardless of the current value of @code{new}.
+
+In other words, with @code{new=1}, all @code{TIMESTAMP} values display as
+strings and @code{DESCRIBE} shows a display width of 19.  For columns created
+while @code{new=1}, they continue to display as strings and to have a display
+width of 19 even if @code{new} is set to 0.
+
+For a @code{TIMESTAMP} column that displays as a string, you can display
+it as a number by retrieving it as @code{@var{col_name}+0}.
+
+
 @node TIMESTAMP 4.1,  , TIMESTAMP pre-4.1, DATETIME
 @subsubsection @code{TIMESTAMP} Properties as of MySQL 4.1
 
@@ -106349,7 +106390,9 @@
 @item
 The @code{--new} option can be used to make a 4.0 server return
 @code{TIMESTAMP} as a string in @code{'YYYY-MM-DD HH:MM:SS'}
-format, the way that 4.1 servers do.
+format, the way that 4.1 servers do.  This is also a @code{new} system
+variable that can be set for the same effect.
+@xref{TIMESTAMP pre-4.1,  , @code{TIMESTAMP pre-4.1}}.
 @end itemize
 
 Bugs fixed: