Introduction - Portability
Prev		Next

Introduction - Portability

Introduction - Portability – Database portability features

Description

Each database management system (DBMS) has its own behaviors. For example, some databases capitalize field names in their output, some lowercase them, while others leave them alone. These quirks make it difficult to port your scripts over to another server type. PEAR DB strives to overcome these differences so your program can switch between DBMS's without any changes.

You control which portability modes are enabled by using the portability configuration option. Configuration options are set via connect() and setOption().

The portability modes are bitwised, so they can be combined using | and removed using ^. See the examples section below on how to do this.

Portability Mode Constants

DB_PORTABILITY_ALL

turn on all portability features
DB_PORTABILITY_DELETE_COUNT

force reporting the number of rows deleted. Some DBMS's don't count the number of rows deleted when performing simple DELETE FROM tablename queries. This mode tricks such DBMS's into telling the count by adding WHERE 1=1 to the end of DELETE queries.

DB_PORTABILITY_ERRORS

makes certain error messages in certain drivers compatible with those from other DBMS's

Error Code Re-mappings
Driver	Description	Old Constant	New Constant
mysql, mysqli	unique and primary key constraints	DB_ERROR_ALREADY_EXISTS	DB_ERROR_CONSTRAINT
mysql, mysqli	not-null constraints	DB_ERROR_CONSTRAINT	DB_ERROR_CONSTRAINT_NOT_NULL
odbc(access)	MS's ODBC driver mistakenly reports 'no such field' as code 07001, which means 'too few parameters.' When this option is on, that code gets remapped.	DB_ERROR_MISMATCH	DB_ERROR_NOSUCHFIELD

DB_PORTABILITY_LOWERCASE

convert names of tables and fields to lower case when using get*(), fetch*() and tableInfo()
DB_PORTABILITY_NONE (default)

turn off all portability features
DB_PORTABILITY_NULL_TO_EMPTY

convert null values to empty strings in data output by get*() and fetch*(). Needed because Oracle considers empty strings to be null, while most other DBMS's know the difference between empty and null.
DB_PORTABILITY_NUMROWS

enable hack that makes numRows() work in Oracle
DB_PORTABILITY_RTRIM

right trim the data output by get*() and fetch*()

Backwards Compatibility

Some of this functionality used to be handled by the now deprecated optimize option. For backwards compatibility, when this option is set to portability, the following databases get these portability modes turned on:

oci8: DB_PORTABILITY_LOWERCASE and DB_PORTABILITY_DELETE_COUNT
fbsql, mysql, mysqli, sqlite: DB_PORTABILITY_DELETE_COUNT

When the optimize option gets set to performance the portability mode is switched to DB_PORTABILITY_NONE.

Example

Turning on all portability options while connecting


<?php
require_once 'DB.php';

$dsn = 'mysql://user:password@host/database'
$options = array(
    'debug'       => 2,
    'portability' => DB_PORTABILITY_ALL,
);

$db =& DB::connect($dsn, $options);
if (PEAR::isError($db)) {
    die($db->getMessage());
}
?>

Using setOption() to enable portability for lowercasing and trimming


<?php
// Once you have a valid DB object named $db...
$db->setOption('portability',
        DB_PORTABILITY_LOWERCASE | DB_PORTABILITY_RTRIM);
?>

Using setOption() to enable all portability options except trimming


<?php
// Once you have a valid DB object named $db...
$db->setOption('portability',
        DB_PORTABILITY_ALL ^ DB_PORTABILITY_RTRIM);
?>

Prev	DB	Next
Introduction - autoPrepare & autoExecute	PEAR Manual	Introduction - Sequences