NAME
	Sql.msql - mSQL SQL server interface

AUTHOR
	Francesco Chemolli <kinkie@comedia.it>

DESCRIPTION
	This is an interface to the mSQL database server.
	This module may or may not be availible on your Pike, depending
	whether the appropriate include and library files (msql.h and libmsql.a
	respectively) could be found at compile-time. Note that you DO NOT
	need to have a mSQL server running on your host to use this module:
	you can connect to the database over a TCP/IP socket

	Please notice that unless you wish to specifically connect to a mSQL
	server, you'd better use the Sql.sql program instead.
	I and Henrik Grubbström have (hopefully) designed a server-independent
	sql-server-class. The interfaces to all existing sql-classes
	are consistent. Using Sql.sql ensures that your pike
	applications will run with any supported SQL server without changing
	a single line of code.

	Also notice that some functions may mSQL/2.0 -specific, and thus missing on
	hosts running mSQL/1.0.*

SEE ALSO
	Sql.sql

============================================================================
NAME
	create - initialize module and/or select database

SYNTAX
	#include <sql.h>
	object msql();
	or
	object Sql.msql();
	or

	#include <msql.h>
	object msql(); //deprecated
	or
	object Msql.msql(); //deprecated

	Arguments (apply to all forementioned variants):
	msql->create();
	or
	msql->create(string hostname);
	or
	msql->create(string hostname, string dbname);

DESCRIPTION
	With one argument, this function
	tries to connect to the specified (use hostname or IP address) database
	server. To connect to a server running on the local host via UNIX domain
	sockets use "localhost". To connect to the local host via TCP/IP sockets
	you have to use the IP address "127.0.0.1".
	With two arguments it also selects a database to use on the server.
	With no arguments it tries to connect to the server on localhost, using
	UNIX sockets.

	The Msql.msql() syntax is deprecated. Please use the Sql.msql() program
	instead.

NOTA BENE
	You need to have a database selected before using the sql-object, 
	otherwise you'll get exceptions when you try to query it.
	Also notice that this function CAN raise exceptions if the db
	server doesn't respond, if the database doesn't exist or is not accessible
	by you.

	You don't need bothering about syncronizing the connection to the database:
	it is automatically closed (and the database is sync-ed) when the msql
	object is destroyed.

SEE ALSO
	msql->select_db

============================================================================
NAME
	select_db - Select the database you're using

SYNTAX
	#include <msql.h>
	void msql->select_db(string dbname);

DESCRIPTION
	Before querying a database you have to select it. This can be accomplished
	in two ways: the first is calling the create() function with two arguments,
	another is calling it with one or no argument and then calling select_db().
	You can also use this function to change the database you're querying,
	as long as it is on the same server you are connected to.

NOTA BENE
	This function CAN raise exceptions in case something goes wrong
	(for example: unexistant database, insufficient permissions, whatever).

SEE ALSO
	msql->create, msql->error

============================================================================
NAME
	query - query the db server

SYNTAX
	#include <msql.h>
	array(mapping(string:mixed)) query (string sql_query);

DESCRIPTION
	This is all you need to query the database. It takes as argument an SQL
	query string (i.e.: "SELECT foo,bar FROM baz WHERE name like '%kinkie%'" 
	or "INSERT INTO baz VALUES ('kinkie','made','this')")
	and returns a data structure containing the returned values.
	The structure is an array (one entry for each returned row) of mappings
	which have the column name as index and the column contents as data.
	So to access a result from the first example you would have to do
	"results[0]->foo".

	A query which returns no data results in an empty array (and NOT in a 0).
	Also notice that when there is a column name clash (that is: when you
	join two or more tables which have columns with the same name), the
	clashing columns are renamed to <tablename>+"."+<column name>.
	To access those you'll have to use the indexing operator '[]
	(i.e.: results[0]["foo.bar"]).

	Errors (both from the interface and the SQL server) are reported via
	exceptions, and you definitely want to catch them.

	Also note that if the query is NOT a of SELECT type, but UPDATE or
	MODIFY, the returned value is an empty array.
	THIS IS NOT AN ERROR. Errors are reported ONLY via exceptions.
	Error messages are not particularly verbose, since they account
	only for errors inside the driver. To get server-related error messages,
	you have to use the msql->error() function.

SEE ALSO
	msql->error

============================================================================
NAME
	list_dbs - list all databases availible on the server

SYNTAX
	#include <msql.h>
	array(string) list_dbs();
	or
	array(string) list_dbs(string glob);

DESCRIPTION
	Returns an array containing the names of all databases availible on
	the system. Will throw an exception if there is no server connected.
	If an argument is specified, it will return only those databases
	whose name matches the given glob.

============================================================================
NAME
	list_tables - list all the tables in the current database

SYNTAX
	#include <msql.h>
	array(string) list_tables();
	or
	array(string) list_tables(string glob);

DESCRIPTION
	Returns an array containing the names of all the tables in the currently
	selected database. Will throw an exception if we aren't connected to
	a database.
	If an argument is specified, it will return only those tables
	whose name matches the given glob.

============================================================================
NAME
	list_fields - describe the fields of a table in the database.

SYNTAX
	mapping(string:mapping(string:mixed)) list_fields(string table, void|string glob);

DESCRIPTION
	Returns a mapping describing the fields of a table in the database.
	The returned value is a mapping, indexed on the column name,
	of mappings.
	The glob argument, if present, filters out the fields not matching the glob.
	These contain currently the fields:

		string "type" describes the field's mSQL data type ("char","integer",...)

		int "length" it describes the field's length. It is only interesting for
		char() fields, in fact.  Also
		notice that the strings returned by msql->query() have the correct length.
		This field only specifies the _maximum_ length a "char()" field can have.

		string "table" The table this field is in. Added only for
		interface compliancy.

		(multiset(string)) "flags" it's a multiset containing textual
		descriptions of the server's flags associated with the current field.
		Currently it can be empty, or contain "unique" or "not null".

WARNING
	The version of this function in the Msql.msql() program is _NOT_ 
	sql-interface compliant (this is the main reason why using that program
	directly is deprecated).

SEE ALSO
	msql->query

============================================================================
NAME
	error - tell what the last server error was.

SYNTAX
	string error();

DESCRIPTION
	This function returns the textual description of the last server-related
	error. Returns 0 if no error has occurred yet. It is not cleared upon
	reading (can be invoked multiple times, will return the same result
	until a new error occurs).

SEE ALSO
	msql->query

============================================================================
NAME
	server_info - describe what server are we talking to.

SYNTAX
	string server_info();

DESCRIPTION
	This function returns a string describing the server we are talking
	to. It has the form "servername/serverversion" (like the HTTP protocol
	description) and is most useful in conjunction with the generic SQL-server
	module.

SEE ALSO
	Sql.sql

============================================================================
NAME
	host_info - describe the connection we're using

SYNTAX
	string host_info();

DESCRIPTION
	This function returns a string describing what host are we talking to,
	and how (TCP/IP or UNIX sockets).

============================================================================
NAME
	create_db - create a new database

SYNTAX
	void create_db(string dbname);

DESCRIPTION
	This function creates a new database with the given name (assuming we
	have enough permissions to do this).

SEE ALSO
	msql->drop_db

============================================================================
NAME
	drop_db - destroy a database

SYNTAX
	void drop_db(string dbname);

DESCRIPTION
	This function destroys a database and all the data it contains (assuming
	we have enough permissions to do so). USE WITH CAUTION!

SEE ALSO
	msql->create_db

============================================================================
NAME
	shutdown - shut down a server

SYNTAX
	void shutdown();

DESCRIPTION
	This function shuts a SQL-server down.

============================================================================
NAME
	reload_acl - reloads a server's ACL

SYNTAX
	void reload_acl();

DESCRIPTION
	This function forces a server to reload its ACLs.

NOTA BENE
	This function is _NOT_ part of the standard interface, so it is NOT
	availible through the Sql.sql interface, but only through Sql.msql and
	Msql.msql programs

SEE ALSO
	msql->create

============================================================================
NAME
	affected_rows - show how many rows were 'touched' by last operation

SYNTAX
	int affected_rows();

DESCRIPTION
	This function returns how many rows in the database were affected by
	our last SQL query.

NOTA BENE
	This function is availible only if you're using mSQL version 2
	or later. (That means: if the includes and library of version 2 of mSQL
	were availible when the module was compiled).

	This function is _NOT_ part of the standard interface, so it is NOT
	availible through the Sql.sql interface, but only through Sql.msql and
	Msql.msql programs

SEE ALSO
	msql->create

============================================================================
NAME
	list_index - show the index structure for a table

SYNTAX
	array(string) list_index(string tablename, string indexname);

DESCRIPTION
	This function returns an array describing the index structure for the
	given table and index name, as defined by the non-standard SQL query
	'create index' (see the mSQL documentation for further informations).
	More than one index can be created for a table. There's currently NO way
	to have a listing of the indexes defined for a table (blame it on
	the mSQL API).

NOTA BENE
	This function is availible if you're using mSQL version 2
	or later.

	This function is _NOT_ part of the standard interface, so it is NOT
	availible through the Sql.sql interface, but only through Sql.msql and
	Msql.msql programs

SEE ALSO
	msql->create

============================================================================
NAME
	version - show the version of the mSQL driver.

SYNTAX
	string Msql.version;

DESCRIPTION
	Should you need to report a bug to the author, please submit along with
	the report the driver version number, as returned by this call.

============================================================================
EXTERNAL INFLUENCES on the module.
	These ones do not depend on my implementation really, they're just part
	of the mSQL C API. They take the form of certain environment variables
	which, if defined in the environment of the pike interpreter, influence
	the interface's behavior. Those are "MSQL_TCP_PORT" which forces the
	server to connect to a port other than the default, "MSQL_UNIX_PORT", same
	as above, only referring to the UNIX domain sockets. If you built your
	mSQL server with the default setttings, you shouldn't worry about these.
	The variable MINERVA_DEBUG can be used to debug the mSQL API (you
	shouldn't worry about this either). Refer to the mSQL documentation
	for further details.

NOTES, TODOs AND OTHER THINGS
	Note that although the database engine should theoretically
	store any kind of values, the interface seems to be quite text-oriented:
	strings are returned as null-terminated char*, and not as a
	(datum,lenght) couple. For now I followed this trend. I will change this
	behavior as soon as I can think of a safe way.

	I didn't make any testsuite for this module, since to test anything it would
	require a working mSQL server, and I can't make any assumption
	on those... You can try to use the included "test_msql.pike" script,
	but you'll probably have to patch it to reflect your site's settings.

	Also note that THIS MODULE USES BLOCKING I/O to connect to the server.
	mSQL should be reasonably fast, but you might want to consider this
	particular aspect. It is thread-safe, and so it can be used
	in a multithread environment.

THANKS
	Many thanks to Henrik Grubbström, without whose help this piece of
	code couldn't be nearly as complete as it is.
	Also thanks to Frederik Hubinette, for designing such a nice language
	as Pike.

COPYRIGHT
	This code and documentation are copyright 1997 Francesco Chemolli 
	<kinkie@comedia.it>.
	It may be copied, modified, redistributed under the terms of the
	GNU General Public License, version 2.
	
	This program is distributed in the hope that it will be useful,
	but WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
	GNU General Public License for more details.

	You should have received a copy of the GNU General Public License
	along with the Pike source. If not, write to the Free Software
	Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

	The mSQL (Mini-SQL) server and its accompanying tools and documentation are 
	copyright 1993-1997 Hughes Technologies Pty Ltd, and are free to use
	for non-commercial entities. For informations about Mini SQL please
	consult the Hughes Thechnologies WWW site, at http://hughes.com.au/

	The Pike programming language is copyright Frederik Hubinette, and is
	distributed under the terms of the GNU General Public License. For furhter
	information, please consult the Pike WWW site, at http://pike.idonex.se/
