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

Class: Bs_MySql

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

Class Overview

Bs_Object
   |
   --Bs_Db
      |
      --Bs_MySql

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


Author(s):

Version:

  • 4.3.$Revision: 1.3 $ $Date: 2003/09/08 17:18:53 $

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 129]
This is the API for mySQL it's an extention of the abstract class Bs_Db.class.php

A good understanding of the built in mySQL functions in php is needed to create clean, good code using these classes. please RTFphpM first. here i'll try to avoid copying the php doc over and over again.

Some collected knowledge:

  • When trying to INSERT or UPDATE and trying to put a large amount of text or data (blob) into a mySQL table you might run into problems. In mysql.err you might see: Packet too large (73904) To fix you just have to start up mySQL with the option -O max_allowed_packet=maxsize You would just replace maxsize with the max size you want to insert, the default is 65536.
  • I think php's mySQL functions are bad documented. Sometimes the functions print out error messages to the browser, but that's not always documented. Use the @ to suppress errors for all those functions. Another problem are the return values. Don't trust them. Sometimes you can get an undocumented NULL on an error instead of the expected bool. Please make sure the coder can trust YOUR return values.
  • In mySQL, databases and tables are file-based. so they are case sensitive, except on windows. (Fields are always case insentitive, btw). Now if you issue a statement on windows like: "create table MyTaBlEnAmE ..." the files generated are: mytablename.frm, mytablename.MYD, mytablename.MYI (!). The table names are written in lower case! So if you take your existing db's from linux, move them to a windows server, and then back to linux, your code is broken because all dbs and tables now are written lowercase. I hope mySQL is going to change this behavior soon... *NEVER* create more than 1 db/table with the same name but different cases.
    --sam Aug.2002:
    One way to avoid the above problem is to use mysqld with -O lower_case_table_names=0. By default this option is 1 on Windows and 0 on Unix. (Not tested) If you move MyISAM files from a Windows to a *nix disk, you may in some cases need to use the `mysql_fix_extensions' tool to fix-up the case of the file extensions in each specified database directory (lowercase `.frm', uppercase `.MYI' and `.MYD'). `mysql_fix_extensions' can be found in the `script' subdirectory.
Quick overview of the features of mySQL
    available             | comments
    ----------------------+------------------------------------------------------------------------
    transactions          | using table/handler:
                          | berkeley: table-lock.
                          | gemini:   row-lock. max record size currently 32kb. no gemini support
                          |           built into the shipped versions. not gpl yet.
                          | innodb:   row-lock. fast, similar to the myISAM type. looks like it's
                          |           the best one of these 3.
                          | note:     not sure if the blob data types of the 3 table types are
                          |           any good now. all 3 table types lack some functionality here
                          |           and there, and have some problems here and there, and need
                          |           some manual configuration after the mysql installation.
    fulltext indexing     | it's kinda new.
    ----------------------+------------------------------------------------------------------------
    not available         | comments
    ----------------------+------------------------------------------------------------------------
    subselects            | :( not in V3.23.xx (planed for V4.1). See $this->subSelect() function
    stored procedures     | (planed for V4.1).
    triggers              | *not* planned. Monty is against it because of the performance los.
    foreign keys          | Quotation from the mySQL doc (march.2001):
                          | "In the near future we will extend the FOREIGN KEY implementation so
                          | that at least the information will be saved in the table specification
                          | file and may be retrieved by mysqldump and ODBC. At a later stage we
                          | will implement the foreign key constraints for application that can't
                          | easily be coded to avoid them."
    views                 | planned, on the todo list.
    'foreign chars'       | No support for spaces, foreign and special chars, and reserved words
                          | in field, table and database names. MS-Access and Oracle support this.
 

The following php mySQL functions are *NOT* implemented here because we don't want you to use them:

  • mysql_fetch_object() => Use fetchRow() which makes use of mysql_fetch_assoc() or mysql_fetch_row()
  • mysql_fetch_array() => Use fetchRow() which makes use of mysql_fetch_assoc() or mysql_fetch_row()
  • mysql_result() => I wanted to code a function fetchCell($result, $row), thought it would be sometimes nice to just check a field before getting the whole record. But the doc sais "Calls to mysql_result() should not be mixed with calls to other functions that deal with the result set." So better don't fuck with it. If you only want one field, well, only select one. Otherwise get the full record using fetchRow(). Also see Bs_Db->getOne()
  • mysql_db_query() => Use read("SELECT * FROM database.table") instead. mysql_db_query() actually SWITCHES the current database PERMANENTLY just like mysql_select_db() does.
  • mysql_create_db() => I don't see an advantage for this compared to "create database database_name".
  • mysql_drop_db() => I don't see an advantage for this compared to "drop database database_name".
  • mysql_fetch_lengths() => I don't see a use for it. If you do, feel free to write a nice clean wrapper.
There are a bunch of interesting C api functions in the mySQL manual that are not yet implemented in php. watch out for them...
  • mysql_change_user() only php3
  • mysql_real_escape_string() see $this->escapeString()
  • mysql_info() Returns information about the most recently executed query.
  • mysql_ping() Checks whether or not the connection to the server is working, reconnecting as necessary.
  • mysql_reload() Tells the server to reload the grant tables.
  • mysql_shutdown() Shuts down the database server.
  • mysql_start_slave() Starts slave replication thread.
  • mysql_stop_slave() Stops slave replication thread.
  • mysql_stat() Returns the server status as a string.




Tags:

pattern:  singleton: (pseudostatic)
access:  public
version:  4.3.$Revision: 1.3 $ $Date: 2003/09/08 17:18:53 $
copyright:  blueshoes.org
author:  andrej arn <at blueshoes dot org>, Sam Blum <sam at blueshoes dot org>


[ Top ]


Class Variables

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

[line 210]

some database specific formats. overwrites parent.



Tags:


Type:   array
Overrides:   Array


[ Top ]

$_currentlyOpenTransactionID =  ''

[line 182]

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



Tags:

see:  startTransaction().

Type:   mixed


[ Top ]



Class Methods


constructor Bs_MySql [line 220]

Bs_MySql Bs_MySql( )

Constructor.



[ Top ]

method affectedRows [line 597]

int affectedRows( )

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

For other queries, this function returns FALSE.

RTFM for mysql_affected_rows() !!!

If the last query was a DELETE query with no WHERE clause, all of the records will have been deleted from the table but this function will return zero. hint I: use "DELETE FROM tbl WHERE 1=1" hint II: maybe you are looking for "TRUNCATE TABLE table_name" anyway.




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 autoCommit [line 248]

bool autoCommit( [bool $on = FALSE])

Turn autoCommit on or off



Tags:

return:  last state: TRUE if it was on; FALSE if it was off.
throws:  Bs_Exception if not supported by this DB
access:  public


Overrides Bs_Db::autoCommit() (Turn autoCommit on or off)

Parameters:

bool   $on   (opt) If TRUE turn on else off (default TRUE)

[ Top ]

method commit [line 284]

bool commit( [$transactionId $transactionId = ''])

Commit the current or given transaction.



Tags:

return:  TRUE on success.
see:  Bs_MySql::startTransaction()
throws:  Bs_Exception if not supported by this DB or on any other error.
access:  public


Overrides Bs_Db::commit() (Commit last query)

Parameters:

$transactionId   $transactionId   string (opt). See $this->startTransaction.

[ Top ]

method connect [line 334]

int connect( array $dsn, [bool $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:

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

[ Top ]

method databaseExists [line 1270]

bool databaseExists( mixed $lookups, [bool $useCache = TRUE])

Tells whether the database (or databases) exist or not.

NOTE I: Databases and tables are file-based in mysql. So they are case sensitive on iX, *but* INsensitive on winblows. So for windows we have to do a case insensitive check.

NOTE II: This method makes use of fetchDatabaseNames(). So if param $useCache is set to TRUE and fetchDatabaseNames() has been called before, the cached values will be used.




Tags:

return:  true if all dbs exists, false if at least one doesn't.
see:  Bs_MySql::fieldExists(), Bs_MySql::tableExists()
throws:  Bs_Exception
access:  public


Parameters:

mixed   $lookups   a db name as a string, or an array with db names.
bool   $useCache   default is TRUE. see note II.

[ Top ]

method databaseName [line 711]

string databaseName( resource $result, int $offset)

Get the name of the specified db in a result you got from mysql_list_dbs().

This is a wrapper for mysql_db_name(). I don't think you ever need this method ...




Tags:

return:  the db name
see:  Bs_MySql::fieldName(), Bs_MySql::tableName(), Bs_MySql::listDatabases(), Bs_MySql::fetchDatabaseNames()
throws:  Bs_Exception with BS_DB_ERROR_INVALID_RS on an invalid $result param, Bs_Exception on a field index that doesn't exist or any other error.
access:  public


Parameters:

resource   $result   a result identifier you got from mysql_list_dbs(), no other result!!
int   $offset   fieled offset in result beginning with 0.

[ Top ]

method disconnect [line 397]

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 2421]

string escapeString( string $query)

Escape string for mysql query.

This method is a wrapper for mysql_escape_string() and overwrites its parent method. mysql_escape_string() is new sinde php403 or 404 and by now it's not documented.

I have found this in the mysql manual: mysql_real_escape_string() Escapes special characters in a string for use in a SQL statement taking into account the current charset of the connection. mysql_escape_string() Escapes special characters in a string for use in a SQL statement. So watch out for mysql_real_escape_string() to be implemented in php...

You can find a pure php impelementation here: http://www.zend.com/codex.php?id=204&single=1




Tags:

return:  the escaped query
static:  
access:  public


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

Parameters:

string   $query  

[ Top ]

method fetchDatabaseNames [line 941]

mixed &fetchDatabaseNames( [string $format = 'vector'], [bool $useCache = TRUE])

Return the available db names.

If successfull the data will be cached for further calls. NOTE: You'll see all db's even if you don't have the rights to access them.

The returned value is dependent on the $format param. E.g.: 'vector' => array(db1, db2, db3) 'string' => 'db1, db2, db3'




Tags:

return:  (see param $format)
see:  Bs_MySql::fetchFieldNames(), Bs_MySql::fetchTableNames()
access:  public


Parameters:

string   $format   the return type. can be one of 'vector' (default) or 'string'. see description.
bool   $useCache   default is TRUE. if set to true and the method has been executed successfully before, the previous result will be used/returned.

[ Top ]

method fetchField [line 1151]

object fetchField( resource $result, [int $offset = NULL])

Returns an object containing field information (of the table structure).

This has nothing to do with fetching data from a field, like fetchRow(). You might be looking for something like php's mysql_result(), which is not supported here for reasons mentioned in the header. See comments of unimplemented functions in the head of this file.

This is a wrapper for mysql_fetch_field().




Tags:

throws:  Bs_Exception with BS_DB_ERROR_INVALID_RS on an invalid $result param, Bs_Exception if mysql_fetch_field() failed somehow.
access:  public


Parameters:

resource   $result   a result set
int   $offset   if not given, the next field (that wasn't yet retrieved) will be used.

[ Top ]

method fetchFieldNames [line 1056]

&mixed &fetchFieldNames( string $tblName, [mixed $dbName = NULL], [string $format = 'vector'], [bool $useCache = TRUE], string $dbName.)

Return the field names of the given database table.

If successfull the data will be cached for succeeding calls. NOTE: Fields may exist but if you don't have the perms, you won't see them!

The returned value is dependent on the $format param. E.g.: 'vector' => array(field1, field2, field3) 'string' => 'field1, field2, field3' we are using comma instead of space here because some db's allow you to use spaces inside of field names.




Tags:

return:  (see param $format)
see:  Bs_MySql::fetchTableNames(), fetchDbNames()
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 or 0) then use the current dbName.
string   $format   the return type. Can be one of 'vector' (default) or 'string'. see description.
bool   $useCache   If TRUE (default) and the method has been executed successfully before for this db table, the previous result will be used/returned.

[ Top ]

method fetchRow [line 525]

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   MySQL result identifier

[ Top ]

method fetchTableNames [line 996]

mixed &fetchTableNames( [mixed $dbName = NULL], [string $format = 'vector'], [bool $useCache = TRUE], string $dbName.)

Return the table names of the given database.

If successfull the data will be cached for further calls. NOTE: Tables may exist but if you don't have the perms, you won't see them!

The returned value is dependent on the $format param. E.g.: 'vector' => array(table1, table2, table3) 'string' => 'table1, table2, table3'




Tags:

return:  (see param $format)
see:  Bs_MySql::fetchFieldNames(), fetchDbNames(), Bs_MySql::getOpenTables()
throws:  Bs_Exception with BS_DB_ERROR_NEED_MORE_DATA if no $dbName available, Bs_Exception otherwise.
access:  public


Parameters:

string   $dbName.   If empty (e.g: '' or NULL or 0) then use the current dbName.
string   $format   the return type. can be one of 'vector' (default) or 'string'. see description.
bool   $useCache   default is TRUE. if set to true and the method has been executed successfully before for this db, the previous result will be used/returned.

[ Top ]

method fieldExists [line 1184]

bool fieldExists( mixed $lookups, string $tableName, [mixed $dbName = NULL], [bool $useCache = TRUE], string $dbName.)

Tells whether the db field (or fields) exist or not.

NOTE I: Fields are not case sensitive in mysql (dbs and tables are, except on windows). This check is made case sensitive! So if your field is called 'myField', you'll get FALSE for 'myfield'.

NOTE II: This method makes use of fetchFieldNames(). So if param $useCache is set to TRUE and fetchFieldNames() has been called before, the cached values will be used.




Tags:

return:  true if all fields exist, false if at least one doesn't.
see:  Bs_MySql::tableExists(), Bs_MySql::databaseExists()
throws:  Bs_Exception with BS_DB_ERROR_NEED_MORE_DATA if no $dbName available, Bs_Exception otherwise.
access:  public


Parameters:

mixed   $lookups   a db field name as a string, or an array with db field names.
string   $tableName   a db table name
string   $dbName.   If empty (e.g: '' or NULL or 0) then use the current dbName.
bool   $useCache   default is TRUE. see note II.

[ Top ]

method fieldFlags [line 763]

mixed fieldFlags( resource $result, int $offset, [string $format = 'string'])

Get the flags of a field at the specified offset from a result id.

This is a wrapper for mysql_field_flags().

The returned value is dependent on the $format param. E.g.: 'string' => 'not_null primary_key blob' 'vector' => array('not_null', 'primary_key', 'blob') 'hash' => array('not_null' => TRUE, 'primary_key' => TRUE, 'unique_key' => FALSE, ...)

Please check the docs for mysql_field_flags to get a list of the current flags supported. By now, they are: (***IF THEY HAVE CHANGED, PLEASE UPDATE THE CODE OF THIS METHOD!***) "not_null", "primary_key", "unique_key", "multiple_key", "blob", "unsigned", "zerofill", "binary", "enum", "auto_increment", "timestamp".

I have read somewhere that the 'flags' blob, enum and timestamp are deprecated because they are not flags but field types. You're descouraged to use them.




Tags:

return:  (based on the param $format) see description.
see:  Bs_MySql::hasFieldFlag()
throws:  Bs_Exception with BS_DB_ERROR_INVALID_RS on an invalid $result param, Bs_Exception on a field index that doesn't exist or any other error.
access:  public


Parameters:

resource   $result   a result identifier.
int   $offset   fieled offset in result beginning with 0.
string   $format   the return type, can be 'string', 'array' or 'assoc'.

[ Top ]

method fieldLen [line 730]

int fieldLen( resource $result, int $offset)

Returns the length of a field at the specified offset from a result id.

NOTE: Not the actual value length but the max possible field space: E.g. if a varchar(20) has the value 'foobar' it returns 20 not 6. This is a wrapper for mysql_field_len() AND mysql_fieldlen() .




Tags:

return:  the field length.
throws:  Bs_Exception with BS_DB_ERROR_INVALID_RS on an invalid $result param, Bs_Exception on a field index that doesn't exist or any other error.
access:  public


Parameters:

resource   $result   a result identifier.
int   $offset   fieled offset in result beginning with 0.

[ Top ]

method fieldName [line 652]

string fieldName( resource $result, int $offset)

Get the field name at the specified offset from a result id.

This is a wrapper for mysql_field_name().




Tags:

return:  the field name
see:  Bs_MySql::tableName(), Bs_MySql::databaseName(), Bs_MySql::listFields(), Bs_MySql::fetchFieldNames()
throws:  Bs_Exception with BS_DB_ERROR_INVALID_RS on an invalid $result param, Bs_Exception on a field index that doesn't exist or any other error.
access:  public


Parameters:

resource   $result   a result identifier you got from mysql_list_fields() OR another result.
int   $offset   fieled offset in result beginning with 0.

[ Top ]

method fieldType [line 854]

string fieldType( resource $result, [int $offset = 0])

Get the type of a field at the specified offset from a result id.

This is a wrapper for mysql_field_type(). CAUTION: The returned types are not the real mysql field types!!

+----------------------------+ | mysql type | returned as |

  • ------------+--------------+
| tinyint | int | | smallint | int | | mediumint | int | | int | int | | bigint | int | | float | real | | double | real | | decimal | real | | date | date | | datetime | datetime | | timestamp | timestamp | | year | year | | char | string | | varchar | string | | tinyblob | blob | | blob | blob | | mediumblob | blob | | longblob | blob | | enum | string | | set | string | +----------------------------+




Tags:

throws:  Bs_Exception with BS_DB_ERROR_INVALID_RS on an invalid $result param, Bs_Exception on a field index that doesn't exist or any other error.
access:  public


Parameters:

resource   $result   a result identifier.
int   $offset   fieled offset in result beginning with 0. default is 0.

[ Top ]

method freeResult [line 637]

void freeResult( mixed $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)
access:  public


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

Parameters:

mixed   $result   MySQL result identifier or DB statement identifier

[ Top ]

method getClientInfo [line 2361]

string getClientInfo( )

Returns a string that represents the client library version.

This method is a wrapper for 'string mysql_get_client_info(void)' and was made available in php405.




Tags:

todo:  code and test this as soon as php405 is out.
since:  php405
static:  
access:  public


[ Top ]

method getDbStructure [line 1113]

array &getDbStructure( [mixed $dbName = NULL], [bool $useCache = TRUE], string $dbName.)

Return a 2-D array of tables and fieldnames found in the given db.

If successfull the data will be cached for succeeding calls. NOTE: Tables and fields may exist but if you don't have the perms, you won't see them!

The returned value sample: array( 'table_1' => array('field_1', 'field_2', 'field_3'), 'table_2' => array('field_A', 'field_B', 'field_C', 'field_D') );




Tags:

return:  hash a 2-D hash of table names contaioning a vector of fields. See above.
see:  Bs_MySql::fetchTableNames(), fetchDbNames()
throws:  Bs_Exception with BS_DB_ERROR_NEED_MORE_DATA if no $dbName available, Bs_Exception otherwise.
access:  public


Parameters:

string   $dbName.   If empty (e.g: '' or NULL or 0) then use the current dbName.
bool   $useCache   If TRUE (default) and the method has been executed successfully before for this db table, the previous result will be returned.

[ Top ]

method getHostInfo [line 2374]

string getHostInfo( )

Returns a string describing the type of connection in use, including the server host name.

This method is a wrapper for 'string mysql_get_host_info([int link_identifier])' and was made available in php405.




Tags:

todo:  code and test this as soon as php405 is out.
since:  php405
access:  public


[ Top ]

method getIniVar [line 2241]

mixed getIniVar( [string $key = NULL], [bool $useCache = TRUE])

Return the value of the currently used ini setting var.

as of mySQL 3.23.36, the following 76 vars are available (with example values): note: in 3.23.47-max-nt the first value 'ansi_mode' isn't there [anymore]. and there are 107 vars in total.

+-------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Variable_name          *| Value                                                                                                                                                                                                  *|
+-------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ansi_mode              *| OFF                                                                                                                                                                                                    *|
| back_log               *| 50                                                                                                                                                                                                     *|
| basedir                *| c:\mysql\                                                                                                                                                                                              *|
| binlog_cache_size      *| 32768                                                                                                                                                                                                  *|
| character_set          *| latin1                                                                                                                                                                                                 *|
| character_sets         *| latin1 big5 czech euc_kr gb2312 gbk sjis tis620 ujis dec8 dos german1 hp8 koi8_ru latin2 swe7 usa7 cp1251 danish hebrew win1251 estonia hungarian koi8_ukr win1251ukr greek win1250 croat cp1257 latin5 |
| concurrent_insert      *| ON                                                                                                                                                                                                     *|
| connect_timeout        *| 5                                                                                                                                                                                                      *|
| datadir                *| c:\mysql\data\                                                                                                                                                                                         *|
| delay_key_write        *| ON                                                                                                                                                                                                     *|
| delayed_insert_limit   *| 100                                                                                                                                                                                                    *|
| delayed_insert_timeout  | 300                                                                                                                                                                                                    *|
| delayed_queue_size     *| 1000                                                                                                                                                                                                   *|
| flush                  *| OFF                                                                                                                                                                                                    *|
| flush_time             *| 1800                                                                                                                                                                                                   *|
| have_bdb               *| NO                                                                                                                                                                                                     *|
| have_gemini            *| NO                                                                                                                                                                                                     *|
| have_innobase          *| NO                                                                                                                                                                                                     *|
| have_isam              *| YES                                                                                                                                                                                                    *|
| have_raid              *| NO                                                                                                                                                                                                     *|
| have_ssl               *| NO                                                                                                                                                                                                     *|
| init_file              *|                                                                                                                                                                                                        *|
| interactive_timeout    *| 28800                                                                                                                                                                                                  *|
| join_buffer_size       *| 131072                                                                                                                                                                                                 *|
| key_buffer_size        *| 8388600                                                                                                                                                                                                *|
| language               *| c:\mysql\share\english\                                                                                                                                                                                *|
| large_files_support    *| ON                                                                                                                                                                                                     *|
| log                    *| OFF                                                                                                                                                                                                    *|
| log_update             *| OFF                                                                                                                                                                                                    *|
| log_bin                *| OFF                                                                                                                                                                                                    *|
| log_slave_updates      *| OFF                                                                                                                                                                                                    *|
| long_query_time        *| 10                                                                                                                                                                                                     *|
| low_priority_updates   *| OFF                                                                                                                                                                                                    *|
| lower_case_table_names  | 1                                                                                                                                                                                                      *|
| max_allowed_packet     *| 1048576                                                                                                                                                                                                *|
| max_binlog_cache_size   | 4294967295                                                                                                                                                                                             *|
| max_binlog_size        *| 1073741824                                                                                                                                                                                             *|
| max_connections        *| 100                                                                                                                                                                                                    *|
| max_connect_errors     *| 10                                                                                                                                                                                                     *|
| max_delayed_threads    *| 20                                                                                                                                                                                                     *|
| max_heap_table_size    *| 16777216                                                                                                                                                                                               *|
| max_join_size          *| 4294967295                                                                                                                                                                                             *|
| max_sort_length        *| 1024                                                                                                                                                                                                   *|
| max_user_connections   *| 0                                                                                                                                                                                                      *|
| max_tmp_tables         *| 32                                                                                                                                                                                                     *|
| max_write_lock_count   *| 4294967295                                                                                                                                                                                             *|
| myisam_recover_options  | OFF                                                                                                                                                                                                    *|
| myisam_sort_buffer_size | 8388608                                                                                                                                                                                                *|
| net_buffer_length      *| 16384                                                                                                                                                                                                  *|
| net_read_timeout       *| 30                                                                                                                                                                                                     *|
| net_retry_count        *| 10                                                                                                                                                                                                     *|
| net_write_timeout      *| 60                                                                                                                                                                                                     *|
| open_files_limit       *| 0                                                                                                                                                                                                      *|
| pid_file               *| c:\mysql\data\workstation.pid                                                                                                                                                                          *|
| port                   *| 3306                                                                                                                                                                                                   *|
| protocol_version       *| 10                                                                                                                                                                                                     *|
| record_buffer          *| 131072                                                                                                                                                                                                 *|
| query_buffer_size      *| 0                                                                                                                                                                                                      *|
| safe_show_database     *| OFF                                                                                                                                                                                                    *|
| server_id              *| 0                                                                                                                                                                                                      *|
| skip_locking           *| ON                                                                                                                                                                                                     *|
| skip_networking        *| OFF                                                                                                                                                                                                    *|
| skip_show_database     *| OFF                                                                                                                                                                                                    *|
| slow_launch_time       *| 2                                                                                                                                                                                                      *|
| socket                 *| MySQL                                                                                                                                                                                                  *|
| sort_buffer            *| 2097144                                                                                                                                                                                                *|
| table_cache            *| 64                                                                                                                                                                                                     *|
| table_type             *| MYISAM                                                                                                                                                                                                 *|
| thread_cache_size      *| 0                                                                                                                                                                                                      *|
| thread_stack           *| 65536                                                                                                                                                                                                  *|
| transaction_isolation   | READ-COMMITTED                                                                                                                                                                                         *|
| timezone               *| Westeuropõische Sommerzeit                                                                                                                                                                             *|
| tmp_table_size         *| 1048576                                                                                                                                                                                                *|
| tmpdir                 *| \                                                                                                                                                                                                      *|
| version                *| 3.23.36                                                                                                                                                                                                *|
| wait_timeout           *| 28800                                                                                                                                                                                                  *|
+-------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
timezone: i have seen the following values 'CEST' 'W. Europe Daylight Time' 'Westeuropõische Sommerzeit' i think that the 'õ' was a 'ä' in the database but was spitted out incorrectly in my telnet session. this makes it hard to find out the used timezone. not for a human, but for a peace of code.

this method uses the 'SHOW VARIABLES' syntax.




Tags:

return:  the ini var value, or an associative array holding all keys/values if no $key specified or $key set to NULL.
see:  getStatusVar();
throws:  NULL if the key does not exist, Bs_Exception otherwise.
access:  public


Parameters:

string   $key   the key (name) of the var you want the value. not case sensitive. if not set or set to NULL, an associative array holding all keys/values will be returned.
bool   $useCache   default is TRUE. if set to true and the method has been executed successfully before *for any key*, the previous result will be used.

[ Top ]

method getOpenTables [line 2087]

mixed getOpenTables( [mixed $dbName = NULL], [string $return = 'vector'], string $dbName.)

Returns the currently open tables in $db.

This is somehow similar to fetchTableNames() but only returns the open ones. NOTE: Tables may exist and be open but you don't have the perms so you won't see them! This method uses the mySQL 'SHOW OPEN TABLES' syntax.

the returned value looks like: 'vector' => array('table1, table2, table3') 'string' => 'table1, table2, table3' 'extended' => array(array('name' => 'table1', 'cached' => '1', 'in_use' => '0'), array('name' => 'table2', 'cached' => '5', 'in_use' => '1')) As you can see, also the numbers are returned as strings, not as int. If the method was not able to read out a number (speaking of cached and in_use), a question mark '?' will be there instead.




Tags:

return:  (see param $return)
see:  Bs_MySql::fetchTableNames()
throws:  Bs_Exception with BS_DB_ERROR_NEED_MORE_DATA if no $dbName available, Bs_Exception otherwise.


Parameters:

string   $dbName.   If empty (e.g: '' or NULL or 0) then use the current dbName.
string   $return   the return type. can be one of 'vector' (default) or 'string'. see description.

[ Top ]

method getProtocolInfo [line 2387]

int getProtocolInfo( )

Returns the protocol version used by current connection.

This method is a wrapper for 'int mysql_get_proto_info([int link_identifier])' and was made available in php405.




Tags:

todo:  code and test this as soon as php405 is out.
since:  php405
access:  public


[ Top ]

method getServerInfo [line 2400]

string getServerInfo( )

Returns a string that represents the server version number.

This method is a wrapper for 'string mysql_get_server_info([int link_identifier])' and was made available in php405.




Tags:

todo:  code and test this as soon as php405 is out.
since:  php405
access:  public


[ Top ]

method getStatusVar [line 2333]

mixed getStatusVar( [string $key = NULL], [bool $useCache = TRUE])

Return the value of the specified status var.

as of 3.23.36, the following 54 vars are available (with example values):

+-------------------------+-------+
| Variable_name           | Value |
+-------------------------+-------+
| Aborted_clients         | 7     |
| Aborted_connects        | 0     |
| Bytes_received          | 0     |
| Bytes_sent              | 0     |
| Connections             | 106   |
| Created_tmp_disk_tables | 0     |
| Created_tmp_tables      | 0     |
| Created_tmp_files       | 0     |
| Delayed_insert_threads  | 0     |
| Delayed_writes          | 0     |
| Delayed_errors          | 0     |
| Flush_commands          | 1     |
| Handler_delete          | 0     |
| Handler_read_first      | 37    |
| Handler_read_key        | 72    |
| Handler_read_next       | 0     |
| Handler_read_prev       | 0     |
| Handler_read_rnd        | 0     |
| Handler_read_rnd_next   | 514   |
| Handler_update          | 36    |
| Handler_write           | 159   |
| Key_blocks_used         | 41    |
| Key_read_requests       | 190   |
| Key_reads               | 0     |
| Key_write_requests      | 159   |
| Key_writes              | 159   |
| Max_used_connections    | 20    |
| Not_flushed_key_blocks  | 0     |
| Not_flushed_delayed_rows| 0     |
| Open_tables             | 0     |
| Open_files              | 0     |
| Open_streams            | 0     |
| Opened_tables           | 166   |
| Questions               | 1316  |
| Select_full_join        | 0     |
| Select_full_range_join  | 0     |
| Select_range            | 0     |
| Select_range_check      | 0     |
| Select_scan             | 72    |
| Slave_running           | OFF   |
| Slave_open_temp_tables  | 0     |
| Slow_launch_threads     | 0     |
| Slow_queries            | 0     |
| Sort_merge_passes       | 0     |
| Sort_range              | 0     |
| Sort_rows               | 0     |
| Sort_scan               | 0     |
| Table_locks_immediate   | 346   |
| Table_locks_waited      | 0     |
| Threads_cached          | 0     |
| Threads_created         | 105   |
| Threads_connected       | 20    |
| Threads_running         | 1     |
| Uptime                  | 200222|
+-------------------------+--------+

this method uses the 'SHOW STATUS' syntax.




Tags:

return:  the status var value, or an associative array holding all keys/values if no $key specified or $key set to NULL.
see:  getIniVar();
throws:  NULL if the key does not exist, Bs_Exception otherwise.
access:  public


Parameters:

string   $key   the key (name) of the var you want the value. not case sensitive. if not set or set to NULL, an associative array holding all keys/values will be returned.
bool   $useCache   default is TRUE. if set to true and the method has been executed successfully before *for any key*, the previous result will be used.

[ Top ]

method getTableInfo [line 1924]

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_MySql::tableHasTransactions(), Bs_MySql::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 getTableLastmod [line 1847]

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

returns the datetime of the last change to the data of the given db table.

changes are things like insert, update, delete, drop, whatever. uses getTableInfo().




Tags:

return:  datetime (eg 2002-04-03 03:31:29)
see:  Bs_MySql::getTablesLastmod(), Bs_MySql::getTableInfo()
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 getTableProperties [line 1798]

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

!!!!!!!!!!!!!!!!deprecated!!!!!!!!!!!!!!!!!!!!!! !!!!!!!!!!!!!!!!deprecated!!!!!!!!!!!!!!!!!!!!!! use getTableStructure() it's a better name and returns better/more info.

Return an array with information about the fields of the given db table. array('fieldName' => array('Type' => 'char', // field type 'Length' => '16' // field leng OR if type=='enum' amount of enums 'Enum' => "'Y','N'" // if type=='enum' the enum values as string: "'value','value',..." 'Null' => (bool?) 'Key' => (bool?) 'Default' => 'N' 'Extra' => string // binary auto_increment zerofill null unsigned ) );




Tags:

return:  (hash, see description.)
throws:  Bs_Exception with BS_DB_ERROR_NEED_MORE_DATA if no $dbName available, Bs_Exception otherwise.
access:  public


Parameters:

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

[ Top ]

method getTablesLastmod [line 1883]

string getTablesLastmod( array $dbs)

this is similar to getTableLastmod(), note the extra s.

it returns the newest datetime of all the given db tables.

all db's need to be on the same machine, and you cannot give a dsn for them. add that functionality when you need it. :)

this method uses getTableLastmod().

param $dbs: it's a vector holding hashes with the keys 'table' and 'db' where table is the table name and db is the db name. if the db key is not set or empty, the default database is used. example: $dbs = array( array('table'=>'a', 'db'=>'test'), array('table'=>'b') );




Tags:

return:  datetime (eg 2002-04-03 03:31:29)
see:  Bs_MySql::getTableLastmod()
throws:  Bs_Exception with BS_DB_ERROR_NEED_MORE_DATA if no $dbName available, Bs_Exception otherwise. bool FALSE if there were no tables specified.
access:  public


Parameters:

array   $dbs   (vector holding hashes, see above)

[ Top ]

method getTableStructure [line 1334]

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

Returns an array with information about the fields of the given db table.

--sam : if ($tmpFieldName == 'ID') it's the wrog place to do debedo stuff 2002-11-28

example return value: array('fieldName' => array('type' => 'char', 'length' => 16 // field length OR if type=='enum' number of enums 'enum' => mixed bool FALSE or array('Y','N') // if type=='enum' the enum values as array 'default' => mixed // string or int or NULL. 'notNull' => bool // true = not null, false = null 'primaryKey' => bool 'multipleKey' => bool // indecates the field has an index 'fulltext' => bool // Is fulltext indexed, RTFM 'unique' => bool 'unsigned' => bool 'zerofill' => bool 'binary' => bool 'autoIncrement' => bool 'foreignKey' => array ) );

'type': field type. possible values are: char, varchar, int, blob, ... 'foreignKey': bool FALSE if it's none. hash with these keys if it's one: 'db' => null (or string if it's different) 'table' => string 'multiple' => bool (IDs)




Tags:

return:  (hash holding hashes, see above.)
todo:  i bet there are a few bugs in the way the data array gets built. have to test this one. need to create a few test-db-tables for that to see how mysql returns the values.
throws:  Bs_Exception with BS_DB_ERROR_NEED_MORE_DATA if no $dbName available, Bs_Exception otherwise.
access:  public


Parameters:

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

[ Top ]

method getTableType [line 1950]

string getTableType( string $tblName, [string $dbName = NULL])

Returns the table type of the specified db table.



Tags:

return:  the table type, currently one of 'MyISAM', 'ISAM', 'MERGE', 'HEAP', 'BDB', 'INNOBASE', 'GEMINI'
see:  Bs_MySql::tableHasTransactions(), Bs_MySql::getTableInfo(), Bs_MySql::serverSupportsTableType()
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   a db name, default is NULL which means use the current one.

[ Top ]

method hasFieldFlag [line 810]

boolean hasFieldFlag( resource $result, int $offset, string $flag)

Tells whether the field has the given flag. The field is specified by offset in a result id.

This method uses $this->fieldFlags() to get the data. Check it's documentation!




Tags:

see:  Bs_MySql::fieldFlags()
throws:  Bs_Exception with BS_DB_ERROR_INVALID_RS on an invalid $result param, NULL if the flag is not known. maybe not supported in this mysql version...
access:  public


Parameters:

resource   $result   a result identifier.
int   $offset   fieled offset in result beginning with 0.
string   $flag   the flag name.

[ Top ]

method insertId [line 624]

int insertId( )

Returns the ID generated for an AUTO_INCREMENT column by the previous INSERT query on this thread.

Returns 0 if the previous query does not generate an AUTO_INCREMENT value If you need to save the value for later, be sure to call this function immediately after the query that generates the value. This method is save, thanks to rick@surveyor.com for the information :)

NOTE I : RTFM for mysql_insert_id()! There are some spcial cases! NOTE II: Returns FALSE if you use "INSERT DELAYED ..." I heared ppl complaining that recent versions only work if link_identifier is omitted.




Tags:

return:  A value>=1 (the ID) or 0 (no AUTO_INCREMENT value given) or FLASE (see above)
throws:  Bs_Exception if mysql_insert_id() return an int >=1.
access:  public


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

[ Top ]

method isReservedWord [line 2488]

int isReservedWord( string $word)

Tells if a word is a reserved word for mysql.

This is a 'shortcut' for => "7.39 Is MySQL Picky About 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.

From the manual: A common problem stems from trying to create a table with column names that use the names of datatypes or functions built into MySQL, such as TIMESTAMP or GROUP. You're allowed to do it (for example, ABS is an allowed column name), but whitespace is not allowed between a function name and the `(' when using functions whose names are also column names. The following words are explicitly reserved in MySQL. Most of them are forbidden by ANSI SQL92 as column and/or table names (for example, group). A few are reserved because MySQL needs them and is (currently) using a yacc parser:




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:  Bs_MySql::isValidName()
static:  
access:  public


Parameters:

string   $word   the word you want to check

[ Top ]

method isValidName [line 2458]

true isValidName( string $string)

Tells if a name for a db, table or field is accepted by mysql 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 listDatabases [line 871]

resource listDatabases( )

returns a result identifier for the available databases.

note: with mysql you see all db's even if you have no access to them. that may be different in other rdbms. this is a wrapper for mysql_list_dbs().




Tags:

return:  A result identifier.
see:  Bs_MySql::fetchDatabaseNames(), Bs_MySql::listFields(), Bs_MySql::listTables()
throws:  Bs_Exception if mysql_list_dbs() failed somehow.
access:  public


[ Top ]

method listFields [line 909]

resource listFields( string $tableName, [mixed $dbName = NULL], string $dbName.)

Retrieves information about the given tablename.

This is a wrapper for mysql_list_fields(). NOTE: Fields may exist but if you don't have the perms, you won't see them!




Tags:

return:  A result identifier.
see:  Bs_MySql::fetchFieldNames(), Bs_MySql::listTables(), Bs_MySql::listDatabases()
throws:  Bs_Exception with BS_DB_ERROR_NEED_MORE_DATA if no $dbName available, Bs_Exception if mysql_list_fields() failed somehow.
access:  public


Parameters:

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

[ Top ]

method listTables [line 888]

resource listTables( [mixed $dbName = NULL], string $dbName.)

Retrieves information about the given table. (does it? is that text correct? --andrej) This is a wrapper for mysql_list_tables().

NOTE: Tables may exist but if you don't have the perms, you won't see them!




Tags:

return:  A result identifier.
see:  Bs_MySql::fetchTableNames(), Bs_MySql::listFields(), Bs_MySql::listDatabases()
throws:  Bs_Exception with BS_DB_ERROR_NEED_MORE_DATA if no $dbName available, Bs_Exception if mysql_list_tables() failed somehow.
access:  public


Parameters:

string   $dbName.   If empty (e.g: '' or NULL or 0) then use the current dbName.

[ Top ]

method nativeError [line 2604]

string &nativeError( )

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



Tags:

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


[ Top ]

method nativeErrorCode [line 2576]

int nativeErrorCode( )

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

This method is a wrapper for mysql_errno().




Tags:

return:  native MySQL error code
see:  Bs_MySql::nativeErrorMsg(), Bs_MySql::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 2591]

string &nativeErrorMsg( )

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

This method is a wrapper for mysql_error(). HINT: Better use nativeErrorCode() before calling this method, or call nativeError() directly.




Tags:

return:  native MySQL error message
see:  Bs_MySql::nativeErrorCode(), Bs_MySql::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 554]

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 mysql_num_fields() failed somehow
access:  public


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

Parameters:

$result   $result   MySQL result identifier

[ Top ]

method numRows [line 572]

int numRows( $result $result)

Get the number of rows from a result set.



Tags:

return:  the number of rows in $result
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 rollback [line 304]

bool rollback( [$transactionId $transactionId = ''])

Rollback last query



Tags:

return:  TRUE on success.
see:  Bs_MySql::startTransaction()
throws:  Bs_Exception if not supported by this DB or on any other error.
access:  public


Overrides Bs_Db::rollback() (Rollback last query)

Parameters:

$transactionId   $transactionId   string (opt). See $this->startTransaction.

[ Top ]

method selectDb [line 409]

bool selectDb( string $db)

Select a MySQL database.

this is a wrapper for mysql_select_db().




Tags:

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


Parameters:

string   $db   a database name.

[ Top ]

method serverSupportsTableType [line 2004]

bool serverSupportsTableType( string $tableType)

Tells whether the given table type is supported by the server or not.

NOTE: 'MyISAM', 'MERGE' and 'HEAP' are always supported. But if you still check for them, of course TRUE is returned.

The default mysql table type currently is MyISAM according to the manual. If you try to create one that's not supported or not compiled into the server, a MyISAM table will be created instead. ISAM is deprecated, it is replaced by MyISAM. BDB, INNOBASE and GEMINI are transaction-safe, the others are not. hrm. i've found an ini var called 'table_type' with the value 'MYISAM'. Prolly you can change the default table type here.




Tags:

return:  true if the table type is supported, false otherwise.
see:  Bs_MySql::getTableType(), Bs_MySql::tableHasTransactions(), Bs_MySql::getTableInfo()
throws:  NULL if the given table type is not recognized, Bs_Exception otherwise.
access:  public


Parameters:

string   $tableType   one of 'MyISAM', 'ISAM', 'MERGE', 'HEAP', 'BDB', 'INNOBASE', 'GEMINI' (case doesn't matter).

[ Top ]

method setPointer [line 2435]

mixed setPointer( $result $result, int $absolutPos)

Sets the internal row pointer of the result id to point to the specified row number.

The next fetch call would return that row.




Tags:

return:  TRUE on success, NULL on a row number (param $absolutPos) that is out of bounds.
throws:  Bs_Exception on error.
access:  public


Overrides Bs_Db::setPointer() (Set the internal row pointer of the result id to point to the specified row number.)

Parameters:

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

[ Top ]

method startTransaction [line 269]

bool startTransaction( [$transactionId $transactionId = ''])

Starts a transaction As optional parameter you can pass a transaction ID.

When working with transactions, I run often in the situation, that I have a 'Master' routine calling other sub-routines and some sub-routines start their own transation. Multiple transaction 'starts' don't bother the Db, the transaction just stays open *BUT* the first to call commit or rollback will terminate the transaction! To prevent sub-routines from closing the 'Masters' transaction you may start a transaction and pass a 'transaction ID'. Folloing commits/rollbacks are ignored as long as it dosen't match the 'transaction ID' given at start. NOTE I: Be aware of the highter deadlocking risk, when using 'transaction ID'. NOTE II: Make sure that you end the open transaction when using 'transaction ID'. Otherwise the transaction will *stay open*.




Tags:

return:  TRUE on success.
throws:  Bs_Exception if not supported by this DB or on any other error.
access:  public


Overrides Bs_Db::startTransaction() (Starts a transaction)

Parameters:

$transactionId   $transactionId   string (opt). See text above.

[ Top ]

method subSelect [line 465]

int subSelect( string $queryWithSubquery)

Handles a single nested SELECT statement to overcome that limitation in MySql as it isn't suported (yet).

E.g. SELECT q,r,t FROM x WHERE y IN (SELECT ID FROM z WHERE ...) ORDER BY xxx; DELETE FROM x WHERE y IN (SELECT ID FROM z WHERE ...);

NOTE I : The sub-select will only use the first colomn in the subselect !! To minimise the overhead, just fetch the 1 colomn in the subselect. NOTE II : The sub-select must be in parenthe and no parenthe may be used *in* the sub-select.

MySql V3.23 states in 5.4.1 Sub-selects: "For more complicated subqueries you can often create temporary tables to hold the subquery. In some cases, *however* this option will not work. The most frequently encountered of these cases arises with DELETE statements, for which standard SQL does not support joins (except in sub-selects). For this situation there are two options available until subqueries are supported by MySQL. The first option is to use a procedural programming language (such as Perl or PHP) to submit a SELECT query to obtain the primary keys for the records to be deleted, and then use these values to construct the DELETE statement (DELETE FROM ... WHERE ... IN (key1, key2, ...))."




Tags:

return:  a valid MySQL result id
throws:  Bs_Exception on error
access:  public


Parameters:

string   $queryWithSubquery   the SQL query with sub-query

[ Top ]

method tableExists [line 1222]

bool tableExists( mixed $lookups, [mixed $dbName = NULL], [bool $useCache = TRUE], string $dbName.)

Tells whether the db table (or tables) exist or not.

NOTE I: Databases and tables are file-based in mysql. So they are case sensitive on iX, *but* INsensitive on winblows. So for windows we have to do a case insensitive check.

NOTE II: This method makes use of fetchTableNames(). So if param $useCache is set to TRUE and fetchTableNames() has been called before, the cached values will be used.




Tags:

return:  true if all tables exist, false if at least one doesn't.
see:  Bs_MySql::fieldExists(), Bs_MySql::databaseExists()
throws:  Bs_Exception with BS_DB_ERROR_NEED_MORE_DATA if no $dbName available, Bs_Exception otherwise.
access:  public


Parameters:

mixed   $lookups   a db table name as a string, or an array with db table names.
string   $dbName.   If empty (e.g: '' or NULL or 0) then use the current dbName.
bool   $useCache   default is TRUE. see note II.

[ Top ]

method tableHasTransactions [line 1968]

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



Tags:

return:  true if table supports transactions, false otherwise.
see:  Bs_MySql::getTableType(), Bs_MySql::getTableInfo()
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   a db name, default is NULL which means use the current one.

[ Top ]

method tableName [line 670]

string tableName( resource $result, int $offset)

Returns the name of the table that the field (specifed by an offset) is in.

This is a wrapper for mysql_field_table().




Tags:

return:  the table name
see:  Bs_MySql::fieldName(), Bs_MySql::databaseName(), Bs_MySql::listTables(), Bs_MySql::fetchTableNames()
throws:  Bs_Exception with BS_DB_ERROR_INVALID_RS on an invalid $result param, Bs_Exception on a field index that doesn't exist or any other error.
access:  public


Parameters:

resource   $result   a result identifier.
int   $offset   fieled offset in result beginning with 0.

[ Top ]

method tableName2 [line 689]

string tableName2( resource $result, int $offset)

Get the name of the specified table in a result you got from mysql_list_tables().

This is a wrapper for mysql_tablename().




Tags:

return:  the table name
see:  Bs_MySql::fieldName(), Bs_MySql::tableName(), Bs_MySql::databaseName(), Bs_MySql::listTables(), Bs_MySql::fetchTableNames()
throws:  bs_exception with BS_DB_ERROR_INVALID_RS on an invalid $result param, bs_exception on a field index that doesn't exist or any other error.
access:  public


Parameters:

resource   $result   a result identifier you got from mysql_list_tables(), no other result!!
int   $offset   fieled offset in result beginning with 0.

[ Top ]

method updateTableStructure [line 1487]

bool updateTableStructure( array $structure, string $tblName, [mixed $dbName = NULL], string $dbName.)

updates an existing db table to the desired structure.

Idea of a param $shrink: *NOT IMPLEMENTED (YET?)* if we should 'shrink' the table in any way.

  1. = no
  2. = make fields smaller if needed
  3. = remove fields if needed
  4. = remove indexes
your user needs alter (maybe create, index, ...) rights to change the structure.




Tags:

return:  (TRUE if changes have/had to be made, FALSE otherwise.)
todo:  code is not done, see yourself. currently only adds fields. maybe we should also create the table if it does not exist at all.
throws:  bs_exception (on the first error, does not continue.)
access:  public


Parameters:

array   $structure   (like the return value of getTableStructure() so look there.)
string   $tblName   a table name
string   $dbName.   If empty (e.g: '' or NULL) then use the current dbName.

[ Top ]

method _dbErrorToBsError [line 2662]

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.
static:  
access:  public


Parameters:

int   $dbError  

[ Top ]


Documentation generated on Mon, 29 Dec 2003 21:11:56 +0100 by phpDocumentor 1.2.3