/lib/php/MDB/Common.php

Large files files are truncated, but you can click here to view the full file

<?php
// +----------------------------------------------------------------------+
// | PHP Version 4                                                        |
// +----------------------------------------------------------------------+
// | Copyright (c) 1998-2004 Manuel Lemos, Tomas V.V.Cox,                 |
// | Stig. S. Bakken, Lukas Smith                                         |
// | All rights reserved.                                                 |
// +----------------------------------------------------------------------+
// | MDB is a merge of PEAR DB and Metabases that provides a unified DB   |
// | API as well as database abstraction for PHP applications.            |
// | This LICENSE is in the BSD license style.                            |
// |                                                                      |
// | Redistribution and use in source and binary forms, with or without   |
// | modification, are permitted provided that the following conditions   |
// | are met:                                                             |
// |                                                                      |
// | Redistributions of source code must retain the above copyright       |
// | notice, this list of conditions and the following disclaimer.        |
// |                                                                      |
// | Redistributions in binary form must reproduce the above copyright    |
// | notice, this list of conditions and the following disclaimer in the  |
// | documentation and/or other materials provided with the distribution. |
// |                                                                      |
// | Neither the name of Manuel Lemos, Tomas V.V.Cox, Stig. S. Bakken,    |
// | Lukas Smith nor the names of his contributors may be used to endorse |
// | or promote products derived from this software without specific prior|
// | written permission.                                                  |
// |                                                                      |
// | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS  |
// | "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT    |
// | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS    |
// | FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE      |
// | REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,          |
// | INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, |
// | BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS|
// |  OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED  |
// | AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT          |
// | LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY|
// | WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE          |
// | POSSIBILITY OF SUCH DAMAGE.                                          |
// +----------------------------------------------------------------------+
// | Author: Lukas Smith <smith@backendmedia.com>                         |
// +----------------------------------------------------------------------+
//
// $Id: Common.php,v 1.114.4.22 2004/04/08 19:11:58 lsmith Exp $

/**
 * @package MDB
 * @author Lukas Smith <smith@backendmedia.com>
 */

// }}}
// {{{ MDB_defaultDebugOutput()

/**
 * default debug output handler
 *
 * @param object $db reference to an MDB database object
 * @param string $message message that should be appended to the debug
 *       variable
 * @return string the corresponding error message, of FALSE
 * if the error code was unknown
 * @access public
 */
function MDB_defaultDebugOutput(&$db, $message)
{
    $db->debug_output .= $db->database . " $message" . $db->getOption('log_line_break');
}

/**
 * MDB_Common: Base class that is extended by each MDB driver
 *
 * @package MDB
 * @category Database
 * @author Lukas Smith <smith@backendmedia.com>
 */
class MDB_Common extends PEAR
{
    // {{{ properties
    /**
    * index of the MDB object withing the global $_MDB_databases array
    * @var integer
    * @access private
    */
    var $database = 0;

    /**
    * @var string
    * @access private
    */
    var $host = '';

    /**
    * @var string
    * @access private
    */
    var $port = '';

    /**
    * @var string
    * @access private
    */
    var $user = '';

    /**
    * @var string
    * @access private
    */
    var $password = '';

    /**
    * @var string
    * @access private
    */
    var $database_name = '';

    /**
    * @var array
    * @access private
    */
    var $supported = array();

    /**
    * $options["persistent"] -> boolean persistent connection true|false?
    * $options["debug"] -> integer numeric debug level
    * $options["autofree"] -> boolean
    * $options["lob_buffer_length"] -> integer LOB buffer length
    * $options["log_line_break"] -> string line-break format
    * $options["seqname_format"] -> string pattern for sequence name
    * $options["includelob"] -> boolean
    * $options["includemanager"] -> boolean
    * $options["UseTransactions"] -> boolean
    * $options["optimize"] -> string 'performance' or 'portability'
    * @var array
    * @access private
    */
    var $options = array(
            'persistent' => FALSE,
            'debug' => FALSE,
            'autofree' => FALSE,
            'lob_buffer_length' => 8192,
            'log_line_break' => "\n",
            'seqname_format' => '%s_seq',
            'sequence_col_name' => 'sequence',
            'includelob' => FALSE,
            'includemanager' => FALSE,
            'UseTransactions' => FALSE,
            'optimize' => 'performance',
        );

    /**
    * @var string
    * @access private
    */
    var $escape_quotes = '';

    /**
    * @var integer
    * @access private
    */
    var $decimal_places = 2;

    /**
    * @var string
    * @access private
    */
    var $manager_included_constant = '';

    /**
    * @var string
    * @access private
    */
    var $manager_include = '';

    /**
    * @var string
    * @access private
    */
    var $manager_class_name = '';

    /**
    * @var object
    * @access private
    */
    var $manager;

    /**
    * @var array
    * @access private
    */
    var $warnings = array();

    /**
    * @var string
    * @access private
    */
    var $debug = '';

    /**
    * @var string
    * @access private
    */
    var $debug_output = '';

    /**
    * @var boolean
    * @access private
    */
    var $pass_debug_handle = FALSE;

    /**
    * @var boolean
    * @access private
    */
    var $auto_commit = TRUE;

    /**
    * @var boolean
    * @access private
    */
    var $in_transaction = FALSE;

    /**
    * @var integer
    * @access private
    */
    var $first_selected_row = 0;

    /**
    * @var integer
    * @access private
    */
    var $selected_row_limit = 0;

    /**
    * DB type (mysql, oci8, odbc etc.)
    * @var string
    * @access private
    */
    var $type;

    /**
    * @var array
    * @access private
    */
    var $prepared_queries = array();

    /**
    * @var array
    * @access private
    */
    var $result_types;

    /**
    * @var string
    * @access private
    */
    var $last_query = '';

    /**
    * @var integer
    * @access private
    */
    var $fetchmode = MDB_FETCHMODE_ORDERED;

    /**
    * @var integer
    * @access private
    */
    var $affected_rows = -1;

    /**
    * @var array
    * @access private
    */
    var $lobs = array();

    /**
    * @var array
    * @access private
    */
    var $clobs = array();

    /**
    * @var array
    * @access private
    */
    var $blobs = array();

    // }}}
    // {{{ constructor

    /**
     * Constructor
     */
    function MDB_Common()
    {
        $database = count($GLOBALS['_MDB_databases']) + 1;
        $GLOBALS['_MDB_databases'][$database] = &$this;
        $this->database = $database;

        $this->PEAR('MDB_Error');
        $this->supported = array();
        $this->errorcode_map = array();
        $this->fetchmode = MDB_FETCHMODE_ORDERED;
    }

    // }}}
    // {{{ __toString()

    /**
     * String conversation
     *
     * @return string
     * @access public
     */
    function __toString()
    {
        $info = get_class($this);
        $info .= ': (phptype = ' . $this->phptype . ', dbsyntax = ' . $this->dbsyntax . ')';
        if ($this->connection) {
            $info .= ' [connected]';
        }
        return($info);
    }

    // }}}
    // {{{ errorCode()

    /**
     * Map native error codes to MDB's portable ones.  Requires that
     * the DB implementation's constructor fills in the $errorcode_map
     * property.
     *
     * @param mixed $nativecode the native error code, as returned by the
     *      backend database extension (string or integer)
     * @return int a portable MDB error code, or FALSE if this MDB
     *      implementation has no mapping for the given error code.
     * @access public
     */
    function errorCode($nativecode)
    {
        if (isset($this->errorcode_map[$nativecode])) {
            return($this->errorcode_map[$nativecode]);
        }
        // Fall back to MDB_ERROR if there was no mapping.
        return(MDB_ERROR);
    }

    // }}}
    // {{{ errorMessage()

    /**
     * Map a MDB error code to a textual message.  This is actually
     * just a wrapper for MDB::errorMessage().
     *
     * @param integer $dbcode the MDB error code
     * @return string the corresponding error message, of FALSE
     *      if the error code was unknown
     * @access public
     */
    function errorMessage($dbcode)
    {
        return(MDB::errorMessage($this->errorcode_map[$dbcode]));
    }

    // }}}
    // {{{ raiseError()

    /**
     * This method is used to communicate an error and invoke error
     * callbacks etc.  Basically a wrapper for PEAR::raiseError
     * without the message string.
     *
     * @param mixed $code integer error code, or a PEAR error object (all
     *      other parameters are ignored if this parameter is an object
     * @param int $mode error mode, see PEAR_Error docs
     * @param mixed $options If error mode is PEAR_ERROR_TRIGGER, this is the
     *      error level (E_USER_NOTICE etc).  If error mode is
     *      PEAR_ERROR_CALLBACK, this is the callback function, either as a
     *      function name, or as an array of an object and method name. For
     *      other error modes this parameter is ignored.
     * @param string $userinfo Extra debug information.  Defaults to the last
     *      query and native error code.
     * @param mixed $nativecode Native error code, integer or string depending
     *      the backend.
     * @return object a PEAR error object
     * @access public
     * @see PEAR_Error
     */
    function &raiseError($code = MDB_ERROR, $mode = NULL, $options = NULL,
        $userinfo = NULL, $nativecode = NULL)
    {
        // The error is yet a MDB error object
        if (is_object($code)) {
            // because we the static PEAR::raiseError, our global
            // handler should be used if it is set
            if ($mode === null && !empty($this->_default_error_mode)) {
                $mode    = $this->_default_error_mode;
                $options = $this->_default_error_options;
            }
            $err = PEAR::raiseError($code, NULL, $mode, $options, NULL, NULL, TRUE);
            return($err);
        }

        if ($userinfo === NULL) {
            $userinfo = $this->last_query;
        }

        if ($nativecode) {
            $userinfo .= ' [nativecode=' . trim($nativecode) . ']';
        }

        $err = PEAR::raiseError(NULL, $code, $mode, $options, $userinfo, 'MDB_Error', TRUE);
        return($err);
    }

    // }}}
    // {{{ errorNative()

    /**
     * returns an errormessage, provides by the database
     *
     * @return mixed MDB_Error or message
     * @access public
     */
    function errorNative()
    {
        return($this->raiseError(MDB_ERROR_NOT_CAPABLE));
    }

    // }}}
    // {{{ resetWarnings()

    /**
     * reset the warning array
     *
     * @access public
     */
    function resetWarnings()
    {
        $this->warnings = array();
    }

    // }}}
    // {{{ getWarnings()

    /**
     * get all warnings in reverse order.
     * This means that the last warning is the first element in the array
     *
     * @return array with warnings
     * @access public
     * @see resetWarnings()
     */
    function getWarnings()
    {
        return array_reverse($this->warnings);
    }

    // }}}
    // {{{ setOption()

    /**
     * set the option for the db class
     *
     * @param string $option option name
     * @param mixed $value value for the option
     * @return mixed MDB_OK or MDB_Error
     * @access public
     */
    function setOption($option, $value)
    {
        if (isset($this->options[$option])) {
            $this->options[$option] = $value;
            return MDB_OK;
        }
        return($this->raiseError(MDB_ERROR_UNSUPPORTED, NULL, NULL, "unknown option $option"));
    }

    // }}}
    // {{{ getOption()

    /**
     * returns the value of an option
     *
     * @param string $option option name
     * @return mixed the option value or error object
     * @access public
     */
    function getOption($option)
    {
        if (isset($this->options[$option])) {
            return($this->options[$option]);
        }
        return($this->raiseError(MDB_ERROR_UNSUPPORTED, NULL, NULL, "unknown option $option"));
    }

    // }}}
    // {{{ captureDebugOutput()

    /**
     * set a debug handler
     *
     * @param string $capture name of the function that should be used in
     *      debug()
     * @access public
     * @see debug()
     */
    function captureDebugOutput($capture)
    {
        $this->pass_debug_handle = $capture;
        $this->debug = ($capture ? 'MDB_defaultDebugOutput' : '');
    }

    // }}}
    // {{{ debug()

    /**
     * set a debug message
     *
     * @param string $message Message with information for the user.
     * @access public
     */
    function debug($message)
    {
        if (strcmp($function = $this->debug, '')) {
            if ($this->pass_debug_handle) {
                $function($this, $message);
            } else {
                $function($message);
            }
        }
    }

    // }}}
    // {{{ debugOutput()

    /**
     * output debug info
     *
     * @return string content of the debug_output class variable
     * @access public
     */
    function debugOutput()
    {
        return($this->debug_output);
    }

    // }}}
    // {{{ setError() (deprecated)

    /**
     * set an error (deprecated)
     *
     * @param string $scope Scope of the error message
     *     (usually the method tht caused the error)
     * @param string $message Message with information for the user.
     * @return boolean FALSE
     * @access private
     */
    function setError($scope, $message)
    {
        $this->last_error = $message;
        $this->debug($scope . ': ' . $message);
        if (($function = $this->error_handler) != '') {
            $error = array(
                'Scope' => $scope,
                'Message' => $message
            );
            $function($this, $error);
        }
        return(0);
    }

    // }}}
    // {{{ setErrorHandler() (deprecated)

    /**
     * Specify a function that is called when an error occurs.
     *
     * @param string $function Name of the function that will be called on
     *      error. If an empty string is specified, no handler function is
     *      called on error. The error handler function receives two arguments.
     *      The first argument a reference to the driver class object that
     *      triggered the error.
     *
     *      The second argument is a reference to an associative array that
     *      provides details about the error that occured. These details provide
     *      more information than it is returned by the MetabaseError function.
     *
     *      These are the currently supported error detail entries:
     *
     *      Scope
     *       String that indicates the scope of the driver object class
     *       within which the error occured.
     *
     *      Message
     *       Error message as is returned by the MetabaseError function.
     * @return string name of last function
     * @access public
     */
    function setErrorHandler($function)
    {
        $last_function = $this->error_handler;
        $this->error_handler = $function;
        return($last_function);
    }

    // }}}
    // {{{ error() (deprecated)

    /**
     * Retrieve the error message text associated with the last operation that
     * failed. Some functions may fail but they do not return the reason that
     * makes them to fail. This function is meant to retrieve a textual
     * description of the failure cause.
     *
     * @return string the error message text associated with the last failure.
     * @access public
     */
    function error()
    {
        return($this->last_error);
    }

    // }}}
    // {{{ _quote()

    /**
     * Quotes a string so it can be safely used in a query. It will quote
     * the text so it can safely be used within a query.
     *
     * @param string $text the input string to quote
     * @return string quoted string
     * @access private
     */
    function _quote($text)
    {
        if (strcmp($this->escape_quotes, "'")) {
            $text = str_replace($this->escape_quotes, $this->escape_quotes . $this->escape_quotes, $text);
        }
        return str_replace("'", $this->escape_quotes . "'", $text);
    }

    // }}}
    // {{{ quoteIdentifier()

    /**
     * Quote a string so it can be safely used as a table or column name
     *
     * Delimiting style depends on which database driver is being used.
     *
     * NOTE: just because you CAN use delimited identifiers doesn't mean
     * you SHOULD use them.  In general, they end up causing way more
     * problems than they solve.
     *
     * Portability is broken by using the following characters inside
     * delimited identifiers:
     *   + backtick (<kbd>`</kbd>) -- due to MySQL
     *   + double quote (<kbd>"</kbd>) -- due to Oracle
     *   + brackets (<kbd>[</kbd> or <kbd>]</kbd>) -- due to Access
     *
     * Delimited identifiers are known to generally work correctly under
     * the following drivers:
     *   + mssql
     *   + mysql
     *   + mysqli
     *   + oci8
     *   + odbc(access)
     *   + odbc(db2)
     *   + pgsql
     *   + sqlite
     *   + sybase
     *
     * InterBase doesn't seem to be able to use delimited identifiers
     * via PHP 4.  They work fine under PHP 5.
     *
     * @param string $str  identifier name to be quoted
     *
     * @return string  quoted identifier string
     *
     * @access public
     */
    function quoteIdentifier($str)
    {
        return '"' . str_replace('"', '""', $str) . '"';
    }

    // }}}
    // {{{ _loadModule()

    /**
     * loads an module
     *
     * @param string $scope information about what method is being loaded,
     *      that is used for error messages
     * @param string $module name of the module that should be loaded
     *      (only used for error messages)
     * @param string $included_constant name of the constant that should be
     *      defined when the module has been loaded
     * @param string $include name of the script that includes the module
     * @access private
     */
    function _loadModule($scope, $module, $included_constant, $include)
    {
        if (strlen($included_constant) == 0 || !defined($included_constant)) {
            if($include) {
                $include = 'MDB/Modules/'.$include;
                if(MDB::isError($debug = $this->getOption('debug')) || $debug > 2) {
                    include_once($include);
                } else {
                    @include_once($include);
                }
            } else {
                return($this->raiseError(MDB_ERROR_LOADMODULE, NULL, NULL,
                    $scope . ': it was not specified an existing ' . $module . ' file (' . $include . ')'));
            }
        }
        return(MDB_OK);
    }

    // }}}
    // {{{ loadLob()

    /**
     * loads the LOB module
     *
     * @param string $scope information about what method is being loaded,
     *                       that is used for error messages
     * @access public
     */
    function loadLob($scope = '')
    {
        if (defined('MDB_LOB_INCLUDED')) {
            return(MDB_OK);
        }
        $result = $this->_loadModule($scope, 'LOB',
            'MDB_LOB_INCLUDED', 'LOB.php');
        if (MDB::isError($result)) {
            return($result);
        }
        return(MDB_OK);
    }

    // }}}
    // {{{ loadManager()

    /**
     * loads the Manager module
     *
     * @param string $scope information about what method is being loaded,
     *                       that is used for error messages
     * @access public
     */
    function loadManager($scope = '')
    {
        if (isset($this->manager) && is_object($this->manager)) {
            return(MDB_OK);
        }
        $result = $this->_loadModule($scope, 'Manager',
            'MDB_MANAGER_'.strtoupper($this->phptype).'_INCLUDED',
            'Manager/'.$this->phptype.'.php');
        if (MDB::isError($result)) {
            return($result);
        }
        $class_name = 'MDB_Manager_'.$this->dbsyntax;
        if (!class_exists($class_name)) {
            return($this->raiseError(MDB_ERROR_LOADMODULE, NULL, NULL,
                'Unable to load extension'));
        }
        @$this->manager = new $class_name;
        return(MDB_OK);
    }

    // }}}
    // {{{ autoCommit()

    /**
     * Define whether database changes done on the database be automatically
     * committed. This function may also implicitly start or end a transaction.
     *
     * @param boolean $auto_commit flag that indicates whether the database
     *      changes should be committed right after executing every query
     *      statement. If this argument is 0 a transaction implicitly started.
     *      Otherwise, if a transaction is in progress it is ended by committing
     *      any database changes that were pending.
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     */
    function autoCommit($auto_commit)
    {
        $this->debug('AutoCommit: ' . ($auto_commit ? 'On' : 'Off'));
        return($this->raiseError(MDB_ERROR_UNSUPPORTED, NULL, NULL,
            'Auto-commit transactions: transactions are not supported'));
    }

    // }}}
    // {{{ commit()

    /**
     * Commit the database changes done during a transaction that is in
     * progress. This function may only be called when auto-committing is
     * disabled, otherwise it will fail. Therefore, a new transaction is
     * implicitly started after committing the pending changes.
     *
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     */
    function commit()
    {
        $this->debug('Commit Transaction');
        return($this->raiseError(MDB_ERROR_UNSUPPORTED, NULL, NULL,
            'Commit transaction: commiting transactions are not supported'));
    }

    // }}}
    // {{{ rollback()

    /**
     * Cancel any database changes done during a transaction that is in
     * progress. This function may only be called when auto-committing is
     * disabled, otherwise it will fail. Therefore, a new transaction is
     * implicitly started after canceling the pending changes.
     *
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     */
    function rollback()
    {
        $this->debug('Rollback Transaction');
        return($this->raiseError(MDB_ERROR_UNSUPPORTED, NULL, NULL,
            'Rollback transaction: rolling back transactions are not supported'));
    }

    // }}}
    // {{{ disconnect()

    /**
     * Log out and disconnect from the database.
     *
     * @return mixed TRUE on success, FALSE if not connected and error
     *                object on error
     * @access public
     */
    function disconnect()
    {
        if ($this->in_transaction && !MDB::isError($this->rollback()) && !MDB::isError($this->autoCommit(TRUE))) {
            $this->in_transaction = FALSE;
        }
        return($this->_close());
    }

    // }}}
    // {{{ _close()

    /**
     * all the RDBMS specific things needed to close a DB connection
     *
     * @access private
     */
    function _close()
    {
        unset($GLOBALS['_MDB_databases'][$this->database]);
    }

    // }}}
    // {{{ setDatabase()

    /**
     * Select a different database
     *
     * @param string $name name of the database that should be selected
     * @return string name of the database previously connected to
     * @access public
     */
    function setDatabase($name)
    {
        $previous_database_name = $this->database_name;
        $this->database_name = $name;
        return($previous_database_name);
    }

    // }}}
    // {{{ setDSN()

    /**
     * set the DSN
     *
     * @param mixed     $dsninfo    DSN string or array
     * @return MDB_OK
     * @access public
     */
    function setDSN($dsn)
    {
        $dsninfo = MDB::parseDSN($dsn);
        if(isset($dsninfo['hostspec'])) {
            $this->host = $dsninfo['hostspec'];
        }
        if(isset($dsninfo['port'])) {
            $this->port = $dsninfo['port'];
        }
        if(isset($dsninfo['username'])) {
            $this->user = $dsninfo['username'];
        }
        if(isset($dsninfo['password'])) {
            $this->password = $dsninfo['password'];
        }
        if(isset($dsninfo['database'])) {
            $this->database_name = $dsninfo['database'];
        }
        return(MDB_OK);
    }

    // }}}
    // {{{ getDSN()

    /**
     * return the DSN as a string
     *
     * @param string     $type    type to return
     * @return mixed DSN in the chosen type
     * @access public
     */
    function getDSN($type = 'string')
    {
        switch($type) {
            case 'array':
                $dsn = array(
                    'phptype' => $this->phptype,
                    'username' => $this->user,
                    'password' => $this->password,
                    'hostspec' => $this->host,
                    'database' => $this->database_name
                );
                break;
            default:
                $dsn = $this->phptype.'://'.$this->user.':'
                    .$this->password.'@'.$this->host
                    .($this->port ? (':'.$this->port) : '')
                    .'/'.$this->database_name;
                break;
        }
        return($dsn);
    }

    // }}}
    // {{{ createDatabase()

    /**
     * create a new database
     *
     * @param string $name name of the database that should be created
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     */
    function createDatabase($name)
    {
        $result = $this->loadManager('Create database');
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->manager->createDatabase($this, $name));
    }

    // }}}
    // {{{ dropDatabase()

    /**
     * drop an existing database
     *
     * @param string $name name of the database that should be dropped
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     */
    function dropDatabase($name)
    {
        $result = $this->loadManager('Drop database');
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->manager->dropDatabase($this, $name));
    }

    // }}}
    // {{{ createTable()

    /**
     * create a new table
     *
     * @param string $name Name of the database that should be created
     * @param array $fields Associative array that contains the definition of
     *      each field of the new table. The indexes of the array entries are
     *      the names of the fields of the table an the array entry values are
     *      associative arrays like those that are meant to be passed with the
     *      field definitions to get[Type]Declaration() functions.
     *
     *      Example
     *        array(
     *            'id' => array(
     *                'type' => 'integer',
     *                'unsigned' => 1
     *                'notnull' => 1
     *                'default' => 0
     *            ),
     *            'name' => array(
     *                'type' => 'text',
     *                'length' => 12
     *            ),
     *            'password' => array(
     *                'type' => 'text',
     *                'length' => 12
     *            )
     *        );
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     */
    function createTable($name, $fields)
    {
        $result = $this->loadManager('Create table');
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->manager->createTable($this, $name, $fields));
    }

    // }}}
    // {{{ dropTable()

    /**
     * drop an existing table
     *
     * @param string $name name of the table that should be dropped
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     */
    function dropTable($name)
    {
        $result = $this->loadManager('Drop table');
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->manager->dropTable($this, $name));
    }

    // }}}
    // {{{ alterTable()

    /**
     * alter an existing table
     *
     * @param string $name name of the table that is intended to be changed.
     * @param array  $changes associative array that contains the details of
     *       each type of change that is intended to be performed. The types of
     *       changes that are currently supported are defined as follows:
     *
     *  name
     *      New name for the table.
     *
     *  AddedFields
     *      Associative array with the names of fields to be added as indexes of
     *      the array. The value of each entry of the array should be set to
     *      another associative array with the properties of the fields to be
     *      added. The properties of the fields should be the same as defined by
     *      the Metabase parser.
     *
     *      Additionally, there should be an entry named Declaration that is
     *      expected to contain the portion of the field declaration already in
     *       DBMS specific SQL code as it is used in the CREATE TABLE statement.
     *
     *  RemovedFields
     *      Associative array with the names of fields to be removed as indexes of
     *      the array. Currently the values assigned to each entry are ignored. An
     *      empty array should be used for future compatibility.
     *
     *  RenamedFields
     *      Associative array with the names of fields to be renamed as indexes of
     *      the array. The value of each entry of the array should be set to another
     *      associative array with the entry named name with the new field name and
     *      the entry named Declaration that is expected to contain the portion of
     *      the field declaration already in DBMS specific SQL code as it is used
     *      in the CREATE TABLE statement.
     *
     *  ChangedFields
     *      Associative array with the names of the fields to be changed as indexes
     *      of the array. Keep in mind that if it is intended to change either the
     *      name of a field and any other properties, the ChangedFields array
     *      entries should have the new names of the fields as array indexes.
     *
     *      The value of each entry of the array should be set to another
     *      associative array with the properties of the fields to that are meant
     *      to be changed as array entries. These entries should be assigned to the
     *      new values of the respective properties. The properties of the fields
     *      should be the* same as defined by the Metabase parser.
     *
     *      If the default property is meant to be added, removed or changed, there
     *      should also be an entry with index ChangedDefault assigned to 1.
     *      Similarly, if the notnull constraint is to be added or removed, there
     *      should also be an entry with index ChangedNotNull assigned to 1.
     *
     *      Additionally, there should be an entry named Declaration that is
     *      expected to contain the portion of the field changed declaration
     *      already in DBMS specific SQL code as it is used in the CREATE TABLE
     *      statement.
     *
     *  Example
     *      array(
     *          'name' => 'userlist',
     *          'AddedFields' => array(
     *              'quota' => array(
     *                  'type' => 'integer',
     *                  'unsigned' => 1,
     *                  'Declaration' => 'quota INT'
     *              )
     *          ),
     *          'RemovedFields' => array(
     *              'file_limit' => array(),
     *              'time_limit' => array()
     *          ),
     *          'ChangedFields' => array(
     *              'gender' => array(
     *                  'default' => 'M',
     *                  'ChangeDefault' => 1,
     *                  'Declaration' => "gender CHAR(1) DEFAULT 'M'"
     *              )
     *          ),
     *          'RenamedFields' => array(
     *              'sex' => array(
     *                  'name' => 'gender',
     *                  'Declaration' => "gender CHAR(1) DEFAULT 'M'"
     *              )
     *          )
     *      )
     *
     * @param boolean $check indicates whether the function should just check
     *       if the DBMS driver can perform the requested table alterations if
     *       the value is TRUE or actually perform them otherwise.
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     */
    function alterTable($name, $changes, $check)
    {
        $result = $this->loadManager('Alter table');
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->manager->alterTable($this, $name, $changes, $check));
    }

    // }}}
    // {{{ listDatabases()

    /**
     * list all databases
     *
     * @return mixed data array on success, a MDB error on failure
     * @access public
     */
    function listDatabases()
    {
        $result = $this->loadManager('List databases');
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->manager->listDatabases($this));
    }

    // }}}
    // {{{ listUsers()

    /**
     * list all users
     *
     * @return mixed data array on success, a MDB error on failure
     * @access public
     */
    function listUsers()
    {
        $result = $this->loadManager('List users');
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->manager->listUsers($this));
    }

    // }}}
    // {{{ listViews()

    /**
     * list all viewes in the current database
     *
     * @return mixed data array on success, a MDB error on failure
     * @access public
     */
    function listViews()
    {
        $result = $this->loadManager('List views');
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->manager->listViews($this));
    }

    // }}}
    // {{{ listFunctions()

    /**
     * list all functions in the current database
     *
     * @return mixed data array on success, a MDB error on failure
     * @access public
     */
    function listFunctions()
    {
        $result = $this->loadManager('List functions');
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->manager->listFunctions($this));
    }

    // }}}
    // {{{ listTables()

    /**
     * list all tables in the current database
     *
     * @return mixed data array on success, a MDB error on failure
     * @access public
     */
    function listTables()
    {
        $result = $this->loadManager('List tables');
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->manager->listTables($this));
    }

    // }}}
    // {{{ listTableFields()

    /**
     * list all fields in a tables in the current database
     *
     * @param string $table name of table that should be used in method
     * @return mixed data array on success, a MDB error on failure
     * @access public
     */
    function listTableFields($table)
    {
        $result = $this->loadManager('List table fields');
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->manager->listTableFields($this, $table));
    }

    // }}}
    // {{{ getTableFieldDefinition()

    /**
     * get the stucture of a field into an array
     *
     * @param string $table name of table that should be used in method
     * @param string $fields name of field that should be used in method
     * @return mixed data array on success, a MDB error on failure
     * @access public
     */
    function getTableFieldDefinition($table, $field)
    {
        $result = $this->loadManager('Get table field definition');
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->manager->getTableFieldDefinition($this, $table, $field));
    }

    // }}}
    // {{{ getFieldDeclaration()

    /**
     * get declaration of a field
     *
     * @param string $field_name name of the field to be created
     * @param string $field associative array with the name of the properties
     *       of the field being declared as array indexes. Currently, the types
     *       of supported field properties are as follows:
     *
     *       default
     *           Boolean value to be used as default for this field.
     *
     *       notnull
     *           Boolean flag that indicates whether this field is constrained
     *           to not be set to NULL.
     * @return mixed string on success, a MDB error on failure
     * @access public
     */
    function getFieldDeclaration($field_name, $field)
    {
        $result = $this->loadManager('Get table field definition');
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->manager->getFieldDeclaration($this, $field_name, $field));
    }

    // }}}
    // {{{ getFieldDeclarationList()

    /**
     * get declaration of a number of field in bulk
     *
     * @param string $fields a multidimensional associative array.
     * The first dimension determines the field name, while the second
     * dimension is keyed with the name of the properties
     *       of the field being declared as array indexes. Currently, the types
     *       of supported field properties are as follows:
     *
     *       default
     *           Boolean value to be used as default for this field.
     *
     *       notnull
     *           Boolean flag that indicates whether this field is constrained
     *           to not be set to NULL.
     *
     *       default
     *           Boolean value to be used as default for this field.
     *
     *       notnull
     *           Boolean flag that indicates whether this field is constrained
     *           to not be set to NULL.
     * @return mixed string on success, a MDB error on failure
     * @access public
     */
    function getFieldDeclarationList($fields)
    {
        $result = $this->loadManager('Get table field list');
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->manager->getFieldDeclarationList($this, $fields));
    }

    // }}}
    // {{{ _isSequenceName()

    /**
     * list all tables in the current database
     *
     * @param string $sqn string that containts name of a potential sequence
     * @return mixed name of the sequence if $sqn is a name of a sequence, else FALSE
     * @access private
     */
    function _isSequenceName($sqn)
    {
        $result = $this->loadManager('is sequence name');
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->manager->_isSequenceName($this, $sqn));
    }

    // }}}
    // {{{ createIndex()

    /**
     * get the stucture of a field into an array
     *
     * @param string $table name of the table on which the index is to be
     *       created
     * @param string $name name of the index to be created
     * @param array $definition associative array that defines properties of
     *       the index to be created. Currently, only one property named FIELDS
     *       is supported. This property is also an associative with the names
     *       of the index fields as array indexes. Each entry of this array is
     *       set to another type of associative array that specifies properties
     *       of the index that are specific to each field.
     *
     *       Currently, only the sorting property is supported. It should be
     *       used to define the sorting direction of the index. It may be set
     *       to either ascending or descending. Not all DBMS support index
     *       sorting direction configuration. The DBMS drivers of those that do
     *       not support it ignore this property. Use the function support() to
     *       determine whether the DBMS driver can manage indexes.
     *
     *       Example
     *          array(
     *              'FIELDS' => array(
     *                  'user_name' => array(
     *                      'sorting' => 'ascending'
     *                  ),
     *                  'last_login' => array()
     *              )
     *          )
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     */
    function createIndex($table, $name, $definition)
    {
        $result = $this->loadManager('Create index');
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->manager->createIndex($this, $table, $name, $definition));
    }

    // }}}
    // {{{ dropIndex()

    /**
     * drop existing index
     *
     * @param string $table name of table that should be used in method
     * @param string $name name of the index to be dropped
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     */
    function dropIndex($table, $name)
    {
        $result = $this->loadManager('Drop index');
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->manager->dropIndex($this, $table , $name));
    }

    // }}}
    // {{{ listTableIndexes()

    /**
     * list all indexes in a table
     *
     * @param string $table name of table that should be used in method
     * @return mixed data array on success, a MDB error on failure
     * @access public
     */
    function listTableIndexes($table)
    {
        $result = $this->loadManager('List table index');
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->manager->listTableIndexes($this, $table));
    }

    // }}}
    // {{{ getTableIndexDefinition()

    /**
     * get the stucture of an index into an array
     *
     * @param string $table name of table that should be used in method
     * @param string $index name of index that should be used in method
     * @return mixed data array on success, a MDB error on failure
     * @access public
     */
    function getTableIndexDefinition($table, $index)
    {
        $result = $this->loadManager('Get table index definition');
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->manager->getTableIndexDefinition($this, $table, $index));
    }

    // }}}
    // {{{ createSequence()

    /**
     * create sequence
     *
     * @param string $name name of the sequence to be created
     * @param string $start start value of the sequence; default is 1
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     */
    function createSequence($name, $start = 1)
    {
        $result = $this->loadManager('Create sequence');
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->manager->createSequence($this, $name, $start));
    }

    // }}}
    // {{{ dropSequence()

    /**
     * drop existing sequence
     *
     * @param string $name name of the sequence to be dropped
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     */
    function dropSequence($name)
    {
        $result = $this->loadManager('Drop sequence');
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->manager->dropSequence($this, $name));
    }

    // }}}
    // {{{ listSequences()

    /**
     * list all tables in the current database
     *
     * @return mixed data array on success, a MDB error on failure
     * @access public
     */
    function listSequences()
    {
        $result = $this->loadManager('List sequences');
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->manager->listSequences($this));
    }

    // }}}
    // {{{ getSequenceDefinition()

    /**
     * get the stucture of a sequence into an array
     *
     * @param string $sequence name of sequence that should be used in method
     * @return mixed data array on success, a MDB error on failure
     * @access public
     */
    function getSequenceDefinition($sequence)
    {
        $result = $this->loadManager('Get sequence definition');
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->manager->getSequenceDefinition($this, $sequence));
    }

    // }}}
    // {{{ query()

    /**
     * Send a query to the database and return any results
     *
     * @param string $query the SQL query
     * @param mixed   $types  array that contains the types of the columns in
     *                        the result set
     * @return mixed a result handle or MDB_OK on success, a MDB error on failure
     * @access public
     */
    function query($query, $types = NULL)
    {
        $this->debug("Query: $query");
        return($this->raiseError(MDB_ERROR_UNSUPPORTED, NULL, NULL, 'Query: database queries are not implemented'));
    }

    // }}}
    // {{{ setSelectedRowRange()

    /**
     * set the range of the next query
     *
     * @param string $first first row to select
     * @param string $limit number of rows to select
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     */
    function setSelectedRowRange($first, $limit)
    {
        if (!isset($this->supported['SelectRowRanges'])) {
            return($this->raiseError(MDB_ERROR_UNSUPPORTED, NULL, NULL,
                'Set selected row range: selecting row ranges is not supported by this driver'));
        }
        $first = (int)$first;
        if ($first < 0) {
            return($this->raiseError(MDB_ERROR_SYNTAX, NULL, NULL,
                'Set selected row range: it was not specified a valid first selected range row'));
        }
        $limit = (int)$limit;
        if ($limit < 1) {
            return($this->raiseError(MDB_ERROR_SYNTAX, NULL, NULL,
                'Set selected row range: it was not specified a valid selected range row limit'));
        }
        $this->first_selected_row = $first;
        $this->selected_row_limit = $limit;
        return(MDB_OK);
    }

    // }}}
    // {{{ limitQuery()

    /**
     * Generates a limited query
     *
     * @param string $query query
     * @param mixed   $types  array that contains the types of the columns in
     *                        the result set
     * @param integer $from the row to start to fetching
     * @param integer $count the numbers of rows to fetch
     * @return mixed a valid ressource pointer or a MDB_Error
     * @access public
     */
    function limitQuery($query, $types = NULL, $from, $count)
    {
        $result = $this->setSelectedRowRange($from, $count);
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->query($query, $types));
    }

    // }}}
    // {{{ subSelect()

    /**
     * simple subselect emulation: leaves the query untouched for all RDBMS
     * that support subselects
     *
     * @access public
     *
     * @param string $query the SQL query for the subselect that may only
     *                      return a column
     * @param string $quote determines if the data needs to be quoted before
     *                      being returned
     *
     * @return string the query
     */
    function subSelect($query, $quote = FALSE)
    {
        if ($this->supported['SubSelects'] == 1) {
            return($query);
        }
        return($this->raiseError(MDB_ERROR_UNSUPPORTED, NULL, NULL, 'Subselect: subselect not implemented'));
    }

    // }}}
    // {{{ replace()

    /**
     * Execute a SQL REPLACE query. A REPLACE query is identical to a INSERT
     * query, except that if there is already a row in the table with the same
     * key field values, the REPLACE query just updates its values instead of
     * inserting a new row.
     *
     * The REPLACE type of query does not make part of the SQL standards. Since
     * pratically only MySQL implements it natively, this type of query is
     * emulated through this method for other DBMS using standard types of
     * queries inside …

Large files files are truncated, but you can click here to view the full file