Information Technology

Alternative Database Interface

aMapApp3 currently comes with code for working with either a mySQL database server (mySQL_datalib.php) or sqlite3 (sqlite_datalib.php). Note that sqlite_datallib.php creates a file, MapApp.sqlite, in the top directory of the application.

It is, however, possible to write interfaces to other database systems and plug them into your system.  To do this you need to create a set of database interface routines and add them to application and they tell MapApp where the interface is during setup time. This is actually not that hard since aMapApp3 does not do anything very complicated with the database, but your database software must either be able to deal with SQL or your functions will have to translate from  SQL to whatever your database understands.  You can look at the xajaxFunctions files for aMapApp3, aLogin2 and aBlog2 to see what types of SQL statements you have to deal with.

The first thing to do is to create a php file with the appropriate routines.  These routines will have available a set of defined constants created at setup time and loaded into the configuration file.  These are,

DB_SERVER – the address of your database server, if you are using one

DB_USER – the name of a user with an account of the database server

DB_PASSWORD – the password associated with the MYSQL_USER

DB_DATABASE – the database on the server to use.  The MYSQL_USER must have permission to create and populate tables in this database.

PREFIX – the prefix used to modify the standard names of tables so they are unique for a particular instance of MapApp

Within the file you need to define the following functions,

dl_dbInit() – This function, which takes no parameters, does whatever is necessary to establish a connection to, or open access to, a database.  This will usually require the use of the defined values.  It returns false on failure.

dl_get_single_record($query) – This function takes a single parameter in the form of a string containing a SQL select statement.  It queries the database and returns the first record returned in the form of an associative array with the names of the fields functioning as the array keys.  It is used when either only a single record should match the query or when looking for a value that would be constant for all matching records.

dl_get_mysql_array($query) – This function takes a single parameter in the form of a string containing a SQL select statement.  It queries the database and returns the all the returned records in the form of an array of associative arrays with the names of the fields in the database functioning as the keys to the second associative array.

dl_insert_record($query) – This function takes a single parameter in the form of a string containing a SQL insert statement.  It inserts the data into the database and returns the id of the inserted record.  The returned id is unique for each record.

dl_update_record($query) – This function takes a single parameter in the form of a string containing a SQL update statement.  It updates the database with the provided data.  It returns whatever it gets back from the database.

dl_run_command($query) = This function runs any query.  It returns whatever the query returns.  In most cases it is identical to dl_update_record.

Note that since handling error conditions in database work can be complicated, MapApp takes the simple approach of assuming that any errors are either eliminated before the call is made, or the called functions deal with them. Most of the functions should return false on failure.

In general, assuming your database speaks SQL, you can take either mysql_datalib.php or sqlite_datalib.php and use them as the basis of your code.