BlueShoes Application Framework - Db

Bs_Db

Bs_Object
|
+-- Bs_Db

**********************************************************************

public class Bs_Db extends Bs_Object

**********************************************************************
abstract class Bs_Db.class.phpThis object is the abstract layer for Db access. It holds the basicfuctions that are DB-independent.To makes use of this object, you must extend it to a DB-specific objectlike Bs_MySql.class.php.Some collected knowledge:-------------------------o) Watch out when you make queries based on variables from a surfer."SELECT * FROM table where ID=$ID" can easily be hacked to empty your table. Parse allvariables submitted through forms/get if they are to be used in any similar situation.Of course, the hacker would need to know the name of your table.o) In some dbms like MS-ACCESS and mssql (if you call them dbms :) can have field names withspaces. A query would look like this "SELECT [fieldname withspace], anotherField FROM tbl".Please *NEVER* ever use that 'feature'. Many dbms don't support it (like mySQL); it's uglyand screams for probs.dependencies: Bs_System, Bs_Date

Authors andrej arn <andrej@arn.li>

Version 4.0.$Revision: 1.1.1.1 $

Copyright blueshoes

Direct known subclasses: Bs_MsSql, Bs_MySql, Bs_Oci

Methods inherited from Bs_Object

isex, isexception, tohtml, persist, unpersist, bs_object, bbsetoutput, bbawake, bbisawake, bbxmsg, bbxfunctionstart, bbxfunctionend, bbxecho, bbxvar, bbxvardump, bbforcetrace, bbbufferstart, bbbufferget, bbbufferendflush, bbbufferendclean

Public Method Summary
object [unknown]	&getDbObject([ string $dsn ]) function to get a db object for a given dsn.
void	Bs_Db() constructor.
mixed	&getDsn([ string $key ]) Return the _dsnInfo-hash.
bool	provides( $feature) Tell whether a DB implementation or its backend extension supports a given feature.
mixed	getFieldValue(string $theTable, string $fieldToSearch, string $valueToSearch, mixed $fieldToGet, [ string $caseSensitive ]) Returns 1-n db-field values.
void	read(string $query) Issue a select query and return a resource (or statement for oci).
object an	&rsRead(string $query) Issue a select query and return an instance of Bs_ResultSet.
int	countRead(string $query) Issue a select query and return the number of 'affected' rows.
bool	write(string $query) Issue a write query (insert, update, delete, replace, drop, alter, create).
int	countWrite(string $query) Issue a write query (update, delete, replace) and return the number of affected rows.
int	idWrite(string $query) Issue an insert query on a table with an auto_increment field and return the newly inserted id.
mixed	&getOne(mixed $source, [ integer $row, mixed $col ]) Fetch a single value from a data amount given by the param $source.
mixed	&getRow(mixed $source, [ integer $row, string $fetchMode ]) Fetch a full row of data as vector or hash given by the param $source.
void	&getCol(mixed $source, [ mixed $col, integer $startRow, integer $amount ]) Fetch a full OR fraction col of data as vector given by the param $source.
void	&getAssoc(mixed $source, [ string $forceArray, string $hashInsteadOfVector ]) Fetch the entire data given by the param $source into a hash using the first column as the key.
void	&getAssoc2(mixed $source, [ string $forceArray ]) hash array COLUMN BY COLUMN not record by record.
array	&getAll(mixed $source, [ string $fetchMode ]) Fetch the entire data given by the param $source into a hash.
bool	assertExtension( $name) Load a PHP database extension if it is not loaded already.
string	toString() Returns a string with information about the current state of this db object.Warning: documentation is missing.
string	escapeString(string $query) Escape string for the query.
string	formatDateForDb(string $date) format and return date string in database date format.
string	formatDatetimeForDb(string $datetime) format and return datetime string in database datetime format.
string	formatTimestampForDb(string $timestamp) format and return timestamp string in database timestamp format.
string	"eArgs(array $arr, [ string $glue ]) Takes a hash and returns a string for an sql query.
void	isManipulation(string $query) Tells whether a query is a data manipulation query (insert, update, delete replace, alter, drop, create).
string	getErrorMessage(long $errCode) Return a textual error message for a bs DB error code
void	autoCommit([ string $on ]) Turn autoCommit on or off
void	startTransaction() Starts a transaction
void	commit() Commit last query
void	rollback() Rollback last query
mixed	setPointer(int $result, $absolutPos) Set the internal row pointer of the result id to point to the specified row number.
mixed	fetchRow( $result, string $fetchMode) Fetch a row and return it as vector or hash depending on the fetchMode.
void	freeResult( $result) Free the internal resources associated with $result.
int	numCols( $result) Get the number of columns (fields) in a result identifier.
int	numRows( $result) Get the number of rows from a result identifier.
int	affectedRows() Gets the number of rows affected by the last data manipulation query.
int	insertId() Get the id generated from the previous INSERT operation.
int	nativeErrorCode() Returns the numerical native error code from the previous DB operation or 0 (zero) if no error occured.
string	nativeErrorMsg() Returns the native error text from the previous DB operation or '' (empty string) if no error occured.

Private Method Summary
int	getNumRecords(string $query, [ string $ignoreLimit ]) Returns the number of records that get selected for a given query.
string	_vendorSpecificWriteMod(string $query) overwrite this method if needed.
void	&_raiseError([ string $code, string $nativeCode, string $msg, string $file, string $line, string $weight ]) This method is called by DB to generate an error.
void	parseDsn( $dsn)
void	_query(string $query) Send a query to the DB and return the result.
bool	_disconnect(string $disconnectFunctionName) Log out and disconnect from the database.
void	fetchDbNames(string $cached) Warning: documentation is missing.
void	listFields() Warning: documentation is missing.

Public Field Summary
object [unknown]	$Bs_Date reference to the globally used pseudostatic Bs_Date object.
array	$format some database specific formats. please overwrite.

Private Field Summary
string	$_connection a reference to a real db connection
string	$_connected Tells whether we're connected.
string	$_persistent Tells whether we're on a persistant connection.
string	$_dsnInfo associative array holding the db-conn info in these fields:
string	$_lastQuery the last executed query.
string	$_Bs_System A few functions are system dependent like assertExtension() and the subclassed Bs_MySql.
string	$_features Associative array of capabilities for this DB implementation

Private Constant Summary
BS_DB_FETCHMODE_ORDERED	>>`1`<<	Column data indexed by numbers, ordered from 0 and up
BS_DB_FETCHMODE_ASSOC	>>`2`<<	Column data indexed by column names
BS_DB_VERSION	>>`4.0.$x$`<<	Warning: documentation is missing.
BS_DB_ERROR	>>`1`<<	Warning: documentation is missing.
BS_DB_ERROR_SYNTAX	>>`2`<<	Warning: documentation is missing.
BS_DB_ERROR_CONSTRAINT	>>`3`<<	Warning: documentation is missing.
BS_DB_ERROR_NOT_FOUND	>>`4`<<	Warning: documentation is missing.
BS_DB_ERROR_ALREADY_EXISTS	>>`5`<<	Warning: documentation is missing.
BS_DB_ERROR_UNSUPPORTED	>>`6`<<	Warning: documentation is missing.
BS_DB_ERROR_MISMATCH	>>`7`<<	Warning: documentation is missing.
BS_DB_ERROR_INVALID	>>`8`<<	Warning: documentation is missing.
BS_DB_ERROR_NOT_CAPABLE	>>`9`<<	Warning: documentation is missing.
BS_DB_ERROR_TRUNCATED	>>`10`<<	Warning: documentation is missing.
BS_DB_ERROR_INVALID_NUMBER	>>`11`<<	Warning: documentation is missing.
BS_DB_ERROR_INVALID_DATE	>>`12`<<	Warning: documentation is missing.
BS_DB_ERROR_DIVZERO	>>`13`<<	Warning: documentation is missing.
BS_DB_ERROR_NODBSELECTED	>>`14`<<	Warning: documentation is missing.
BS_DB_ERROR_CANNOT_CREATE	>>`15`<<	Warning: documentation is missing.
BS_DB_ERROR_CANNOT_DELETE	>>`16`<<	Warning: documentation is missing.
BS_DB_ERROR_CANNOT_DROP	>>`17`<<	Warning: documentation is missing.
BS_DB_ERROR_NOSUCHTABLE	>>`18`<<	Warning: documentation is missing.
BS_DB_ERROR_NOSUCHFIELD	>>`19`<<	Warning: documentation is missing.
BS_DB_ERROR_NEED_MORE_DATA	>>`20`<<	Warning: documentation is missing.
BS_DB_ERROR_NOT_LOCKED	>>`21`<<	Warning: documentation is missing.
BS_DB_ERROR_VALUE_COUNT_ON_ROW	>>`22`<<	Warning: documentation is missing.
BS_DB_ERROR_INVALID_DSN	>>`23`<<	Warning: documentation is missing.
BS_DB_ERROR_CONNECT_FAILED	>>`24`<<	Warning: documentation is missing.
BS_DB_ERROR_CANNOT_SELECT_DB	>>`25`<<	Warning: documentation is missing.
BS_DB_ERROR_NOT_CONNECTED	>>`26`<<	Warning: documentation is missing.
BS_DB_ERROR_INVALID_RS	>>`27`<<	Warning: documentation is missing.

Public Method Details

&getDbObject

public object [unknown] &getDbObject( [ string $dsn ] )

function to get a db object for a given dsn.
note: this is a function, not a method of a db object.if $dsn is not given or set to null, a reference to the global shared db objectwill be returned. if it does not exist, this function tries to open the connectionfor it.example:$dsn = array('host'=>'localhost', 'port'=>3306, 'user'=>'foo', 'pass'=>'bar', 'syntax'=>'mysql', 'type'=>'mysql');$db = &getDbObject($dsn);^^ important!!!^

Parameter

string	$dsn	`= >>null<<`
	(a hash, see Bs_Form->dbDsn for a description)

Returns

object [unknown]

(instance of a subclassed db class)

Throws bs_exception

Author(s) ,

Bs_Db

public void Bs_Db( )

constructor.

Returns

void

&getDsn

public mixed &getDsn( [ string $key ] )

Return the _dsnInfo-hash.

Parameter

string	$key	`= >>NULL<<`
	if specified then only the value for the given key will be returned.

Returns

mixed

(&hash return the _dsnInfo-hash or mixed, depending on param $key.)

provides

public bool provides( $feature )

Tell whether a DB implementation or its backend extension supports a given feature.
currently, these features are reported (see constructor of subclassing class, like Bs_MySql)'prepare', 'pconnect', 'transactions', 'innerSelects', 'insertId', 'affectedRows','numRows', 'numCols'

Parameter

	$feature
	Warning: documentation is missing.

Returns

bool

whether this DB implementation supports $feature (or NULL if $feature not known).

getFieldValue

public mixed getFieldValue( string $theTable, string $fieldToSearch, string $valueToSearch, mixed $fieldToGet, [ string $caseSensitive ] )

Returns 1-n db-field values.
Example I:$birthday = getFieldValue($theTable='employees', $fieldToSearch='username', $valueToSearch='Hugentobler', $fieldToGet='birthday')Example II:list($birthday, $phone) = getFieldValue('employees', 'username', 'Hugentobler', array('birthday', 'phone'))NOTE: Only the first found record is used.

Parameter

string	$theTable
	The db-table to search. Can also be 'database.table'.

string	$fieldToSearch
	The field to compare.

string	$valueToSearch
	The value to compare.

mixed	$fieldToGet
	The field name as string of which we want the value, or an array with field names.

string	$caseSensitive	`= >>TRUE<<`
	(opt) if the compare in the db should be made case sensitive or no. default is TRUE.

Returns

mixed

The desired field value, whatever that is. If param $fieldToGet is an array, an array is returned here.

Throws bs_exception

read

public void read( string $query )

Issue a select query and return a resource (or statement for oci).

Parameter

string	$query
	A read only SQL statement.

Returns

void

Throws Bs_Exception

&rsRead

public object an &rsRead( string $query )

Issue a select query and return an instance of Bs_ResultSet.

Parameter

string	$query
	A read only SQL statement.

Returns

object an

instance of Bs_ResultSet

Throws Bs_Exception

countRead

public int countRead( string $query )

Issue a select query and return the number of 'affected' rows.
This method makes use of this->numRows().

Parameter

string	$query
	A SQL statement.

Returns

int

number of rows matched (0-x)

Throws Bs_Exception

write

public bool write( string $query )

Issue a write query (insert, update, delete, replace, drop, alter, create).

Parameter

string	$query
	A modifing SQL statement.

Returns

bool

true on success, otherwise throws an exception.

Throws Bs_Exception

countWrite

public int countWrite( string $query )

Issue a write query (update, delete, replace) and return the number of affected rows.
this method makes use of this->affectedRows() read the doc of it!

Parameter

string	$query
	A modifing SQL statement.

Returns

int

number of rows affected

Throws Bs_Exception if the query was unsuccessful, FALSE if the count with affectedRows() failed.

See Also write(), idWrite(), affectedRows()

idWrite

public int idWrite( string $query )

Issue an insert query on a table with an auto_increment field and return the newly inserted id.
this method makes use of this->insertId() read the doc of it!

Parameter

string	$query
	A SQL statement that inserts a record.

Returns

int

>=1

Throws Bs_Exception if the query failed, FALSE if the operation was not an insert.

See Also countWrite(), write(), insertId()

&getOne

public mixed &getOne( mixed $source, [ integer $row, mixed $col ] )

Fetch a single value from a data amount given by the param $source.
$source can be either a SQL query string or a result set.IF param $source is a query-string:Execute the query, fetch value and clean up (free the results set).ELSEIF param $source is a result set:Move down $row-rows, fetch value at $col and leave DB curser*after* offset rows. Don't free result set.A row and col offset can be given. Top left cell is row=0 / col=0.The default behavior is to fetch cell [0,0] (top left cell).NOTE: col may be given as col-name (string) instead of offset (int). It will beused as key to identify the right column. So pass the right type!Sample: Given is the table "mytable" containing:\/ID TEXT DATE--------------------------------> 1 'one' 09.05.19602 'two' 25.12.19703 'three' 31.01.1980getOne('SELECT id, teXt, date as birthday FROM mytable'); // would return '1'.getOne($query, 1, 2); // would return '25.12.1970'.getOne($query, 2, 'teXt'); // would return 'two'.

Parameter

mixed	$source
	can be an SQL query as string, or a result set (a resource).

integer	$row	`= >>0<<`
	the row number

mixed	$col	`= >>0<<`
	which column to return (integer [column number, starting at 0] or string [column name])

Returns

mixed

just one value or NULL if row or col are out of bounds or don't exsist.

Throws Bs_Exception on error

&getRow

public mixed &getRow( mixed $source, [ integer $row, string $fetchMode ] )

Fetch a full row of data as vector or hash given by the param $source.
$source can be either a SQL query string or a result set.If fetchMode is BS_DB_FETCHMODE_ASSOC (default) returns a hash array that correspondsto the fetched row else if it's BS_DB_FETCHMODE_ORDERED returns a vector starting at offset 0.IF param $source is a query-string:Execute the query, fetch row and clean up (free the results set).ELSEIF param $source is a result set:Move down $row-rows, fetch row and leave DB curser*after* offset rows. Don't free result set.The default behaver is to fetch current row.Sample: Given is the table "mytable" containing:ID TEXT DATE--------------------------------> 1 'one' 09.05.1960 <-2 'two' 25.12.19703 'three' 31.01.1980getRow('SELECT id, teXt, date as birthday FROM mydate'); // would return array('id' => '1','teXt' => 'one','birthday' => '09.05.1960');

Parameter

mixed	$source
	can be an SQL query string, or a resource.

integer	$row	`= >>-1<<`
	IF >=0 will move internal row pointer to abs. position befor fetching the data. Default is -1.

string	$fetchMode	`= >>BS_DB_FETCHMODE_ASSOC<<`
	(opt) (default BS_DB_FETCHMODE_ASSOC) see above.

Returns

mixed

vector , hash. NULL if row offest is out of bounds OR no data found.

Throws Bs_Exception on error

&getCol

public void &getCol( mixed $source, [ mixed $col, integer $startRow, integer $amount ] )

Fetch a full OR fraction col of data as vector given by the param $source.
IF param $source is a query-string:Execute the query, fetch col and clean up (free the results set).ELSEIF param $source is a result set:Move down $row-rows, fetch col and leave DB curser*after* last read row. Don't free result set.NOTE: col may be given as col-name (string) instead of offset (int). It will beused as key to identify the right column. So pass the right type!Sample: Given is the table "mytable" containing:\/ID TEXT DATE-------------------------------1 'one' 09.05.19602 'two' 25.12.19703 'three' 31.01.1980/\getCol('SELECT id, teXt, date as birthday FROM mydate', 'teXt'); // would return array('one', 'two', 'three');If you'd only wand to get array('two', 'three') you'd do:getCol($query, 1, 1) or getCol($query, 1, 1, 2) or getCol($query, 'teXt', 1)

Parameter

mixed	$source
	can be an SQL query string, or a resource.

mixed	$col	`= >>0<<`
	which column to return (integer [column number, starting at 0] or string [column name])

integer	$startRow	`= >>0<<`
	the row number at which we start, including that row. default is 0.

integer	$amount	`= >>-1<<`
	the row number at which we stop, including that row. default is -1 which means loop until the end.

Returns

void

Throws Bs_Exception on error

&getAssoc

public void &getAssoc( mixed $source, [ string $forceArray, string $hashInsteadOfVector ] )

Fetch the entire data given by the param $source into a hash using the first column as the key.
$source can be either a SQL query string or a result set.IF param $source is a query-string:Execute the query, fetch entire data and clean up (free the results set).ELSEIF param $source is a result set:Fetch the entire data. Don't free result set.If more than 2 values are involved in the result set or if $forceArray is TRUE,a hash containing a vector is returned e.g. array('1' => array('one', '944679408'));otherwise a simple hash is returned (see sample below).If the result set contains fewer than two columns, a BS_DB_ERROR_TRUNCATED exception is raised.Sample: Given is the table "mytable" containing:ID TEXT DATE-------------------------------1 'one' 09.05.19602 'two' 25.12.19703 'three' 31.01.1980example 1:getAssoc('SELECT id,text FROM mytable'); // would return: array( '1' => 'one','2' => 'two','3' => 'three')example 2:getAssoc('SELECT id,text,date FROM mydate') // would return: array( '1' => array('one', '944679408'),'2' => array('two', '944679408'),'3' => array('three', '944679408'))example 3:getAssoc('SELECT id,text,date FROM mydate', TRUE, TRUE) // would return:array( '1' => array('text'=>'one', 'date'=>'944679408'),'2' => array('text'=>'two', 'date'=>'944679408'),'3' => array('text'=>'three', 'date'=>'944679408'))this option is new, 2002/03/25 --andrejspecial note: you have to use a key that is unique. otherwise only one record will beused, i think the later ones overwrite the previews.

Parameter

mixed	$source
	can be an SQL query string, or a resource.

string	$forceArray	`= >>FALSE,<<`
	(opt) used only when the query returns exactly two columns. If true, the values of the returned array will be one-element arrays instead of scalars.

string	$hashInsteadOfVector	`= >>FALSE<<`
	(default is FALSE. if set to true then the values will be returned in a hash (with field names) instead of a vector. see example 3 above.)

Returns

void

Throws Bs_Exception on error

&getAssoc2

public void &getAssoc2( mixed $source, [ string $forceArray ] )

hash array COLUMN BY COLUMN not record by record.
The rest is like getAssoc(). See above.Sample: Given is the table "mytable" containing:ID TEXT DATE-------------------------------1 'one' 09.05.19602 'two' 25.12.19703 'three' 31.01.1980getAssoc2('SELECT id, teXt, date as birthday FROM mytable');would return:array( 'id' => array('1', '2', '3'),'teXt' => array('one', 'two', 'three'),'birthday' => array('09.05.1960', '25.12.1970', '31.01.1980'))

Parameter

mixed	$source
	can be an SQL query string, or a resource.

string	$forceArray	`= >>FALSE<<`
	used only when the query returns exactly 1 column. If true, the values of the returned array will be one-element arrays instead of scalars.

Returns

void

Throws Bs_Exception on error

&getAll

public array &getAll( mixed $source, [ string $fetchMode ] )

Fetch the entire data given by the param $source into a hash.
$source can be either a SQL query string or a result set.IF param $source is a query-string:Execute the query, fetch entire data and clean up (free the results set).ELSEIF param $source is a result set:Fetch the entire data. Don't free result set.Sample: Given is the table "mytable" containing:ID TEXT DATE-------------------------------1 'one' 09.05.19602 'two' 25.12.19703 'three' 31.01.1980getAll('SELECT id, teXt, date as birthday FROM mydate', 'teXt', BS_DB_FETCHMODE_ASSOC) returns:would return:array( array('id' => '1', 'teXt' => 'one', 'birthday' => '09.05.1960'),array('id' => '2', 'teXt' => 'two', 'birthday' => '25.12.1970'),array('id' => '3', 'teXt' => 'three', 'birthday' => '31.01.1980'))

Parameter

mixed	$source
	can be an SQL query string, or a resource.

string	$fetchMode	`= >>BS_DB_FETCHMODE_ASSOC<<`
	(opt) (default BS_DB_FETCHMODE_ASSOC) see getRow.

Returns

array

a nested array. See sample above. may be an empty array if nothing was found.

Throws Bs_Exception on error

assertExtension

public bool assertExtension( $name )

Load a PHP database extension if it is not loaded already.

Parameter

	$name
	Warning: documentation is missing.

Returns

bool

true if the extension was already or successfully loaded, false if it could not be loaded

toString

public string toString( )

Returns a string with information about the current state of this db object.
for security reason, no user/pass information is returned here because someone(you?) might log the returned value.

Warning: documentation is missing.

Returns

string

escapeString

public string escapeString( string $query )

Escape string for the query.
if there is a better/specialized way for your specific rdbms, overwrite this.

Parameter

string	$query

Returns

string

the escaped query

formatDateForDb

public string formatDateForDb( string $date )

format and return date string in database date format.
overwrite this if needed.

Parameter

string	$date
	(yyyy-mm-dd)

Returns

string

(date formatted for this rdbms implementation)

See Also formatDatetimeForDb(), formatTimestampForDb()

formatDatetimeForDb

public string formatDatetimeForDb( string $datetime )

format and return datetime string in database datetime format.
overwrite this if needed.

Parameter

string	$datetime
	(yyyy-mm-dd hh:mm:ss)

Returns

string

(datetime formatted for this rdbms implementation)

See Also formatDateForDb(), formatTimestampForDb()

formatTimestampForDb

public string formatTimestampForDb( string $timestamp )

format and return timestamp string in database timestamp format.
overwrite this if needed.

Parameter

string	$timestamp
	(yyyy-mm-dd hh:mm:ss)

Returns

string

(timestamp formatted for this rdbms implementation)

See Also formatDateForDb(), formatDatetimeForDb()

"eArgs

public string "eArgs( array $arr, [ string $glue ] )

Takes a hash and returns a string for an sql query.
example 1:$arr = array('name' => 'tom', 'age' => '35', 'sex' => 'm');$sqlQuery = "UPDATE tbl SET " . $db->quoteArgs($arr, ', ') . " WHERE ID = 1";=> "UPDATE tbl SET name = 'tom', age = '35', sex = 'm' WHERE ID = 1";example 2:$arr = array('name' => 'tom', 'age' => '35', 'sex' => 'm');$sqlQuery = "SELECT * FROM tbl WHERE " . $db->quoteArgs($arr, ' AND ');=> "SELECT * FROM tbl WHERE name = 'tom' AND age = '35' AND sex = 'm'";Note I: $this->escapeString() is used on the $value.Note II: boolean values are converted to ints.

Parameter

array	$arr
	an associative array.

string	$glue	`= >>', '<<`
	a delimiter, default is ', ', could be ' AND ' or ' OR ' ...

Returns

string

a string to include in an sql query.

isManipulation

public void isManipulation( string $query )

Tells whether a query is a data manipulation query (insert, update, delete replace, alter, drop, create).

Parameter

string	$query
	query

Returns

void

getErrorMessage

public string getErrorMessage( long $errCode )

Return a textual error message for a bs DB error code

Parameter

long	$errCode
	a bs error code (see constants)

Returns

string

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

autoCommit

public void autoCommit( [ string $on ] )

Turn autoCommit on or off

Parameter

string	$on	`= >>FALSE<<`
	(opt) If TRUE turn on else off (default TRUE)

Returns

void

Throws Bs_Exception if not supported by this DB

startTransaction

public void startTransaction( )

Starts a transaction

Returns

void

Throws Bs_Exception if not supported by this DB or on any other error.

commit

public void commit( )

Commit last query

Returns

void

Throws Bs_Exception if not supported by this DB or on any other error.

rollback

public void rollback( )

Rollback last query

Returns

void

Throws Bs_Exception if not supported by this DB or on any other error.

setPointer

public mixed setPointer( int $result, $absolutPos )

Set the internal row pointer of the result id to point to the specified row number.
The next fetch call would return that row.

Parameter

int	$result
	the row number, which starts at position 0.

	$absolutPos
	Warning: documentation is missing.

Returns

mixed

TRUE on success, NULL on a row number (param $num) that is out of bounds.

Throws Bs_Exception if not supported by this DB or on any other error.

fetchRow

public mixed fetchRow( $result, string $fetchMode )

Fetch a row and return it as vector or hash depending on the fetchMode.
Subsequent calls will return the next row in the result set, or NULL if there are no more rows.If fetchMode is BS_DB_FETCHMODE_ASSOC (default) it returns a hash array that correspondsto the fetched row else if it's BS_DB_FETCHMODE_ORDERED returns a vector starting at offset 0.

Parameter

	$result
	Warning: documentation is missing.

string	$fetchMode
	Warning: documentation is missing.

Returns

mixed

vector , hash or NULL if there is no more data

Throws Bs_Exception if not supported by this DB or any other error.

freeResult

public void freeResult( $result )

Free the internal resources associated with $result.

Parameter

	$result
	Warning: documentation is missing.

Returns

void

numCols

public int numCols( $result )

Get the number of columns (fields) in a result identifier.

Parameter

	$result
	Warning: documentation is missing.

Returns

int

the number of columns per row in $result

Throws Bs_Exception if not supported by this DB or any other error.

numRows

public int numRows( $result )

Get the number of rows from a result identifier.

Parameter

	$result
	Warning: documentation is missing.

Returns

int

see above

Throws Bs_Exception if not supported by this DB or any other error.

affectedRows

public int affectedRows( )

Gets the number of rows affected by the last data manipulation query.

Returns

int

see above

Throws Bs_Exception if not supported by this DB or any other error.

insertId

public int insertId( )

Get the id generated from the previous INSERT operation.

Returns

int

a positive integer, which means >=1

Throws Bs_Exception if not supported by this DB or any other error.

nativeErrorCode

public int nativeErrorCode( )

Returns the numerical native error code from the previous DB operation or 0 (zero) if no error occured.

Returns

int

see above

Throws Bs_Exception if not supported by this DB or any other error.

nativeErrorMsg

public string nativeErrorMsg( )

Returns the native error text from the previous DB operation or '' (empty string) if no error occured.

Returns

string

see above

Throws Bs_Exception if not supported by this DB or any other error.

Private Method Details

getNumRecords

private int getNumRecords( string $query, [ string $ignoreLimit ] )

Returns the number of records that get selected for a given query.
Example: You want to display page 5 of your search engine with 10 results (per page).So your query would look like this: "select * from searchEngine limit 40,10".But at the same time, you want to show the user how many records really *were*found. The numRows() for the above query will only show you 10...Caution: Never fire a delete statement to this method. This is for select queries only.If you do and it has a 'limit' clause and $ignoreLimit is set to true, thelimit will be ignored...NOTE: This method is *not* optimized. It should not be used with queries thatreturn a large amound of data. Your query is executed in real, and thenumRows() is returned.

Parameter

string	$query

string	$ignoreLimit	`= >>TRUE<<`
	(opt) Default TRUE. If TRUE, a limit x,y in the given query is ignored.

Returns

int

the number of records

Throws Bs_Exception

_vendorSpecificWriteMod

private string _vendorSpecificWriteMod( string $query )

overwrite this method if needed.

Parameter

string	$query
	(write query like insert, update, delete ...)

Returns

string

(the modified or unmodified query)

&_raiseError

private void &_raiseError( [ string $code, string $nativeCode, string $msg, string $file, string $line, string $weight ] )

This method is called by DB to generate an error.

Parameter

string	$code	`= >>BS_DB_ERROR,<<`

string	$nativeCode	`= >>NULL,<<`

string	$msg	`= >>NULL,<<`
	a custom error message. if not specified, the var $_lastQuery will be used here.

string	$file	`= >>''<<`
	(use __FILE__)

string	$line	`= >>''<<`
	(use __LINE__)

string	$weight	`= >>''<<`
	('fatal')

Returns

void

parseDsn

private void parseDsn( $dsn )

Parameter

	$dsn
	Warning: documentation is missing.

Returns

void

_query

private void _query( string $query )

Send a query to the DB and return the result.
NOTE: This is so fundemental that we exit with error, if this function is not overloaded.

Parameter

string	$query
	the SQL query

Returns

void

_disconnect

private bool _disconnect( string $disconnectFunctionName )

Log out and disconnect from the database.
Note: p-connected links won't be closed.

Parameter

string	$disconnectFunctionName

Returns

bool

TRUE if we already have been or are now disconnected, FALSE if we're on a persistant conn.

Throws NULL if we cannot tell in which state the connection is now. internally for this object, the connection is 'closed'.

fetchDbNames

private void fetchDbNames( string $cached )

Warning: documentation is missing.

Parameter

string	$cached
	Warning: documentation is missing.

Returns

void

listFields

private void listFields( )

Warning: documentation is missing.

Returns

void

Public Field Details
$Bs_Date
public object [unknown] $Bs_Date >><< reference to the globally used pseudostatic Bs_Date object.

$format
public array $format >>`array( 'date' => "'Y-m-d'", //no escapeString() will be used on that. 'datetime' => "'Y-m-d H:i:s'", //no escapeString() will be used on that. 'timestamp' => "'YmdHis'", //no escapeString() will be used on that. )`<< some database specific formats. please overwrite.
See Also	formatDateForDb(), formatDatetimeForDb(), formatTimestampForDb()

Private Field Details
$_connection
private string $_connection >>`NULL`<< a reference to a real db connection

$_connected
private string $_connected >>`FALSE`<< Tells whether we're connected.

$_persistent
private string $_persistent >>`FALSE`<< Tells whether we're on a persistant connection.

$_dsnInfo
private string $_dsnInfo >>`NULL`<< associative array holding the db-conn info in these fields: 'name' => db name 'pass' => letmein'host' => localhost 'socket' => a unix socket'port' => 6667 'syntax' => mysql'user' => root 'type' => mysql'tns' => identifier for oracleDB type (mysql, oci8, odbc etc.)Db syntax (mysql, access, oracle, ...)

$_lastQuery
private string $_lastQuery >>`NULL`<< the last executed query.

$_Bs_System
private string $_Bs_System >>`NULL`<< A few functions are system dependent like assertExtension() and the subclassed Bs_MySql. They make use of _Bs_System->isWindows() function.

$_features
private string $_features >>`NULL`<< Associative array of capabilities for this DB implementation with the elements'prepare' => bool'pconnect' => bool'transactions' => bool'innerSelects' => bool'insertId' => bool'affectedRows' => bool'numRows' => bool'numCols' => bool'storedProc' => bool

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

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

BS_DB_VERSION `define( BS_DB_VERSION, >>4.0.$x$<< )` Case: default: case sensitive

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

BS_DB_ERROR_INVALID_DSN `define( BS_DB_ERROR_INVALID_DSN, >>23<< )` Case: default: case sensitive

BS_DB_ERROR_CONNECT_FAILED `define( BS_DB_ERROR_CONNECT_FAILED, >>24<< )` Case: default: case sensitive

BS_DB_ERROR_CANNOT_SELECT_DB `define( BS_DB_ERROR_CANNOT_SELECT_DB, >>25<< )` Case: default: case sensitive

BS_DB_ERROR_NOT_CONNECTED `define( BS_DB_ERROR_NOT_CONNECTED, >>26<< )` Case: default: case sensitive

BS_DB_ERROR_INVALID_RS `define( BS_DB_ERROR_INVALID_RS, >>27<< )` Case: default: case sensitive

BlueShoes Application Framework - Db

Bs_Db

public class Bs_Db extends Bs_Object

Methods inherited from Bs_Object

Public Method Summary

&getDbObject([ string $dsn ])

Bs_Db()

&getDsn([ string $key ])

provides( $feature)

getFieldValue(string $theTable, string $fieldToSearch, string $valueToSearch, mixed $fieldToGet, [ string $caseSensitive ])

read(string $query)

&rsRead(string $query)

countRead(string $query)

write(string $query)

countWrite(string $query)

idWrite(string $query)

&getOne(mixed $source, [ integer $row, mixed $col ])

&getRow(mixed $source, [ integer $row, string $fetchMode ])

&getCol(mixed $source, [ mixed $col, integer $startRow, integer $amount ])

&getAssoc(mixed $source, [ string $forceArray, string $hashInsteadOfVector ])

&getAssoc2(mixed $source, [ string $forceArray ])

&getAll(mixed $source, [ string $fetchMode ])

assertExtension( $name)

toString()

escapeString(string $query)

formatDateForDb(string $date)

formatDatetimeForDb(string $datetime)

formatTimestampForDb(string $timestamp)

"eArgs(array $arr, [ string $glue ])

isManipulation(string $query)

getErrorMessage(long $errCode)

autoCommit([ string $on ])

startTransaction()

commit()

rollback()

setPointer(int $result, $absolutPos)

fetchRow( $result, string $fetchMode)

freeResult( $result)

numCols( $result)

numRows( $result)

affectedRows()

insertId()

nativeErrorCode()

nativeErrorMsg()

Private Method Summary

getNumRecords(string $query, [ string $ignoreLimit ])

_vendorSpecificWriteMod(string $query)

&_raiseError([ string $code, string $nativeCode, string $msg, string $file, string $line, string $weight ])

parseDsn( $dsn)

_query(string $query)

_disconnect(string $disconnectFunctionName)

fetchDbNames(string $cached)

listFields()

Public Field Summary

$Bs_Date

$format

Private Field Summary

$_connection

$_connected

$_persistent

$_dsnInfo

$_lastQuery

$_Bs_System

$_features

Private Constant Summary

Public Method Details

&getDbObject

Bs_Db

&getDsn

provides

getFieldValue

read

&rsRead

countRead

write

countWrite

idWrite

&getOne

&getRow

&getCol