Index: includes/database/database.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/database/database.inc,v
retrieving revision 1.98
diff -u -r1.98 database.inc
--- includes/database/database.inc	1 Mar 2010 11:30:37 -0000	1.98
+++ includes/database/database.inc	5 Mar 2010 10:21:55 -0000
@@ -31,15 +31,15 @@
  * For example, one might wish to return a list of the most recent 10 nodes
  * authored by a given user. Instead of directly issuing the SQL query
  * @code
- *   SELECT n.nid, n.title, n.created FROM node n WHERE n.uid = $uid LIMIT 0, 10;
+ * SELECT n.nid, n.title, n.created FROM node n WHERE n.uid = $uid LIMIT 0, 10;
  * @endcode
  * one would instead call the Drupal functions:
  * @code
- *   $result = db_query_range('SELECT n.nid, n.title, n.created
- *     FROM {node} n WHERE n.uid = :uid', array(':uid' => $uid), 0, 10);
- *   foreach($result as $record) {
- *     // Perform operations on $node->title, etc. here.
- *   }
+ * $result = db_query_range('SELECT n.nid, n.title, n.created
+ *   FROM {node} n WHERE n.uid = :uid', array(':uid' => $uid), 0, 10);
+ * foreach($result as $record) {
+ *   // Perform operations on $node->title, etc. here.
+ * }
  * @endcode
  * Curly braces are used around "node" to provide table prefixing via
  * DatabaseConnection::prefixTables(). The explicit use of a user ID is pulled
@@ -63,7 +63,7 @@
  *
  * Named placeholders begin with a colon followed by a unique string. Example:
  * @code
- * SELECT nid, title FROM {node} WHERE uid=:uid
+ * SELECT nid, title FROM {node} WHERE uid=:uid;
  * @endcode
  *
  * ":uid" is a placeholder that will be replaced with a literal value when
@@ -75,7 +75,7 @@
  *
  * Unnamed placeholders are simply a question mark. Example:
  * @code
- * SELECT nid, title FROM {node} WHERE uid=?
+ * SELECT nid, title FROM {node} WHERE uid=?;
  * @endcode
  *
  * In this case, the array of arguments must be an indexed array of values to
@@ -84,17 +84,13 @@
  * Note that placeholders should be a "complete" value. For example, when
  * running a LIKE query the SQL wildcard character, %, should be part of the
  * value, not the query itself. Thus, the following is incorrect:
- *
  * @code
- * SELECT nid, title FROM {node} WHERE title LIKE :title%
+ * SELECT nid, title FROM {node} WHERE title LIKE :title%;
  * @endcode
- *
  * It should instead read:
- *
  * @code
- * SELECT nid, title FROM {node} WHERE title LIKE :title
+ * SELECT nid, title FROM {node} WHERE title LIKE :title;
  * @endcode
- *
  * and the value for :title should include a % as appropriate. Again, note the
  * lack of quotation marks around :title. Because the value is not inserted
  * into the query as one big string but as an explicitly separate value, the
@@ -105,9 +101,10 @@
  *
  * INSERT, UPDATE, and DELETE queries need special care in order to behave
  * consistently across all different databases. Therefore, they use a special
- * object-oriented API for defining a query structurally. For example, rather than
+ * object-oriented API for defining a query structurally. For example, rather
+ * than:
  * @code
- * INSERT INTO node (nid, title, body) VALUES (1, 'my title', 'my body')
+ * INSERT INTO node (nid, title, body) VALUES (1, 'my title', 'my body');
  * @endcode
  * one would instead write:
  * @code
@@ -400,6 +397,7 @@
    *
    * @param $sql
    *   A string containing a partial or entire SQL query.
+   *
    * @return
    *   The properly-prefixed string.
    */
@@ -436,6 +434,7 @@
    * @param $query
    *   The query string as SQL, with curly-braces surrounding the
    *   table names.
+   *
    * @return DatabaseStatementInterface
    *   A PDO prepared statement ready for its execute() method.
    */
@@ -505,6 +504,7 @@
    *   The table name to use for the sequence.
    * @param $field
    *   The field name to use for the sequence.
+   *
    * @return
    *   A table prefix-parsed string for the sequence name.
    */
@@ -536,6 +536,7 @@
    * @param $options
    *   An associative array of options to control how the query is run. See
    *   the documentation for DatabaseConnection::defaultOptions() for details.
+   *
    * @return DatabaseStatementInterface
    *   This method will return one of: the executed statement, the number of
    *   rows affected by the query (not the number matched), or the generated
@@ -607,6 +608,7 @@
    *   The query string to modify.
    * @param $args
    *   The arguments for the query.
+   *
    * @return
    *   TRUE if the query was modified, FALSE otherwise.
    */
@@ -651,7 +653,6 @@
   /**
    * Prepare and return a SELECT query object with the specified ID.
    *
-   * @see SelectQuery
    * @param $table
    *   The base table for this query, that is, the first table in the FROM
    *   clause. This table will also be used as the "base" table for query_alter
@@ -660,8 +661,13 @@
    *   The alias of the base table of this query.
    * @param $options
    *   An array of options on the query.
+   *
    * @return SelectQueryInterface
-   *   A new SelectQuery object.
+   *   An appropriate SelectQuery object for this database connection. Note that
+   *   it may be a driver-specific subclass of SelectQuery, depending on the
+   *   driver.
+   *
+   * @see SelectQuery
    */
   public function select($table, $alias = NULL, array $options = array()) {
     if (empty($this->selectClass)) {
@@ -681,11 +687,13 @@
   /**
    * Prepare and return an INSERT query object with the specified ID.
    *
-   * @see InsertQuery
    * @param $options
    *   An array of options on the query.
+   *
    * @return InsertQuery
    *   A new InsertQuery object.
+   *
+   * @see InsertQuery
    */
   public function insert($table, array $options = array()) {
     if (empty($this->insertClass)) {
@@ -701,11 +709,13 @@
   /**
    * Prepare and return a MERGE query object with the specified ID.
    *
-   * @see MergeQuery
    * @param $options
    *   An array of options on the query.
+   *
    * @return MergeQuery
    *   A new MergeQuery object.
+   *
+   * @see MergeQuery
    */
   public function merge($table, array $options = array()) {
     if (empty($this->mergeClass)) {
@@ -722,11 +732,13 @@
   /**
    * Prepare and return an UPDATE query object with the specified ID.
    *
-   * @see UpdateQuery
    * @param $options
    *   An array of options on the query.
+   *
    * @return UpdateQuery
    *   A new UpdateQuery object.
+   *
+   * @see UpdateQuery
    */
   public function update($table, array $options = array()) {
     if (empty($this->updateClass)) {
@@ -742,11 +754,13 @@
   /**
    * Prepare and return a DELETE query object with the specified ID.
    *
-   * @see DeleteQuery
    * @param $options
    *   An array of options on the query.
+   *
    * @return DeleteQuery
    *   A new DeleteQuery object.
+   *
+   * @see DeleteQuery
    */
   public function delete($table, array $options = array()) {
     if (empty($this->deleteClass)) {
@@ -762,11 +776,13 @@
   /**
    * Prepare and return a TRUNCATE query object.
    *
-   * @see TruncateQuery
    * @param $options
    *   An array of options on the query.
+   *
    * @return TruncateQuery
-   *   A new DeleteQuery object.
+   *   A new TruncateQuery object.
+   *
+   * @see TruncateQuery
    */
   public function truncate($table, array $options = array()) {
     if (empty($this->truncateClass)) {
@@ -831,6 +847,7 @@
    *
    * @param $string
    *   The string to escape.
+   *
    * @return
    *   The escaped string.
    */
@@ -1030,6 +1047,7 @@
    *   The maximum number of result rows to return.
    * @param $options
    *   An array of options on the query.
+   *
    * @return DatabaseStatementInterface
    *   A database query result resource, or NULL if the query was not executed
    *   correctly.
@@ -1065,6 +1083,7 @@
    * @param $options
    *   An associative array of options to control how the query is run. See
    *   the documentation for DatabaseConnection::defaultOptions() for details.
+   *
    * @return
    *   The name of the temporary table.
    */
@@ -1117,11 +1136,13 @@
    * overridable lookup function. Database connections should define only
    * those operators they wish to be handled differently than the default.
    *
-   * @see DatabaseCondition::compile()
    * @param $operator
    *   The condition operator, such as "IN", "BETWEEN", etc. Case-sensitive.
+   *
    * @return
    *   The extra handling directives for the specified operator, or NULL.
+   *
+   * @see DatabaseCondition::compile()
    */
   abstract public function mapConditionOperator($operator);
 
@@ -1151,6 +1172,7 @@
    *   After a database import, it might be that the sequences table is behind,
    *   so by passing in the maximum existing id, it can be assured that we
    *   never issue the same id.
+   *
    * @return
    *   An integer number larger than any number returned by earlier calls and
    *   also larger than the $existing_id if one was passed in.
@@ -1164,7 +1186,6 @@
  * This class is uninstantiatable and un-extendable. It acts to encapsulate
  * all control and shepherding of database connections into a single location
  * without the use of globals.
- *
  */
 abstract class Database {
 
@@ -1248,15 +1269,17 @@
   /**
    * Start logging a given logging key on the specified connection.
    *
-   * @see DatabaseLog
    * @param $logging_key
    *   The logging key to log.
    * @param $key
    *   The database connection key for which we want to log.
+   *
    * @return DatabaseLog
    *   The query log object. Note that the log object does support richer
    *   methods than the few exposed through the Database class, so in some
    *   cases it may be desirable to access it directly.
+   *
+   * @see DatabaseLog
    */
   final public static function startLog($logging_key, $key = 'default') {
     if (empty(self::$logs[$key])) {
@@ -1278,13 +1301,14 @@
   /**
    * Set a logging callback for notices and errors.
    *
-   * @see watchdog()
    * @param $logging_callback
    *   The function to use as the logging callback.
    * @param $logging_default_severity
    *   The default severity level to use for logged messages.
    * @param $logging_error_severity
    *   The severity level to use for logging error messages.
+   *
+   * @see watchdog()
    */
   final public static function setLoggingCallback($callback, $default_severity, $error_severity) {
     self::$logging_callback = array(
@@ -1314,13 +1338,15 @@
    * it again (which does nothing to an open log key) and call methods on it as
    * desired.
    *
-   * @see DatabaseLog
    * @param $logging_key
    *   The logging key to log.
    * @param $key
    *   The database connection key for which we want to log.
-   * @return array
+   *
+   * @return array $queries
    *   The query log for the specified logging key and connection.
+   *
+   * @see DatabaseLog
    */
   final public static function getLog($logging_key, $key = 'default') {
     if (empty(self::$logs[$key])) {
@@ -1338,6 +1364,7 @@
    *   The database target name.
    * @param $key
    *   The database connection key. Defaults to NULL which means the active key.
+   *
    * @return DatabaseConnection
    *   The corresponding connection object.
    */
@@ -1572,7 +1599,7 @@
 }
 
 /**
- * Exception to throw when popTransaction() is called when no transaction is active.
+ * Exception for when popTransaction() is called with no active transaction.
  */
 class NoActiveTransactionException extends Exception { }
 
@@ -1620,8 +1647,9 @@
  * commands, allowing user-space code to proceed normally. The only difference
  * is that rollbacks won't actually do anything.
  *
- * In the vast majority of cases, you should not instantiate this class directly.
- * Instead, call ->startTransaction(), from the appropriate connection object.
+ * In the vast majority of cases, you should not instantiate this class
+ * directly. Instead, call ->startTransaction(), from the appropriate connection
+ * object.
  */
 class DatabaseTransaction {
 
@@ -1716,6 +1744,7 @@
    *   the SQL statement being executed.
    * @param $options
    *   An array of options for this query.
+   *
    * @return
    *   TRUE on success, or FALSE on failure.
    */
@@ -1770,6 +1799,7 @@
    *   Not implemented in all database drivers, don't use.
    * @param $cursor_offset
    *   Not implemented in all database drivers, don't use.
+   *
    * @return
    *   A result, formatted according to $mode.
    */
@@ -1780,6 +1810,7 @@
    *
    * @param $index
    *   The numeric index of the field to return. Defaults to the first field.
+   *
    * @return
    *   A single field from the next record.
    */
@@ -1814,6 +1845,7 @@
    *   If $mode is PDO::FETCH_COLUMN, the index of the column to fetch.
    * @param $constructor_arguments
    *   If $mode is PDO::FETCH_CLASS, the arguments to pass to the constructor.
+   *
    * @return
    *   An array of results.
    */
@@ -1826,6 +1858,7 @@
    *
    * @param $index
    *   The index of the column number to fetch.
+   *
    * @return
    *   An indexed array.
    */
@@ -1845,6 +1878,7 @@
    *   The numeric index of the field to use as the array key.
    * @param $value_index
    *   The numeric index of the field to use as the array value.
+   *
    * @return
    *   An associative array.
    */
@@ -1865,6 +1899,7 @@
    *   The fetchmode to use. If set to PDO::FETCH_ASSOC, PDO::FETCH_NUM, or
    *   PDO::FETCH_BOTH the returned value with be an array of arrays. For any
    *   other value it will be an array of objects.
+   *
    * @return
    *   An associative array.
    */
@@ -2057,17 +2092,17 @@
 
 /**
  * The following utility functions are simply convenience wrappers.
+ *
  * They should never, ever have any database-specific code in them.
  */
 
 /**
- * Execute an arbitrary query string against the active database.
+ * Executes an arbitrary query string against the active database.
  *
  * Do not use this function for INSERT, UPDATE, or DELETE queries. Those should
  * be handled via the appropriate query builder factory. Use this function for
  * SELECT queries that do not require a query builder.
  *
- * @see DatabaseConnection::defaultOptions()
  * @param $query
  *   The prepared statement query to run. Although it will accept both named and
  *   unnamed placeholders, named placeholders are strongly preferred as they are
@@ -2079,8 +2114,11 @@
  *   the order of placeholders in the query string.
  * @param $options
  *   An array of options to control how the query operates.
+ *
  * @return DatabaseStatementInterface
  *   A prepared statement object, already executed.
+ *
+ * @see DatabaseConnection::defaultOptions()
  */
 function db_query($query, array $args = array(), array $options = array()) {
   if (empty($options['target'])) {
@@ -2091,10 +2129,10 @@
 }
 
 /**
- * Execute an arbitrary query string against the active database, restricted to
- * a specified range.
+ * Executes an arbitrary query string against the active database.
+ * 
+ * The query string has to be restricted to a specified range.
  *
- * @see DatabaseConnection::defaultOptions()
  * @param $query
  *   The prepared statement query to run. Although it will accept both named and
  *   unnamed placeholders, named placeholders are strongly preferred as they are
@@ -2110,8 +2148,11 @@
  *   the order of placeholders in the query string.
  * @param $options
  *   An array of options to control how the query operates.
+ *
  * @return DatabaseStatementInterface
  *   A prepared statement object, already executed.
+ *
+ * @see DatabaseConnection::defaultOptions()
  */
 function db_query_range($query, $from, $count, array $args = array(), array $options = array()) {
   if (empty($options['target'])) {
@@ -2122,10 +2163,10 @@
 }
 
 /**
- * Execute a query string against the active database and save the result set
- * to a temp table.
+ * Executes a query string and save the result set to a temp table.
+ *
+ * The execution of the query string happens against the active database.
  *
- * @see DatabaseConnection::defaultOptions()
  * @param $query
  *   The prepared statement query to run. Although it will accept both named and
  *   unnamed placeholders, named placeholders are strongly preferred as they are
@@ -2137,8 +2178,11 @@
  *   the order of placeholders in the query string.
  * @param $options
  *   An array of options to control how the query operates.
+ *
  * @return
  *   The name of the temporary table.
+ *
+ * @see DatabaseConnection::defaultOptions()
  */
 function db_query_temporary($query, array $args = array(), array $options = array()) {
   if (empty($options['target'])) {
@@ -2155,6 +2199,7 @@
  *   The table into which to insert.
  * @param $options
  *   An array of options to control how the query operates.
+ *
  * @return InsertQuery
  *   A new InsertQuery object for this connection.
  */
@@ -2172,6 +2217,7 @@
  *   The table into which to merge.
  * @param $options
  *   An array of options to control how the query operates.
+ *
  * @return MergeQuery
  *   A new MergeQuery object for this connection.
  */
@@ -2189,6 +2235,7 @@
  *   The table to update.
  * @param $options
  *   An array of options to control how the query operates.
+ *
  * @return UpdateQuery
  *   A new UpdateQuery object for this connection.
  */
@@ -2206,6 +2253,7 @@
  *   The table from which to delete.
  * @param $options
  *   An array of options to control how the query operates.
+ *
  * @return DeleteQuery
  *   A new DeleteQuery object for this connection.
  */
@@ -2223,6 +2271,7 @@
  *   The table from which to delete.
  * @param $options
  *   An array of options to control how the query operates.
+ *
  * @return TruncateQuery
  *   A new TruncateQuery object for this connection.
  */
@@ -2243,6 +2292,7 @@
  *   The alias for the base table of this query.
  * @param $options
  *   An array of options to control how the query operates.
+ *
  * @return SelectQuery
  *   A new SelectQuery object for this connection.
  */
@@ -2263,6 +2313,7 @@
  * @param $options
  *   An array of options to control how the transaction operates.  Only the
  *   target key has any meaning in this case.
+ *
  * @return DatabaseTransaction
  *   A new DatabaseTransaction object for this connection.
  */
@@ -2278,6 +2329,7 @@
  *
  * @param $key
  *   The key in the $databases array to set as the default database.
+ *
  * @return
  *   The key of the formerly active database.
  */
@@ -2306,6 +2358,7 @@
  *
  * @param $table
  *   The table name to escape.
+ *
  * @return
  *   The escaped table name as a string.
  */
@@ -2334,6 +2387,7 @@
  *
  * @param $string
  *   The string to escape.
+ *
  * @return
  *   The escaped string.
  */
@@ -2342,10 +2396,10 @@
 }
 
 /**
- * Retrieve the name of the currently active database driver, such as "mysql" or
- * "pgsql".
+ * Retrieves the name of the currently active database driver.
  *
- * @return The name of the currently active database driver.
+ * @return
+ *   The name of the currently active database driver.
  */
 function db_driver() {
   return Database::getConnection()->driver();
@@ -2375,6 +2429,7 @@
  *   After a database import, it might be that the sequences table is behind, so
  *   by passing in a minimum ID, it can be assured that we never issue the same
  *   ID.
+ *
  * @return
  *   An integer number larger than any number returned before for this sequence.
  */
@@ -2415,6 +2470,7 @@
  *
  * @param $fields
  *   An array of key/index column specifiers.
+ *
  * @return
  *   An array of field names.
  */
@@ -2429,6 +2485,7 @@
  *   The name of the table in drupal (no prefixing).
  * @param $name
  *   The name of the index in drupal (no prefixing).
+ *
  * @return
  *   TRUE if the given index exists, otherwise FALSE.
  */
@@ -2441,6 +2498,7 @@
  *
  * @param $table
  *   The name of the table in drupal (no prefixing).
+ *
  * @return
  *   TRUE if the given table exists, otherwise FALSE.
  */
@@ -2455,6 +2513,7 @@
  *   The name of the table in drupal (no prefixing).
  * @param $name
  *   The name of the column.
+ *
  * @return
  *   TRUE if the given column exists, otherwise FALSE.
  */
@@ -2468,6 +2527,7 @@
  * @param $table_expression
  *   An SQL expression, for example "simpletest%" (without the quotes).
  *   BEWARE: this is not prefixed, the caller should take care of that.
+ *
  * @return
  *   Array, both the keys and the values are the matching tables.
  */
@@ -2480,8 +2540,10 @@
 }
 
 /**
- * This maps a generic data type in combination with its data size
- * to the engine-specific data type.
+ * Maps a generic data type.
+ * 
+ * The mapping happens in combination with its data size to the engine-specific
+ * data type.
  */
 function db_type_map() {
   return Database::getConnection()->schema()->getFieldTypeMap();
@@ -2527,6 +2589,7 @@
  *   without the 'fields' element. If you are adding a type 'serial' field, you
  *   MUST specify at least one key or index including it in this array. See
  *   db_change_field() for more explanation why.
+ *
  * @see db_change_field()
  */
 function db_add_field($table, $field, $spec, $keys_new = array()) {
@@ -2713,19 +2776,6 @@
  * @} End of "ingroup schemaapi".
  */
 
-/**
- * Prints a themed maintenance page with the 'Site offline' text, adding the
- * provided error message in the case of 'display_errors' set to on. Ends the
- * page request; no return.
- */
-function _db_error_page($error = '') {
-  global $db_type;
-  drupal_language_initialize();
-  drupal_maintenance_theme();
-  drupal_add_http_header($_SERVER['SERVER_PROTOCOL'] . ' 503 Service Unavailable');
-  drupal_set_title('Site offline');
-}
-
  /**
  * Helper function to get duration lag from variable and set the session
  * variable that contains the lag.