GENERAL INFORMATION

JdmMysqlDriver is a VisualWorks 3.0 Smalltalk driver for Mysql.
The current version is JdmMysqlDriver 0.1.0.

INSTALLATION:

To install the Mysql driver, load the parcel named "JdmMysqlDriver-X.X.X" 
from the distribution directory.  If you want to load the test suite as 
well, load the parcel JdmMysqlDriverTests-X.X.X.

MYSQL VERSIONS SUPPORTED:

The Mysql driver has only been tested using versions 3.21.33b and
3.22.14-gamma, however all versions in between should work.  It has
been tested on Linux (Red Hat 5.1 kernel version 2.0.36)...it should
work on all other platforms as well.

The driver does not support the YEAR type which is new to 3.22.

USAGE:

Using the driver is fairly simple.  To execute a query you need to 
create a connection to the database, create a statement on the connection,
and execute your query.

Example:

Let's say I want to connect to the "test" database on the localhost.
My user name is "doe" and my password is "mypass".  I will first
need to create a JdmConnection defined by a JdmConnectionSpec.
The JdmConnectionSpec is initialized with defaults for all its values
which are:

user := ''.
password := ''.
host := 'localhost'.
port := 3306.
database := 'test'

Here is the example code.

| connection statement result |

connection := JdmConnection on: 
  (JdmConnectionSpec new initialize user: 'doe'; password: 'mypass').

Now I want to insert a row into a table I have named "aTable".  First
I need to create a statement.

statement := connection createStatement.

Now execute the query.

result := statement executeQuery: 'insert into aTable (aField) values (aValue)'.

The result that is returned is a JdmResult.  It holds two values:  The result
type and the actual result value.  For update queries (such as INSERT,
UPDATE, DELETE, CREATE TABLE, etc.) the type is set to #update and the
value is an Integer designating the number of rows effected.  For read
queries (such as SELECT...others such as SHOW, DESCRIBE, etc are not
yet implemented) the type is set to #read and the value is a JdmResultSet.

A JdmResultSet reads rows off the result stream.  It also contains a
collection of column information (JdmColumns) which describe the type, size,
and other characteristics of the returned column.  Generally you
grab the columns by sending the "next" message to the result set.  
The next message returns a Boolean which indicates whether or not
there are any more rows to be read.  Do NOT read past the last row...
currently the driver will block when this happens.

A common usage of a JdmResultSet would be:

| resultSet value |

[resultSet next] whileFalse: [value := resultSet valueNamed: 'columnName'].

The result set has several accessing methods. They are:

valueAt: anInteger       -- returns the Smalltalk value at column 
                            number anInteger
rawValueAt: anInteger    -- returns the raw (String) value at column
                            number anInteger
valueNamed: aString      -- returns the Smalltalk value for the column
                            named aString.
rawValueNamed: aString   -- returns the raw (String) value for the column
                            named aString

The value* methods use the JdmFieldConverter to convert the Mysql
data into Smalltalk objects.  The only unsupported Mysql type is
the YEAR type.  Mysql sends the types of columns with it's query
results which are used to determine what Smalltalk object a field should be
converted to.  One problem is that mysql reports SETS as STRINGS so SETS values
result in Strings. This will be resolved in in the 3.23 release of Mysql. 

Some of the converted types (such as FLOAT, DOUBLE, DATE, TIMESTAMP, and TIME)
are not returned as their Smalltalk equivalent. Holders are returned instead
which hold the Smalltalk equivalent.  All holders respond to
value and value: messages. The reason holders are used is that
the Smalltalk equivalent objects printing format is not usable in a
Mysql query.  The holders can print their Smalltalk value on
a stream as a Mysql type.  This is done by sending them the printOn: message.

NOTES

The error handling in the driver needs some work.  General errors and
database errors are reported well, but if the protocol fails the results can
be non-deterministic.  The protocol SHOULDNT fail unless the connection
is broken.  The sockets should be implemented in a non-blocking fashion, but
this is a shortcoming of VisualWorks.  Blocking sockets cause the system
to wait for an undetermined amount of time if there is nothing available
on the stream.  This scenario occurs when a connection is broken or
an attempt is made to read past the end of an ExternalStream.  If you
VisualWorks seems to freeze when you try to connect to the
database, it means that a connection cannot be established and
VisualWorks is blocking.  Hit Ctrl-y to interrupt.

If a JdmResultSet is opened and not read to the end, no further queries
can be made on the connection.  Eventually the driver will handle this,
but it does not at this time.

Mysql supports times between -838:59:59 and 838:59:59 however the VisualWorks
Time class only supports times between 00:00:00 and 23:59:59 so any value
in the database outside this range cannot be converted to Time.  You can
get the raw value and handle it yourself.

If you declare a Mysql numeric type with the qualifier ZEROFILL, automatic
conversion to the corresponding Smalltalk type will drop the zeroes. Get
the raw value to avoid this.

Only full Timestamps are currently converted (ie a TIMESTAMP(14)).

When ObjectShare releases their beta to the public (supposedly
sometime in January 99) I will port the driver to their common
database interface.

TESTING

See INSTALLATION for installing the test suites.  To run the test suites
your mysql server needs to be on the local machine, the database "test" 
needs to exists (it is created initially by the mysql_install_db script),
and all users on the localhost need full access to the database "test".

The described conditions are true when Mysql is first installed.

The tests run fairly slow since each row consists of all possible
Mysql types and many of the inserted values are generated.

To run the tests execute the following:

JdmMysqlTestSuite new run inspect

KNOWN BUGS

None.

This is the first release of the driver so there are bound to be bugs
lurking.  I have attempted to test it thoroughly (see the test suites), 

ACKNOWLEDGEMENTS

Thanks to:
  The guys at TCX for writing Mysql and letting us all use it.
  Michael Widenius (Monty) for being so helpful in answering
   my questions.

CONTACT

Please report bugs to joshmiller@earthlink.net.  

If you get the driver to work on platforms other than
the Red Hat 5.1 distribution of Linux (kernel version 2.0.36) 
please let me know.
