[gnome-db] GNOME-DB & Mono

[Rodrigo Moya <rodrigo ximian com>]

Hi

I've just made a development release of libgda/libgnomedb (the 2
GNOME-DB libraries) for GNOME 2, to help people wanting to use it for
ADO.NET in Mono. The announcement:

http://mail.gnome.org/archives/gnome-db-list/2001-December/msg00087.html

Miguel also asked me to send a little introduction about GNOME-DB usage,
so that you feel comfortable, so here it is.

First, the best thing to do for sample code is to look at the source
code in both libgda/libgnomedb/gnome-db CVS modules. Interesting are the
testing/ directories in both libgda/libgnomedb, which, although
incomplete, may help you. libgda/testing/gda-test includes tests for
(almost) all features in the API, so might be a good starting point.

Well, to open a connection, first you need a GdaClient, which implements
a connection pool (to be optional later on):

GdaClient *client = gda_client_new ();

to actually open the connection:

GdaConnection *cnc = gda_client_open_connection (
	client, "dsn_name", "username", "password");

"dsn_name" is the name of a data source, as defined in the GDA
configuration. This GDA configuration stores, per "dsn_name", all the
information it needs to access a given database. It contains:

Provider="OAFIID:GNOME_Database_Provider_MySQL"
DSN="DATABASE=mydb;HOST=server;..."
...

the DSN string is database-dependant, and is parsed by the component
implementing the access to that given database
(OAFIID:GNOME_Database_Provider_MySQL), called provider in the GDA
terminology.

To execute a command:

GList *recset_list;
GdaCommand *cmd;

cmd = gda_command_new ("SELECT * FROM mytable", GDA_COMMAND_TYPE_SQL);
recset_list = gda_connection_execute_command (cnc, cmd, NULL);

The GDA_COMMAND_TYPE_SQL is because we support different kind of command
types: GDA_COMMAND_TYPE_SQL for SQL, _XML for XML, _TABLE for a table
name, which results in a "SELECT * FROM table_name", etc.
Also, the execute_command returns a GList of GdaRecordset's (see next).
We return a list of GdaRecordset's instead of just a GdaRecordset
because there are databases, such as Sybase, that may return several
recordsets for some commands. Also, we've taken advantage of this so
that you can just send in the command string, a set of SQL commands
separated by ';':

cmd = gda_command_new (
	"UPDATE a SET b = c; DELETE FROM a WHERE d = e; ...",
	GDA_COMMAND_TYPE_SQL);

To get data from a GdaRecordset, which is a GdaDataModel, you just do:

gint row, col;
for (row = 0; row < gda_data_model_get_n_rows (recset); row++) {
  for (col = 0; col < gda_data_model_get_n_columns (recset); col++) {
    GdaValue *value = gda_data_model_get_value_at (recset, col, row);
    printf ("Value = %s\n" gda_value_stringify (value));
  }
}

of course, recset is just a GdaRecordset contained in the GList returned
by gda_connection_execute_command. Please note that I plan to add a
gda_connection_execute_single_command function to just get a single
recordset.

For transactions:

gboolean gda_connection_begin_transaction (GdaConnection *cnc, const
gchar *id);
gboolean gda_connection_commit_transaction (GdaConnection *cnc, const
gchar *id);
gboolean gda_connection_rollback_transaction (GdaConnection *cnc, const
gchar *id);

To get information about database objects, such as tables, views, etc:

GdaServerRecordset *gda_connection_get_schema (cnc,
GDA_CONNECTION_SCHEMA_TABLES);

Then, there are high-level services in the API, such as the XML queries,
the XML database format for exporting/importing/designing databases, the
report engine, etc, but those are still in heavy refactoring, and not
yet integrated with the rest of the API, so I'll explain them another
day :-)

About libgnomedb, there's not much to say if you know GTK and libgda,
since it just contains a set of data-bound GTK widgets that use libgda.
And, anyway, I suppose the UI part in ADO.Net will come much later, so
I'll explain this one also another day :-)

So, that's all as a quick introduction. I just want to finish by noting
that as we're in a big refactoring process, it is now the time to
add/modify/remove stuff, so please, don't hesitate in telling me any
worries you may have.

cheers
-- 
Rodrigo Moya <rodrigo gnome-db org> - <rodrigo ximian com>
http://www.gnome-db.org/ - http://www.ximian.com/