blueshoes php application framework and cms            core_db
[ class tree: core_db ] [ index: core_db ] [ all elements ]

Class: Bs_Oci

Source Location: /core/db/Bs_Oci.class.php

Class Overview

Bs_Object
   |
   --Bs_Db
      |
      --Bs_Oci

*********************************************************************** This is the API for Oracle. it's an extention of the abstract class Bs_Db.class.php


Author(s):

Version:

  • 4.3.$Revision: 1.2 $ $Date: 2003/08/09 15:17:44 $

Copyright:

  • blueshoes.org

Variables

Methods


Inherited Variables

Inherited Methods

Class: Bs_Db

Bs_Db::Bs_Db()
constructor.
Bs_Db::affectedRows()
Gets the number of rows affected by the last data manipulation query.
Bs_Db::assertExtension()
Load a PHP database extension if it is not loaded already.
Bs_Db::autoCommit()
Turn autoCommit on or off
Bs_Db::commit()
Commit last query
Bs_Db::countRead()
Issue a select query and return the number of 'affected' rows.
Bs_Db::countWrite()
Issue a write query (update, delete, replace) and return the number of affected rows.
Bs_Db::dbPing()
Tells whether we're connected.
Bs_Db::escapeString()
Escape string for the query.
Bs_Db::fetchRow()
Fetch a row and return it as vector or hash depending on the fetchMode.
Bs_Db::formatDateForDb()
format and return date string in database date format.
Bs_Db::formatDatetimeForDb()
format and return datetime string in database datetime format.
Bs_Db::formatTimestampForDb()
format and return timestamp string in database timestamp format.
Bs_Db::freeResult()
Free the internal resources associated with $result.
Bs_Db::getAll()
Fetch the entire data given by the param $source into a hash.
Bs_Db::getAssoc()
Fetch the entire data given by the param $source into a hash using the first column as the key.
Bs_Db::getAssoc2()
hash array COLUMN BY COLUMN not record by record.
Bs_Db::getAssoc3()
group the values of one field by another one. see the example.
Bs_Db::getCol()
Fetch a full OR fraction col of data as vector given by the param $source.
Bs_Db::getDsn()
Return the _dsnInfo-hash.
Bs_Db::getErrorMessage()
Return a textual error message for a bs DB error code
Bs_Db::getFieldValue()
Returns 1-n db-field values.
Bs_Db::getNumRecords()
Returns the number of records that get selected for a given query.
Bs_Db::getOne()
Fetch a single value from a data amount given by the param $source.
Bs_Db::getRow()
Fetch a full row of data as vector or hash given by the param $source.
Bs_Db::idWrite()
Issue an insert query on a table with an auto_increment field and return the newly inserted id.
Bs_Db::insertId()
Get the id generated from the previous INSERT operation.
Bs_Db::isManipulation()
Tells whether a query is a data manipulation query (insert, update, delete replace, alter, drop, create).
Bs_Db::nativeErrorCode()
Returns the numerical native error code from the previous DB operation or 0 (zero) if no error occured.
Bs_Db::nativeErrorMsg()
Returns the native error text from the previous DB operation or '' (empty string) if no error occured.
Bs_Db::numCols()
Get the number of columns (fields) in a result identifier.
Bs_Db::numRows()
Get the number of rows from a result identifier.
Bs_Db::parseDsn()
Bs_Db::provides()
Tell whether a DB implementation or its backend extension supports a given feature.
Bs_Db::quoteArgs()
Takes a hash and returns a string for an sql query.
Bs_Db::read()
Issue a select query and return a resource (or statement for oci).
Bs_Db::rollback()
Rollback last query
Bs_Db::rsRead()
Issue a select query and return an instance of Bs_ResultSet.
Bs_Db::setPointer()
Set the internal row pointer of the result id to point to the specified row number.
Bs_Db::startTransaction()
Starts a transaction
Bs_Db::toString()
Returns a string with information about the current state of this db object.
Bs_Db::write()
Issue a write query (insert, update, delete, replace, drop, alter, create).

Class: Bs_Object

Bs_Object::Bs_Object()
Bs_Object::getErrors()
Basic error handling: Get *all* errors as string array from the global Bs_Error-error stack.
Bs_Object::getLastError()
Basic error handling: Get last error string from the global Bs_Error-error stack.
Bs_Object::getLastErrors()
Basic error handling: Get last errors string array from the global Bs_Error-error stack sinc last call of getLastErrors().
Bs_Object::persist()
Persists this object by serializing it and saving it to a file with unique name.
Bs_Object::setError()
Basic error handling: Push an error string on the global Bs_Error-error stack.
Bs_Object::toHtml()
Dumps the content of this object to a string using PHP's var_dump().
Bs_Object::toString()
Dumps the content of this object to a string using PHP's var_dump().
Bs_Object::unpersist()
Fetches an object that was persisted with persist()

Class Details

[line 56]
*********************************************************************** This is the API for Oracle. it's an extention of the abstract class Bs_Db.class.php

Some collected knowledge and things to know:

  • oracle uses parsed "statements" instead of "result sets". params and return values may be called "result set" or "result" and then that means "statement" here.
  • "SELECT 2+2" must be "SELECT 2+2 FROM dual" in Oracle everything without a table needs the dummy table "dual" specified.
  • an empty string is treated as NULL from what i've read. kinda crap, isn't it? while 0 stays 0.
  • Oracle is case sensitive when columns are created with quotes around them. When they are created without quotes around them, they are case insensitive. However, Oracle will always display them as being all caps. If PHP referes to a column, it probably gets the case from Oracle. Then since PHP is case sensitive, you have to supply it in all caps. Maxwell_Smart@ThePentagon.com
At the end of this code there are some internal notes.

Quick overview of the features of oracle

    available             | comments
    ----------------------+------------------------------------------------------------------------
    everything that's not |
    listed below          |
    ----------------------+------------------------------------------------------------------------
    not available         | comments
    ----------------------+------------------------------------------------------------------------
    limit                 | has to be hacked, see above.
    rowcount              | has to be hacked, see above.
    insert_id             | different approach than mysql has, see above.
    ansi92 dates          | format is 01-Feb-02, see NLS_DATE_FORMAT
    easy c/blob handling  | hacky.
 




Tags:

pattern:  singleton: (pseudostatic)
access:  public
version:  4.3.$Revision: 1.2 $ $Date: 2003/08/09 15:17:44 $
copyright:  blueshoes.org
author:  andrej arn <at blueshoes dot org>


[ Top ]


Class Variables

$format = array(
    'date'       => "'Y-m-d'",              'datetime'   => "'Y-m-d, h:i:s A'",     'timestamp'  => "'Y-m-d, h:i:s A'",   )

[line 145]

some database specific formats. overwrites parent.



Tags:


Type:   array
Overrides:   Array


[ Top ]

$_currentlyOpenTransactionID =  ''

[line 109]

Holds the 'transaction ID'. (If an trans. ID was set).



Tags:

see:  $this->startTransaction.

Type:   mixed


[ Top ]



Class Methods


constructor Bs_Oci [line 156]

Bs_Oci Bs_Oci( )

Constructor.



[ Top ]

method affectedRows [line 420]

int affectedRows( )

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

For other queries, this function returns FALSE. see numRows().




Tags:

return:  number of rows affected by the last query or FALSE if none are affected or not a manipulation query.
throws:  Bs_Exception if mysql_affected_rows() fails.
access:  public


Overrides Bs_Db::affectedRows() (Gets the number of rows affected by the last data manipulation query.)

[ Top ]

method connect [line 177]

int connect( $dsn $dsn, [$persistent $persistent = TRUE])

Connect to a database server and log in as the specified user.

use (select) the given db, if any.

NOTE I: If we are already connected to somewhere (no matter where), the existing db connection gets closed first.

NOTE II: It's possible to get back an exception but the connection was successfull. Probably the given default database could not be selected => BS_DB_ERROR_CANNOT_SELECT_DB




Tags:

return:  resource id # on success
throws:  Bs_Exception: one of BS_DB_ERROR_INVALID_DSN, BS_DB_ERROR_CONNECT_FAILED, BS_DB_ERROR_CANNOT_SELECT_DB
access:  public


Parameters:

$dsn   $dsn   the data source name as an array. The parseDSN() is deactivated, would need cleanup.
$persistent   $persistent   (opt) whether the connection should be persistent. (Default TRUE)

[ Top ]

method disconnect [line 239]

bool disconnect( )

Log out and disconnect from the database.



Tags:

return:  TRUE if we already have been or are now disconnected, FALSE if we're on a persistant conn.
see:  Bs_Db::_disconnect()
throws:  NULL if we cannot tell in which state the connection is now. internally for this object, the connection is 'closed'.
access:  public


[ Top ]

method escapeString [line 2096]

string escapeString( string $query)

Escape string for oracle query.



Tags:

return:  the escaped query


Overrides Bs_Db::escapeString() (Escape string for the query.)

Parameters:

string   $query  

[ Top ]

method fetchRow [line 319]

mixed &fetchRow( $result $result, [int $fetchMode = BS_DB_FETCHMODE_ASSOC])

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 corresponds to the fetched row else if it's BS_DB_FETCHMODE_ORDERED returns a vector starting at offset 0.

A clean example usage of this method to fetch rows into an array:

while ($row = $this->fetchRow($res, $fetchMode)) { if (isEx($row)) { $row->stackTrace('was here: currentFunction()', __FILE__, __LINE__); return $row; } $ret[] = $row; }




Tags:

return:  vector, hash or NULL if there is no more data
throws:  Bs_Exception on error.
access:  public


Overrides Bs_Db::fetchRow() (Fetch a row and return it as vector or hash depending on the fetchMode.)

Parameters:

int   $fetchMode   (opt) (default BS_DB_FETCHMODE_ASSOC) see above.
$result   $result   db result identifier

[ Top ]

method formatDateForDb [line 2111]

string formatDateForDb( string $date)

format and return date string in database date format.

overwrites parent method.




Tags:

return:  (date formatted for this rdbms implementation)
see:  Bs_Oci::formatDatetimeForDb(), Bs_Oci::formatTimestampForDb()
throws:  string "''" (two single quotes)


Overrides Bs_Db::formatDateForDb() (format and return date string in database date format.)

Parameters:

string   $date   (yyyy-mm-dd)

[ Top ]

method formatDatetimeForDb [line 2132]

string formatDatetimeForDb( string $datetime)

format and return datetime string in database datetime format.

overwrites parent method.




Tags:

return:  (datetime formatted for this rdbms implementation)
see:  Bs_Oci::formatDateForDb(), Bs_Oci::formatTimestampForDb()


Overrides Bs_Db::formatDatetimeForDb() (format and return datetime string in database datetime format.)

Parameters:

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

[ Top ]

method formatTimestampForDb [line 2145]

string formatTimestampForDb( mixed $timestamp, string $datetime)

format and return timestamp string in database timestamp format.

overwrites parent method.




Tags:

return:  (timestamp formatted for this rdbms implementation)
see:  Bs_Oci::formatDateForDb(), Bs_Oci::formatDatetimeForDb()


Overrides Bs_Db::formatTimestampForDb() (format and return timestamp string in database timestamp format.)

Parameters:

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

[ Top ]

method freeResult [line 448]

void freeResult( $result $result)

Free the internal resources associated with $result. Only needs to be called if you are concerned about how much memory is being used for queries that return large result sets.

All associated result memory is automatically freed at the end of the script's execution.




Tags:

return:  (any errors are ignored)
todo:  should we rename this to freeStatement here? think so.
access:  public


Overrides Bs_Db::freeResult() (Free the internal resources associated with $result.)

Parameters:

$result   $result   db result identifier or DB statement identifier

[ Top ]

method getTableInfo [line 1609]

array getTableInfo( string $tblName, [mixed $dbName = NULL], string $dbName.)

Returns a hash holding information about the given db table.

The returned hash (for mySQL 3.23.36) returns these 15 keys (values are examples):

mysql> show table status like 'test'; +------+--------+------------+------+----------------+-------------+-----------------+--------------+-----------+----------------+---------------------+---------------------+------------+----------------+---------+ | Name | Type | Row_format | Rows | Avg_row_length | Data_length | Max_data_length | Index_length | Data_free | Auto_increment | Create_time | Update_time | Check_time | Create_options | Comment | +------+--------+------------+------+----------------+-------------+-----------------+--------------+-----------+----------------+---------------------+---------------------+------------+----------------+---------+ | test | MyISAM | Dynamic | 4 | 22 | 88 | 4294967295 | 2048 | 0 | 5 | 2001-04-02 09:06:58 | 2001-04-02 09:07:00 | NULL | | | +------+--------+------------+------+----------------+-------------+-----------------+--------------+-----------+----------------+---------------------+---------------------+------------+----------------+---------+




Tags:

return:  assoc. array see description.
see:  Bs_Oci::tableHasTransactions(), getTableType()
throws:  Bs_Exception with BS_DB_ERROR_NEED_MORE_DATA if no $dbName available, Bs_Exception otherwise.
access:  public


Parameters:

string   $tblName   a db table name
string   $dbName.   If empty (e.g: '' or NULL) then use the current dbName.

[ Top ]

method idWrite [line 2190]

int idWrite( string $query)

overwrites parent method.

needed cause oracle is different than mysql. i don't like it. we need a sequence for this to work.




Tags:

return:  (number >= 1)
access:  public


Overrides Bs_Db::idWrite() (Issue an insert query on a table with an auto_increment field and return the newly inserted id.)

Parameters:

string   $query  

[ Top ]

method insertId [line 434]

void insertId( )



Tags:

todo:  implement this. currently returns a not-capable exception.
access:  public


Overrides Bs_Db::insertId() (Get the id generated from the previous INSERT operation.)

[ Top ]

method isReservedWord [line 2279]

int isReservedWord( string $word)

Tells if a word is a reserved word for the rdbms.

This is a 'shortcut' for => "sql reference" pdf chapter "C Oracle Reserved Words" and is great for something like an autmated system checkup.

HINT: Make a type conversion (bool) and check for true or false on the returned value.




Tags:

return:  0 if the word is ok, 1 if it's a discouraged word but allowed (don't use it please!!!), 2 if it's disallowed.
see:  $this->isValidName()


Parameters:

string   $word   the word you want to check

[ Top ]

method isValidName [line 2259]

true isValidName( string $string)

Tells if a name for a db, table or field is accepted by the rdbms or not.



Tags:

return:  if it's valid, false if the syntax is incorrect or it's a reserved (or discouraged) word.
todo:  add regexp for syntax check.
see:  $this->isReservedWord()
access:  public


Parameters:

string   $string  

[ Top ]

method nativeError [line 2336]

string &nativeError( )

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



Tags:

return:  native rdbms error code and message like "code:text" or empty string if no error.
see:  Bs_Oci::nativeErrorCode(), Bs_Oci::nativeErrorMsg()
access:  public


[ Top ]

method nativeErrorCode [line 2309]

int nativeErrorCode( )

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



Tags:

return:  native rdbms error code
see:  Bs_Oci::nativeErrorMsg(), Bs_Oci::nativeError()
access:  public


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

[ Top ]

method nativeErrorMsg [line 2323]

string &nativeErrorMsg( )

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

HINT: Better use nativeErrorCode() before calling this method, or call nativeError() directly.




Tags:

return:  native rdbms error message
see:  Bs_Oci::nativeErrorCode(), Bs_Oci::nativeError()
access:  public


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

[ Top ]

method numCols [line 366]

int numCols( $result $result)

Get the number of columns (fields) from a result set.



Tags:

return:  the number of columns per row in $result
throws:  Bs_Exception with BS_DB_ERROR_INVALID_RS on an invalid $result param, Bs_Exception if it failed somehow
access:  public


Overrides Bs_Db::numCols() (Get the number of columns (fields) in a result identifier.)

Parameters:

$result   $result   db result identifier

[ Top ]

method numRows [line 385]

int numRows( $result $result)

Get the number of rows from a result set.



Tags:

return:  the number of rows in $result
todo:  implement this. currently returns a not-capable exception.
throws:  Bs_Exception with BS_DB_ERROR_INVALID_RS on an invalid $result param, Bs_Exception if mysql_num_rows() failed somehow.
access:  public


Overrides Bs_Db::numRows() (Get the number of rows from a result identifier.)

Parameters:

$result   $result   MySQL result identifier

[ Top ]

method selectDb [line 250]

bool selectDb( string $db)

Select a database.



Tags:

return:  true on success, false on failure.
access:  public


Parameters:

string   $db   a database name.

[ Top ]

method tableHasTransactions [line 1752]

bool tableHasTransactions( string $tblName, [string $dbName = NULL])



Tags:

return:  true if table supports transactions, false otherwise.
see:  getTableType(), Bs_Oci::getTableInfo()
access:  public


Parameters:

string   $tblName   a db table name
string   $dbName   a db name, default is NULL which means use the current one.

[ Top ]

method _dbErrorToBsError [line 2392]

mixed _dbErrorToBsError( int $dbError)

Maps error codes of the current dbms to bs-dbErrorCodes.



Tags:

return:  (int bs-dbErrorCode if the error code is mapped, bool FALSE otherwise.


Parameters:

int   $dbError  

[ Top ]


Documentation generated on Mon, 29 Dec 2003 21:12:14 +0100 by phpDocumentor 1.2.3