Search:

# CWIS Developers Documentation

# Database Class Reference

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

## 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.
## Setup/Initialization
| Database ($UserName=NULL, $Password=NULL, $DatabaseName=NULL, $HostName=NULL)
| Object constructor.
| 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.
static | SetGlobalServerInfo ($UserName, $Password, $HostName="localhost")
| Set default login and host info for database server.
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).
| 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.

List of all members.

## Detailed Description

SQL database abstraction object with smart query caching.

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

Inheritance diagram for Database:

[legend]

## Member Function Documentation

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:

  | NewSetting | TRUE to enable advanced caching or FALSE to disable. (OPTIONAL)

Returns:
  Current advanced caching setting.

Definition at line 159 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 569 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:

  | NewSetting | TRUE to enable caching or FALSE to disable. (OPTIONAL)

Returns:
  Current caching setting.

Definition at line 134 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:

  | UserName | User name to use to log in to database server. (OPTIONAL)
  | Password | Password to use to log in to database server. (OPTIONAL)
  | DatabaseName | Name of database to use once logged in. (OPTIONAL)
  | HostName | Host name of system on which database server resides. (OPTIONAL, defaults to "localhost")

See also:
  SetGlobalServerInfo()

  SetGlobalDatabaseName()

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

References 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 111 of file Axis--Database.php.

Referenced by Database().

Here is the caller graph for this function:

Database::DBName | ( |  | ) |

Get current database name.

Returns:
  Database name.

See also:
  SetGlobalDatabaseName()

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

Referenced by 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 125 of file Axis--Database.php.

Referenced by Database().

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:

  | FieldName | Name of database field.
  | IndexFieldName | Name 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 417 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:

  | FieldName | Name of field.

Returns:
  Value from specified field.

Definition at line 442 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 351 of file Axis--Database.php.

Referenced by 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:

  | NumberOfRows | Maximum 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 386 of file Axis--Database.php.

References FetchRow().

Database::FieldExists | ( | $ | TableName,
|  | $ | FieldName |
| ) |  |  |

Get whether specified field exists in specified table.

Parameters:

  | TableName | Name of database table.
  | FieldName | Name of database field.

Returns:
  TRUE if table and field exist, or FALSE otherwise.

Definition at line 523 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:

  | TableName | Name of SQL table into which row was inserted.

Returns:
  Numerical ID value.

Definition at line 455 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:

  | String | Debug string.

Definition at line 512 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 559 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 548 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 332 of file Axis--Database.php.

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

Query database (with caching if enabled).

Parameters:

  | QueryString | SQL query string.
  | FieldName | Name of field for which to return value to caller. (OPTIONAL)

Returns:
  Query handle or retrieved value if FieldName supplied. Returns FALSE on error.

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

References FetchField().

Referenced by 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:

  | NewSetting | TRUE to enable output or FALSE to disable output.

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

static Database::SetGlobalDatabaseName | ( | $ | DatabaseName | ) | `[static]`

Set default database name.

Parameters:

  | DatabaseName | Name of database to use once logged in.

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

static Database::SetGlobalServerInfo | ( | $ | UserName,
|  | $ | Password,
|  | $ | HostName = `"localhost"` |
| ) |  |  | `[static]`

Set default login and host info for database server.

Parameters:

  | UserName | User name to use to log in to database server.
  | Password | Password to use to log in to database server.
  | HostName | Host name of system on which database server resides. (OPTIONAL, defaults to "localhost")

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

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:

  | TableName | Name of database table.
  | FieldName | Name of database field.
  | NewValue | New value to set. Use DB_NOVALUE to not set a new value (i.e. when just getting a value).
  | Condition | SQL query conditional to use in SELECT or UPDATE statements (should not include "WHERE"). Use NULL if no conditional is needed.
  | CachedRecord | Variable to use to cache values. Accessed by reference.

Returns:
  Requested value.

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

References FetchRow(), and Query().

## Member Data Documentation

Database::$DBHostName`[protected]`

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

Database::$DBName`[protected]`

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

Database::$DBPassword`[protected]`

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

Database::$DBUserName`[protected]`

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

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

- Axis--Database.php