CWIS Developer Documentation
List of all members
Database Class Reference

SQL database abstraction object with smart query caching. More...

Inheritance diagram for Database:
Inheritance graph
[legend]

Setup/Initialization

 Database ($UserName=NULL, $Password=NULL, $DatabaseName=NULL, $HostName=NULL)
 Object constructor.
 
 __sleep ()
 
 
 __wakeup ()
 Restore database connection when unserialized.
 
 DBHostName ()
 Get host name of system on which database server resides.
 
 DBName ()
 Get current database name.
 
 DBUserName ()
 Get name used to connect with database server.
 
 SetQueryErrorsToIgnore ($ErrorsToIgnore)
 Set query errors to ignore.
 
static SetGlobalServerInfo ($UserName, $Password, $HostName="localhost")
 
 
static SetGlobalDatabaseName ($DatabaseName)
 Set default database name.
 
static Caching ($NewSetting=NULL)
 Get or set whether query result caching is currently enabled.
 
static AdvancedCaching ($NewSetting=NULL)
 Get or set whether advanced query result cachine is currently enabled.
 

Data Manipulation

 Query ($QueryString, $FieldName="")
 Query database (with caching if enabled).
 
 QueryErrMsg ()
 Get most recent error message text set by Query().
 
 QueryErrNo ()
 Get most recent error code set by Query().
 
 NumRowsSelected ()
 Get number of rows returned by last query.
 
 FetchRow ()
 Get next database row retrieved by most recent query.
 
 FetchRows ($NumberOfRows=NULL)
 Get specified number of database rows retrieved by most recent query.
 
 FetchColumn ($FieldName, $IndexFieldName=NULL)
 Get all available values for specified database field retrieved by most recent query.
 
 FetchField ($FieldName)
 Pull next row from last DB query and get a specific value from that row.
 
 LastInsertId ($TableName)
 Get ID of row added by the last SQL "INSERT" statement.
 
 UpdateValue ($TableName, $FieldName, $NewValue, $Condition, &$CachedRecord)
 A convenience function to get or set a value in the database.
 
 UpdateIntValue ($TableName, $FieldName, $NewValue, $Condition, &$CachedRecord)
 A convenience function to get or set an integer value in the database.
 
 UpdateFloatValue ($TableName, $FieldName, $NewValue, $Condition, &$CachedRecord)
 A convenience function to get or set a float value in the database.
 
static DisplayQueryErrors ($NewValue=NULL)
 Get/set whether Query() errors will be displayed.
 

Miscellaneous

 $DBUserName
 
 $DBPassword
 
 $DBHostName
 
 $DBName
 
 LogComment ($String)
 Peform query that consists of SQL comment statement.
 
 FieldExists ($TableName, $FieldName)
 Get whether specified field exists in specified table.
 
static QueryDebugOutput ($NewSetting)
 Enable or disable debugging output for queries.
 
static NumQueries ()
 Get the number of queries that have been run since program execution began.
 
static NumCacheHits ()
 Get the number of queries that have resulted in cache hits since program execution began.
 
static CacheHitRate ()
 Get the ratio of query cache hits to queries as a percentage.
 

Detailed Description

SQL database abstraction object with smart query caching.

Definition at line 22 of file Axis--Database.php.

Member Function Documentation

Database::__sleep ( )

Specify variables to be saved when serialized.

Definition at line 80 of file Axis--Database.php.

Database::__wakeup ( )

Restore database connection when unserialized.

Definition at line 87 of file Axis--Database.php.

References DBHostName(), DBName(), and DBUserName().

static Database::AdvancedCaching (   $NewSetting = NULL)
static

Get or set whether advanced query result cachine is currently enabled.

Advanced caching attempts to determine whether a query has modified any of the referenced tables since the data was last cached. Advanced caching is disabled by default. This setting applies to all instances of the Database class.

Parameters
NewSettingTRUE to enable advanced caching or FALSE to disable. (OPTIONAL)
Returns
Current advanced caching setting.

Definition at line 184 of file Axis--Database.php.

static Database::CacheHitRate ( )
static

Get the ratio of query cache hits to queries as a percentage.

The value returned is for all instances of the Database class.

Returns
Percentage of queries that resulted in hits.

Definition at line 702 of file Axis--Database.php.

static Database::Caching (   $NewSetting = NULL)
static

Get or set whether query result caching is currently enabled.

Caching is enabled by default. This setting applies to all instances of the Database class.

Parameters
NewSettingTRUE to enable caching or FALSE to disable. (OPTIONAL)
Returns
Current caching setting.

Definition at line 159 of file Axis--Database.php.

Database::Database (   $UserName = NULL,
  $Password = NULL,
  $DatabaseName = NULL,
  $HostName = NULL 
)

Object constructor.

If user name, password, or database name are omitted they must have been set earlier with SetGlobalServerInfo() and SetGlobalDatabaseName().

Parameters
UserNameUser name to use to log in to database server. (OPTIONAL)
PasswordPassword to use to log in to database server. (OPTIONAL)
DatabaseNameName of database to use once logged in. (OPTIONAL)
HostNameHost name of system on which database server resides. (OPTIONAL, defaults to "localhost")
See Also
SetGlobalServerInfo()
SetGlobalDatabaseName()

Definition at line 40 of file Axis--Database.php.

References $DBName, DBHostName(), DBName(), and DBUserName().

Referenced by SPTDatabase\SPTDatabase().

Here is the caller graph for this function:

Database::DBHostName ( )

Get host name of system on which database server resides.

Returns
Host name of database server.
See Also
SetGlobalServerInfo()

Definition at line 136 of file Axis--Database.php.

References $DBHostName.

Referenced by __wakeup(), and Database().

Here is the caller graph for this function:

Database::DBName ( )

Get current database name.

Returns
Database name.
See Also
SetGlobalDatabaseName()

Definition at line 143 of file Axis--Database.php.

References $DBName.

Referenced by __wakeup(), and Database().

Here is the caller graph for this function:

Database::DBUserName ( )

Get name used to connect with database server.

Returns
Login name.
See Also
SetGlobalServerInfo()

Definition at line 150 of file Axis--Database.php.

References $DBUserName.

Referenced by __wakeup(), and Database().

Here is the caller graph for this function:

static Database::DisplayQueryErrors (   $NewValue = NULL)
static

Get/set whether Query() errors will be displayed.

By default errors are not displayed.

Parameters
NewValueTRUE to display errors or FALSE to not display. (OPTIONAL)
Returns
Current value of whether Query() errors will be displayed.

Definition at line 398 of file Axis--Database.php.

Referenced by MetadataFieldOrder\GetRowsForUpgrade().

Here is the caller graph for this function:

Database::FetchColumn (   $FieldName,
  $IndexFieldName = NULL 
)

Get all available values for specified database field retrieved by most recent query.

If a second database field name is specified then the array returned will be indexed by the values from that field. If all index field values are not unique then some values will be overwritten.

A common use for this method is to retrieve a set of values with an ID field specified for the index:
$CNames = $DB->FetchColumn("ControlledName", "ControlledNameId");

Parameters
FieldNameName of database field.
IndexFieldNameName of second database field to use for array index. (OPTIONAL)
Returns
Array of values from specified field, indexed numerically. If IndexFieldName is supplied then array will be indexed by corresponding values from that field.

Definition at line 508 of file Axis--Database.php.

References FetchRow().

Database::FetchField (   $FieldName)

Pull next row from last DB query and get a specific value from that row.

This is a convenience method that in effect combines a FetchRow() with getting a value from the array returned. This method does advance the pointer to the next row returned by the query each time it is called.

Parameters
FieldNameName of field.
Returns
Value from specified field.

Definition at line 533 of file Axis--Database.php.

References FetchRow().

Referenced by FieldExists(), and Query().

Here is the caller graph for this function:

Database::FetchRow ( )

Get next database row retrieved by most recent query.

Returns
Array of database values with field names for indexes. Returns FALSE if no more rows are available.

Definition at line 433 of file Axis--Database.php.

Referenced by MysqlSystemVariables\__construct(), FetchColumn(), FetchField(), FetchRows(), and UpdateValue().

Here is the caller graph for this function:

Database::FetchRows (   $NumberOfRows = NULL)

Get specified number of database rows retrieved by most recent query.

Parameters
NumberOfRowsMaximum number of rows to return. (OPTIONAL – if not specified then all available rows are returned)
Returns
Array of rows. Each row is an associative array indexed by field name.

Definition at line 477 of file Axis--Database.php.

References FetchRow().

Database::FieldExists (   $TableName,
  $FieldName 
)

Get whether specified field exists in specified table.

Parameters
TableNameName of database table.
FieldNameName of database field.
Returns
TRUE if table and field exist, or FALSE otherwise.

Definition at line 656 of file Axis--Database.php.

References FetchField(), and Query().

Database::LastInsertId (   $TableName)

Get ID of row added by the last SQL "INSERT" statement.

It should be called immediately after the INSERT statement query. This method uses the SQL "LAST_INSERT_ID()" function.

Parameters
TableNameName of SQL table into which row was inserted.
Returns
Numerical ID value.

Definition at line 546 of file Axis--Database.php.

References Query().

Database::LogComment (   $String)

Peform query that consists of SQL comment statement.

This is used primarily when query debug output is turned on, to insert additional information into the query stream.

Parameters
StringDebug string.

Definition at line 645 of file Axis--Database.php.

References Query().

static Database::NumCacheHits ( )
static

Get the number of queries that have resulted in cache hits since program execution began.

The value returned is for all instances of the Database class.

Returns
Number of queries that resulted in cache hits.

Definition at line 692 of file Axis--Database.php.

static Database::NumQueries ( )
static

Get the number of queries that have been run since program execution began.

The value returned is for all instances of the Database class.

Returns
Number of queries.

Definition at line 681 of file Axis--Database.php.

Database::NumRowsSelected ( )

Get number of rows returned by last query.

Returns
Number of database rows selected by last query.

Definition at line 408 of file Axis--Database.php.

Database::Query (   $QueryString,
  $FieldName = "" 
)

Query database (with caching if enabled).

Parameters
QueryStringSQL query string.
FieldNameName of field for which to return value to caller. (OPTIONAL)
Returns
Query handle, retrieved value (if FieldName supplied), or FALSE on error.

Definition at line 221 of file Axis--Database.php.

References FetchField().

Referenced by MysqlSystemVariables\__construct(), FieldExists(), LastInsertId(), LogComment(), and UpdateValue().

Here is the caller graph for this function:

static Database::QueryDebugOutput (   $NewSetting)
static

Enable or disable debugging output for queries.

Output is disabled by default. This setting applies to all instances of the Database class.

Parameters
NewSettingTRUE to enable output or FALSE to disable output.

Definition at line 671 of file Axis--Database.php.

Database::QueryErrMsg ( )

Get most recent error message text set by Query().

Returns
Error message text from database server.
See Also
QueryErrNo()

Definition at line 377 of file Axis--Database.php.

Database::QueryErrNo ( )

Get most recent error code set by Query().

Returns
Error code from database server.
See Also
QueryErrMsg()

Definition at line 387 of file Axis--Database.php.

static Database::SetGlobalDatabaseName (   $DatabaseName)
static

Set default database name.

Parameters
DatabaseNameName of database to use once logged in.

Definition at line 122 of file Axis--Database.php.

static Database::SetGlobalServerInfo (   $UserName,
  $Password,
  $HostName = "localhost" 
)
static

Set default login and host info for database server.

Parameters
UserNameUser name to use to log in to database server.
PasswordPassword to use to log in to database server.
HostNameHost name of system on which database server resides. (OPTIONAL, defaults to "localhost")

Definition at line 107 of file Axis--Database.php.

Database::SetQueryErrorsToIgnore (   $ErrorsToIgnore)

Set query errors to ignore.

The command and error message patterns should be formatted for preg_match(). For example:

$SqlErrorsWeCanIgnore = array(
"/ALTER TABLE [a-z]+ ADD COLUMN/i" => "/Duplicate column name/i",
"/CREATE TABLE /i" => "/Table '[a-z0-9_]+' already exists/i",
);
Parameters
ErrorsToIgnoreAssociative array containing errors to ignore when running queries, with patterns for SQL commands as the indexes and the patterns for the SQL error messages as the values. Pass in NULL to clear list of errors to ignore.

Definition at line 207 of file Axis--Database.php.

Database::UpdateFloatValue (   $TableName,
  $FieldName,
  $NewValue,
  $Condition,
$CachedRecord 
)

A convenience function to get or set a float value in the database.

This will typically be called from inside a private convenience method within an object that supplies the table name, condition, and cache. This method should be used instead of UpdateValue() in situations where the incoming value specifically needs to be forced to an float.

Parameters
TableNameName of database table.
FieldNameName of database field.
NewValueNew value to set. Use DB_NOVALUE to not set a new value (i.e. when just getting a value).
ConditionSQL query conditional to use in SELECT or UPDATE statements (should not include "WHERE"). Use NULL if no conditional is needed.
CachedRecordVariable to use to cache values. Accessed by reference.
Returns
Requested value.

Definition at line 628 of file Axis--Database.php.

References DB_NOVALUE, and UpdateValue().

Database::UpdateIntValue (   $TableName,
  $FieldName,
  $NewValue,
  $Condition,
$CachedRecord 
)

A convenience function to get or set an integer value in the database.

This will typically be called from inside a private convenience method within an object that supplies the table name, condition, and cache. This method should be used instead of UpdateValue() in situations where the incoming value specifically needs to be forced to an int.

Parameters
TableNameName of database table.
FieldNameName of database field.
NewValueNew value to set. Use DB_NOVALUE to not set a new value (i.e. when just getting a value).
ConditionSQL query conditional to use in SELECT or UPDATE statements (should not include "WHERE"). Use NULL if no conditional is needed.
CachedRecordVariable to use to cache values. Accessed by reference.
Returns
Requested value.

Definition at line 607 of file Axis--Database.php.

References DB_NOVALUE, and UpdateValue().

Database::UpdateValue (   $TableName,
  $FieldName,
  $NewValue,
  $Condition,
$CachedRecord 
)

A convenience function to get or set a value in the database.

This will typically be called from inside a private convenience method within an object that supplies the table name, condition, and cache.

Parameters
TableNameName of database table.
FieldNameName of database field.
NewValueNew value to set. Use DB_NOVALUE to not set a new value (i.e. when just getting a value).
ConditionSQL query conditional to use in SELECT or UPDATE statements (should not include "WHERE"). Use NULL if no conditional is needed.
CachedRecordVariable to use to cache values. Accessed by reference.
Returns
Requested value.

Definition at line 564 of file Axis--Database.php.

References DB_NOVALUE, FetchRow(), and Query().

Referenced by UpdateFloatValue(), and UpdateIntValue().

Here is the caller graph for this function:

Member Data Documentation

Database::$DBHostName
protected

Definition at line 720 of file Axis--Database.php.

Referenced by DBHostName().

Database::$DBName
protected

Definition at line 721 of file Axis--Database.php.

Referenced by Database(), and DBName().

Database::$DBPassword
protected

Definition at line 719 of file Axis--Database.php.

Database::$DBUserName
protected

Definition at line 718 of file Axis--Database.php.

Referenced by DBUserName().


The documentation for this class was generated from the following file: