PEAR 2000/12/03 -

DB

The main "DB" class is simply a container class with some static

private class DB

The main "DB" class is simply a container class with some static
methods for creating DB objects as well as some utility functionscommon to all parts of DB.The object model of DB is as follows (indentation means inheritance):DB The main DB class. This is simply a utility classwith some "static" methods for creating DB objects aswell as common utility functions for other DB classes.DB_common The base for each DB implementation. Provides default| implementations (in OO lingo virtual methods) for| the actual DB implementations as well as a bunch of| query utility functions.|+-DB_mysql The DB implementation for MySQL. Inherits DB_common.When calling DB::factory or DB::connect for MySQLconnections, the object returned is an instance of thisclass.

Authors Stig Bakken <ssb@fast.no>

Since PHP 4.0

Version 2

Public Method Summary
void	DB_Error([ mixed $code, string $mode ], string $level, string $debuginfo) DB_Error constructor.
void	DB_Warning([ mixed $code, string $mode ], string $level, string $debuginfo) DB_Warning constructor.

Private Method Summary
object a	&factory(string $type) Create a new DB object for the specified database type
object a	&connect(string $dsn, [ boolean $persistent ]) Create a new DB object and connect to the specified database
int	apiVersion() Return the DB API version
bool	isError(int $value) Tell whether a result code from a DB method is an error
bool	isWarning(mixed $value) Tell whether a result code from a DB method is a warning.
string	errorMessage(int $value) Return a textual error message for a DB error code
array	parseDSN(string $dsn) Parse a data source name
void	DB_result(object reference &$dbh, $result) DB_result constructor.
array	fetchRow(string $fetchmode) Fetch and return a row of data.
int	fetchInto(array &$arr, string $fetchmode) Fetch a row of data into an existing array.
int	numCols() Get the the number of columns in a result set.
int	free() Frees the resources allocated for this result set.

Private Field Summary
unknown	$dbh
unknown	$result

Private Constant Summary
DB_FETCHMODE_DEFAULT	>>`0`<<	This is a special constant that tells DB the user hasn't specified
DB_FETCHMODE_ORDERED	>>`1`<<	Column data indexed by numbers, ordered from 0 and up
DB_FETCHMODE_ASSOC	>>`2`<<	Column data indexed by column names
DB_FETCHMODE_FLIPPED	>>`4`<<	For multi-dimensional results: normally the first level of arrays
DB_OK	>>`0`<<	Warning: documentation is missing.
DB_ERROR	>>`-1`<<	Warning: documentation is missing.
DB_ERROR_SYNTAX	>>`-2`<<	Warning: documentation is missing.
DB_ERROR_CONSTRAINT	>>`-3`<<	Warning: documentation is missing.
DB_ERROR_NOT_FOUND	>>`-4`<<	Warning: documentation is missing.
DB_ERROR_ALREADY_EXISTS	>>`-5`<<	Warning: documentation is missing.
DB_ERROR_UNSUPPORTED	>>`-6`<<	Warning: documentation is missing.
DB_ERROR_MISMATCH	>>`-7`<<	Warning: documentation is missing.
DB_ERROR_INVALID	>>`-8`<<	Warning: documentation is missing.
DB_ERROR_NOT_CAPABLE	>>`-9`<<	Warning: documentation is missing.
DB_ERROR_TRUNCATED	>>`-10`<<	Warning: documentation is missing.
DB_ERROR_INVALID_NUMBER	>>`-11`<<	Warning: documentation is missing.
DB_ERROR_INVALID_DATE	>>`-12`<<	Warning: documentation is missing.
DB_ERROR_DIVZERO	>>`-13`<<	Warning: documentation is missing.
DB_ERROR_NODBSELECTED	>>`-14`<<	Warning: documentation is missing.
DB_ERROR_CANNOT_CREATE	>>`-15`<<	Warning: documentation is missing.
DB_ERROR_CANNOT_DELETE	>>`-16`<<	Warning: documentation is missing.
DB_ERROR_CANNOT_DROP	>>`-17`<<	Warning: documentation is missing.
DB_ERROR_NOSUCHTABLE	>>`-18`<<	Warning: documentation is missing.
DB_ERROR_NOSUCHFIELD	>>`-19`<<	Warning: documentation is missing.
DB_ERROR_NEED_MORE_DATA	>>`-20`<<	Warning: documentation is missing.
DB_ERROR_NOT_LOCKED	>>`-21`<<	Warning: documentation is missing.
DB_ERROR_VALUE_COUNT_ON_ROW	>>`-22`<<	Warning: documentation is missing.
DB_WARNING	>>`-1000`<<	Warning: documentation is missing.
DB_WARNING_READ_ONLY	>>`-1001`<<	Warning: documentation is missing.
DB_PARAM_SCALAR	>>`1`<<	Warning: documentation is missing.
DB_PARAM_OPAQUE	>>`2`<<	Warning: documentation is missing.
DB_BINMODE_PASSTHRU	>>`1`<<	Warning: documentation is missing.
DB_BINMODE_RETURN	>>`2`<<	Warning: documentation is missing.
DB_BINMODE_CONVERT	>>`3`<<	Warning: documentation is missing.
DB_GETMODE_ORDERED	>>`DB_FETCHMODE_ORDERED`<<	Warning: documentation is missing.
DB_GETMODE_ASSOC	>>`DB_FETCHMODE_ASSOC`<<	Warning: documentation is missing.
DB_GETMODE_FLIPPED	>>`DB_FETCHMODE_FLIPPED`<<	Warning: documentation is missing.

Included files Summary, Type: include_once
DB/$.php	Warning: documentation is missing.

Public Method Details

DB_Error

public void DB_Error( [ mixed $code, string $mode ], string $level, string $debuginfo )

DB_Error constructor.

Parameter

mixed	$code	`= >>DB_ERROR,<<`
	error code, or string with error message.

string	$mode	`= >>PEAR_ERROR_RETURN,<<`
	"error mode" to operate in

string	$level
	Warning: documentation is missing.

string	$debuginfo
	Warning: documentation is missing.

Returns

void

DB_Warning

public void DB_Warning( [ mixed $code, string $mode ], string $level, string $debuginfo )

DB_Warning constructor.

Parameter

mixed	$code	`= >>DB_WARNING,<<`
	error code, or string with error message.

string	$mode	`= >>PEAR_ERROR_RETURN,<<`
	"error mode" to operate in

string	$level
	Warning: documentation is missing.

string	$debuginfo
	Warning: documentation is missing.

Returns

void

Private Method Details

&factory

private object a &factory( string $type )

Create a new DB object for the specified database type

Parameter

string	$type
	type, for example "mysql"

Returns

object a

newly created DB object, or a DB error code on
error

&connect

private object a &connect( string $dsn, [ boolean $persistent ] )

Create a new DB object and connect to the specified database

Parameter

string	$dsn
	"data source name", see the DB::parseDSN method for a description of the dsn format.

boolean	$persistent	`= >>false<<`
	this connection should be persistent. Ignored if the backend extension does not support persistent connections.

Returns

object a

newly created DB object, or a DB error code on
error

apiVersion

private int apiVersion( )

Return the DB API version

Returns

int

the DB API version number

isError

private bool isError( int $value )

Tell whether a result code from a DB method is an error

Parameter

int	$value
	code

Returns

bool $value

whether is an error

isWarning

private bool isWarning( mixed $value )

Tell whether a result code from a DB method is a warning.
Warnings differ from errors in that they are generated by DB,and are not fatal.

Parameter

mixed	$value
	value

Returns

bool $value

whether is a warning

errorMessage

private string errorMessage( int $value )

Return a textual error message for a DB error code

Parameter

int	$value
	code

Returns

string

error message, or false if the error code was
not recognized

parseDSN

private array parseDSN( string $dsn )

Parse a data source name

Parameter

string	$dsn
	Source Name to be parsed

Returns

array

an associative array with the following keys:
<dl>
<dt>phptype</dt>
<dd>Database backend used in PHP (mysql, odbc etc.)</dd>
<dt>dbsyntax</dt>
<dd>Database used with regards to SQL syntax etc.</dd>
<dt>protocol</dt>
<dd>Communication protocol to use (tcp, unix etc.)</dd>
<dt>hostspec</dt>
<dd>Host specification (hostname[:port])</dd>
<dt>database</dt>
<dd>Database to use on the DBMS server</dd>
<dt>username</dt>
<dd>User name for login</dd>
<dt>password</dt>
<dd>Password for login</dd>
</dl>
</p>

<p>
The format of the supplied DSN is in its fullest form:
<ul>
<li>phptype(dbsyntax)://username:password@protocol+hostspec/database</li>
</ul>
Most variations are allowed:
<ul>
<li>phptype://username:password@protocol+hostspec/database</li>
<li>phptype://username:password@hostspec/database</li>
<li>phptype://username:password@hostspec</li>
<li>phptype://hostspec/database</li>
<li>phptype://hostspec</li>
<li>phptype(dbsyntax)</li>
<li>phptype</li>
</ul>
</p>

DB_result

private void DB_result( object reference &$dbh, $result )

DB_result constructor.

Parameter

object reference	&$dbh

	$result
	Warning: documentation is missing.

Returns

void

fetchRow

private array fetchRow( string $fetchmode )

Fetch and return a row of data.

Parameter

string	$fetchmode
	Warning: documentation is missing.

Returns

array

a row of data, or false on error

fetchInto

private int fetchInto( array &$arr, string $fetchmode )

Fetch a row of data into an existing array.

Parameter

array	&$arr

string	$fetchmode
	Warning: documentation is missing.

Returns

int

error code

numCols

private int numCols( )

Get the the number of columns in a result set.

Returns

int

the number of columns, or a DB error code

free

private int free( )

Frees the resources allocated for this result set.

Returns

int

error code

Private Field Details
$dbh
private unknown $dbh >><<

$result
private unknown $result >><<

Private Constant Details
DB_FETCHMODE_DEFAULT `define( DB_FETCHMODE_DEFAULT, >>0<< )` Case: default: case sensitive This is a special constant that tells DB the user hasn't specified any particular get mode, so the default should be used.

DB_FETCHMODE_ORDERED `define( DB_FETCHMODE_ORDERED, >>1<< )` Case: default: case sensitive Column data indexed by numbers, ordered from 0 and up

DB_FETCHMODE_ASSOC `define( DB_FETCHMODE_ASSOC, >>2<< )` Case: default: case sensitive Column data indexed by column names

DB_FETCHMODE_FLIPPED `define( DB_FETCHMODE_FLIPPED, >>4<< )` Case: default: case sensitive For multi-dimensional results: normally the first level of arrays is the row number, and the second level indexed by column number or name.DB_FETCHMODE_FLIPPED switches this order, so the first level of arraysis the column name, and the second level the row number.

DB_OK `define( DB_OK, >>0<< )` Case: default: case sensitive

DB_ERROR `define( DB_ERROR, >>-1<< )` Case: default: case sensitive

DB_ERROR_SYNTAX `define( DB_ERROR_SYNTAX, >>-2<< )` Case: default: case sensitive

DB_ERROR_CONSTRAINT `define( DB_ERROR_CONSTRAINT, >>-3<< )` Case: default: case sensitive

DB_ERROR_NOT_FOUND `define( DB_ERROR_NOT_FOUND, >>-4<< )` Case: default: case sensitive

DB_ERROR_ALREADY_EXISTS `define( DB_ERROR_ALREADY_EXISTS, >>-5<< )` Case: default: case sensitive

DB_ERROR_UNSUPPORTED `define( DB_ERROR_UNSUPPORTED, >>-6<< )` Case: default: case sensitive

DB_ERROR_MISMATCH `define( DB_ERROR_MISMATCH, >>-7<< )` Case: default: case sensitive

DB_ERROR_INVALID `define( DB_ERROR_INVALID, >>-8<< )` Case: default: case sensitive

DB_ERROR_NOT_CAPABLE `define( DB_ERROR_NOT_CAPABLE, >>-9<< )` Case: default: case sensitive

DB_ERROR_TRUNCATED `define( DB_ERROR_TRUNCATED, >>-10<< )` Case: default: case sensitive

DB_ERROR_INVALID_NUMBER `define( DB_ERROR_INVALID_NUMBER, >>-11<< )` Case: default: case sensitive

DB_ERROR_INVALID_DATE `define( DB_ERROR_INVALID_DATE, >>-12<< )` Case: default: case sensitive

DB_ERROR_DIVZERO `define( DB_ERROR_DIVZERO, >>-13<< )` Case: default: case sensitive

DB_ERROR_NODBSELECTED `define( DB_ERROR_NODBSELECTED, >>-14<< )` Case: default: case sensitive

DB_ERROR_CANNOT_CREATE `define( DB_ERROR_CANNOT_CREATE, >>-15<< )` Case: default: case sensitive

DB_ERROR_CANNOT_DELETE `define( DB_ERROR_CANNOT_DELETE, >>-16<< )` Case: default: case sensitive

DB_ERROR_CANNOT_DROP `define( DB_ERROR_CANNOT_DROP, >>-17<< )` Case: default: case sensitive

DB_ERROR_NOSUCHTABLE `define( DB_ERROR_NOSUCHTABLE, >>-18<< )` Case: default: case sensitive

DB_ERROR_NOSUCHFIELD `define( DB_ERROR_NOSUCHFIELD, >>-19<< )` Case: default: case sensitive

DB_ERROR_NEED_MORE_DATA `define( DB_ERROR_NEED_MORE_DATA, >>-20<< )` Case: default: case sensitive

DB_ERROR_NOT_LOCKED `define( DB_ERROR_NOT_LOCKED, >>-21<< )` Case: default: case sensitive

DB_ERROR_VALUE_COUNT_ON_ROW `define( DB_ERROR_VALUE_COUNT_ON_ROW, >>-22<< )` Case: default: case sensitive

DB_WARNING `define( DB_WARNING, >>-1000<< )` Case: default: case sensitive

DB_WARNING_READ_ONLY `define( DB_WARNING_READ_ONLY, >>-1001<< )` Case: default: case sensitive

DB_PARAM_SCALAR `define( DB_PARAM_SCALAR, >>1<< )` Case: default: case sensitive

DB_PARAM_OPAQUE `define( DB_PARAM_OPAQUE, >>2<< )` Case: default: case sensitive

DB_BINMODE_PASSTHRU `define( DB_BINMODE_PASSTHRU, >>1<< )` Case: default: case sensitive

DB_BINMODE_RETURN `define( DB_BINMODE_RETURN, >>2<< )` Case: default: case sensitive

DB_BINMODE_CONVERT `define( DB_BINMODE_CONVERT, >>3<< )` Case: default: case sensitive

DB_GETMODE_ORDERED `define( DB_GETMODE_ORDERED, >>DB_FETCHMODE_ORDERED<< )` Case: default: case sensitive

DB_GETMODE_ASSOC `define( DB_GETMODE_ASSOC, >>DB_FETCHMODE_ASSOC<< )` Case: default: case sensitive

DB_GETMODE_FLIPPED `define( DB_GETMODE_FLIPPED, >>DB_FETCHMODE_FLIPPED<< )` Case: default: case sensitive

Included Files, Type: include_once
DB/$.php
include_once( DB/$.php )

PHPDoc 1.0beta

PEAR 2000/12/03 -

DB

private class DB

Public Method Summary

DB_Error([ mixed $code, string $mode ], string $level, string $debuginfo)

DB_Warning([ mixed $code, string $mode ], string $level, string $debuginfo)

Private Method Summary

&factory(string $type)

&connect(string $dsn, [ boolean $persistent ])

apiVersion()

isError(int $value)

isWarning(mixed $value)

errorMessage(int $value)

parseDSN(string $dsn)

DB_result(object reference &$dbh, $result)

fetchRow(string $fetchmode)

fetchInto(array &$arr, string $fetchmode)

numCols()

free()

Private Field Summary

$dbh

$result

Private Constant Summary

Included files Summary, Type: include_once

Public Method Details

DB_Error

DB_Warning

Private Method Details

&factory

&connect

apiVersion

isError

isWarning

errorMessage

parseDSN

DB_result

fetchRow

fetchInto

numCols

free

Private Field Details

$dbh

$result

Private Constant Details

DB_FETCHMODE_DEFAULT

DB_FETCHMODE_ORDERED

DB_FETCHMODE_ASSOC

DB_FETCHMODE_FLIPPED

DB_OK

DB_ERROR

DB_ERROR_SYNTAX

DB_ERROR_CONSTRAINT

DB_ERROR_NOT_FOUND

DB_ERROR_ALREADY_EXISTS

DB_ERROR_UNSUPPORTED

DB_ERROR_MISMATCH

DB_ERROR_INVALID

DB_ERROR_NOT_CAPABLE

DB_ERROR_TRUNCATED

DB_ERROR_INVALID_NUMBER

DB_ERROR_INVALID_DATE

DB_ERROR_DIVZERO

DB_ERROR_NODBSELECTED

DB_ERROR_CANNOT_CREATE

DB_ERROR_CANNOT_DELETE

DB_ERROR_CANNOT_DROP

DB_ERROR_NOSUCHTABLE

DB_ERROR_NOSUCHFIELD

DB_ERROR_NEED_MORE_DATA

DB_ERROR_NOT_LOCKED

DB_ERROR_VALUE_COUNT_ON_ROW

DB_WARNING

DB_WARNING_READ_ONLY

DB_PARAM_SCALAR

DB_PARAM_OPAQUE

DB_BINMODE_PASSTHRU

DB_BINMODE_RETURN

DB_BINMODE_CONVERT

DB_GETMODE_ORDERED

DB_GETMODE_ASSOC