Added 4.1 protocol description

innobase/log/log0log.c:
  Removed compiler warnings

1 files changed, 270 insertions, 0 deletions

diff --git a/Docs/internals.texi b/Docs/internals.texi
index 1f803f43a22..7e364774e39 100644
--- a/Docs/internals.texi
+++ b/Docs/internals.texi
@@ -1579,6 +1579,276 @@ fe 00                       . .
 
 @c @printindex fn
 
+@node 4.1 protocol,,,
+@subchapter MySQL 4.1 protocol
+
+@node 4.1 protocol changes,,,
+@section Changes to 4.0 protocol in 4.1
+
+All basic package handling is identical to 4.0. When communication
+with an old 4.0 or 3.x client we will use the old protocol.
+
+The new things that we support with 4.1 are:
+
+@itemize @bullet
+@item
+Warnings
+@item
+Prepared statements
+@item
+Binary protocol (will be much faster than the current protocol that
+converts everything to strings)
+@end itemize
+
+
+What has changed in 4.1 are:
+
+@itemize @bullet
+@item
+A lot of new field information (database, real table name etc)
+@item
+The 'ok' packet has more status fields
+@item
+The 'end' packet (send last for each result set) now contains some
+extra information
+@item
+New protocol for prepared statements.  In this case all parameters and
+results will sent as binary (low-byte-first).
+@end itemize
+
+
+@node 4.1 field package,,,
+@section 4.1 field description package
+
+The field description package is sent as a response to a query that
+contains a result set.  It can be distinguished from a ok package by
+the fact that the first byte can't be 0 for a field package.
+@xref {4.1 ok package}.
+
+The header package has the following structure:
+
+@multitable @columnfractions .10 .90
+@item Size @tab Comment
+@item 1-9  @tab Number of columns in result set (never 0)
+@item 1-9  @tab Extra information sent be some command (SHOW COLUMNS
+uses this to send the number of rows in the table)
+@end multitable
+
+This package is always followed by a field description set.
+@xref{4.1 field desc}.
+
+@node 4.1 field desc,,,
+@section 4.1 field description result set
+
+The field description result set contains the meta info for a result set.
+
+@multitable @columnfractions .20 .80
+@item Type   @tab Comment
+@item string @tab Database name
+@item string @tab Table name alias (or table name if no alias)
+@item string @tab Real table name
+@item string @tab Alias for column name (or column name if not used)
+@item 3 byte int @tab Length of column definition
+@item 1 byte int @tab Enum value for field type
+@item 3 byte int @tab 2 byte column flags (NOT_NULL_FLAG etc..) + 1 byte number of decimals.
+@item string int @tab Default value, only set when using mysql_list_fields().
+@end multitable
+
+
+@node 4.1 ok package,,,
+@section 4.1 ok package
+
+The ok package is the first that is sent as an response for a query
+that didn't return a result set.
+
+The ok package has the following structure:
+
+@multitable @columnfractions .10 .90
+@item Size @tab Comment
+@item 1	  @tab  0 ; Marker for ok package
+@item 1-9 @tab	Affected rows
+@item 1-9 @tab  Last insert id (0 if one wasn't used)
+@item 2   @tab  Server status; Can be used by client to check if we are inside an transaction
+@item 2	  @tab  Warning count
+@item 1-9 @tab  Message length (optional)
+@item xxx @tab  Message (optional)
+@end multitable
+
+Size 1-9 means that the parameter is packed in to 1-9 bytes depending on
+the value.  (See function sql/net_pkg.cc::net_store_length).
+
+The message is optional.  For example for multi line INSERT it
+contains a string for how many rows was inserted / deleted.
+
+
+@node 4.1 end package,,,
+@section 4.1 end package
+
+The end package is sent as the last package for
+
+@itemize @bullet
+@item
+End of field information
+@item
+End of parameter type information
+@item
+End of result set
+@end itemize
+
+The end package has the following structure:
+
+@multitable @columnfractions .10 .90
+@item Size @tab Comment
+@item 1	   @tab 254  ; Marker for EOF package
+@item 2	   @tab Warning count
+@item 2	   @tab Status flags (For flags like SERVER_STATUS_MORE_RESULTS)
+@end multitable
+
+Note that a normal package may start with byte 254, which means
+'length stored in 9 bytes'.  One can different between these cases
+by checking the packet length < 9 bytes (in which case it's and end
+packet).
+
+
+@node 4.1 error package
+@section 4.1 error package.
+
+The error package is sent when something goes wrong.
+The error package has the following structure:
+
+@multitable @columnfractions .10 .90
+@item Size  @tab Comment
+@item 1	    @tab 255  Error package marker
+@item 1-255 @tab Null terminated error message
+@end multitable
+
+The client/server protocol is designed in such a way that a package
+can only start with 255 if it's an error package.
+
+
+@node 4.1 prep init,,,
+@section 4.1 prepared statement init package
+
+This is the return package when one sends a query with the COM_PREPARE
+command.
+
+@multitable @columnfractions .10 .90
+@item Size @tab Comment
+@item 4	   @tab Statement handler id
+@item 2	   @tab Number of columns in result set
+@item 2	   @tab Number of parameters in query
+@end multitable
+
+After this, there is a packet that contains the following for each
+parameter in the query:
+
+@multitable @columnfractions .10 .90
+@item Size @tab Comment
+@item 2	@tab Enum value for field type. (MYSQL_TYPE_UNKNOWN if not known)
+@item 2 @tab 2 byte column flags (NOT_NULL_FLAG etc)
+@item 1 @tab Number of decimals
+@item 4 @tab Max column length.
+@end itemize
+
+Note that the above is not yet in 4.1 but will be added this month.
+
+As MySQL can have a parameter 'anywhere' it will in many cases not be
+able to provide the optimal information for all parameters.
+
+If number of columns, in the header package, is not 0 then the
+prepared statement will contain a result set. In this case the package
+is followed by a field description result set. @xref{4.1 field descr}.
+
+
+@node 4.1 long data,,,
+@section 4.1 long data handling
+
+This is used by mysql_send_long_data() to set any parameter to a string
+value.  One can call mysql_send_long_data() multiple times for the
+same parameter; The server will concatenate the results to a one big
+string.
+
+The server will not require an end package for the string.
+mysql_send_long_data() is responsible updating a flag that all data
+has been sent. (Ie;  That the last call to mysql_send_long_data() has
+the 'last_data' flag set).
+
+This package is sent from client -> server:
+
+@multitable @columnfractions .10 .90
+@item Size @tab Comment
+@item 4	@tab Statement handler
+@item 2 @tab Parameter number
+@item 2 @tab Type of parameter  (not used at this point)
+@item # @tab data (Rest of package)
+@end itemize
+
+The server will NOT send an @code{ok} or @code{error} package in
+responce for this.  If there is any errors (like to big string), one
+will get the error when calling execute.
+
+@node 4.1 execute,,,
+@section 4.1 execute
+
+On execute we send all parameters to the server in a COM_EXECUTE
+package.
+
+The package contains the following information:
+
+@multitable @columnfractions .30 .70
+@item Size @tab Comment
+@item (param_count+7)/8 @tab Null bit map
+@item 1	   @tab new_parameter_bound flag.  Is set to 1 for first
+execute or if one has rebound the parameters.
+@item 2*param_count     @tab Type of parameters (only given if new_parameter_bound flag is 1)
+@item #    @tab Parameter data, repeated for each parameter that are
+NOT NULL and not used with mysql_send_long_data().
+@end itemize
+
+The null-bit-map is for all parameters (including parameters sent with
+'mysql_send_long_data). If parameter 0 is NULL, then bit 0 in the
+null-bit-map should be 1 (ie:  first byte should be 1)
+
+The parameters are stored the following ways:
+
+@multitable @columnfractions .20 .10 .70
+@item Type    @tab Size @tab Comment
+@item tynyint @tab 1	@tab One byte integer
+@item short   @tab 2	@tab
+@item int     @tab 4	@tab
+@item longlong @tab 8	@tab
+@item float   @tab 4	@tab
+@item double  @tab 8	@tab
+@item string  @tab 1-9 + # @tab Packed string length + string
+@end multitable
+
+The result for this will be either an ok package or a binary result
+set.
+
+@node 4.1 binary result,,,
+@section 4.1 binary result set
+
+A binary result are sent the following way.
+
+For each result row:
+
+@itemize
+@item
+null bit map with first two bits set to 01 (bit 0,1 value 1)
+@item
+parameter data, repeated for each not null parameter.
+@end itemize
+
+The idea with the reserving two bits in the null map is that we can
+use standard error (first byte 255) and ok packages (first byte 0)
+to end a result sets.
+
+Except that the null-bit-map is shifted two steps, the server is
+sending the data to the client the same way that the server is sending
+bound parameters to the client.  The server is always sending the data
+as type given for 'column type' for respective column.  It's up to the
+client to convert the parameter to the requested type.
+
 @node Fulltext Search,  , protocol, Top
 @chapter Fulltext Search in MySQL