/lib/php/MDB/Common.php

<?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 a transaction to assure the atomicity of the operation.
     *
     * @param string $table name of the table on which the REPLACE query will
     *       be executed.
     * @param array $fields associative array that describes the fields and the
     *       values that will be inserted or updated in the specified table. The
     *       indexes of the array are the names of all the fields of the table.
     *       The values of the array are also associative arrays that describe
     *       the values and other properties of the table fields.
     *
     *       Here follows a list of field properties that need to be specified:
     *
     *       Value
     *           Value to be assigned to the specified field. This value may be
     *           of specified in database independent type format as this
     *           function can perform the necessary datatype conversions.
     *
     *           Default: this property is required unless the Null property is
     *           set to 1.
     *
     *       Type
     *           Name of the type of the field. Currently, all types Metabase
     *           are supported except for clob and blob.
     *
     *           Default: no type conversion
     *
     *       Null
     *           Boolean property that indicates that the value for this field
     *           should be set to NULL.
     *
     *           The default value for fields missing in INSERT queries may be
     *           specified the definition of a table. Often, the default value
     *           is already NULL, but since the REPLACE may be emulated using
     *           an UPDATE query, make sure that all fields of the table are
     *           listed in this function argument array.
     *
     *           Default: 0
     *
     *       Key
     *           Boolean property that indicates that this field should be
     *           handled as a primary key or at least as part of the compound
     *           unique index of the table that will determine the row that will
     *           updated if it exists or inserted a new row otherwise.
     *
     *           This function will fail if no key field is specified or if the
     *           value of a key field is set to NULL because fields that are
     *           part of unique index they may not be NULL.
     *
     *           Default: 0
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     */
    function replace($table, $fields)
    {
        if (!$this->supported['Replace']) {
            return($this->raiseError(MDB_ERROR_UNSUPPORTED, NULL, NULL, 'Replace: replace query is not supported'));
        }
        $count = count($fields);
        for($keys = 0, $condition = $insert = $values = '', reset($fields), $field = 0;
            $field < $count;
            next($fields), $field++)
        {
            $name = key($fields);
            if ($field > 0) {
                $insert .= ', ';
                $values .= ', ';
            }
            $insert .= $name;
            if (isset($fields[$name]['Null']) && $fields[$name]['Null']) {
                $value = 'NULL';
            } else {
                if(isset($fields[$name]['Type'])) {
                    switch ($fields[$name]['Type']) {
                        case 'text':
                            $value = $this->getTextValue($fields[$name]['Value']);
                            break;
                        case 'boolean':
                            $value = $this->getBooleanValue($fields[$name]['Value']);
                            break;
                        case 'integer':
                            $value = $this->getIntegerValue($fields[$name]['Value']);
                            break;
                        case 'decimal':
                            $value = $this->getDecimalValue($fields[$name]['Value']);
                            break;
                        case 'float':
                            $value = $this->getFloatValue($fields[$name]['Value']);
                            break;
                        case 'date':
                            $value = $this->getDateValue($fields[$name]['Value']);
                            break;
                        case 'time':
                            $value = $this->getTimeValue($fields[$name]['Value']);
                            break;
                        case 'timestamp':
                            $value = $this->getTimestampValue($fields[$name]['Value']);
                            break;
                        default:
                            return($this->raiseError(MDB_ERROR_CANNOT_REPLACE, NULL, NULL,
                                'no supported type for field "' . $name . '" specified'));
                    }
                } else {
                    $value = $fields[$name]['Value'];
                }
            }
            $values .= $value;
            if (isset($fields[$name]['Key']) && $fields[$name]['Key']) {
                if ($value === 'NULL') {
                    return($this->raiseError(MDB_ERROR_CANNOT_REPLACE, NULL, NULL,
                        'key values may not be NULL'));
                }
                $condition .= ($keys ? ' AND ' : ' WHERE ') . $name . '=' . $value;
                $keys++;
            }
        }
        if ($keys == 0) {
            return($this->raiseError(MDB_ERROR_CANNOT_REPLACE, NULL, NULL,
                'not specified which fields are keys'));
        }
        $in_transaction = $this->in_transaction;
        if (!$in_transaction && MDB::isError($result = $this->autoCommit(FALSE))) {
            return($result);
        }
        $success = $this->query("DELETE FROM $table$condition");
        if (!MDB::isError($success)) {
            $affected_rows = $this->affected_rows;
            $success = $this->query("INSERT INTO $table ($insert) VALUES ($values)");
            $affected_rows += $this->affected_rows;
        }

        if (!$in_transaction) {
            if (!MDB::isError($success)) {
                if (!MDB::isError($success = $this->commit())
                    && !MDB::isError($success = $this->autoCommit(TRUE))
                    && isset($this->supported['AffectedRows'])
                ) {
                    $this->affected_rows = $affected_rows;
                }
            } else {
                $this->rollback();
                $this->autoCommit(TRUE);
            }
        }
        return($success);
    }

    // }}}
    // {{{ prepareQuery()

    /**
     * Prepares a query for multiple execution with execute().
     * With some database backends, this is emulated.
     * prepareQuery() requires a generic query as string like
     * 'INSERT INTO numbers VALUES(?,?,?)'. The ? are wildcards.
     * Types of wildcards:
     *    ? - a quoted scalar value, i.e. strings, integers
     *
     * @param string $ the query to prepare
     * @return mixed resource handle for the prepared query on success, a DB
     *        error on failure
     * @access public
     * @see execute
     */
    function prepareQuery($query)
    {
        $this->debug("PrepareQuery: $query");
        $positions = array();
        for($position = 0;
            $position < strlen($query) && is_integer($question = strpos($query, '?', $position));
        ) {
            if (is_integer($quote = strpos($query, "'", $position))
                && $quote < $question
            ) {
                if (!is_integer($end_quote = strpos($query, "'", $quote + 1))) {
                    return($this->raiseError(MDB_ERROR_SYNTAX, NULL, NULL,
                        'Prepare query: query with an unterminated text string specified'));
                }
                switch ($this->escape_quotes) {
                    case '':
                    case "'":
                        $position = $end_quote + 1;
                        break;
                    default:
                        if ($end_quote == $quote + 1) {
                            $position = $end_quote + 1;
                        } else {
                            if ($query[$end_quote-1] == $this->escape_quotes) {
                                $position = $end_quote;
                            } else {
                                $position = $end_quote + 1;
                            }
                        }
                        break;
                }
            } else {
                $positions[] = $question;
                $position = $question + 1;
            }
        }
        $this->prepared_queries[] = array(
            'Query' => $query,
            'Positions' => $positions,
            'Values' => array(),
            'Types' => array()
            );
        $prepared_query = count($this->prepared_queries);
        if ($this->selected_row_limit > 0) {
            $this->prepared_queries[$prepared_query-1]['First'] = $this->first_selected_row;
            $this->prepared_queries[$prepared_query-1]['Limit'] = $this->selected_row_limit;
        }
        return($prepared_query);
    }

    // }}}
    // {{{ _validatePreparedQuery()

    /**
     * validate that a handle is infact a prepared query
     *
     * @param int $prepared_query argument is a handle that was returned by
     *       the function prepareQuery()
     * @access private
     */
    function _validatePreparedQuery($prepared_query)
    {
        if ($prepared_query < 1 || $prepared_query > count($this->prepared_queries)) {
            return($this->raiseError(MDB_ERROR_INVALID, NULL, NULL,
                'Validate prepared query: invalid prepared query'));
        }
        if (gettype($this->prepared_queries[$prepared_query-1]) != 'array') {
            return($this->raiseError(MDB_ERROR_INVALID, NULL, NULL,
                'Validate prepared query: prepared query was already freed'));
        }
        return(MDB_OK);
    }

    // }}}
    // {{{ freePreparedQuery()

    /**
     * Release resources allocated for the specified prepared query.
     *
     * @param int $prepared_query argument is a handle that was returned by
     *       the function prepareQuery()
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     */
    function freePreparedQuery($prepared_query)
    {
        $result = $this->_validatePreparedQuery($prepared_query);
        if (MDB::isError($result)) {
            return($result);
        }
        $this->prepared_queries[$prepared_query-1] = '';
        return(MDB_OK);
    }

    // }}}
    // {{{ _executePreparedQuery()

    /**
     * Execute a prepared query statement.
     *
     * @param int $prepared_query argument is a handle that was returned by
     *       the function prepareQuery()
     * @param string $query query to be executed
     * @param array $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 private
     */
    function _executePreparedQuery($prepared_query, $query, $types = NULL)
    {
        return($this->query($query, $types));
    }

    // }}}
    // {{{ executeQuery()

    /**
     * Execute a prepared query statement.
     *
     * @param int $prepared_query argument is a handle that was returned by
     *       the function prepareQuery()
     * @param array $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 executeQuery($prepared_query, $types = NULL)
    {
        $result = $this->_validatePreparedQuery($prepared_query);
        if (MDB::isError($result)) {
            return($result);
        }
        $index = $prepared_query-1;
        $success = MDB_OK;
        $this->clobs[$prepared_query] = $this->blobs[$prepared_query] = array();
        $query = '';
        for($last_position = $position = 0;
            $position < count($this->prepared_queries[$index]['Positions']);
            $position++) {
            if (!isset($this->prepared_queries[$index]['Values'][$position])) {
                return($this->raiseError(MDB_ERROR_NEED_MORE_DATA, NULL, NULL,
                    'Execute query: it was not defined query argument '.($position + 1)));
            }
            $current_position = $this->prepared_queries[$index]['Positions'][$position];
            $query .= substr($this->prepared_queries[$index]['Query'], $last_position, $current_position - $last_position);
            $value = $this->prepared_queries[$index]['Values'][$position];
            if ($this->prepared_queries[$index]['IsNULL'][$position]) {
                $query .= $value;
            } else {
                switch ($this->prepared_queries[$index]['Types'][$position]) {
                    case 'clob':
                        if (!MDB::isError($success = $this->getClobValue($prepared_query, $position + 1, $value))) {
                            $this->clobs[$prepared_query][$position + 1] = $success;
                            $query .= $this->clobs[$prepared_query][$position + 1];
                        }
                        break;
                    case 'blob':
                        if (!MDB::isError($success = $this->getBlobValue($prepared_query, $position + 1, $value))) {
                            $this->blobs[$prepared_query][$position + 1] = $success;
                            $query .= $this->blobs[$prepared_query][$position + 1];
                        }
                        break;
                    default:
                        $query .= $value;
                        break;
                }
            }
            $last_position = $current_position + 1;
        }
        if (!MDB::isError($success)) {
            $query .= substr($this->prepared_queries[$index]['Query'], $last_position);
            if ($this->selected_row_limit > 0) {
                $this->prepared_queries[$index]['First'] = $this->first_selected_row;
                $this->prepared_queries[$index]['Limit'] = $this->selected_row_limit;
            }
            if (isset($this->prepared_queries[$index]['Limit'])
                && $this->prepared_queries[$index]['Limit'] > 0
            ) {
                $this->first_selected_row = $this->prepared_queries[$index]['First'];
                $this->selected_row_limit = $this->prepared_queries[$index]['Limit'];
            } else {
                $this->first_selected_row = $this->selected_row_limit = 0;
            }
            $success = $this->_executePreparedQuery($prepared_query, $query, $types);
        }
        for(reset($this->clobs[$prepared_query]), $clob = 0;
            $clob < count($this->clobs[$prepared_query]);
            $clob++, next($this->clobs[$prepared_query])) {
            $this->freeClobValue($prepared_query, key($this->clobs[$prepared_query]), $this->clobs[$prepared_query][key($this->clobs[$prepared_query])], $success);
        }
        unset($this->clobs[$prepared_query]);
        for(reset($this->blobs[$prepared_query]), $blob = 0;
            $blob < count($this->blobs[$prepared_query]);
            $blob++, next($this->blobs[$prepared_query])) {
            $this->freeBlobValue($prepared_query, key($this->blobs[$prepared_query]), $this->blobs[$prepared_query][key($this->blobs[$prepared_query])], $success);
        }
        unset($this->blobs[$prepared_query]);
        return($success);
    }

    // }}}
    // {{{ execute()

    /**
     * Executes a prepared SQL query
     * With execute() the generic query of prepare is assigned with the given
     * data array. The values of the array inserted into the query in the same
     * order like the array order
     *
     * @param resource $prepared_query query handle from prepare()
     * @param array $types array that contains the types of the columns in
     *        the result set
     * @param array $params numeric array containing the data to insert into
     *        the query
     * @param array $param_types array that contains the types of the values
     *        defined in $params
     * @return mixed a new result handle or a MDB_Error when fail
     * @access public
     * @see prepare()
     */
    function execute($prepared_query, $types = NULL, $params = FALSE, $param_types = NULL)
    {
        $this->setParamArray($prepared_query, $params, $param_types);

        return($this->executeQuery($prepared_query, $types));
    }

    // }}}
    // {{{ executeMultiple()

    /**
     * This function does several execute() calls on the same statement handle.
     * $params must be an array indexed numerically from 0, one execute call is
     * done for every 'row' in the array.
     *
     * If an error occurs during execute(), executeMultiple() does not execute
     * the unfinished rows, but rather returns that error.
     *
     * @param resource $stmt query handle from prepare()
     * @param array $types array that contains the types of the columns in
     *        the result set
     * @param array $params numeric array containing the
     *        data to insert into the query
     * @param array $parAM_types array that contains the types of the values
     *        defined in $params
     * @return mixed a result handle or MDB_OK on success, a MDB error on failure
     * @access public
     * @see prepare(), execute()
     */
    function executeMultiple($prepared_query, $types = NULL, $params, $param_types = NULL)
    {
        for($i = 0, $j = count($params); $i < $j; $i++) {
            $result = $this->execute($prepared_query, $types, $params[$i], $param_types);
            if (MDB::isError($result)) {
                return($result);
            }
        }
        return(MDB_OK);
    }

    // }}}
    // {{{ setParam()

    /**
     * Set the value of a parameter of a prepared query.
     *
     * @param int $prepared_query argument is a handle that was returned
     *       by the function prepareQuery()
     * @param int $parameter the order number of the parameter in the query
     *       statement. The order number of the first parameter is 1.
     * @param string $type designation of the type of the parameter to be set.
     *       The designation of the currently supported types is as follows:
     *           text, boolean, integer, decimal, float, date, time, timestamp,
     *           clob, blob
     * @param mixed $value value that is meant to be assigned to specified
     *       parameter. The type of the value depends on the $type argument.
     * @param boolean $is_null flag that indicates whether whether the
     *       parameter is a NULL
     * @param string $field name of the field that is meant to be assigned
     *       with this parameter value when it is of type clob or blob
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     */
    function setParam($prepared_query, $parameter, $type, $value, $is_null = 0, $field = '')
    {
        $result = $this->_validatePreparedQuery($prepared_query);
        if (MDB::isError($result)) {
            return($result);
        }
        $index = $prepared_query - 1;
        if ($parameter < 1 || $parameter > count($this->prepared_queries[$index]['Positions'])) {
            return($this->raiseError(MDB_ERROR_SYNTAX, NULL, NULL,
                'Query set: it was not specified a valid argument number'));
        }
        $this->prepared_queries[$index]['Values'][$parameter-1] = $value;
        $this->prepared_queries[$index]['Types'][$parameter-1] = $type;
        $this->prepared_queries[$index]['Fields'][$parameter-1] = $field;
        $this->prepared_queries[$index]['IsNULL'][$parameter-1] = $is_null;
        return(MDB_OK);
    }

    // }}}
    // {{{ setParamArray()

    /**
     * Set the values of multiple a parameter of a prepared query in bulk.
     *
     * @param int $prepared_query argument is a handle that was returned by
     *       the function prepareQuery()
     * @param array $params array thats specifies all necessary infromation
     *       for setParam() the array elements must use keys corresponding to
     *       the number of the position of the parameter.
     * @param array $types array thats specifies the types of the fields
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     * @see setParam()
     */
    function setParamArray($prepared_query, $params, $types = NULL)
    {
        if (is_array($types)) {
            if (count($params) != count($types)) {
                return $this->raiseError(MDB_ERROR_SYNTAX, NULL, NULL,
                    'setParamArray: the number of given types ('.count($types).')'
                    .'is not corresponding to the number of given parameters ('.count($params).')');
            }
            for($i = 0, $j = count($params); $i < $j; ++$i) {
                switch ($types[$i]) {
                    case 'NULL':
                        $success = $this->setParam($prepared_query, $i + 1, $params[$i][0], 'NULL', 1, '');
                        break;
                    case 'text':
                        $success = $this->setParam($prepared_query, $i + 1, 'text', $this->getTextValue($params[$i]));
                        break;
                    case 'clob':
                        $success = $this->setParam($prepared_query, $i + 1, 'clob', $params[$i][0], 0, $params[$i][1]);
                        break;
                    case 'blob':
                        $success = $this->setParam($prepared_query, $i + 1, 'blob', $params[$i][0], 0, $params[$i][1]);
                        break;
                    case 'integer':
                        $success = $this->setParam($prepared_query, $i + 1, 'integer', $this->getIntegerValue($params[$i]));
                        break;
                    case 'boolean':
                        $success = $this->setParam($prepared_query, $i + 1, 'boolean', $this->getBooleanValue($params[$i]));
                        break;
                    case 'date':
                        $success = $this->setParam($prepared_query, $i + 1, 'date', $this->getDateValue($params[$i]));
                        break;
                    case 'timestamp':
                        $success = $this->setParam($prepared_query, $i + 1, 'timestamp', $this->getTimestampValue($params[$i]));
                        break;
                    case 'time':
                        $success = $this->setParam($prepared_query, $i + 1, 'time', $this->getTimeValue($params[$i]));
                        break;
                    case 'float':
                        $success = $this->setParam($prepared_query, $i + 1, 'float', $this->getFloatValue($params[$i]));
                        break;
                    case 'decimal':
                        $success = $this->setParam($prepared_query, $i + 1, 'decimal', $this->getDecimalValue($params[$i]));
                        break;
                    default:
                        $success = $this->setParam($prepared_query, $i + 1, 'text', $this->getTextValue($params[$i]));
                        break;
                }
                if (MDB::isError($success)) {
                    return($success);
                }
            }
        } else {
            for($i = 0, $j = count($params); $i < $j; ++$i) {
                $success = $this->setParam($prepared_query, $i + 1, 'text', $this->getTextValue($params[$i]));
                if (MDB::isError($success)) {
                    return($success);
                }
            }
        }
        return(MDB_OK);
    }

    // }}}
    // {{{ setParamNull()

    /**
     * Set the value of a parameter of a prepared query to NULL.
     *
     * @param int $prepared_query argument is a handle that was returned by
     *       the function prepareQuery()
     * @param int $parameter order number of the parameter in the query
     *       statement. The order number of the first parameter is 1.
     * @param string $type designation of the type of the parameter to be set.
     *       The designation of the currently supported types is list in the
     *       usage of the function  setParam()
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     * @see setParam()
     */
    function setParamNull($prepared_query, $parameter, $type)
    {
        return($this->setParam($prepared_query, $parameter, $type, 'NULL', 1, ''));
    }

    // }}}
    // {{{ setParamText()

    /**
     * Set a parameter of a prepared query with a text value.
     *
     * @param int $prepared_query argument is a handle that was returned by
     *       the function prepareQuery()
     * @param int $parameter order number of the parameter in the query
     *       statement. The order number of the first parameter is 1.
     * @param string $value text value that is meant to be assigned to
     *       specified parameter.
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     * @see setParam()
     */
    function setParamText($prepared_query, $parameter, $value)
    {
        return($this->setParam($prepared_query, $parameter, 'text', $this->getTextValue($value)));
    }

    // }}}
    // {{{ setParamClob()

    /**
     * Set a parameter of a prepared query with a character large object value.
     *
     * @param int $prepared_query argument is a handle that was returned by
     *       the function prepareQuery()
     * @param int $parameter order number of the parameter in the query
     *       statement. The order number of the first parameter is 1.
     * @param int $value handle of large object created with createLOB()
     *       function from which it will be read the data value that is meant
     *       to be assigned to specified parameter.
     * @param string $field name of the field of a INSERT or UPDATE query to
     *       which it will be assigned the value to specified parameter.
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     * @see setParam()
     */
    function setParamClob($prepared_query, $parameter, $value, $field)
    {
        return($this->setParam($prepared_query, $parameter, 'clob', $value, 0, $field));
    }

    // }}}
    // {{{ setParamBlob()

    /**
     * Set a parameter of a prepared query with a binary large object value.
     *
     * @param int $prepared_query argument is a handle that was returned by
     *       the function prepareQuery()
     * @param int $parameter order number of the parameter in the query
     *       statement. The order number of the first parameter is 1.
     * @param int $value handle of large object created with createLOB()
     *       function from which it will be read the data value that is meant
     *       to be assigned to specified parameter.
     * @param string $field name of the field of a INSERT or UPDATE query to
     *       which it will be assigned the value to specified parameter.
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     * @see setParam()
     */
    function setParamBlob($prepared_query, $parameter, $value, $field)
    {
        return($this->setParam($prepared_query, $parameter, 'blob', $value, 0, $field));
    }

    // }}}
    // {{{ setParamInteger()

    /**
     * Set a parameter of a prepared query with a text value.
     *
     * @param int $prepared_query argument is a handle that was returned by
     *       the function prepareQuery()
     * @param int $parameter order number of the parameter in the query
     *       statement. The order number of the first parameter is 1.
     * @param int $value an integer value that is meant to be assigned to
     *       specified parameter.
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     * @see setParam()
     */
    function setParamInteger($prepared_query, $parameter, $value)
    {
        return($this->setParam($prepared_query, $parameter, 'integer', $this->getIntegerValue($value)));
    }

    // }}}
    // {{{ setParamBoolean()

    /**
     * Set a parameter of a prepared query with a boolean value.
     *
     * @param int $prepared_query argument is a handle that was returned by
     *       the function prepareQuery()
     * @param int $parameter order number of the parameter in the query
     *       statement. The order number of the first parameter is 1.
     * @param boolean $value boolean value that is meant to be assigned to
     *       specified parameter.
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     * @see setParam()
     */
    function setParamBoolean($prepared_query, $parameter, $value)
    {
        return($this->setParam($prepared_query, $parameter, 'boolean', $this->getBooleanValue($value)));
    }

    // }}}
    // {{{ setParamDate()

    /**
     * Set a parameter of a prepared query with a date value.
     *
     * @param int $prepared_query argument is a handle that was returned by
     *       the function prepareQuery()
     * @param int $parameter order number of the parameter in the query
     *       statement. The order number of the first parameter is 1.
     * @param string $value date value that is meant to be assigned to
     *       specified parameter.
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     * @see setParam()
     */
    function setParamDate($prepared_query, $parameter, $value)
    {
        return($this->setParam($prepared_query, $parameter, 'date', $this->getDateValue($value)));
    }

    // }}}
    // {{{ setParamTimestamp()

    /**
     * Set a parameter of a prepared query with a time stamp value.
     *
     * @param int $prepared_query argument is a handle that was returned by
     *       the function prepareQuery()
     * @param int $parameter order number of the parameter in the query
     *       statement. The order number of the first parameter is 1.
     * @param string $value time stamp value that is meant to be assigned to
     *       specified parameter.
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     * @see setParam()
     */
    function setParamTimestamp($prepared_query, $parameter, $value)
    {
        return($this->setParam($prepared_query, $parameter, 'timestamp', $this->getTimestampValue($value)));
    }

    // }}}
    // {{{ setParamTime()

    /**
     * Set a parameter of a prepared query with a time value.
     *
     * @param int $prepared_query argument is a handle that was returned by
     *       the function prepareQuery()
     * @param int $parameter order number of the parameter in the query
     *       statement. The order number of the first parameter is 1.
     * @param string $value time value that is meant to be assigned to
     *       specified parameter.
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     * @see setParam()
     */
    function setParamTime($prepared_query, $parameter, $value)
    {
        return($this->setParam($prepared_query, $parameter, 'time', $this->getTimeValue($value)));
    }

    // }}}
    // {{{ setParamFloat()

    /**
     * Set a parameter of a prepared query with a float value.
     *
     * @param int $prepared_query argument is a handle that was returned by
     *       the function prepareQuery()
     * @param int $parameter order number of the parameter in the query
     *       statement. The order number of the first parameter is 1.
     * @param string $value float value that is meant to be assigned to
     *       specified parameter.
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     * @see setParam()
     */
    function setParamFloat($prepared_query, $parameter, $value)
    {
        return($this->setParam($prepared_query, $parameter, 'float', $this->getFloatValue($value)));
    }

    // }}}
    // {{{ setParamDecimal()

    /**
     * Set a parameter of a prepared query with a decimal value.
     *
     * @param int $prepared_query argument is a handle that was returned by
     *       the function prepareQuery()
     * @param int $parameter order number of the parameter in the query
     *       statement. The order number of the first parameter is 1.
     * @param string $value decimal value that is meant to be assigned to
     *       specified parameter.
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     * @see setParam()
     */
    function setParamDecimal($prepared_query, $parameter, $value)
    {
        return($this->setParam($prepared_query, $parameter, 'decimal', $this->getDecimalValue($value)));
    }

    // }}}
    // {{{ setResultTypes()

    /**
     * Define the list of types to be associated with the columns of a given
     * result set.
     *
     * This function may be called before invoking fetchInto(), fetchOne(),
     * fetchRow(), fetchCol() and fetchAll() so that the necessary data type
     * conversions are performed on the data to be retrieved by them. If this
     * function is not called, the type of all result set columns is assumed
     * to be text, thus leading to not perform any conversions.
     *
     * @param resource $result result identifier
     * @param string $types array variable that lists the
     *       data types to be expected in the result set columns. If this array
     *       contains less types than the number of columns that are returned
     *       in the result set, the remaining columns are assumed to be of the
     *       type text. Currently, the types clob and blob are not fully
     *       supported.
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access public
     */
    function setResultTypes($result, $types)
    {
        $result_value = intval($result);
        if (isset($this->result_types[$result_value])) {
            return($this->raiseError(MDB_ERROR_INVALID, NULL, NULL,
                'Set result types: attempted to redefine the types of the columns of a result set'));
        }
        $columns = $this->numCols($result);
        if (MDB::isError($columns)) {
            return($columns);
        }
        if ($columns < count($types)) {
            return($this->raiseError(MDB_ERROR_SYNTAX, NULL, NULL,
                'Set result types: it were specified more result types (' . count($types) . ') than result columns (' . $columns . ')'));
        }
        $valid_types = array(
            'text'      => MDB_TYPE_TEXT,
            'boolean'   => MDB_TYPE_BOOLEAN,
            'integer'   => MDB_TYPE_INTEGER,
            'decimal'   => MDB_TYPE_DECIMAL,
            'float'     => MDB_TYPE_FLOAT,
            'date'      => MDB_TYPE_DATE,
            'time'      => MDB_TYPE_TIME,
            'timestamp' => MDB_TYPE_TIMESTAMP,
            'clob'      => MDB_TYPE_CLOB,
            'blob'      => MDB_TYPE_BLOB
        );
        for($column = 0; $column < count($types); $column++) {
            if (!isset($valid_types[$types[$column]])) {
                return($this->raiseError(MDB_ERROR_UNSUPPORTED, NULL, NULL,
                    'Set result types: ' . $types[$column] . ' is not a supported column type'));
            }
            $this->result_types[$result_value][$column] = $valid_types[$types[$column]];
        }
        while ($column < $columns) {
            $this->result_types[$result_value][$column] = MDB_TYPE_TEXT;
            $column++;
        }
        return(MDB_OK);
    }

    // }}}
    // {{{ affectedRows()

    /**
     * returns the affected rows of a query
     *
     * @return mixed MDB_Error or number of rows
     * @access public
     */
    function affectedRows()
    {
        if ($this->affected_rows == -1) {
            return($this->raiseError(MDB_ERROR_NEED_MORE_DATA));
        }
        return($this->affected_rows);
    }

    // }}}
    // {{{ getColumnNames()

    /**
     * Retrieve the names of columns returned by the DBMS in a query result.
     *
     * @param resource $result result identifier
     * @return mixed associative array variable
     *       that holds the names of columns. The indexes of the array are
     *       the column names mapped to lower case and the values are the
     *       respective numbers of the columns starting from 0. Some DBMS may
     *       not return any columns when the result set does not contain any
     *       rows.
     *      a MDB error on failure
     * @access public
     */
    function getColumnNames($result)
    {
        return($this->raiseError(MDB_ERROR_UNSUPPORTED, NULL, NULL,
            'Get column names: obtaining result column names is not implemented'));
    }

    // }}}
    // {{{ numCols()

    /**
     * Count the number of columns returned by the DBMS in a query result.
     *
     * @param resource $result result identifier
     * @return mixed integer value with the number of columns, a MDB error
     *       on failure
     * @access public
     */
    function numCols($result)
    {
        return($this->raiseError(MDB_ERROR_UNSUPPORTED, NULL, NULL,
            'Number of columns: obtaining the number of result columns is not implemented'));
    }

    // }}}
    // {{{ endOfResult()

    /**
     * check if the end of the result set has been reached
     *
     * @param resource $result result identifier
     * @return mixed TRUE or FALSE on sucess, a MDB error on failure
     * @access public
     */
    function endOfResult($result)
    {
        return($this->raiseError(MDB_ERROR_UNSUPPORTED, NULL, NULL,
            'End of result: end of result method not implemented'));
    }

    // }}}
    // {{{ setFetchMode()

    /**
     * Sets which fetch mode should be used by default on queries
     * on this connection.
     *
     * @param integer $fetchmode MDB_FETCHMODE_ORDERED or MDB_FETCHMODE_ASSOC,
     *       possibly bit-wise OR'ed with MDB_FETCHMODE_FLIPPED.
     * @access public
     * @see MDB_FETCHMODE_ORDERED
     * @see MDB_FETCHMODE_ASSOC
     * @see MDB_FETCHMODE_FLIPPED
     */
    function setFetchMode($fetchmode)
    {
        switch ($fetchmode) {
            case MDB_FETCHMODE_ORDERED:
            case MDB_FETCHMODE_ASSOC:
                $this->fetchmode = $fetchmode;
                break;
            default:
                return($this->raiseError('invalid fetchmode mode'));
        }
    }

    // }}}
    // {{{ fetch()

    /**
     * fetch value from a result set
     *
     * @param resource $result result identifier
     * @param int $row number of the row where the data can be found
     * @param int $field field number where the data can be found
     * @return mixed string on success, a MDB error on failure
     * @access public
     */
    function fetch($result, $row, $field)
    {
        return($this->raiseError(MDB_ERROR_UNSUPPORTED, NULL, NULL,
            'Fetch: fetch result method not implemented'));
    }

    // }}}
    // {{{ fetchLob()

    /**
     * fetch a lob value from a result set
     *
     * @param resource $result result identifier
     * @param int $row number of the row where the data can be found
     * @param int $field field number where the data can be found
     * @return mixed string on success, a MDB error on failure
     * @access public
     */
    function fetchLob($result, $row, $field)
    {
        $lob = count($this->lobs) + 1;
        $this->lobs[$lob] = array(
            'Result' => $result,
            'Row' => $row,
            'Field' => $field,
            'Position' => 0
        );
        $dst_lob = array(
            'Database' => $this,
            'Error' => '',
            'Type' => 'resultlob',
            'ResultLOB' => $lob
        );
        if (MDB::isError($lob = $this->createLob($dst_lob))) {
            return($this->raiseError(MDB_ERROR, NULL, NULL,
                'Fetch LOB result: ' . $dst_lob['Error']));
        }
        return($lob);
    }

    // }}}
    // {{{ _retrieveLob()

    /**
     * fetch a float value from a result set
     *
     * @param int $lob handle to a lob created by the createLob() function
     * @return mixed MDB_OK on success, a MDB error on failure
     * @access private
     */
    function _retrieveLob($lob)
    {
        if (!isset($this->lobs[$lob])) {
            return($this->raiseError(MDB_ERROR_NEED_MORE_DATA, NULL, NULL,
                'Fetch LOB result: it was not specified a valid lob'));
        }
        if (!isset($this->lobs[$lob]['Value'])) {
            $this->lobs[$lob]['Value'] = $this->fetch($this->lobs[$lob]['Result'], $this->lobs[$lob]['Row'], $this->lobs[$lob]['Field']);
        }
        return(MDB_OK);
    }

    // }}}
    // {{{ endOfResultLob()

    /**
     * Determine whether it was reached the end of the large object and
     * therefore there is no more data to be read for the its input stream.
     *
     * @param int $lob handle to a lob created by the createLob() function
     * @return mixed TRUE or FALSE on success, a MDB error on failure
     * @access public
     */
    function endOfResultLob($lob)
    {
        $result = $this->_retrieveLob($lob);
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->lobs[$lob]['Position'] >= strlen($this->lobs[$lob]['Value']));
    }

    // }}}
    // {{{ _readResultLob()

    /**
     * Read data from large object input stream.
     *
     * @param int $lob handle to a lob created by the createLob() function
     * @param blob $data reference to a variable that will hold data to be
     *       read from the large object input stream
     * @param int $length integer value that indicates the largest ammount of
     *       data to be read from the large object input stream.
     * @return mixed length on success, a MDB error on failure
     * @access private
     */
    function _readResultLob($lob, &$data, $length)
    {
        $result = $this->_retrieveLob($lob);
        if (MDB::isError($result)) {
            return($result);
        }
        $length = min($length, strlen($this->lobs[$lob]['Value']) - $this->lobs[$lob]['Position']);
        $data = substr($this->lobs[$lob]['Value'], $this->lobs[$lob]['Position'], $length);
        $this->lobs[$lob]['Position'] += $length;
        return($length);
    }

    // }}}
    // {{{ _destroyResultLob()

    /**
     * Free any resources allocated during the lifetime of the large object
     * handler object.
     *
     * @param int $lob handle to a lob created by the createLob() function
     * @access private
     */
    function _destroyResultLob($lob)
    {
        if (isset($this->lobs[$lob])) {
            $this->lobs[$lob] = '';
        }
    }

    // }}}
    // {{{ fetchClob()

    /**
     * fetch a clob value from a result set
     *
     * @param resource $result result identifier
     * @param int $row number of the row where the data can be found
     * @param int $field field number where the data can be found
     * @return mixed content of the specified data cell, a MDB error on failure,
     *        a MDB error on failure
     * @access public
     */
    function fetchClob($result, $row, $field)
    {
        return($this->raiseError(MDB_ERROR_UNSUPPORTED, NULL, NULL,
            'fetch clob result method is not implemented'));
    }

    // }}}
    // {{{ fetchBlob()

    /**
     * fetch a blob value from a result set
     *
     * @param resource $result result identifier
     * @param int $row number of the row where the data can be found
     * @param int $field field number where the data can be found
     * @return mixed content of the specified data cell, a MDB error on failure
     * @access public
     */
    function fetchBlob($result, $row, $field)
    {
        return($this->raiseError(MDB_ERROR_UNSUPPORTED, NULL, NULL,
            'fetch blob result method is not implemented'));
    }

    // }}}
    // {{{ resultIsNull()

    /**
     * Determine whether the value of a query result located in given row and
     *    field is a NULL.
     *
     * @param resource $result result identifier
     * @param int $row number of the row where the data can be found
     * @param int $field field number where the data can be found
     * @return mixed TRUE or FALSE on success, a MDB error on failure
     * @access public
     */
    function resultIsNull($result, $row, $field)
    {
        $result = $this->fetch($result, $row, $field);
        if (MDB::isError($result)) {
            return($result);
        }
        return(!isset($result));
    }

    // }}}
    // {{{ _baseConvertResult()

    /**
     * general type conversion method
     *
     * @param mixed $value refernce to a value to be converted
     * @param int $type constant that specifies which type to convert to
     * @return object a MDB error on failure
     * @access private
     */
    function _baseConvertResult($value, $type)
    {
        switch ($type) {
            case MDB_TYPE_TEXT:
                return($value);
            case MDB_TYPE_BLOB:
                return($value);
            case MDB_TYPE_CLOB:
                return($value);
            case MDB_TYPE_INTEGER:
                return(intval($value));
            case MDB_TYPE_BOOLEAN:
                return ($value == 'Y') ? TRUE : FALSE;
            case MDB_TYPE_DECIMAL:
                return($value);
            case MDB_TYPE_FLOAT:
                return(doubleval($value));
            case MDB_TYPE_DATE:
                return($value);
            case MDB_TYPE_TIME:
                return($value);
            case MDB_TYPE_TIMESTAMP:
                return($value);
            case MDB_TYPE_CLOB:
                return($value);
            case MDB_TYPE_BLOB:
                return($this->raiseError(MDB_ERROR_INVALID, NULL, NULL,
                    'BaseConvertResult: attempt to convert result value to an unsupported type ' . $type));
            default:
                return($this->raiseError(MDB_ERROR_INVALID, NULL, NULL,
                    'BaseConvertResult: attempt to convert result value to an unknown type ' . $type));
        }
    }

    // }}}
    // {{{ convertResult()

    /**
     * convert a value to a RDBMS indepdenant MDB type
     *
     * @param mixed $value value to be converted
     * @param int $type constant that specifies which type to convert to
     * @return mixed converted value or a MDB error on failure
     * @access public
     */
    function convertResult($value, $type)
    {
        return($this->_baseConvertResult($value, $type));
    }

    // }}}
    // {{{ convertResultRow()

    /**
     * convert a result row
     *
     * @param resource $result result identifier
     * @param array $row array with data
     * @return mixed MDB_OK on success,  a MDB error on failure
     * @access public
     */
    function convertResultRow($result, $row)
    {
        $result_value = intval($result);
        if (isset($this->result_types[$result_value])) {
            $current_column = -1;
            foreach($row as $key => $column) {
                ++$current_column;
                if (!isset($this->result_types[$result_value][$current_column])
                   ||!isset($column)
                ) {
                    continue;
                }
                switch ($type = $this->result_types[$result_value][$current_column]) {
                    case MDB_TYPE_TEXT:
                    case MDB_TYPE_BLOB:
                    case MDB_TYPE_CLOB:
                        break;
                    case MDB_TYPE_INTEGER:
                        $row[$key] = intval($row[$key]);
                        break;
                    default:
                        $value = $this->convertResult($row[$key], $type);
                        if (MDB::isError($value)) {
                            return $value;
                        }
                        $row[$key] = $value;
                        break;
                }
            }
        }
        return ($row);
    }

    // }}}
    // {{{ fetchDate()

    /**
     * fetch a date value from a result set
     *
     * @param resource $result result identifier
     * @param int $row number of the row where the data can be found
     * @param int $field field number where the data can be found
     * @return mixed content of the specified data cell, a MDB error on failure
     * @access public
     */
    function fetchDate($result, $row, $field)
    {
        $value = $this->fetch($result, $row, $field);
        return($this->convertResult($value, MDB_TYPE_DATE));
    }

    // }}}
    // {{{ fetchTimestamp()

    /**
     * fetch a timestamp value from a result set
     *
     * @param resource $result result identifier
     * @param int $row number of the row where the data can be found
     * @param int $field field number where the data can be found
     * @return mixed content of the specified data cell, a MDB error on failure
     * @access public
     */
    function fetchTimestamp($result, $row, $field)
    {
        $value = $this->fetch($result, $row, $field);
        return($this->convertResult($value, MDB_TYPE_TIMESTAMP));
    }

    // }}}
    // {{{ fetchTime()

    /**
     * fetch a time value from a result set
     *
     * @param resource $result result identifier
     * @param int $row number of the row where the data can be found
     * @param int $field field number where the data can be found
     * @return mixed content of the specified data cell, a MDB error on failure
     * @access public
     */
    function fetchTime($result, $row, $field)
    {
        $value = $this->fetch($result, $row, $field);
        return($this->convertResult($value, MDB_TYPE_TIME));
    }

    // }}}
    // {{{ fetchBoolean()

    /**
     * fetch a boolean value from a result set
     *
     * @param resource $result result identifier
     * @param int $row number of the row where the data can be found
     * @param int $field field number where the data can be found
     * @return mixed content of the specified data cell, a MDB error on failure
     * @access public
     */
    function fetchBoolean($result, $row, $field)
    {
        $value = $this->fetch($result, $row, $field);
        return($this->convertResult($value, MDB_TYPE_BOOLEAN));
    }

    // }}}
    // {{{ fetchFloat()

    /**
     * fetch a float value from a result set
     *
     * @param resource $result result identifier
     * @param int $row number of the row where the data can be found
     * @param int $field field number where the data can be found
     * @return mixed content of the specified data cell, a MDB error on failure
     * @access public
     */
    function fetchFloat($result, $row, $field)
    {
        $value = $this->fetch($result, $row, $field);
        return($this->convertResult($value, MDB_TYPE_FLOAT));
    }

    // }}}
    // {{{ fetchDecimal()

    /**
     * fetch a decimal value from a result set
     *
     * @param resource $result result identifier
     * @param int $row number of the row where the data can be found
     * @param int $field field number where the data can be found
     * @return mixed content of the specified data cell, a MDB error on failure
     * @access public
     */
    function fetchDecimal($result, $row, $field)
    {
        $value = $this->fetch($result, $row, $field);
        return($this->convertResult($value, MDB_TYPE_DECIMAL));
    }

    // }}}
    // {{{ numRows()

    /**
     * returns the number of rows in a result object
     *
     * @param ressource $result a valid result ressouce pointer
     * @return mixed MDB_Error or the number of rows
     * @access public
     */
    function numRows($result)
    {
        return($this->raiseError(MDB_ERROR_UNSUPPORTED, NULL, NULL, 'Num Rows: number of rows method not implemented'));
    }

    // }}}
    // {{{ freeResult()

    /**
     * Free the internal resources associated with $result.
     *
     * @param  $result result identifier
     * @return boolean TRUE on success, FALSE if $result is invalid
     * @access public
     */
    function freeResult($result)
    {
        return($this->raiseError(MDB_ERROR_UNSUPPORTED, NULL, NULL, 'Free Result: free result method not implemented'));
    }

    // }}}
    // {{{ getIntegerDeclaration()

    /**
     * Obtain DBMS specific SQL code portion needed to declare an integer type
     * field to be used in statements like CREATE TABLE.
     *
     * @param string $name name the field to be declared.
     * @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:
     *
     *       unsigned
     *           Boolean flag that indicates whether the field should be
     *           declared as unsigned integer if possible.
     *
     *       default
     *           Integer 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 string DBMS specific SQL code portion that should be used to
     *       declare the specified field.
     * @access public
     */
    function getIntegerDeclaration($name, $field)
    {
        if (isset($field['unsigned'])) {
            $this->warnings[] = "unsigned integer field \"$name\" is being
                declared as signed integer";
        }
        return("$name INT" . (isset($field['default']) ? ' DEFAULT ' . $field['default'] : '') . (isset($field['notnull']) ? ' NOT NULL' : ''));
    }

    // }}}
    // {{{ getTextDeclaration()

    /**
     * Obtain DBMS specific SQL code portion needed to declare an text type
     * field to be used in statements like CREATE TABLE.
     *
     * @param string $name name the field to be declared.
     * @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:
     *
     *       length
     *           Integer value that determines the maximum length of the text
     *           field. If this argument is missing the field should be
     *           declared to have the longest length allowed by the DBMS.
     *
     *       default
     *           Text 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 string DBMS specific SQL code portion that should be used to
     *       declare the specified field.
     * @access public
     */
    function getTextDeclaration($name, $field)
    {
        return((isset($field['length']) ? "$name CHAR (" . $field['length'] . ')' : "$name TEXT") . (isset($field['default']) ? ' DEFAULT ' . $this->getTextValue($field['default']) : '') . (isset($field['notnull']) ? ' NOT NULL' : ''));
    }

    // }}}
    // {{{ getClobDeclaration()

    /**
     * Obtain DBMS specific SQL code portion needed to declare an character
     * large object type field to be used in statements like CREATE TABLE.
     *
     * @param string $name name the field to be declared.
     * @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:
     *
     *       length
     *           Integer value that determines the maximum length of the large
     *           object field. If this argument is missing the field should be
     *           declared to have the longest length allowed by the DBMS.
     *
     *       notnull
     *           Boolean flag that indicates whether this field is constrained
     *           to not be set to NULL.
     * @return string DBMS specific SQL code portion that should be used to
     *       declare the specified field.
     * @access public
     */
    function getClobDeclaration($name, $field)
    {
        return((isset($field['length']) ? "$name CHAR (" . $field['length'] . ')' : "$name TEXT") . (isset($field['default']) ? ' DEFAULT ' . $this->getTextValue($field['default']) : '') . (isset($field['notnull']) ? ' NOT NULL' : ''));
    }

    // }}}
    // {{{ getBlobDeclaration()

    /**
     * Obtain DBMS specific SQL code portion needed to declare an binary large
     * object type field to be used in statements like CREATE TABLE.
     *
     * @param string $name name the field to be declared.
     * @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:
     *
     *       length
     *           Integer value that determines the maximum length of the large
     *           object field. If this argument is missing the field should be
     *           declared to have the longest length allowed by the DBMS.
     *
     *       notnull
     *           Boolean flag that indicates whether this field is constrained
     *           to not be set to NULL.
     * @return string DBMS specific SQL code portion that should be used to
     *       declare the specified field.
     * @access public
     */
    function getBlobDeclaration($name, $field)
    {
        return((isset($field['length']) ? "$name CHAR (" . $field['length'] . ')' : "$name TEXT") . (isset($field['default']) ? ' DEFAULT ' . $this->getTextValue($field['default']) : '') . (isset($field['notnull']) ? ' NOT NULL' : ''));
    }

    // }}}
    // {{{ getBooleanDeclaration()

    /**
     * Obtain DBMS specific SQL code portion needed to declare a boolean type
     * field to be used in statements like CREATE TABLE.
     *
     * @param string $name name the field to be declared.
     * @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.
     *
     *       notnullL
     *           Boolean flag that indicates whether this field is constrained
     *           to not be set to NULL.
     * @return string DBMS specific SQL code portion that should be used to
     *       declare the specified field.
     * @access public
     */
    function getBooleanDeclaration($name, $field)
    {
        return("$name CHAR (1)" . (isset($field['default']) ? ' DEFAULT ' . $this->getBooleanValue($field['default']) : '') . (isset($field['notnull']) ? ' NOT NULL' : ''));
    }

    // }}}
    // {{{ getDateDeclaration()

    /**
     * Obtain DBMS specific SQL code portion needed to declare a date type
     * field to be used in statements like CREATE TABLE.
     *
     * @param string $name name the field to be declared.
     * @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
     *           Date 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 string DBMS specific SQL code portion that should be used to
     *       declare the specified field.
     * @access public
     */
    function getDateDeclaration($name, $field)
    {
        return("$name CHAR (" . strlen("YYYY-MM-DD") . ")" . (isset($field['default']) ? ' DEFAULT ' . $this->getDateValue($field['default']) : '') . (isset($field['notnull']) ? ' NOT NULL' : ''));
    }

    // }}}
    // {{{ getTimestampDeclaration()

    /**
     * Obtain DBMS specific SQL code portion needed to declare a timestamp
     * field to be used in statements like CREATE TABLE.
     *
     * @param string $name name the field to be declared.
     * @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
     *           Timestamp 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 string DBMS specific SQL code portion that should be used to
     *       declare the specified field.
     * @access public
     */
    function getTimestampDeclaration($name, $field)
    {
        return("$name CHAR (" . strlen("YYYY-MM-DD HH:MM:SS") . ")" . (isset($field['default']) ? ' DEFAULT ' . $this->getTimestampValue($field['default']) : '') . (isset($field['notnull']) ? ' NOT NULL' : ''));
    }

    // }}}
    // {{{ getTimeDeclaration()

    /**
     * Obtain DBMS specific SQL code portion needed to declare a time
     * field to be used in statements like CREATE TABLE.
     *
     * @param string $name name the field to be declared.
     * @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
     *           Time 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 string DBMS specific SQL code portion that should be used to
     *       declare the specified field.
     * @access public
     */
    function getTimeDeclaration($name, $field)
    {
        return("$name CHAR (" . strlen("HH:MM:SS") . ")" . (isset($field['default']) ? ' DEFAULT ' . $this->getTimeValue($field['default']) : '') . (isset($field['notnull']) ? ' NOT NULL' : ''));
    }

    // }}}
    // {{{ getFloatDeclaration()

    /**
     * Obtain DBMS specific SQL code portion needed to declare a float type
     * field to be used in statements like CREATE TABLE.
     *
     * @param string $name name the field to be declared.
     * @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
     *           Float 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 string DBMS specific SQL code portion that should be used to
     *       declare the specified field.
     * @access public
     */
    function getFloatDeclaration($name, $field)
    {
        return("$name TEXT " . (isset($field['default']) ? ' DEFAULT ' . $this->getFloatValue($field['default']) : '') . (isset($field['notnull']) ? ' NOT NULL' : ''));
    }

    // }}}
    // {{{ getDecimalDeclaration()

    /**
     * Obtain DBMS specific SQL code portion needed to declare a decimal type
     * field to be used in statements like CREATE TABLE.
     *
     * @param string $name name the field to be declared.
     * @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
     *           Decimal 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 string DBMS specific SQL code portion that should be used to
     *       declare the specified field.
     * @access public
     */
    function getDecimalDeclaration($name, $field)
    {
        return("$name TEXT " . (isset($field['default']) ? ' DEFAULT ' . $this->getDecimalValue($field['default']) : '') . (isset($field['notnull']) ? ' NOT NULL' : ''));
    }

    // }}}
    // {{{ getIntegerValue()

    /**
     * Convert a text value into a DBMS specific format that is suitable to
     * compose query statements.
     *
     * @param string $value text string value that is intended to be converted.
     * @return string text string that represents the given argument value in
     *       a DBMS specific format.
     * @access public
     */
    function getIntegerValue($value)
    {
        return(($value === NULL) ? 'NULL' : (int)$value);
    }

    // }}}
    // {{{ getTextValue()

    /**
     * Convert a text value into a DBMS specific format that is suitable to
     * compose query statements.
     *
     * @param string $value text string value that is intended to be converted.
     * @return string text string that already contains any DBMS specific
     *       escaped character sequences.
     * @access public
     */
    function getTextValue($value)
    {
        return(($value === NULL) ? 'NULL' : "'".$this->_quote($value)."'");
    }

    // }}}
    // {{{ getClobValue()

    /**
     * Convert a text value into a DBMS specific format that is suitable to
     * compose query statements.
     *
     * @param resource $prepared_query query handle from prepare()
     * @param  $parameter
     * @param  $clob
     * @return string text string that represents the given argument value in
     *       a DBMS specific format.
     * @access public
     */
    function getClobValue($prepared_query, $parameter, $clob)
    {
        return($this->raiseError(MDB_ERROR_UNSUPPORTED, NULL, NULL,
            'Get CLOB field value: prepared queries with values of type "clob" are not yet supported'));
    }

    // }}}
    // {{{ freeClobValue()

    /**
     * free a character large object
     *
     * @param resource $prepared_query query handle from prepare()
     * @param string $blob
     * @param string $value
     * @access public
     */
    function freeClobValue($prepared_query, $clob, &$value)
    {
    }

    // }}}
    // {{{ getBlobValue()

    /**
     * Convert a text value into a DBMS specific format that is suitable to
     * compose query statements.
     *
     * @param resource $prepared_query query handle from prepare()
     * @param  $parameter
     * @param  $blob
     * @return string text string that represents the given argument value in
     *       a DBMS specific format.
     * @access public
     */
    function getBlobValue($prepared_query, $parameter, $blob)
    {
        return($this->raiseError(MDB_ERROR_UNSUPPORTED, NULL, NULL,
            'Get BLOB field value: prepared queries with values of type "blob" are not yet supported'));
    }

    // }}}
    // {{{ freeBlobValue()

    /**
     * free a binary large object
     *
     * @param resource $prepared_query query handle from prepare()
     * @param string $blob
     * @param string $value
     * @access public
     */
    function freeBlobValue($prepared_query, $blob, &$value)
    {
    }

    // }}}
    // {{{ getBooleanValue()

    /**
     * Convert a text value into a DBMS specific format that is suitable to
     * compose query statements.
     *
     * @param string $value text string value that is intended to be converted.
     * @return string text string that represents the given argument value in
     *       a DBMS specific format.
     * @access public
     */
    function getBooleanValue($value)
    {
        return(($value === NULL) ? 'NULL' : ($value ? "'Y'" : "'N'"));
    }

    // }}}
    // {{{ getDateValue()

    /**
     * Convert a text value into a DBMS specific format that is suitable to
     * compose query statements.
     *
     * @param string $value text string value that is intended to be converted.
     * @return string text string that represents the given argument value in
     *       a DBMS specific format.
     * @access public
     */
    function getDateValue($value)
    {
        return(($value === NULL) ? 'NULL' : "'$value'");
    }

    // }}}
    // {{{ getTimestampValue()

    /**
     * Convert a text value into a DBMS specific format that is suitable to
     * compose query statements.
     *
     * @param string $value text string value that is intended to be converted.
     * @return string text string that represents the given argument value in
     *       a DBMS specific format.
     * @access public
     */
    function getTimestampValue($value)
    {
        return(($value === NULL) ? 'NULL' : "'$value'");
    }

    // }}}
    // {{{ getTimeValue()

    /**
     * Convert a text value into a DBMS specific format that is suitable to
     *       compose query statements.
     *
     * @param string $value text string value that is intended to be converted.
     * @return string text string that represents the given argument value in
     *       a DBMS specific format.
     * @access public
     */
    function getTimeValue($value)
    {
        return(($value === NULL) ? 'NULL' : "'$value'");
    }

    // }}}
    // {{{ getFloatValue()

    /**
     * Convert a text value into a DBMS specific format that is suitable to
     * compose query statements.
     *
     * @param string $value text string value that is intended to be converted.
     * @return string text string that represents the given argument value in
     *       a DBMS specific format.
     * @access public
     */
    function getFloatValue($value)
    {
        return(($value === NULL) ? 'NULL' : "'$value'");
    }

    // }}}
    // {{{ getDecimalValue()

    /**
     * Convert a text value into a DBMS specific format that is suitable to
     * compose query statements.
     *
     * @param string $value text string value that is intended to be converted.
     * @return string text string that represents the given argument value in
     *       a DBMS specific format.
     * @access public
     */
    function getDecimalValue($value)
    {
        return(($value === NULL) ? 'NULL' : "'$value'");
    }

    // }}}
    // {{{ getValue()

    /**
     * Convert a text value into a DBMS specific format that is suitable to
     * compose query statements.
     *
     * @param string $type type to which the value should be converted to
     * @param string $value text string value that is intended to be converted.
     * @return string text string that represents the given argument value in
     *       a DBMS specific format.
     * @access public
     */
    function getValue($type, $value)
    {
        if (empty($type)) {
            return($this->raiseError(MDB_ERROR_SYNTAX, NULL, NULL,
                'getValue: called without type to convert to'));
        }
        if (method_exists($this,"get{$type}Value")) {
            return $this->{"get{$type}Value"}($value);
        }
        return $value;
    }

    // }}}
    // {{{ support()

    /**
     * Tell whether a DB implementation or its backend extension
     * supports a given feature.
     *
     * @param string $feature name of the feature (see the MDB class doc)
     * @return boolean whether this DB implementation supports $feature
     * @access public
     */
    function support($feature)
    {
        return(isset($this->supported[$feature]) && $this->supported[$feature]);
    }

    // }}}
    // {{{ getSequenceName()

    /**
     * adds sequence name formating to a sequence name
     *
     * @param string $sqn name of the sequence
     * @return string formatted sequence name
     * @access public
     */
    function getSequenceName($sqn)
    {
        return sprintf($this->options['seqname_format'],
            preg_replace('/[^a-z0-9_]/i', '_', $sqn));
    }

    // }}}
    // {{{ nextId()

    /**
     * returns the next free id of a sequence
     *
     * @param string $seq_name name of the sequence
     * @param boolean $ondemand when TRUE the seqence is
     *                           automatic created, if it
     *                           not exists
     * @return mixed MDB_Error or id
     * @access public
     */
    function nextId($seq_name, $ondemand = FALSE)
    {
        return($this->raiseError(MDB_ERROR_NOT_CAPABLE, NULL, NULL,
            'Next Sequence: getting next sequence value not supported'));
    }

    // }}}
    // {{{ currId()

    /**
     * returns the current id of a sequence
     *
     * @param string $seq_name name of the sequence
     * @return mixed MDB_Error or id
     * @access public
     */
    function currId($seq_name)
    {
        $this->warnings[] = 'database does not support getting current
            sequence value, the sequence value was incremented';
        $this->expectError(MDB_ERROR_NOT_CAPABLE);
        $id = $this->nextId($seq_name);
        $this->popExpect(MDB_ERROR_NOT_CAPABLE);
        if (MDB::isError($id)) {
            if ($id->getCode() == MDB_ERROR_NOT_CAPABLE) {
                return($this->raiseError(MDB_ERROR_NOT_CAPABLE, NULL, NULL,
                    'Current Sequence: getting current sequence value not supported'));
            }
            return($id);
        }
        return($id);
    }

    // }}}
    // {{{ fetchInto()

    /**
     * Fetch a row and return data in an array.
     *
     * @param resource $result result identifier
     * @param int $fetchmode ignored
     * @param int $rownum the row number to fetch
     * @return mixed data array or NULL on success, a MDB error on failure
     * @access public
     */
    function fetchInto($result, $fetchmode = MDB_FETCHMODE_DEFAULT, $rownum = NULL)
    {
        $result_value = intval($result);
        if (MDB::isError($this->endOfResult($result))) {
            $this->freeResult($result);
            $result = $this->raiseError(MDB_ERROR_NEED_MORE_DATA, NULL, NULL,
                'Fetch field: result set is empty');
        }
        if ($rownum == NULL) {
            ++$this->highest_fetched_row[$result_value];
            $rownum = $this->highest_fetched_row[$result_value];
        } else {
            $this->highest_fetched_row[$result_value] =
                max($this->highest_fetched_row[$result_value], $row);
        }
        if ($fetchmode == MDB_FETCHMODE_DEFAULT) {
            $fetchmode = $this->fetchmode;
        }
        $columns = $this->numCols($result);
        if (MDB::isError($columns)) {
            return($columns);
        }
        if ($fetchmode & MDB_FETCHMODE_ASSOC) {
            $column_names = $this->getColumnNames($result);
        }
        for($column = 0; $column < $columns; $column++) {
            if (!$this->resultIsNull($result, $rownum, $column)) {
                $value = $this->fetch($result, $rownum, $column);
                if ($value === FALSE) {
                    if ($this->options['autofree']) {
                        $this->freeResult($result);
                    }
                    return(NULL);
                } elseif (MDB::isError($value)) {
                    if ($value->getMessage() == '') {
                        if ($this->options['autofree']) {
                            $this->freeResult($result);
                        }
                        return(NULL);
                    } else {
                        return($value);
                    }
                }
            }
            $row[$column] = $value;
        }
        if ($fetchmode & MDB_FETCHMODE_ASSOC) {
            $row = array_combine($column_names, $row);
            if (is_array($row) && $this->options['optimize'] == 'portability') {
                $row = array_change_key_case($row, CASE_LOWER);
            }
        }
        if (isset($this->result_types[$result_value])) {
            $row = $this->convertResultRow($result, $row);
        }
        return($row);
    }

    // }}}
    // {{{ fetchOne()

    /**
     * Fetch and return a field of data (it uses fetchInto for that)
     *
     * @param resource $result result identifier
     * @return mixed data on success, a MDB error on failure
     * @access public
     */
    function fetchOne($result)
    {
        $row = $this->fetchInto($result, MDB_FETCHMODE_ORDERED);
        if (!$this->options['autofree'] || $row != NULL) {
            $this->freeResult($result);
        }
        if (is_array($row)) {
            return($row[0]);
        }
        return($row);
    }

    // }}}
    // {{{ fetchRow()

    /**
     * Fetch and return a row of data (it uses fetchInto for that)
     *
     * @param resource $result result identifier
     * @param int $fetchmode how the array data should be indexed
     * @param int $rownum the row number to fetch
     * @return mixed data array on success, a MDB error on failure
     * @access public
     */
    function fetchRow($result, $fetchmode = MDB_FETCHMODE_DEFAULT, $rownum = NULL)
    {
        $row = $this->fetchInto($result, $fetchmode, $rownum);
        if (!$this->options['autofree'] || $row != NULL) {
            $this->freeResult($result);
        }
        return($row);
    }

    // }}}
    // {{{ fetchCol()

    /**
     * Fetch and return a column of data (it uses fetchInto for that)
     *
     * @param resource $result result identifier
     * @param int $colnum the row number to fetch
     * @return mixed data array on success, a MDB error on failure
     * @access public
     */
    function fetchCol($result, $colnum = 0)
    {
        $fetchmode = is_numeric($colnum) ? MDB_FETCHMODE_ORDERED : MDB_FETCHMODE_ASSOC;
        $column = array();
        $row = $this->fetchInto($result, $fetchmode);
        if (is_array($row)) {
            if (!array_key_exists($colnum, $row)) {
                return($this->raiseError(MDB_ERROR_TRUNCATED));
            }
            do {
                $column[] = $row[$colnum];
            } while (is_array($row = $this->fetchInto($result, $fetchmode)));
        }
        if (!$this->options['autofree']) {
            $this->freeResult($result);
        }
        if (MDB::isError($row)) {
            return($row);
        }
        return($column);
    }

    // }}}
    // {{{ fetchAll()

    /**
     * Fetch and return a column of data (it uses fetchInto for that)
     *
     * @param resource $result result identifier
     * @param int $fetchmode how the array data should be indexed
     * @param boolean $rekey if set to TRUE, the $all will have the first
     *       column as its first dimension
     * @param boolean $force_array used only when the query returns exactly
     *       two columns. If TRUE, the values of the returned array will be
     *       one-element arrays instead of scalars.
     * @param boolean $group if TRUE, the values of the returned array is
     *       wrapped in another array.  If the same key value (in the first
     *       column) repeats itself, the values will be appended to this array
     *       instead of overwriting the existing values.
     * @return mixed data array on success, a MDB error on failure
     * @access public
     * @see getAssoc()
     */
    function fetchAll($result, $fetchmode = MDB_FETCHMODE_DEFAULT, $rekey = FALSE, $force_array = FALSE, $group = FALSE)
    {
        if ($rekey) {
            $cols = $this->numCols($result);
            if (MDB::isError($cols)) {
                return($cols);
            }
            if ($cols < 2) {
                return($this->raiseError(MDB_ERROR_TRUNCATED));
            }
        }
        $all = array();
        while (is_array($row = $this->fetchInto($result, $fetchmode))) {
            if ($rekey) {
                if ($fetchmode & MDB_FETCHMODE_ASSOC) {
                    $key = reset($row);
                    unset($row[key($row)]);
                } else {
                    $key = array_shift($row);
                }
                if (!$force_array && count($row) == 1) {
                    $row = array_shift($row);
                }
                if ($group) {
                    $all[$key][] = $row;
                } else {
                    $all[$key] = $row;
                }
            } else {
                if ($fetchmode & MDB_FETCHMODE_FLIPPED) {
                    foreach ($row as $key => $val) {
                        $all[$key][] = $val;
                    }
                } else {
                   $all[] = $row;
                }
            }
        }
        if (!$this->options['autofree']) {
            $this->freeResult($result);
        }
        if (MDB::isError($row)) {
            return($row);
        }
        return($all);
    }

    // }}}
    // {{{ queryOne()

    /**
     * Execute the specified query, fetch the value from the first column of
     * the first row of the result set and then frees
     * the result set.
     *
     * @param string $query the SELECT query statement to be executed.
     * @param string $type optional argument that specifies the expected
     *       datatype of the result set field, so that an eventual conversion
     *       may be performed. The default datatype is text, meaning that no
     *       conversion is performed
     * @return mixed field value on success, a MDB error on failure
     * @access public
     */
    function queryOne($query, $type = NULL)
    {
        if ($type != NULL) {
            $type = array($type);
        }
        $result = $this->query($query, $type);
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->fetchOne($result));
    }

    // }}}
    // {{{ queryRow()

    /**
     * Execute the specified query, fetch the values from the first
     * row of the result set into an array and then frees
     * the result set.
     *
     * @param string $query the SELECT query statement to be executed.
     * @param array $types optional array argument that specifies a list of
     *       expected datatypes of the result set columns, so that the eventual
     *       conversions may be performed. The default list of datatypes is
     *       empty, meaning that no conversion is performed.
     * @param int $fetchmode how the array data should be indexed
     * @return mixed data array on success, a MDB error on failure
     * @access public
     */
    function queryRow($query, $types = NULL, $fetchmode = MDB_FETCHMODE_DEFAULT)
    {
        $result = $this->query($query, $types);
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->fetchRow($result, $fetchmode));
    }

    // }}}
    // {{{ queryCol()

    /**
     * Execute the specified query, fetch the value from the first column of
     * each row of the result set into an array and then frees the result set.
     *
     * @param string $query the SELECT query statement to be executed.
     * @param string $type optional argument that specifies the expected
     *       datatype of the result set field, so that an eventual conversion
     *       may be performed. The default datatype is text, meaning that no
     *       conversion is performed
     * @param int $colnum the row number to fetch
     * @return mixed data array on success, a MDB error on failure
     * @access public
     */
    function queryCol($query, $type = NULL, $colnum = 0)
    {
        if ($type != NULL) {
            $type = array($type);
        }
        $result = $this->query($query, $type);
        if (MDB::isError($result)) {
            return($result);
        }
        return($this->fetchCol($result, $colnum));
    }

    // }}}
    // {{{ queryAll()

    /**
     * Execute the specified query, fetch all the rows of the result set into
     * a two dimensional array and then frees the result set.
     *
     * @param string $query the SELECT query statement to be executed.
     * @param array $types optional array argument that specifies a list of
     *       expected datatypes of the result set columns, so that the eventual
     *       conversions may be performed. The default list of datatypes is
     *       empty, meaning that no conversion is performed.
     * @param int $fetchmode how the array data should be indexed
     * @param boolean $rekey if set to TRUE, the $all will have the first
     *       column as its first dimension
     * @param boolean $force_array used only when the query returns exactly
     *       two columns. If TRUE, the values of the returned array will be
     *       one-element arrays instead of scalars.
     * @param boolean $group if TRUE, the values of the returned array is
     *       wrapped in another array.  If the same key value (in the first
     *       column) repeats itself, the values will be appended to this array
     *       instead of overwriting the existing values.
     * @return mixed data array on success, a MDB error on failure
     * @access public
     */
    function queryAll($query, $types = NULL, $fetchmode = MDB_FETCHMODE_DEFAULT,
        $rekey = FALSE, $force_array = FALSE, $group = FALSE)
    {
        if (MDB::isError($result = $this->query($query, $types))) {
            return($result);
        }
        return($this->fetchAll($result, $fetchmode, $rekey, $force_array, $group));
    }

    // }}}
    // {{{ getOne()

    /**
     * Fetch the first column of the first row of data returned from
     * a query.  Takes care of doing the query and freeing the results
     * when finished.
     *
     * @param string $query the SQL query
     * @param string $type string that contains the type of the column in the
     *       result set
     * @param array $params if supplied, prepare/execute will be used
     *       with this array as execute parameters
     * @param array $param_types array that contains the types of the values
     *       defined in $params
     * @return mixed MDB_Error or the returned value of the query
     * @access public
     */
    function getOne($query, $type = NULL, $params = array(), $param_types = NULL)
    {
        if ($type != NULL) {
            $type = array($type);
        }
        settype($params, 'array');
        if (count($params) > 0) {
            $prepared_query = $this->prepareQuery($query);
            if (MDB::isError($prepared_query)) {
                return($prepared_query);
            }
            $this->setParamArray($prepared_query, $params, $param_types);
            $result = $this->executeQuery($prepared_query, $type);
        } else {
            $result = $this->query($query, $type);
        }

        if (MDB::isError($result)) {
            return($result);
        }

        $value = $this->fetchOne($result, MDB_FETCHMODE_ORDERED);
        if (MDB::isError($value)) {
            return($value);
        }
        if (isset($prepared_query)) {
            $result = $this->freePreparedQuery($prepared_query);
            if (MDB::isError($result)) {
                return($result);
            }
        }

        return($value);
    }

    // }}}
    // {{{ getRow()

    /**
     * Fetch the first row of data returned from a query.  Takes care
     * of doing the query and freeing the results when finished.
     *
     * @param string $query the SQL query
     * @param array $types array that contains the types of the columns in
     *       the result set
     * @param array $params array if supplied, prepare/execute will be used
     *       with this array as execute parameters
     * @param array $param_types array that contains the types of the values
     *       defined in $params
     * @param integer $fetchmode the fetch mode to use
     * @return array the first row of results as an array indexed from
     * 0, or a MDB error code.
     * @access public
     */
    function getRow($query, $types = NULL, $params = array(), $param_types = NULL, $fetchmode = MDB_FETCHMODE_DEFAULT)
    {
        settype($params, 'array');
        if (count($params) > 0) {
            $prepared_query = $this->prepareQuery($query);
            if (MDB::isError($prepared_query)) {
                return($prepared_query);
            }
            $this->setParamArray($prepared_query, $params, $param_types);
            $result = $this->executeQuery($prepared_query, $types);
        } else {
            $result = $this->query($query, $types);
        }

        if (MDB::isError($result)) {
            return($result);
        }

        $row = $this->fetchRow($result, $fetchmode);
        if (MDB::isError($row)) {
            return($row);
        }
        if (isset($prepared_query)) {
            $result = $this->freePreparedQuery($prepared_query);
            if (MDB::isError($result)) {
                return($result);
            }
        }

        return($row);
    }

    // }}}
    // {{{ getCol()

    /**
     * Fetch a single column from a result set and return it as an
     * indexed array.
     *
     * @param string $query the SQL query
     * @param string $type string that contains the type of the column in the
     *       result set
     * @param array $params array if supplied, prepare/execute will be used
     *       with this array as execute parameters
     * @param array $param_types array that contains the types of the values
     *       defined in $params
     * @param mixed $colnum which column to return(integer [column number,
     *       starting at 0] or string [column name])
     * @return array an indexed array with the data from the first
     * row at index 0, or a MDB error code.
     * @access public
     */
    function getCol($query, $type = NULL, $params = array(), $param_types = NULL, $colnum = 0)
    {
        if ($type != NULL) {
            $type = array($type);
        }
        settype($params, 'array');
        if (count($params) > 0) {
            $prepared_query = $this->prepareQuery($query);

            if (MDB::isError($prepared_query)) {
                return($prepared_query);
            }
            $this->setParamArray($prepared_query, $params, $param_types);
            $result = $this->executeQuery($prepared_query, $type);
        } else {
            $result = $this->query($query, $type);
        }

        if (MDB::isError($result)) {
            return($result);
        }

        $col = $this->fetchCol($result, $colnum);
        if (MDB::isError($col)) {
            return($col);
        }
        if (isset($prepared_query)) {
            $result = $this->freePreparedQuery($prepared_query);
            if (MDB::isError($result)) {
                return($result);
            }
        }
        return($col);
    }

    // }}}
    // {{{ getAssoc()

    /**
     * Fetch the entire result set of a query and return it as an
     * associative array using the first column as the key.
     *
     * If the result set contains more than two columns, the value
     * will be an array of the values from column 2-n.  If the result
     * set contains only two columns, the returned value will be a
     * scalar with the value of the second column (unless forced to an
     * array with the $force_array parameter).  A MDB error code is
     * returned on errors.  If the result set contains fewer than two
     * columns, a MDB_ERROR_TRUNCATED error is returned.
     *
     * For example, if the table 'mytable' contains:
     *
     *   ID      TEXT       DATE
     * --------------------------------
     *   1       'one'      944679408
     *   2       'two'      944679408
     *   3       'three'    944679408
     *
     * Then the call getAssoc('SELECT id,text FROM mytable') returns:
     *    array(
     *      '1' => 'one',
     *      '2' => 'two',
     *      '3' => 'three',
     *    )
     *
     * ...while the call getAssoc('SELECT id,text,date FROM mytable') returns:
     *    array(
     *      '1' => array('one', '944679408'),
     *      '2' => array('two', '944679408'),
     *      '3' => array('three', '944679408')
     *    )
     *
     * If the more than one row occurs with the same value in the
     * first column, the last row overwrites all previous ones by
     * default.  Use the $group parameter if you don't want to
     * overwrite like this.  Example:
     *
     * getAssoc('SELECT category,id,name FROM mytable', NULL, NULL
     *           MDB_FETCHMODE_ASSOC, FALSE, TRUE) returns:
     *    array(
     *      '1' => array(array('id' => '4', 'name' => 'number four'),
     *                   array('id' => '6', 'name' => 'number six')
     *             ),
     *      '9' => array(array('id' => '4', 'name' => 'number four'),
     *                   array('id' => '6', 'name' => 'number six')
     *             )
     *    )
     *
     * Keep in mind that database functions in PHP usually return string
     * values for results regardless of the database's internal type.
     *
     * @param string $query the SQL query
     * @param array $types array that contains the types of the columns in
     *       the result set
     * @param array $params array if supplied, prepare/execute will be used
     *       with this array as execute parameters
     * @param array $param_types array that contains the types of the values
     *       defined in $params
     * @param boolean $force_array used only when the query returns
     * exactly two columns.  If TRUE, the values of the returned array
     * will be one-element arrays instead of scalars.
     * @param boolean $group if TRUE, the values of the returned array
     *       is wrapped in another array.  If the same key value (in the first
     *       column) repeats itself, the values will be appended to this array
     *       instead of overwriting the existing values.
     * @return array associative array with results from the query.
     * @access public
     */
    function getAssoc($query, $types = NULL, $params = array(), $param_types = NULL,
        $fetchmode = MDB_FETCHMODE_ORDERED, $force_array = FALSE, $group = FALSE)
    {
        settype($params, 'array');
        if (count($params) > 0) {
            $prepared_query = $this->prepareQuery($query);

            if (MDB::isError($prepared_query)) {
                return($prepared_query);
            }
            $this->setParamArray($prepared_query, $params, $param_types);
            $result = $this->executeQuery($prepared_query, $types);
        } else {
            $result = $this->query($query, $types);
        }

        if (MDB::isError($result)) {
            return($result);
        }

        $all = $this->fetchAll($result, $fetchmode, TRUE, $force_array, $group);
        if (MDB::isError($all)) {
            return($all);
        }
        if (isset($prepared_query)) {
            $result = $this->freePreparedQuery($prepared_query);
            if (MDB::isError($result)) {
                return($result);
            }
        }
        return($all);
    }

    // }}}
    // {{{ getAll()

    /**
     * Fetch all the rows returned from a query.
     *
     * @param string $query the SQL query
     * @param array $types array that contains the types of the columns in
     *       the result set
     * @param array $params array if supplied, prepare/execute will be used
     *       with this array as execute parameters
     * @param array $param_types array that contains the types of the values
     *       defined in $params
     * @param integer $fetchmode the fetch mode to use
     * @return array an nested array, or a MDB error
     * @access public
     */
    function getAll($query, $types = NULL, $params = array(), $param_types = NULL, $fetchmode = MDB_FETCHMODE_DEFAULT)
    {
        settype($params, 'array');
        if (count($params) > 0) {
            $prepared_query = $this->prepareQuery($query);

            if (MDB::isError($prepared_query)) {
                return($prepared_query);
            }
            $this->setParamArray($prepared_query, $params, $param_types);
            $result = $this->executeQuery($prepared_query, $types);
        } else {
            $result = $this->query($query, $types);
        }

        if (MDB::isError($result)) {
            return($result);
        }

        $all = $this->fetchAll($result, $fetchmode);
        if (MDB::isError($all)) {
            return($all);
        }
        if (isset($prepared_query)) {
            $result = $this->freePreparedQuery($prepared_query);
            if (MDB::isError($result)) {
                return($result);
            }
        }
        return($all);
    }

    // }}}
    // {{{ tableInfo()

    /**
     * returns meta data about the result set
     *
     * @param resource $result result identifier
     * @param mixed $mode depends on implementation
     * @return array an nested array, or a MDB error
     * @access public
     */
    function tableInfo($result, $mode = NULL)
    {
        return($this->raiseError(MDB_ERROR_NOT_CAPABLE));
    }

    // }}}
    // {{{ createLob()

    /**
     * Create a handler object of a specified class with functions to
     * retrieve data from a large object data stream.
     *
     * @param array $arguments An associative array with parameters to create
     *                  the handler object. The array indexes are the names of
     *                  the parameters and the array values are the respective
     *                  parameter values.
     *
     *                  Some parameters are specific of the class of each type
     *                  of handler object that is created. The following
     *                  parameters are common to all handler object classes:
     *
     *                  Type
     *
     *                      Name of the type of the built-in supported class
     *                      that will be used to create the handler object.
     *                      There are currently four built-in types of handler
     *                      object classes: data, resultlob, inputfile and
     *                      outputfile.
     *
     *                      The data handler class is the default class. It
     *                      simply reads data from a given data string.
     *
     *                      The resultlob handler class is meant to read data
     *                      from a large object retrieved from a query result.
     *                      This class is not used directly by applications.
     *
     *                      The inputfile handler class is meant to read data
     *                      from a file to use in prepared queries with large
     *                      object field parameters.
     *
     *                      The outputfile handler class is meant to write to
     *                      a file data from result columns with large object
     *                      fields. The functions to read from this type of
     *                      large object do not return any data. Instead, the
     *                      data is just written to the output file with the
     *                      data retrieved from a specified large object handle.
     *
     *                  Class
     *
     *                      Name of the class of the handler object that will be
     *                      created if the Type argument is not specified. This
     *                      argument should be used when you need to specify a
     *                      custom handler class.
     *
     *                  Database
     *
     *                      Database object as returned by MDB::connect.
     *                      This is an option argument needed by some handler
     *                      classes like resultlob.
     *
     *                  The following arguments are specific of the inputfile
     *                  handler class:
     *
     *                      File
     *
     *                          Integer handle value of a file already opened
     *                          for writing.
     *
     *                      FileName
     *
     *                          Name of a file to be opened for writing if the
     *                          File argument is not specified.
     *
     *                  The following arguments are specific of the outputfile
     *                  handler class:
     *
     *                      File
     *
     *                          Integer handle value of a file already opened
     *                          for writing.
     *
     *                      FileName
     *
     *                          Name of a file to be opened for writing if the
     *                          File argument is not specified.
     *
     *                      BufferLength
     *
     *                          Integer value that specifies the length of a
     *                          buffer that will be used to read from the
     *                          specified large object.
     *
     *                      LOB
     *
     *                          Integer handle value that specifies a large
     *                          object from which the data to be stored in the
     *                          output file will be written.
     *
     *                      Result
     *
     *                          Integer handle value as returned by the function
     *                          MDB::query() or MDB::executeQuery() that specifies
     *                          the result set that contains the large object value
     *                          to be retrieved. If the LOB argument is specified,
     *                          this argument is ignored.
     *
     *                      Row
     *
     *                          Integer value that specifies the number of the
     *                          row of the result set that contains the large
     *                          object value to be retrieved. If the LOB
     *                          argument is specified, this argument is ignored.
     *
     *                      Field
     *
     *                          Integer or string value that specifies the
     *                          number or the name of the column of the result
     *                          set that contains the large object value to be
     *                          retrieved. If the LOB argument is specified,
     *                          this argument is ignored.
     *
     *                      Binary
     *
     *                          Boolean value that specifies whether the large
     *                          object column to be retrieved is of binary type
     *                          (blob) or otherwise is of character type (clob).
     *                          If the LOB argument is specified, this argument
     *                          is ignored.
     *
     *                  The following argument is specific of the data
     *                  handler class:
     *
     *                  Data
     *
     *                      String of data that will be returned by the class
     *                      when it requested with the readLOB() method.
     *
     *                  The following argument is specific of the resultlob
     *                  handler class:
     *
     *                      ResultLOB
     *
     *                          Integer handle value of a large object result
     *                          row field.
     * @return integer handle value that should be passed as argument insubsequent
     * calls to functions that retrieve data from the large object input stream.
     * @access public
     */
    function createLob($arguments)
    {
        $result = $this->loadLob('Create LOB');
        if (MDB::isError($result)) {
            return($result);
        }
        $class_name = 'MDB_LOB';
        if (isset($arguments['Type'])) {
            switch ($arguments['Type']) {
                case 'data':
                    break;
                case 'resultlob':
                    $class_name = 'MDB_LOB_Result';
                    break;
                case 'inputfile':
                    $class_name = 'MDB_LOB_Input_File';
                    break;
                case 'outputfile':
                    $class_name = 'MDB_LOB_Output_File';
                    break;
                default:
                    if (isset($arguments['Error'])) {
                        $arguments['Error'] = $arguments['Type'] . ' is not a valid type of large object';
                    }
                    return($this->raiseError());
            }
        } else {
            if (isset($arguments['Class'])) {
                $class = $arguments['Class'];
            }
        }
        $lob = count($GLOBALS['_MDB_lobs']) + 1;
        $GLOBALS['_MDB_lobs'][$lob] = &new $class_name;
        if (isset($arguments['Database'])) {
            $GLOBALS['_MDB_lobs'][$lob]->database = $arguments['Database'];
        } else {
            $GLOBALS['_MDB_lobs'][$lob]->database = &$this;
        }
        if (MDB::isError($result = $GLOBALS['_MDB_lobs'][$lob]->create($arguments))) {
            $GLOBALS['_MDB_lobs'][$lob]->database->destroyLob($lob);
            return($result);
        }
        return($lob);
    }

    // }}}
    // {{{ readLob()

    /**
     * Read data from large object input stream.
     *
     * @param integer $lob argument handle that is returned by the
     *                          MDB::createLob() method.
     * @param string $data reference to a variable that will hold data
     *                          to be read from the large object input stream
     * @param integer $length    value that indicates the largest ammount ofdata
     *                          to be read from the large object input stream.
     * @return mixed the effective number of bytes read from the large object
     *                      input stream on sucess or an MDB error object.
     * @access public
     * @see endOfLob()
     */
    function readLob($lob, &$data, $length)
    {
        return($GLOBALS['_MDB_lobs'][$lob]->readLob($data, $length));
    }

    // }}}
    // {{{ endOfLob()

    /**
     * Determine whether it was reached the end of the large object and
     * therefore there is no more data to be read for the its input stream.
     *
     * @param integer $lob argument handle that is returned by the
     *                          MDB::createLob() method.
     * @access public
     * @return boolean flag that indicates whether it was reached the end of the large object input stream
     */
    function endOfLob($lob)
    {
        return($GLOBALS['_MDB_lobs'][$lob]->endOfLob());
    }

    // }}}
    // {{{ destroyLob()

    /**
     * Free any resources allocated during the lifetime of the large object
     * handler object.
     *
     * @param integer $lob argument handle that is returned by the
     *                          MDB::createLob() method.
     * @access public
     */
    function destroyLob($lob)
    {
        $GLOBALS['_MDB_lobs'][$lob]->destroy();
        unset($GLOBALS['_MDB_lobs'][$lob]);
    }

    // }}}
    // {{{ Destructor

    /**
    * this function closes open transactions to be executed at shutdown
    *
    * @access private
    */
    function _MDB_Common()
    {
        if ($this->in_transaction && !MDB::isError($this->rollback())) {
            $this->autoCommit(TRUE);
        }
    }
};
?>