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

Class: Bs_MsSql

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

Class Overview

Bs_Object
   |
   --Bs_Db
      |
      --Bs_MsSql

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


Author(s):

Version:

  • 4.3.$Revision: 1.1.1.1 $ $Date: 2003/07/04 14:04:37 $

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

A good understanding of the built in MSSQL 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.

known problems/bugs: 1) 2002-02-27 --andrej SYSTEM CONFIG: php running on the local workstation, connecting to the in-house sql-server. workstation: os : winnt 2000 pro (workstation) build 2195 php : version 4.1.1 php_mssql.dll : 44kb (45056 bytes) mssql: sql server enterprise manager (version unknown) server: os : winnt 2000 server mssql : mssql 2000 i think. PROBLEM: i was connecting using php code to the sql server. everything worked fine. then after issueing the query "SELECT name FROM master.dbo.sysdatabases ORDER BY name" it would not connect anymore. actually i think it was already short before doing this one, i cannot tell anymore. so i dunno if it matters. i went into the the sql server enterprise manager, and was able to re-connect using exactly the same dsn-info. so the sql server was fine. what helped was restarting apache. crap.

########################################################################### see http://www.php.net/manual/en/function.mssql-connect.php for all this and much more... --------------------------------------------------------------------------- Remember, you must build Linux/Unix PHP with Sybase support in order to get MSSQL support. ./configure --with-sybase=/opt/sybase-11.9.2/ For Linux, you can get the required "Adaptive Server Enterprise" Sybase RPMs from http://www.sybase.com/products/databaseservers/linux/

You should then put any MSSQL database you want to connect to in the /opt/sybase-11.9.2/interfaces file, in the format EXAMPLE_Host query tcp ether IP_OR_FQDN PORTNUMBER Where PORTNUMBER is usually (but not always) 1433

In your code, refer to the EXAMPLE_Host in your connect string like this; mssql_connect("EXAMPLE_Hostname","username","Password") or die("Connection error"); --------------------------------------------------------------------------- --------------------------------------------------------------------------- --------------------------------------------------------------------------- ###########################################################################

 Quick overview of the features of MSSQL

    ----------------------+------------------------------------------------------------------------
    available             | comments
    ----------------------+------------------------------------------------------------------------
    transactions          | none
    fulltext indexing     | none
    subselects            | none
    stored procedures     | none
    triggers              | none
    foreign keys          | none
    views                 | none
    ----------------------+------------------------------------------------------------------------
    not available         | comments
    ----------------------+------------------------------------------------------------------------
    '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 MSSQL functions are *NOT* implemented here because we don't want you to use them:

  • mssql_fetch_object() => Use fetchRow() which makes use of mysql_fetch_assoc() or mysql_fetch_row()
  • mssql_fetch_array() => Use fetchRow() which makes use of mysql_fetch_assoc() or mysql_fetch_row()
  • mssql_result() => as you can reas in the manual, this function is not really recommended. also see the MySql implementation. Also see Bs_Db->getOne()




Tags:

version:  4.3.$Revision: 1.1.1.1 $ $Date: 2003/07/04 14:04:37 $
copyright:  blueshoes.org
author:  andrej arn <at blueshoes dot org>
todo:  his class is accurate for MsSQL __version__.
  • please check the following methods to be up to date:
    2do > fieldFlags(), hasFieldFlag(), fieldType(), getTableProperties(), getTableInfo(), getTableType(),
    2do > getIniVar(), getStatusVar() Make sure the existing code doesn't break because of your changes! thanx.
  • recode some functions more down the file for mssql (taken from mysql).
  • code the transaction stuff
  • implement the stored procedures functionality.
  • i wonder if we should move more logic into bs_db.class (that is the same in the mssql and mysql implementation). i don't want to copy the same code blocks over and over again for every db vendor. but then how many impl. will we write?
dependencies: Bs_Db


[ Top ]


Class Variables

$_currentlyOpenTransactionID =  ''

[line 189]

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



Tags:

see:  $this->startTransaction.

Type:   mixed


[ Top ]



Class Methods


constructor Bs_MsSql [line 195]

Bs_MsSql Bs_MsSql( )

Constructor.



[ Top ]

method affectedRows [line 556]

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 none affected
throws:  Bs_Exception if mssql_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 234]

last autoCommit( [bool $on = FALSE])

Turn autoCommit on or off



Tags:

return:  state: TRUE if it was on; FALSE if it was off.
todo:  rewrite code for mssql.
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 272]

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

Commit the current or given transaction.



Tags:

return:  on success.
todo:  rewrite code for mssql.
see:  $this->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 323]

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 databaseExists [line 1255]

bool databaseExists( mixed $dbName, [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, except 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.
todo:  rewrite code for mssql.
see:  Bs_MsSql::fieldExists(), Bs_MsSql::tableExists()
throws:  Bs_Exception
access:  public


Parameters:

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

[ Top ]

method databaseName [line 671]

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
todo:  rewrite code for mssql.
see:  Bs_MsSql::fieldName(), Bs_MsSql::tableName(), Bs_MsSql::listDatabases(), Bs_MsSql::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 390]

bool disconnect( )

Log out and disconnect from the database.

Note: mssql_close() will not close persistent links (created by mssql_pconnect()).




Tags:

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


[ Top ]

method escapeString [line 1921]

string escapeString( string $query)

Escape string for mssql query.

This method overwrites its parent method because stupid mssql wants non-standard escaping.




Tags:

return:  the escaped query string
todo:  check if that really works. and what about \n etc? see http://www.zend.com/codex.php?id=204&single=1


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

Parameters:

string   $query   (the sql query param you want to have escaped.)

[ Top ]

method fetchDatabaseNames [line 921]

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

Returns 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_MsSql::listDatabases(), Bs_MsSql::fetchFieldNames(), Bs_MsSql::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 1106]

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 mssql_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 mssql_fetch_field().




Tags:

throws:  Bs_Exception with BS_DB_ERROR_INVALID_RS on an invalid $result param, Bs_Exception if mssql_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 1010]

&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 may not see them! (that's how mysql is built, not sure about mssql.)

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)
todo:  rewrite code for mssql.
see:  Bs_MsSql::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 484]

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

[ Top ]

method fetchTableNames [line 962]

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_MsSql::fetchFieldNames(), fetchDbNames(), Bs_MsSql::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 1140]

bool fieldExists( mixed $fieldName, 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.
todo:  rewrite code for mssql.
see:  Bs_MsSql::tableExists(), Bs_MsSql::databaseExists()
throws:  Bs_Exception with BS_DB_ERROR_NEED_MORE_DATA if no $dbName available, Bs_Exception otherwise.
access:  public


Parameters:

mixed   $fieldName   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 725]

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.
todo:  rewrite code for mssql.
see:  $this->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 691]

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.
todo:  rewrite code for mssql.
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 609]

string fieldName( resource $result, int $offset)

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

This is a wrapper for mssql_field_name().




Tags:

return:  the field name
see:  Bs_MsSql::tableName(), Bs_MsSql::databaseName(), Bs_MsSql::listFields(), Bs_MsSql::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 mssql_list_fields() OR another result.
int   $offset   fieled offset in result beginning with 0.

[ Top ]

method fieldType [line 820]

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 mssql_field_type().

-------------------------------------------------------------------------- CAUTION: mysql used to return wrong names. maybe mssql does the same? please verify. (from mysql:) +----------------------------+ | mysql type | returned as |

  • ------------+--------------+
| tinyint | int | // php4.0.4pl1 used to return unknown. Corrected in php4.0.5 | smallint | int | | mediumint | int | | int | int | | bigint | int | | float | real | | double | real | | decimal | real | | date | date | | datetime | datetime | | timestamp | timestamp | | year | year | // php4.0.4pl1 used to return unknown. Corrected in php4.0.5 | char | string | | varchar | string | | tinyblob | blob | | blob | blob | | mediumblob | blob | | longblob | blob | | enum | string | | set | string | +----------------------------+ --------------------------------------------------------------------------




Tags:

todo:  check documentation above and the return values. maybe test a view.
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 594]

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)
access:  public


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

Parameters:

$result   $result   MsSQL result identifier or DB statement identifier

[ Top ]

method getClientInfo [line 1865]

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:  rewrite code for mssql.
todo:  code and test this as soon as php405 is out.
since:  php405


[ Top ]

method getDbStructure [line 1068]

hash &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:  a 2-D hash of table names contaioning a vector of fields. See above.
todo:  rewrite code for mssql.
see:  Bs_MsSql::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 1879]

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:  rewrite code for mssql.
todo:  code and test this as soon as php405 is out.
since:  php405
access:  public


[ Top ]

method getIniVar [line 1746]

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):

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.
todo:  rewrite code for mssql.
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 1593]

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)
todo:  rewrite code for mssql.
see:  Bs_MsSql::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 1893]

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:  rewrite code for mssql.
todo:  code and test this as soon as php405 is out.
since:  php405
access:  public


[ Top ]

method getServerInfo [line 1907]

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:  rewrite code for mssql.
todo:  code and test this as soon as php405 is out.
since:  php405
access:  public


[ Top ]

method getStatusVar [line 1837]

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):

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.
todo:  rewrite code for mssql.
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 1329]

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

Returns an 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.
todo:  rewrite code for mssql.
see:  Bs_MsSql::tableHasTransactions(), Bs_MsSql::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 or 0) then use the current dbName.

[ Top ]

method getTableType [line 1453]

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'
todo:  rewrite code for mssql.
see:  Bs_MsSql::tableHasTransactions(), Bs_MsSql::getTableInfo(), Bs_MsSql::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 773]

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:

todo:  rewrite code for mssql.
see:  $this->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 579]

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 :)




Tags:

return:  A value>=1 (the ID) or 0 (no AUTO_INCREMENT value given) or FLASE (see above)
todo:  decide about return value 0/false/null/exception.
access:  public


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

[ Top ]

method isReservedWord [line 1991]

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.
todo:  rewrite code for mssql.
see:  $this->isValidName()


Parameters:

string   $word   the word you want to check

[ Top ]

method isValidName [line 1961]

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:  rewrite code for mssql.
todo:  add regexp for syntax check.
see:  $this->isReservedWord()
access:  public


Parameters:

string   $string  

[ Top ]

method listDatabases [line 839]

resource listDatabases( )

returns a result identifier for the available databases.

note I: with mssql you see all db's even if you have no access to them. that may be different in other rdbms.




Tags:

return:  A result identifier.
todo:  test this code.
see:  Bs_MsSql::fetchDatabaseNames(), Bs_MsSql::listFields(), Bs_MsSql::listTables()
throws:  Bs_Exception.
access:  public


[ Top ]

method listFields [line 889]

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.
todo:  rewrite code for mssql.
see:  Bs_MsSql::fetchFieldNames(), Bs_MsSql::listTables(), Bs_MsSql::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 860]

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

returns a result identifier for the available tables in the given database.

note I: tables may exist but if you don't have the perms, you won't see them! note II: only 'U'ser tables will be listed. no 'S'ystem stuff.




Tags:

return:  A result identifier.
see:  Bs_MsSql::fetchTableNames(), Bs_MsSql::listFields(), Bs_MsSql::listDatabases()
throws:  Bs_Exception with BS_DB_ERROR_NEED_MORE_DATA if no $dbName available, Bs_Exception if something fails.
access:  public


Parameters:

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

[ Top ]

method nativeError [line 2075]

string nativeError( )

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

This method is a wrapper for mysql_error().




Tags:

return:  native MySQL error code and message like "code:text"
see:  Bs_Db::nativeErrorCode(), Bs_MsSql::nativeErrorMsg()
access:  public


[ Top ]

method nativeErrorMsg [line 2061]

string nativeErrorMsg( )

Returns the native error text from the previous MsSQL operation or '' (empty string) if no error occured or the error was below the min_message_severity.

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




Tags:

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

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


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

Parameters:

$result   $result   MsSQL result identifier

[ Top ]

method numRows [line 531]

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


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

Parameters:

$result   $result   MsSQL result identifier

[ Top ]

method rollback [line 293]

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

Rollback last query



Tags:

return:  on success.
todo:  rewrite code for mssql.
see:  $this->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 432]

bool selectDb( string $db)

Select a MsSQL database.

this is a wrapper for mssql_select_db().




Tags:

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


Parameters:

string   $db   a database name.

[ Top ]

method serverSupportsTableType [line 1509]

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 there.




Tags:

return:  true if the table type is supported, false otherwise.
todo:  rewrite code for mssql.
see:  Bs_MsSql::getTableType(), Bs_MsSql::tableHasTransactions(), Bs_MsSql::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 1937]

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

TRUE 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:  on success.
todo:  rewrite code for mssql.
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 tableExists [line 1188]

bool tableExists( mixed $tableName, [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, except 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.
todo:  rewrite code for mssql.
see:  Bs_MsSql::fieldExists(), Bs_MsSql::databaseExists()
throws:  Bs_Exception with BS_DB_ERROR_NEED_MORE_DATA if no $dbName available, Bs_Exception otherwise.
access:  public


Parameters:

mixed   $tableName   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 1472]

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



Tags:

return:  true if table supports transactions, false otherwise.
todo:  rewrite code for mssql.
see:  Bs_MsSql::getTableType(), Bs_MsSql::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 628]

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
todo:  rewrite code for mssql.
see:  Bs_MsSql::fieldName(), Bs_MsSql::databaseName(), Bs_MsSql::listTables(), Bs_MsSql::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 648]

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
todo:  rewrite code for mssql.
see:  Bs_MsSql::fieldName(), Bs_MsSql::tableName(), Bs_MsSql::databaseName(), Bs_MsSql::listTables(), Bs_MsSql::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 _dbErrorToBsError [line 2140]

mixed _dbErrorToBsError( int $dbError)

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

the way mssql is built it is hard to map our universal db errors to the mssql ones. there are so many... and i cannot find a complete list. maybe we should work with the severity only... but even the manual for that is bad imo.




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:11:50 +0100 by phpDocumentor 1.2.3