Function prototypes

All functions within the driver have to be written according to a prototype. Below you'll find a list of prototypes to which the driver functions have to conform.

Function selectDB

This functions provide the DAL with a function to select a database. The DAL will check if there is a connection to the database so that doesn't have to be done within this function. However, with postgres by example you have the case that the database will be selected at connect time. So this requires a special solution within the driver. The order as DAL will call the function is always connectDB -> selectDB. So with putting in special functions you can use that knowlegde.

Boolean selectDB(string database);

The return value is the result of selecting the database. So this is either true when selecting went ok or false when selecting went not ok.

Function executeQuery

This function executes the query. In other words this function feeds it to the database. The function doesn't need to perform error checking like is there a connection to the database. DAL is taking care of that. So if there is no commection to the database the query won't be feeded to this function.

int executeQuery(String query);

The returning value is the response from executing the query. So normally this would be a result index. DAL expects it to be 0 (zero) if there was a failure executing the query.

Function connectDB

This function connects to the database. Any needed variables can be taken from the global scope. This includes username+password and connectstring.

Int connectDB(void);

The return value is either the connection identifier or 0 (zero). DAL expects it to be zero when something went wrong with connecting to the database.

Function closeDB

This functions closes the database connection

boolean closeDB(void);

The function doesn't take any parameters. All houskeeping necessary to make the connection close, such as remembering which link to close has to be done within the driver itself.

Function capabilities

This function returns an array with the capabilities of the driver.

array capabilities(void);

Function getDBerror

This function returns the error, if any, that occured while processing the last instruction.

string getDBerror(void);

Function fetchObject

This function returns an object of the last result. It's returning one object per row. So if there are 10 rows this function can get called 10 times.

object fetchObject(void);

If there is no object to return DAL expects to receive NULL.

Function affectedRows

This function is called by the DAL to find out how many rows where affected by an insert, update or delete statement.

int affectedRows(void);

Funtion resultRowcount

This functions is called by the DAL to find out how many rows there are in the resultset. So basicly it's finding out how many rows where returned by a select.

int resultRowcount(void);

Function fetchArray

This function returns a row as an associative array (array is indexed by fieldnames from the database)

array fetchArray(void);

If there is no array to return DAL expects to receive NULL.

Function fetchRow

This function returns a row as an indexed array.

array fetchRow(void);

If there is no array to return DAL expects to receive NULL.

Function fetchLastInsert

This function returns the last inserted record. This record is the last one that got inserted via the object from which this function is called. This implies that checking for the last insert should be done at an insert query.

object fetchLastInsert(void);

Function startTransaction

This functions starts a transaction. The checking for any running transactions is done by DAL. So the only thing to do is to actually start the transaction. Returns true on success and false on failure.

boolean startTransaction (void);

Function commitTransaction

Commits a running transaction. The check if there is a running transaction will be done by DAL. So the only concern is to commit the transaction to the database. Returns true on success and false on failure.

boolean commitTransaction (void);

Function abortTransaction

Aborts a running transaction. The check if there is a running transaction is done by DAL. Returns true on success and false on failure.

boolean abortTransaction (void);

Function nextRecord

This functions seeks to the next record if possible. Returns true on success and false on failure.

boolean nextRecord (void);

Function prevRecord

This functions seeks to the previous record if possible. Returns true on success and false on failure.

boolean prevRecord (void);

Function seekRecord

This function takes an integer as argument and seeks to that row number. Returns true on success and false on failure.

boolean prevRecord ( int rowID );

Function saveState

This function saves the current state of the driver. So the database connection, the current resultset and so on. This function needs to be completed successfully and therefore doesn't return anything. Al the important things within the driver need to get saved with this function.

saveState (void);

Function restoreState

This function restores the saved state. It also destroys any resultsets created after the saved state. So basicly it makes sure that everything that has happened after the saveState doesn't leave any traces.

restoreState (void);