mSQL -> Tcl/Tk  Version 0.2:
----------------------------

    This is a preliminary document explaining the mSQL to Tcl/Tk interface.
    The interface as it stands can do all that the current mSQL API allows.
    It will likely change in the future when the mSQL API is worked on
    some more.  If anyone has a good name for this beast, please mail me!

Commands:
---------

    msql connect <name> [ <host> ]

        Connects to the mSQL database.  Creates a new command using the
	<name> that will be used for all future interaction with the
	connection.  Returns a blank string on success or an error string
	on failure.  This must be done before any other sql commands.
	The host is optional and if not given the connection will be
	to the local machine.

    msql connections

	This returns a list of all the current connection names.  It is
	not currently implemented.

    <name> get databases

	Returns a list of space seperated databases available from the
	mSQL daemon you are connected to.

    <name> set database <database>

	Sets the current database.  It can be changed at any time.  It
	will return either an empty string on success or an error string
	on failure.  This must be done before any commands that work
	on the current database.

    <name> get tables

	Returns a list of space seperated tables available in the current
	database.

    <name> get fields <table>

	Returns a list of space seperated field info.

    <name> query <query>

	Passes the <query> to mSQL.  Returns a blank string on success or
	an errors message on failure.

    <name> get ( rest | next )

	Return either the next row or all the rest of the rows.  The next
	row is returned as a list of column data.  The rest of the rows
	will be returned as a list or rows elements which are a list of
	column data.

    <name> get rows

	Returns the number of rows in the last query result.

    <name> get cols

	Returns the number of columns in the last query result.

    <name> disconnect

	Disconnects from the mSQL daemon and deletes the <name> command.

Known Bugs:
-----------

    The mSQL API currently will freeze if you do things like queries
    before you have set the database.

Limitations:
------------

    Only one database can be used per connection.  This is how the
	mSQL API works.
    The query command doesn't return until the query is done.

Future Plans:
-------------

    The future plans all depend on changes to the current mSQL API.
    The admin stuff like creating and dropping tables should be available
    through the API.

    The current way of hacking up the 'tclmsql' and 'msqlwish' programs
    is not very nice.  It comes from looking at how the 'sql_tcl' package
    did its interface.  Comments on how to do this better would be
    appreciated.

Contents:
---------

    This tar file contains:

	README		- this file
	tclSQL.c/h	- my source code for the new Tcl commands
	tclAppInit.c	- replacement for the tclAppInit.c in tcl7.3
	tkAppInit.c	- replacement for the tkAppInit.c in tk3.6
	Makefile	- makefile to build tclmsql and msqlwish
	test.tcl	- simple test Tcl program to try things out
	test.tk		- simple test Tk program to try things out

Installation:
-------------

    To install this you will need the tcl, tk, and msql includes and
    libraries.  To build the programs:

	1. Edit Makefile and change the paths for the TCL_INC/LIB,
		TK_INC/LIB, and MSQL_INC/LIB variables.

	2. Type 'make'

    If all goes well you should get two programs generated.  The first
    is called 'tclmsql' which is a simple 'tclsh' replacement with the
    'sql' command included.  The second is called 'msqlwish' which is
    a wish replacement with the 'sql' command included.

    You can test it out by typing 'test.tcl' to run the test program
    provided.  The mSQL daemon (msqld) must be running or you won't
    be able to connect.

Author Details:
---------------

    This code was written by:

	Brad Pepers
	Senior Systems Analyst
	Choice Software Systems Ltd.

    Email: pepersb@cuug.ab.ca

Credits:
--------

    This code would not have been possible (well it would have been
    possible but stupid to write when there was nothing to interface to!)
    without the great contribution of Mini SQL by David J. Hughes.  My
    thanks to him for giving me something to interface to!

Questions/Comments:
-------------------

    Any questions or comments should be sent to pepersb@cuug.ab.ca.
