---

GtkSQL

0.4.2

This is the source documentation for the GtkSQL program. GtkSQL is a query interface to a number of different databases. This version includes experimental support for querying XML files using XPath, as well as the existing support for MySQL and PostgreSQL databases.

The XPath driver code has been merged back into the main trunk, but is not complete. It will not be included in a build unless '--enable-xpath' is specified to ./configure.

Suggestions

If you have any suggestions for the development of GtkSQL, please let me know. There are a lot of SQL query interfaces out there. I'd like to make GtkSQL a bit different. My immediate plans are:

• Implement XPath queries of XML files (partially done - see d_xpath_f.c)
• Implement a forms interface so that GtkSQL can be called to display a form to the user, take some input, and run a query. So it can be used as a generic database application for small utilities. (forms interface is done. can't be scripted yet).
• Implement scripting (partially done - see luaif.c).

Other things that I initially thought would be good, but then wasn't so sure, are:

• Ability to generate code fragments to access the connected databases. So you could connect to a database, then generate the C, C++, Perl etc code needed to access that database.
• A tree-type interface. Look at the gtksql2 module in CVS. This module doesn't do anything, it's just a mock-up of a new interface.

General Guidelines

I've tried to partition the source and reduce the number of calls between the modules. Where a structure is defined, I usually provide access functions for the structure members and use those instead of accessing the members directly. This makes it easier to see where things are referenced from.

I've made a fair few changes lately to seperate the database drivers from the interface code. Originally the database drivers stored data directly into the GTK widgets. I want to make it so that the GtkSQL core is totally divorced from the user interface. I probably wont ever write a Curses frontend, but I want the rest of the code organised so I can if I want to!

I also try to keep functions small enough to fit into a single screen where it makes sense to do so. And I hate having duplicate code in different sections. So I tend to break things up fairly small. There are many places where this isn't done, and there are still some pretty big functions. That probably just means that I haven't had to deal with that part of the code yet!

Coding Standards

I like consistancy in code formatting. And you need it to make things easy to find - especially in code maintained by multiple people! So I've modified (I think) all the code to conform to these naming standards:

• Function names use the GTK type syntax with all lower case, and seperate words in the name seperated with underscores. For example a function to set the configuration filename would be called config_set_filename().
• Variables are named using 'camel-case' with an initial lower-case letter. For example a variable holding the configuration filename would be called configFilename.
• Typedefs are named the same as variables, except that the first character is upper-case. So a typedef for a file format would be called FileFormat.

I also run the code through 'indent' whenever I make changes, using the format string:

 -br -brs -c40 -cdw -fca -i4 -nbc -nce -npcs -npsl -sc -ss -ts4

If you're making any changes, please try and follow the naming standard so things are easy to find. If you submit them in another format, they'll eventually magically morph into the above format anyway!

If you really don't like these formats, please suggest a better one. I don't really care what the standard format is, as long as all of the code is consistant with it.

Documentation

The source is documented for Doxygen. All functions are documented where they occur in the .c file.

Modules

The program is divided into three main modules:

• The DB module, which handles the database drivers. This module provides an API (defined by dbapi.h) to other modules.
• The GUI module, which handles the user interface. This module provides an API (defined by guiapi.h) to other modules.
• The scripting module, which uses the LUA scripting engine to run scripts which can control both the DB and GUI modules.

All calls between modules are hopefully calls declared in these interface files.

Todo:

Add something like this to see if it makes updates available during long result fetches. But do it in the db drivers without introducing a Gtk dependency. // computation going on ... while (gtk_events_pending ()) gtk_main_iteration (); ... // computation continued

---