If your storage engine returns an error from rnd_init (or doStartTableScan as it’s named in Drizzle) and does not save this error and return it in any subsequent calls to rnd_next, your engine is buggy. Namely it is buggy in that a) an error may not be reported back to the user and b) everything may explode horribly when rnd_next is called after rnd_init returned an error.
Unless it is running on MariaDB 5.2 or (soon, when the patch hits the tree) Drizzle.
Monty (ï»¿ï»¿Widenius, not Taylor) wrote a patch for MariaDB based on my bug report that addressed that problem. It uses the compiler feature to throw a warning if the result of a function isn’t checked to make sure that all places that call rnd_init are checking for an error from the engine.
Today I (finally) pulled that into Drizzle as well.
So… if your engine does the logical thing and goes “oh look, this method returns an error… I’ll return my error” it will exhibit bugs in MySQL but not MariaDB 5.2 or Drizzle (when patch hits).
Here’s something that’s not really documented anywhere (unless you count ha_innodb.cc as a source of server documentation). You may have some idea about the MySQL/Drizzle row buffer format. This is passed around the storage engine interface: in for write_row and update_row and out for the various scan and index read methods.
If you want to see the docs for it that exist in the code, check out store_key_val_for_row in ha_innodb.cc.
However, there is another format that is passed to your engine (and that your engine is expected to understand) and for lack of a better name, I’m going to call it the key tuple format. The first place you’ll probably see this is when implementing the index_read function for a Cursor (or handler in MySQL speak).
You get two things: a pointer to the buffer and the length of the buffer. Since a key can be made up of multiple parts, some of which can be NULL and some of which can be of variable length, this buffer is not (usually) a simple value. If you are starting out in your engine development, you can use this buffer blindly as a single value for non-nullable indexes with only 1 column.
The basic format is this:
The buffer is in-order of the index. First column in the index is first in the buffer, second second etc.
The buffer must be zero-filled. The server kernel will use memcmp to compare two key values.
If the column is NULLable, then the first byte is set to 1 if the column is null. Else, 0 means not-null.
From ha_innodb.cc (for BLOBs, which I haven’t put in embedded_innodb yet): If the column is of a BLOB type (it must be a column prefix fieldÂ in this case), then we put the length of the data in the field to theÂ next 2 bytes, in the little-endian format. If the field is SQL NULL,Â then these 2 bytes are set to 0. Note that the length of data in theÂ field is <= column prefix length.
For fixed length fields (such as int), the next max field length bytes are for that field.
For VARCHAR, there is always a 2 byte (in little endian) length. This is different to the row format, which may have 1 or 2 bytes. In the key tuple format it is ALWAYS two bytes.
I’ll discuss the use of this for rnd_pos() and position() in a later post…