Every supported database module must be loaded by PHP before it can be used. Every supported database module must be added to the dbx-module before it can be used. Currently there is support for MySQL, PostgreSQL, Microsoft SQL Server, Frontbase, Sybase-CT, Oracle (oci8) and ODBC. It is not difficult to add support for more databases.<br>
The dbx module is found in de PHP ext/dbx folder. The support-code is found in the same folder <br>
<br>
To add support for module 'blabla' the following steps must be taken: <br>
1. the dbx.c source file must be extended to recognize module 'blabla' and switch to the 'blabla' functions.<br>
2. the files dbx_blabla.h and dbx_blabla.c must be created and edited to produce the required response.<br>
3. add the files from step 2 to the project.<br>
4. compile.<br>
5. enjoy.<br>
<br>
You may need a bit of help for step 1 and 2. If you need help for step 3 or 4, you shouldn't try to attempt this probably :-). If you need help with step 5 you're in big trouble ;o)<br>
Help for step 1 and 2 is given below, bold text in code indicate the important bits.<br>
</div>
<p>
<ahref="index.html">home</a><br>
<divclass="newpage"></div>
<divclass="fn-title"><aname="step1"></a>
1. the dbx.c source file must be extended<br>
</div>
<divclass="text">
Define a module identifier and assign it a unique number. Include your header file here as well.<br>
<preclass="code">
// defines for supported databases
#define DBX_UNKNOWN 0
#define DBX_MYSQL 1
#define DBX_ODBC 2
<spanclass="bold">#define DBX_BLABLA 3</span>
// includes for supported databases
#include "dbx.h"
#include "dbx_mysql.h"
#include "dbx_odbc.h"
<spanclass="bold">#include "dbx_blabla.h"</span>
</pre>
Add code to the module_identifier_exists function so DBX_BLABLA will be recognized:<br>
<preclass="code">
int module_identifier_exists(long module_identifier) {
php_info_print_table_row(2, "dbx support for MySQL", "enabled");
php_info_print_table_row(2, "dbx support for ODBC", "enabled");
<spanclass="bold">php_info_print_table_row(2, "dbx support for BlaBla", "enabled");</span>
php_info_print_table_end();
DISPLAY_INI_ENTRIES();
}
</pre>
Finally, for the implementation of all switch_dbx_XXXXX functions, copy a 'case'-line for every function that you support (should be all functions!). Here is an example for only the switch_dbx_connect function:<br>
zend_error(E_WARNING, "dbx_connect: not supported in this module");
return 0;
}
</pre>
This should be done for all switch_dbx_XXXXX functions. They are listed below:<br>
<preclass="code">
int <ahref="#connect">switch_dbx_connect(...)</a>;
int <ahref="#pconnect">switch_dbx_pconnect(...)</a>;
int <ahref="#close">switch_dbx_close(...)</a>;
int <ahref="#query">switch_dbx_query(...)</a>;
int <ahref="#getcolumncount">switch_dbx_getcolumncount(...)</a>;
int <ahref="#getcolumnname">switch_dbx_getcolumnname(...)</a>;
int <ahref="#getcolumntype">switch_dbx_getcolumntype(...)</a>;
int <ahref="#getrow">switch_dbx_getrow(...)</a>;
int <ahref="#error">switch_dbx_error(...)</a>;
</pre>
This concludes the changes for the dbx.c file. All that is needed now is to actually code the dbx_blabla_connect and other functions, which we will see in the following step.<br>
</div>
<p>
<ahref="#top">top</a><br>
<divclass="newpage"></div>
<divclass="fn-title"><aname="step1"></a>
2. the files dbx_blabla.h and dbx_blabla.c<br>
</div>
<divclass="text">
The dbx_blabla.h and dbx_blabla.c file are created in the folder /ext/dbx.<br>
The easiest method is to just copy dbx_mysql.h en dbx_mysql.c, open both files, and do a search and replace ('blabla' for 'mysql' and 'BLABLA' for 'MYSQL'). Yes, case-sensitive.<br>
For the .h file, that's all. <br>
For the .c file, the fun has just started :-)<br>
In the .c is the actual realization of the database abstraction, where a call to a standard function is translated into one or more database-specific calls. For mysql, a dbx_connect translates to a mysql_connect followed by a mysql_select_db. Refer to the dbx_mysql.c and dbx_odbc.c files regularly for examples!<br>
In dbx.h one macro and one function are defined to make the calling of external module functions and returning of the results easier: dbx_call_any_function and MOVE_RETURNED_TO_RV.<br>
<p>
The details of what each of the functions do, what parameters they get, and what parameters they should return are discussed below. But first, the dbx_mysql_connect function is presented and explained, so you get an idea of how things work.<br>
First of all, all functions return 0 on failure and 1 on success. These values are used in the dbx-routines, they are never actually given back to the PHP-script writer that calls the dbx_connect function.<br>
The actual value that is of interest to the caller is returned in the <spanclass="bold">rv</span> parameter. In this case it is a connection handle (or link identifier, in mysql-speak), that is also returned if the database selection doesn't succeed. <br>
The parameters that are of interest to the function are located between the <spanclass="bold">rv</span> and <spanclass="bold">INTERNAL_FUNCTION_PARAMETERS</span> parameters, in this case it is a <spanclass="bold">host</span> name, a <spanclass="bold">db</span> name, a <spanclass="bold">username</span> and a <spanclass="bold">password</span>. These are the values that the user specifies if he calls dbx_connect(); These parameters are used in the calls to the mysql-database functions. The user actually also specifies a module-name, that decides which connect-function should be called. Here, he specified 'mysql'.<br>
To actually call a mysql module function, you can use <spanclass="bold">dbx_call_any_function</span> where you specify the function name (it is used twice in dbx_mysql_connect, see <spanclass="bold">'mysql_connect'</span> and <spanclass="bold">'mysql_select_db'</span>, they are printed bold in the code). The value that is returned from the function will be stored in the next argument, a zval * (e.g. <spanclass="bold">returned_zval</span>) parameter that you must declare locally. To actually return such a parameter, use the <spanclass="bold">MOVE_RETURNED_TO_RV(rv, returned_zval)</span> macro, which copies the values to <spanclass="bold">rv</span> and frees anything that may be left in <spanclass="bold">returned_zval</span>. Parameters that must be passed to the mysql-function are stored in the <spanclass="bold">arguments</span> array, which must be large enough to hold all parameters to the function-call that requires the most parameters (in this case, mysql_connect expects 3 parameters, mysql_select_db expects two parameters, so the <spanclass="bold">arguments</span> array is defined 'zval **arguments[<spanclass="bold">3</span>]'). The <spanclass="bold">number_of_arguments</span> parameter is set to the actual number of arguments that the function-call requires. As you can see it is initialized to 3, for the first call to mysql_connect. Then it is set to 2, for the call to mysql_select_db. If you call a function that retrieves a value, and you don't return it with MOVE_RETURNED_TO_RV, then you must free the value using <spanclass="bold">zval_ptr_dtor</span>, as can be seen right after the call to mysql_select_db. This can also be seen directly after the call to mysql_connect, if somehow this function failed or didn't return a resource (on a successful connect mysql_connect returns a resource) the returned value is freed as well (and 0 is returned because the connection failed).<br>
// int: returns 0 on connect-failure and 1 on success
// rv: connection handle as resource on success or nothing on failure
</pre>
dbx_blabla_connect creates a connection to a database on a specified host, using username and password for authentication. This may be done by connecting to a server and selecting a database (as mysql does), or connecting to a specific database directly (as in ODBC). <br>
What must be returned (in <spanclass="bold">rv</span>) is the link identifier that is returned from the blabla_connect function, in it's native form so the end-user can use $db->handle to call other blabla_* functions that expect this parameter.<br>
What must be returned from the function is a 1 on success and a 0 on failure. Remember that a failed database selection can still return a 1 because the connection succeeded!<br>
The host (string) is the name of the machine the server is run on, but it may be empty if a database name is enough to establish a connection.<br>
The db (string) is the name of the database to select, or, for e.g. ODBC, the identifier that is needed to actually select the database.<br>
The username (string) and password (string) are used for authentication.<br>
// int: returns 0 on close-failure and 1 on success
// rv: 1 as bool on success or nothing on failure
</pre>
dbx_blabla_close closes an open connection, whether it was created persistently or not.<br>
What must be returned (in <spanclass="bold">rv</span>) is a boolean true that indicates when the connection was closed successfully. If it wasn't, no value is returned in <spanclass="bold">rv</span>.<br>
What must be returned from the function is a 1 on success and a 0 on failure. Note that an unsuccessful close is still a succeeded function call.<br>
The dbx_handle is the same value that you returned from dbx_blabla_connect or dbx_blabla_pconnect.<br>
// int: returns 0 on query-failure and 1 on success
// rv: 1 as bool or a result identifier as resource on success
// or nothing on failure
</pre>
dbx_blabla_query executes an SQL statement over the connection.<br>
What must be returned (in <spanclass="bold">rv</span>) is a nothing on failure, on success it must return either a boolean 1 for queries that don't return data (like INSERT INTO) or a native result-handle for queries that do return data (SELECT). The native result handle ($q->handle) can be used by the end-user to call other blabla_* functions that expect this parameter.<br>
What must be returned from the function is a 1 on success and a 0 on failure. Note that a failed query execution can still return a 1 because the query function succeeded!<br>
The dbx_handle is the same value that you returned from dbx_blabla_connect or dbx_blabla_pconnect.<br>
The sql_statement (string) can have any value.<br>
int <spanclass="fn-name">dbx_blabla_getcolumnname</span>(zval **rv, zval **<spanclass="fn-param">result_handle</span>, long <spanclass="fn-param">column_index</span>, INTERNAL_FUNCTION_PARAMETERS);
int <spanclass="fn-name">dbx_blabla_getcolumntype</span>(zval **rv, zval **<spanclass="fn-param">result_handle</span>, long <spanclass="fn-param">column_index</span>, INTERNAL_FUNCTION_PARAMETERS);
int <spanclass="fn-name">dbx_blabla_getrow</span>(zval **rv, zval **<spanclass="fn-param">result_handle</span>, long <spanclass="fn-param">row_number</span>, INTERNAL_FUNCTION_PARAMETERS);
// returns array[0..columncount-1] as strings on success or 0 as long
// on failure
</pre>
dbx_blabla_getrow gets the next row from the query-results.<br>
In some cases (PostgreSQL) the rownumber is needed to actually fetch the row. This will be provided (it will be indexed starting at 0) by the dbx_query function. In other cases it is not needed and thus not used.<br>
What must be returned (in <spanclass="bold">rv</span>) is an indexed array[0..columncount-1] of strings, containing the data from the row (for mysql this is easy since it already performs this way, for ODBC the array has to be constructed inside this function from a loop that fetches the data for each column).<br>
What must be returned from the function is a 1 on success and a 0 on failure (function failed or there are no more rows available). <br>
The result_handle is the same value that you returned from dbx_query.<br>