source: branches/dev/data/module/MDB2.php @ 15936

Revision 15936, 137.1 KB checked in by kakinaka, 15 years ago (diff)
Line 
1<?php
2// vim: set et ts=4 sw=4 fdm=marker:
3// +----------------------------------------------------------------------+
4// | PHP versions 4 and 5                                                 |
5// +----------------------------------------------------------------------+
6// | Copyright (c) 1998-2007 Manuel Lemos, Tomas V.V.Cox,                 |
7// | Stig. S. Bakken, Lukas Smith                                         |
8// | All rights reserved.                                                 |
9// +----------------------------------------------------------------------+
10// | MDB2 is a merge of PEAR DB and Metabases that provides a unified DB  |
11// | API as well as database abstraction for PHP applications.            |
12// | This LICENSE is in the BSD license style.                            |
13// |                                                                      |
14// | Redistribution and use in source and binary forms, with or without   |
15// | modification, are permitted provided that the following conditions   |
16// | are met:                                                             |
17// |                                                                      |
18// | Redistributions of source code must retain the above copyright       |
19// | notice, this list of conditions and the following disclaimer.        |
20// |                                                                      |
21// | Redistributions in binary form must reproduce the above copyright    |
22// | notice, this list of conditions and the following disclaimer in the  |
23// | documentation and/or other materials provided with the distribution. |
24// |                                                                      |
25// | Neither the name of Manuel Lemos, Tomas V.V.Cox, Stig. S. Bakken,    |
26// | Lukas Smith nor the names of his contributors may be used to endorse |
27// | or promote products derived from this software without specific prior|
28// | written permission.                                                  |
29// |                                                                      |
30// | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS  |
31// | "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT    |
32// | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS    |
33// | FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE      |
34// | REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,          |
35// | INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, |
36// | BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS|
37// |  OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED  |
38// | AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT          |
39// | LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY|
40// | WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE          |
41// | POSSIBILITY OF SUCH DAMAGE.                                          |
42// +----------------------------------------------------------------------+
43// | Author: Lukas Smith <smith@pooteeweet.org>                           |
44// +----------------------------------------------------------------------+
45//
46// $Id: MDB2.php,v 1.292 2007/04/25 09:31:01 quipo Exp $
47//
48
49/**
50 * @package     MDB2
51 * @category    Database
52 * @author      Lukas Smith <smith@pooteeweet.org>
53 */
54
55if(!defined('MDB2_PHP_DIR')) {
56    $MDB2_PHP_DIR = realpath(dirname( __FILE__));
57    define("MDB2_PHP_DIR", $MDB2_PHP_DIR); 
58}
59
60require_once MDB2_PHP_DIR . '/PEAR.php';
61
62// {{{ Error constants
63
64/**
65 * The method mapErrorCode in each MDB2_dbtype implementation maps
66 * native error codes to one of these.
67 *
68 * If you add an error code here, make sure you also add a textual
69 * version of it in MDB2::errorMessage().
70 */
71
72define('MDB2_OK',                      true);
73define('MDB2_ERROR',                     -1);
74define('MDB2_ERROR_SYNTAX',              -2);
75define('MDB2_ERROR_CONSTRAINT',          -3);
76define('MDB2_ERROR_NOT_FOUND',           -4);
77define('MDB2_ERROR_ALREADY_EXISTS',      -5);
78define('MDB2_ERROR_UNSUPPORTED',         -6);
79define('MDB2_ERROR_MISMATCH',            -7);
80define('MDB2_ERROR_INVALID',             -8);
81define('MDB2_ERROR_NOT_CAPABLE',         -9);
82define('MDB2_ERROR_TRUNCATED',          -10);
83define('MDB2_ERROR_INVALID_NUMBER',     -11);
84define('MDB2_ERROR_INVALID_DATE',       -12);
85define('MDB2_ERROR_DIVZERO',            -13);
86define('MDB2_ERROR_NODBSELECTED',       -14);
87define('MDB2_ERROR_CANNOT_CREATE',      -15);
88define('MDB2_ERROR_CANNOT_DELETE',      -16);
89define('MDB2_ERROR_CANNOT_DROP',        -17);
90define('MDB2_ERROR_NOSUCHTABLE',        -18);
91define('MDB2_ERROR_NOSUCHFIELD',        -19);
92define('MDB2_ERROR_NEED_MORE_DATA',     -20);
93define('MDB2_ERROR_NOT_LOCKED',         -21);
94define('MDB2_ERROR_VALUE_COUNT_ON_ROW', -22);
95define('MDB2_ERROR_INVALID_DSN',        -23);
96define('MDB2_ERROR_CONNECT_FAILED',     -24);
97define('MDB2_ERROR_EXTENSION_NOT_FOUND',-25);
98define('MDB2_ERROR_NOSUCHDB',           -26);
99define('MDB2_ERROR_ACCESS_VIOLATION',   -27);
100define('MDB2_ERROR_CANNOT_REPLACE',     -28);
101define('MDB2_ERROR_CONSTRAINT_NOT_NULL',-29);
102define('MDB2_ERROR_DEADLOCK',           -30);
103define('MDB2_ERROR_CANNOT_ALTER',       -31);
104define('MDB2_ERROR_MANAGER',            -32);
105define('MDB2_ERROR_MANAGER_PARSE',      -33);
106define('MDB2_ERROR_LOADMODULE',         -34);
107define('MDB2_ERROR_INSUFFICIENT_DATA',  -35);
108// }}}
109// {{{ Verbose constants
110/**
111 * These are just helper constants to more verbosely express parameters to prepare()
112 */
113
114define('MDB2_PREPARE_MANIP', false);
115define('MDB2_PREPARE_RESULT', null);
116
117// }}}
118// {{{ Fetchmode constants
119
120/**
121 * This is a special constant that tells MDB2 the user hasn't specified
122 * any particular get mode, so the default should be used.
123 */
124define('MDB2_FETCHMODE_DEFAULT', 0);
125
126/**
127 * Column data indexed by numbers, ordered from 0 and up
128 */
129define('MDB2_FETCHMODE_ORDERED', 1);
130
131/**
132 * Column data indexed by column names
133 */
134define('MDB2_FETCHMODE_ASSOC', 2);
135
136/**
137 * Column data as object properties
138 */
139define('MDB2_FETCHMODE_OBJECT', 3);
140
141/**
142 * For multi-dimensional results: normally the first level of arrays
143 * is the row number, and the second level indexed by column number or name.
144 * MDB2_FETCHMODE_FLIPPED switches this order, so the first level of arrays
145 * is the column name, and the second level the row number.
146 */
147define('MDB2_FETCHMODE_FLIPPED', 4);
148
149// }}}
150// {{{ Portability mode constants
151
152/**
153 * Portability: turn off all portability features.
154 * @see MDB2_Driver_Common::setOption()
155 */
156define('MDB2_PORTABILITY_NONE', 0);
157
158/**
159 * Portability: convert names of tables and fields to case defined in the
160 * "field_case" option when using the query*(), fetch*() and tableInfo() methods.
161 * @see MDB2_Driver_Common::setOption()
162 */
163define('MDB2_PORTABILITY_FIX_CASE', 1);
164
165/**
166 * Portability: right trim the data output by query*() and fetch*().
167 * @see MDB2_Driver_Common::setOption()
168 */
169define('MDB2_PORTABILITY_RTRIM', 2);
170
171/**
172 * Portability: force reporting the number of rows deleted.
173 * @see MDB2_Driver_Common::setOption()
174 */
175define('MDB2_PORTABILITY_DELETE_COUNT', 4);
176
177/**
178 * Portability: not needed in MDB2 (just left here for compatibility to DB)
179 * @see MDB2_Driver_Common::setOption()
180 */
181define('MDB2_PORTABILITY_NUMROWS', 8);
182
183/**
184 * Portability: makes certain error messages in certain drivers compatible
185 * with those from other DBMS's.
186 *
187 * + mysql, mysqli:  change unique/primary key constraints
188 *   MDB2_ERROR_ALREADY_EXISTS -> MDB2_ERROR_CONSTRAINT
189 *
190 * + odbc(access):  MS's ODBC driver reports 'no such field' as code
191 *   07001, which means 'too few parameters.'  When this option is on
192 *   that code gets mapped to MDB2_ERROR_NOSUCHFIELD.
193 *
194 * @see MDB2_Driver_Common::setOption()
195 */
196define('MDB2_PORTABILITY_ERRORS', 16);
197
198/**
199 * Portability: convert empty values to null strings in data output by
200 * query*() and fetch*().
201 * @see MDB2_Driver_Common::setOption()
202 */
203define('MDB2_PORTABILITY_EMPTY_TO_NULL', 32);
204
205/**
206 * Portability: removes database/table qualifiers from associative indexes
207 * @see MDB2_Driver_Common::setOption()
208 */
209define('MDB2_PORTABILITY_FIX_ASSOC_FIELD_NAMES', 64);
210
211/**
212 * Portability: turn on all portability features.
213 * @see MDB2_Driver_Common::setOption()
214 */
215define('MDB2_PORTABILITY_ALL', 127);
216
217// }}}
218// {{{ Globals for class instance tracking
219
220/**
221 * These are global variables that are used to track the various class instances
222 */
223
224$GLOBALS['_MDB2_databases'] = array();
225$GLOBALS['_MDB2_dsninfo_default'] = array(
226    'phptype'  => false,
227    'dbsyntax' => false,
228    'username' => false,
229    'password' => false,
230    'protocol' => false,
231    'hostspec' => false,
232    'port'     => false,
233    'socket'   => false,
234    'database' => false,
235    'mode'     => false,
236);
237
238// }}}
239// {{{ class MDB2
240
241/**
242 * The main 'MDB2' class is simply a container class with some static
243 * methods for creating DB objects as well as some utility functions
244 * common to all parts of DB.
245 *
246 * The object model of MDB2 is as follows (indentation means inheritance):
247 *
248 * MDB2          The main MDB2 class.  This is simply a utility class
249 *              with some 'static' methods for creating MDB2 objects as
250 *              well as common utility functions for other MDB2 classes.
251 *
252 * MDB2_Driver_Common   The base for each MDB2 implementation.  Provides default
253 * |            implementations (in OO lingo virtual methods) for
254 * |            the actual DB implementations as well as a bunch of
255 * |            query utility functions.
256 * |
257 * +-MDB2_Driver_mysql  The MDB2 implementation for MySQL. Inherits MDB2_Driver_Common.
258 *              When calling MDB2::factory or MDB2::connect for MySQL
259 *              connections, the object returned is an instance of this
260 *              class.
261 * +-MDB2_Driver_pgsql  The MDB2 implementation for PostGreSQL. Inherits MDB2_Driver_Common.
262 *              When calling MDB2::factory or MDB2::connect for PostGreSQL
263 *              connections, the object returned is an instance of this
264 *              class.
265 *
266 * @package     MDB2
267 * @category    Database
268 * @author      Lukas Smith <smith@pooteeweet.org>
269 */
270class MDB2
271{
272    // {{{ function setOptions(&$db, $options)
273
274    /**
275     * set option array   in an exiting database object
276     *
277     * @param   MDB2_Driver_Common  MDB2 object
278     * @param   array   An associative array of option names and their values.
279     *
280     * @return mixed   MDB2_OK or a PEAR Error object
281     *
282     * @access  public
283     */
284    function setOptions(&$db, $options)
285    {
286        if (is_array($options)) {
287            foreach ($options as $option => $value) {
288                $test = $db->setOption($option, $value);
289                if (PEAR::isError($test)) {
290                    return $test;
291                }
292            }
293        }
294        return MDB2_OK;
295    }
296
297    // }}}
298    // {{{ function classExists($classname)
299
300    /**
301     * Checks if a class exists without triggering __autoload
302     *
303     * @param   string  classname
304     *
305     * @return  bool    true success and false on error
306     * @static
307     * @access  public
308     */
309    function classExists($classname)
310    {
311        if (version_compare(phpversion(), "5.0", ">=")) {
312            return class_exists($classname, false);
313        }
314        return class_exists($classname);
315    }
316
317    // }}}
318    // {{{ function loadClass($class_name, $debug)
319
320    /**
321     * Loads a PEAR class.
322     *
323     * @param   string  classname to load
324     * @param   bool    if errors should be suppressed
325     *
326     * @return  mixed   true success or PEAR_Error on failure
327     *
328     * @access  public
329     */
330    function loadClass($class_name, $debug)
331    {
332        if (!MDB2::classExists($class_name)) {
333            $file_name = str_replace('_', DIRECTORY_SEPARATOR, $class_name).'.php';
334            if ($debug) {
335                $include = include_once($file_name);
336            } else {
337                $include = @include_once($file_name);
338            }
339            if (!$include) {
340                if (!MDB2::fileExists($file_name)) {
341                    $msg = "unable to find package '$class_name' file '$file_name'";
342                } else {
343                    $msg = "unable to load class '$class_name' from file '$file_name'";
344                }
345                $err =& MDB2::raiseError(MDB2_ERROR_NOT_FOUND, null, null, $msg);
346                return $err;
347            }
348        }
349        return MDB2_OK;
350    }
351
352    // }}}
353    // {{{ function &factory($dsn, $options = false)
354
355    /**
356     * Create a new MDB2 object for the specified database type
357     *
358     * IMPORTANT: In order for MDB2 to work properly it is necessary that
359     * you make sure that you work with a reference of the original
360     * object instead of a copy (this is a PHP4 quirk).
361     *
362     * For example:
363     *     $db =& MDB2::factory($dsn);
364     *          ^^
365     * And not:
366     *     $db = MDB2::factory($dsn);
367     *
368     * @param   mixed   'data source name', see the MDB2::parseDSN
369     *                      method for a description of the dsn format.
370     *                      Can also be specified as an array of the
371     *                      format returned by MDB2::parseDSN.
372     * @param   array   An associative array of option names and
373     *                            their values.
374     *
375     * @return  mixed   a newly created MDB2 object, or false on error
376     *
377     * @access  public
378     */
379    function &factory($dsn, $options = false)
380    {
381        $dsninfo = MDB2::parseDSN($dsn);
382        sfprintr($dsninfo);
383        if (empty($dsninfo['phptype'])) {
384            $err =& MDB2::raiseError(MDB2_ERROR_NOT_FOUND,
385                null, null, 'no RDBMS driver specified');
386            return $err;
387        }
388        $class_name = 'MDB2_Driver_'.$dsninfo['phptype'];
389
390        $debug = (!empty($options['debug']));
391        $err = MDB2::loadClass($class_name, $debug);
392        if (PEAR::isError($err)) {
393            return $err;
394        }
395
396        $db =& new $class_name();
397        $db->setDSN($dsninfo);
398        $err = MDB2::setOptions($db, $options);
399        if (PEAR::isError($err)) {
400            return $err;
401        }
402
403        return $db;
404    }
405
406    // }}}
407    // {{{ function &connect($dsn, $options = false)
408
409    /**
410     * Create a new MDB2 connection object and connect to the specified
411     * database
412     *
413     * IMPORTANT: In order for MDB2 to work properly it is necessary that
414     * you make sure that you work with a reference of the original
415     * object instead of a copy (this is a PHP4 quirk).
416     *
417     * For example:
418     *     $db =& MDB2::connect($dsn);
419     *          ^^
420     * And not:
421     *     $db = MDB2::connect($dsn);
422     *          ^^
423     *
424     * @param   mixed   'data source name', see the MDB2::parseDSN
425     *                            method for a description of the dsn format.
426     *                            Can also be specified as an array of the
427     *                            format returned by MDB2::parseDSN.
428     * @param   array   An associative array of option names and
429     *                            their values.
430     *
431     * @return  mixed   a newly created MDB2 connection object, or a MDB2
432     *                  error object on error
433     *
434     * @access  public
435     * @see     MDB2::parseDSN
436     */
437    function &connect($dsn, $options = false)
438    {
439        $db =& MDB2::factory($dsn, $options);
440        if (PEAR::isError($db)) {
441            return $db;
442        }
443
444        $err = $db->connect();
445        if (PEAR::isError($err)) {
446            $dsn = $db->getDSN('string', 'xxx');
447            $db->disconnect();
448            $err->addUserInfo($dsn);
449            return $err;
450        }
451
452        return $db;
453    }
454
455    // }}}
456    // {{{ function &singleton($dsn = null, $options = false)
457
458    /**
459     * Returns a MDB2 connection with the requested DSN.
460     * A new MDB2 connection object is only created if no object with the
461     * requested DSN exists yet.
462     *
463     * IMPORTANT: In order for MDB2 to work properly it is necessary that
464     * you make sure that you work with a reference of the original
465     * object instead of a copy (this is a PHP4 quirk).
466     *
467     * For example:
468     *     $db =& MDB2::singleton($dsn);
469     *          ^^
470     * And not:
471     *     $db = MDB2::singleton($dsn);
472     *          ^^
473     *
474     * @param   mixed   'data source name', see the MDB2::parseDSN
475     *                            method for a description of the dsn format.
476     *                            Can also be specified as an array of the
477     *                            format returned by MDB2::parseDSN.
478     * @param   array   An associative array of option names and
479     *                            their values.
480     *
481     * @return  mixed   a newly created MDB2 connection object, or a MDB2
482     *                  error object on error
483     *
484     * @access  public
485     * @see     MDB2::parseDSN
486     */
487    function &singleton($dsn = null, $options = false)
488    {
489        if ($dsn) {
490            $dsninfo = MDB2::parseDSN($dsn);
491            $dsninfo = array_merge($GLOBALS['_MDB2_dsninfo_default'], $dsninfo);
492            $keys = array_keys($GLOBALS['_MDB2_databases']);
493            for ($i=0, $j=count($keys); $i<$j; ++$i) {
494                if (isset($GLOBALS['_MDB2_databases'][$keys[$i]])) {
495                    $tmp_dsn = $GLOBALS['_MDB2_databases'][$keys[$i]]->getDSN('array');
496                    if (count(array_diff_assoc($tmp_dsn, $dsninfo)) == 0) {
497                        MDB2::setOptions($GLOBALS['_MDB2_databases'][$keys[$i]], $options);
498                        return $GLOBALS['_MDB2_databases'][$keys[$i]];
499                    }
500                }
501            }
502        } elseif (is_array($GLOBALS['_MDB2_databases']) && reset($GLOBALS['_MDB2_databases'])) {
503            $db =& $GLOBALS['_MDB2_databases'][key($GLOBALS['_MDB2_databases'])];
504            return $db;
505        }
506        $db =& MDB2::factory($dsn, $options);
507        return $db;
508    }
509
510    // }}}
511    // {{{ function loadFile($file)
512
513    /**
514     * load a file (like 'Date')
515     *
516     * @param   string  name of the file in the MDB2 directory (without '.php')
517     *
518     * @return  string  name of the file that was included
519     *
520     * @access  public
521     */
522    function loadFile($file)
523    {
524        $file_name = 'MDB2'.DIRECTORY_SEPARATOR.$file.'.php';
525        if (!MDB2::fileExists($file_name)) {
526            return MDB2::raiseError(MDB2_ERROR_NOT_FOUND, null, null,
527                'unable to find: '.$file_name);
528        }
529        if (!include_once($file_name)) {
530            return MDB2::raiseError(MDB2_ERROR_NOT_FOUND, null, null,
531                'unable to load driver class: '.$file_name);
532        }
533        return $file_name;
534    }
535
536    // }}}
537    // {{{ function apiVersion()
538
539    /**
540     * Return the MDB2 API version
541     *
542     * @return  string  the MDB2 API version number
543     *
544     * @access  public
545     */
546    function apiVersion()
547    {
548        return '2.4.1';
549    }
550
551    // }}}
552    // {{{ function &raiseError($code = null, $mode = null, $options = null, $userinfo = null)
553
554    /**
555     * This method is used to communicate an error and invoke error
556     * callbacks etc.  Basically a wrapper for PEAR::raiseError
557     * without the message string.
558     *
559     * @param   mixed  int error code
560     *
561     * @param   int    error mode, see PEAR_Error docs
562     *
563     * @param   mixed  If error mode is PEAR_ERROR_TRIGGER, this is the
564     *                 error level (E_USER_NOTICE etc).  If error mode is
565     *                 PEAR_ERROR_CALLBACK, this is the callback function,
566     *                 either as a function name, or as an array of an
567     *                 object and method name.  For other error modes this
568     *                 parameter is ignored.
569     *
570     * @param   string Extra debug information.  Defaults to the last
571     *                 query and native error code.
572     *
573     * @return PEAR_Error instance of a PEAR Error object
574     *
575     * @access  private
576     * @see     PEAR_Error
577     */
578    function &raiseError($code = null, $mode = null, $options = null, $userinfo = null)
579    {
580        $err =& PEAR::raiseError(null, $code, $mode, $options, $userinfo, 'MDB2_Error', true);
581        return $err;
582    }
583
584    // }}}
585    // {{{ function isError($data, $code = null)
586
587    /**
588     * Tell whether a value is a MDB2 error.
589     *
590     * @param   mixed   the value to test
591     * @param   int     if is an error object, return true
592     *                        only if $code is a string and
593     *                        $db->getMessage() == $code or
594     *                        $code is an integer and $db->getCode() == $code
595     *
596     * @return  bool    true if parameter is an error
597     *
598     * @access  public
599     */
600    function isError($data, $code = null)
601    {
602        if (is_a($data, 'MDB2_Error')) {
603            if (is_null($code)) {
604                return true;
605            } elseif (is_string($code)) {
606                return $data->getMessage() === $code;
607            } else {
608                $code = (array)$code;
609                return in_array($data->getCode(), $code);
610            }
611        }
612        return false;
613    }
614
615    // }}}
616    // {{{ function isConnection($value)
617
618    /**
619     * Tell whether a value is a MDB2 connection
620     *
621     * @param   mixed   value to test
622     *
623     * @return  bool    whether $value is a MDB2 connection
624     *
625     * @access  public
626     */
627    function isConnection($value)
628    {
629        return is_a($value, 'MDB2_Driver_Common');
630    }
631
632    // }}}
633    // {{{ function isResult($value)
634
635    /**
636     * Tell whether a value is a MDB2 result
637     *
638     * @param   mixed   value to test
639     *
640     * @return  bool    whether $value is a MDB2 result
641     *
642     * @access  public
643     */
644    function isResult($value)
645    {
646        return is_a($value, 'MDB2_Result');
647    }
648
649    // }}}
650    // {{{ function isResultCommon($value)
651
652    /**
653     * Tell whether a value is a MDB2 result implementing the common interface
654     *
655     * @param   mixed   value to test
656     *
657     * @return  bool    whether $value is a MDB2 result implementing the common interface
658     *
659     * @access  public
660     */
661    function isResultCommon($value)
662    {
663        return is_a($value, 'MDB2_Result_Common');
664    }
665
666    // }}}
667    // {{{ function isStatement($value)
668
669    /**
670     * Tell whether a value is a MDB2 statement interface
671     *
672     * @param   mixed   value to test
673     *
674     * @return  bool    whether $value is a MDB2 statement interface
675     *
676     * @access  public
677     */
678    function isStatement($value)
679    {
680        return is_a($value, 'MDB2_Statement');
681    }
682
683    // }}}
684    // {{{ function errorMessage($value = null)
685
686    /**
687     * Return a textual error message for a MDB2 error code
688     *
689     * @param   int|array   integer error code,
690                                null to get the current error code-message map,
691                                or an array with a new error code-message map
692     *
693     * @return  string  error message, or false if the error code was
694     *                  not recognized
695     *
696     * @access  public
697     */
698    function errorMessage($value = null)
699    {
700        static $errorMessages;
701
702        if (is_array($value)) {
703            $errorMessages = $value;
704            return MDB2_OK;
705        }
706
707        if (!isset($errorMessages)) {
708            $errorMessages = array(
709                MDB2_OK                       => 'no error',
710                MDB2_ERROR                    => 'unknown error',
711                MDB2_ERROR_ALREADY_EXISTS     => 'already exists',
712                MDB2_ERROR_CANNOT_CREATE      => 'can not create',
713                MDB2_ERROR_CANNOT_ALTER       => 'can not alter',
714                MDB2_ERROR_CANNOT_REPLACE     => 'can not replace',
715                MDB2_ERROR_CANNOT_DELETE      => 'can not delete',
716                MDB2_ERROR_CANNOT_DROP        => 'can not drop',
717                MDB2_ERROR_CONSTRAINT         => 'constraint violation',
718                MDB2_ERROR_CONSTRAINT_NOT_NULL=> 'null value violates not-null constraint',
719                MDB2_ERROR_DIVZERO            => 'division by zero',
720                MDB2_ERROR_INVALID            => 'invalid',
721                MDB2_ERROR_INVALID_DATE       => 'invalid date or time',
722                MDB2_ERROR_INVALID_NUMBER     => 'invalid number',
723                MDB2_ERROR_MISMATCH           => 'mismatch',
724                MDB2_ERROR_NODBSELECTED       => 'no database selected',
725                MDB2_ERROR_NOSUCHFIELD        => 'no such field',
726                MDB2_ERROR_NOSUCHTABLE        => 'no such table',
727                MDB2_ERROR_NOT_CAPABLE        => 'MDB2 backend not capable',
728                MDB2_ERROR_NOT_FOUND          => 'not found',
729                MDB2_ERROR_NOT_LOCKED         => 'not locked',
730                MDB2_ERROR_SYNTAX             => 'syntax error',
731                MDB2_ERROR_UNSUPPORTED        => 'not supported',
732                MDB2_ERROR_VALUE_COUNT_ON_ROW => 'value count on row',
733                MDB2_ERROR_INVALID_DSN        => 'invalid DSN',
734                MDB2_ERROR_CONNECT_FAILED     => 'connect failed',
735                MDB2_ERROR_NEED_MORE_DATA     => 'insufficient data supplied',
736                MDB2_ERROR_EXTENSION_NOT_FOUND=> 'extension not found',
737                MDB2_ERROR_NOSUCHDB           => 'no such database',
738                MDB2_ERROR_ACCESS_VIOLATION   => 'insufficient permissions',
739                MDB2_ERROR_LOADMODULE         => 'error while including on demand module',
740                MDB2_ERROR_TRUNCATED          => 'truncated',
741                MDB2_ERROR_DEADLOCK           => 'deadlock detected',
742            );
743        }
744
745        if (is_null($value)) {
746            return $errorMessages;
747        }
748
749        if (PEAR::isError($value)) {
750            $value = $value->getCode();
751        }
752
753        return isset($errorMessages[$value]) ?
754           $errorMessages[$value] : $errorMessages[MDB2_ERROR];
755    }
756
757    // }}}
758    // {{{ function parseDSN($dsn)
759
760    /**
761     * Parse a data source name.
762     *
763     * Additional keys can be added by appending a URI query string to the
764     * end of the DSN.
765     *
766     * The format of the supplied DSN is in its fullest form:
767     * <code>
768     *  phptype(dbsyntax)://username:password@protocol+hostspec/database?option=8&another=true
769     * </code>
770     *
771     * Most variations are allowed:
772     * <code>
773     *  phptype://username:password@protocol+hostspec:110//usr/db_file.db?mode=0644
774     *  phptype://username:password@hostspec/database_name
775     *  phptype://username:password@hostspec
776     *  phptype://username@hostspec
777     *  phptype://hostspec/database
778     *  phptype://hostspec
779     *  phptype(dbsyntax)
780     *  phptype
781     * </code>
782     *
783     * @param   string  Data Source Name to be parsed
784     *
785     * @return  array   an associative array with the following keys:
786     *  + phptype:  Database backend used in PHP (mysql, odbc etc.)
787     *  + dbsyntax: Database used with regards to SQL syntax etc.
788     *  + protocol: Communication protocol to use (tcp, unix etc.)
789     *  + hostspec: Host specification (hostname[:port])
790     *  + database: Database to use on the DBMS server
791     *  + username: User name for login
792     *  + password: Password for login
793     *
794     * @access  public
795     * @author  Tomas V.V.Cox <cox@idecnet.com>
796     */
797    function parseDSN($dsn)
798    {
799        $parsed = $GLOBALS['_MDB2_dsninfo_default'];
800
801        if (is_array($dsn)) {
802            $dsn = array_merge($parsed, $dsn);
803            if (!$dsn['dbsyntax']) {
804                $dsn['dbsyntax'] = $dsn['phptype'];
805            }
806            return $dsn;
807        }
808
809        // Find phptype and dbsyntax
810        if (($pos = strpos($dsn, '://')) !== false) {
811            $str = substr($dsn, 0, $pos);
812            $dsn = substr($dsn, $pos + 3);
813        } else {
814            $str = $dsn;
815            $dsn = null;
816        }
817
818        // Get phptype and dbsyntax
819        // $str => phptype(dbsyntax)
820        if (preg_match('|^(.+?)\((.*?)\)$|', $str, $arr)) {
821            $parsed['phptype']  = $arr[1];
822            $parsed['dbsyntax'] = !$arr[2] ? $arr[1] : $arr[2];
823        } else {
824            $parsed['phptype']  = $str;
825            $parsed['dbsyntax'] = $str;
826        }
827
828        if (!count($dsn)) {
829            return $parsed;
830        }
831
832        // Get (if found): username and password
833        // $dsn => username:password@protocol+hostspec/database
834        if (($at = strrpos($dsn,'@')) !== false) {
835            $str = substr($dsn, 0, $at);
836            $dsn = substr($dsn, $at + 1);
837            if (($pos = strpos($str, ':')) !== false) {
838                $parsed['username'] = rawurldecode(substr($str, 0, $pos));
839                $parsed['password'] = rawurldecode(substr($str, $pos + 1));
840            } else {
841                $parsed['username'] = rawurldecode($str);
842            }
843        }
844
845        // Find protocol and hostspec
846
847        // $dsn => proto(proto_opts)/database
848        if (preg_match('|^([^(]+)\((.*?)\)/?(.*?)$|', $dsn, $match)) {
849            $proto       = $match[1];
850            $proto_opts  = $match[2] ? $match[2] : false;
851            $dsn         = $match[3];
852
853        // $dsn => protocol+hostspec/database (old format)
854        } else {
855            if (strpos($dsn, '+') !== false) {
856                list($proto, $dsn) = explode('+', $dsn, 2);
857            }
858            if (   strpos($dsn, '//') === 0
859                && strpos($dsn, '/', 2) !== false
860                && $parsed['phptype'] == 'oci8'
861            ) {
862                //oracle's "Easy Connect" syntax:
863                //"username/password@[//]host[:port][/service_name]"
864                //e.g. "scott/tiger@//mymachine:1521/oracle"
865                $proto_opts = $dsn;
866                $dsn = null;
867            } elseif (strpos($dsn, '/') !== false) {
868                list($proto_opts, $dsn) = explode('/', $dsn, 2);
869            } else {
870                $proto_opts = $dsn;
871                $dsn = null;
872            }
873        }
874
875        // process the different protocol options
876        $parsed['protocol'] = (!empty($proto)) ? $proto : 'tcp';
877        $proto_opts = rawurldecode($proto_opts);
878        if (strpos($proto_opts, ':') !== false) {
879            list($proto_opts, $parsed['port']) = explode(':', $proto_opts);
880        }
881        if ($parsed['protocol'] == 'tcp') {
882            $parsed['hostspec'] = $proto_opts;
883        } elseif ($parsed['protocol'] == 'unix') {
884            $parsed['socket'] = $proto_opts;
885        }
886
887        // Get dabase if any
888        // $dsn => database
889        if ($dsn) {
890            // /database
891            if (($pos = strpos($dsn, '?')) === false) {
892                $parsed['database'] = $dsn;
893            // /database?param1=value1&param2=value2
894            } else {
895                $parsed['database'] = substr($dsn, 0, $pos);
896                $dsn = substr($dsn, $pos + 1);
897                if (strpos($dsn, '&') !== false) {
898                    $opts = explode('&', $dsn);
899                } else { // database?param1=value1
900                    $opts = array($dsn);
901                }
902                foreach ($opts as $opt) {
903                    list($key, $value) = explode('=', $opt);
904                    if (!isset($parsed[$key])) {
905                        // don't allow params overwrite
906                        $parsed[$key] = rawurldecode($value);
907                    }
908                }
909            }
910        }
911
912        return $parsed;
913    }
914
915    // }}}
916    // {{{ function fileExists($file)
917
918    /**
919     * Checks if a file exists in the include path
920     *
921     * @param   string  filename
922     *
923     * @return  bool    true success and false on error
924     *
925     * @access  public
926     */
927    function fileExists($file)
928    {
929        // safe_mode does notwork with is_readable()
930        if (!@ini_get('safe_mode')) {
931             $dirs = explode(PATH_SEPARATOR, ini_get('include_path'));
932             foreach ($dirs as $dir) {
933                 if (is_readable($dir . DIRECTORY_SEPARATOR . $file)) {
934                     return true;
935                 }
936            }
937        } else {
938            $fp = @fopen($file, 'r', true);
939            if (is_resource($fp)) {
940                @fclose($fp);
941                return true;
942            }
943        }
944        return false;
945    }
946    // }}}
947}
948
949// }}}
950// {{{ class MDB2_Error extends PEAR_Error
951
952/**
953 * MDB2_Error implements a class for reporting portable database error
954 * messages.
955 *
956 * @package     MDB2
957 * @category    Database
958 * @author Stig Bakken <ssb@fast.no>
959 */
960class MDB2_Error extends PEAR_Error
961{
962    // {{{ constructor: function MDB2_Error($code = MDB2_ERROR, $mode = PEAR_ERROR_RETURN, $level = E_USER_NOTICE, $debuginfo = null)
963
964    /**
965     * MDB2_Error constructor.
966     *
967     * @param   mixed   MDB2 error code, or string with error message.
968     * @param   int     what 'error mode' to operate in
969     * @param   int     what error level to use for $mode & PEAR_ERROR_TRIGGER
970     * @param   smixed   additional debug info, such as the last query
971     */
972    function MDB2_Error($code = MDB2_ERROR, $mode = PEAR_ERROR_RETURN,
973              $level = E_USER_NOTICE, $debuginfo = null)
974    {
975        if (is_null($code)) {
976            $code = MDB2_ERROR;
977        }
978        $this->PEAR_Error('MDB2 Error: '.MDB2::errorMessage($code), $code,
979            $mode, $level, $debuginfo);
980    }
981
982    // }}}
983}
984
985// }}}
986// {{{ class MDB2_Driver_Common extends PEAR
987
988/**
989 * MDB2_Driver_Common: Base class that is extended by each MDB2 driver
990 *
991 * @package     MDB2
992 * @category    Database
993 * @author      Lukas Smith <smith@pooteeweet.org>
994 */
995class MDB2_Driver_Common extends PEAR
996{
997    // {{{ Variables (Properties)
998
999    /**
1000     * index of the MDB2 object within the $GLOBALS['_MDB2_databases'] array
1001     * @var     int
1002     * @access  public
1003     */
1004    var $db_index = 0;
1005
1006    /**
1007     * DSN used for the next query
1008     * @var     array
1009     * @access  protected
1010     */
1011    var $dsn = array();
1012
1013    /**
1014     * DSN that was used to create the current connection
1015     * @var     array
1016     * @access  protected
1017     */
1018    var $connected_dsn = array();
1019
1020    /**
1021     * connection resource
1022     * @var     mixed
1023     * @access  protected
1024     */
1025    var $connection = 0;
1026
1027    /**
1028     * if the current opened connection is a persistent connection
1029     * @var     bool
1030     * @access  protected
1031     */
1032    var $opened_persistent;
1033
1034    /**
1035     * the name of the database for the next query
1036     * @var     string
1037     * @access  protected
1038     */
1039    var $database_name = '';
1040
1041    /**
1042     * the name of the database currently selected
1043     * @var     string
1044     * @access  protected
1045     */
1046    var $connected_database_name = '';
1047
1048    /**
1049     * server version information
1050     * @var     string
1051     * @access  protected
1052     */
1053    var $connected_server_info = '';
1054
1055    /**
1056     * list of all supported features of the given driver
1057     * @var     array
1058     * @access  public
1059     */
1060    var $supported = array(
1061        'sequences' => false,
1062        'indexes' => false,
1063        'affected_rows' => false,
1064        'summary_functions' => false,
1065        'order_by_text' => false,
1066        'transactions' => false,
1067        'savepoints' => false,
1068        'current_id' => false,
1069        'limit_queries' => false,
1070        'LOBs' => false,
1071        'replace' => false,
1072        'sub_selects' => false,
1073        'auto_increment' => false,
1074        'primary_key' => false,
1075        'result_introspection' => false,
1076        'prepared_statements' => false,
1077        'identifier_quoting' => false,
1078        'pattern_escaping' => false,
1079        'new_link' => false,
1080    );
1081
1082    /**
1083     * Array of supported options that can be passed to the MDB2 instance.
1084     *
1085     * The options can be set during object creation, using
1086     * MDB2::connect(), MDB2::factory() or MDB2::singleton(). The options can
1087     * also be set after the object is created, using MDB2::setOptions() or
1088     * MDB2_Driver_Common::setOption().
1089     * The list of available option includes:
1090     * <ul>
1091     *  <li>$options['ssl'] -> boolean: determines if ssl should be used for connections</li>
1092     *  <li>$options['field_case'] -> CASE_LOWER|CASE_UPPER: determines what case to force on field/table names</li>
1093     *  <li>$options['disable_query'] -> boolean: determines if queries should be executed</li>
1094     *  <li>$options['result_class'] -> string: class used for result sets</li>
1095     *  <li>$options['buffered_result_class'] -> string: class used for buffered result sets</li>
1096     *  <li>$options['result_wrap_class'] -> string: class used to wrap result sets into</li>
1097     *  <li>$options['result_buffering'] -> boolean should results be buffered or not?</li>
1098     *  <li>$options['fetch_class'] -> string: class to use when fetch mode object is used</li>
1099     *  <li>$options['persistent'] -> boolean: persistent connection?</li>
1100     *  <li>$options['debug'] -> integer: numeric debug level</li>
1101     *  <li>$options['debug_handler'] -> string: function/method that captures debug messages</li>
1102     *  <li>$options['debug_expanded_output'] -> bool: BC option to determine if more context information should be send to the debug handler</li>
1103     *  <li>$options['default_text_field_length'] -> integer: default text field length to use</li>
1104     *  <li>$options['lob_buffer_length'] -> integer: LOB buffer length</li>
1105     *  <li>$options['log_line_break'] -> string: line-break format</li>
1106     *  <li>$options['idxname_format'] -> string: pattern for index name</li>
1107     *  <li>$options['seqname_format'] -> string: pattern for sequence name</li>
1108     *  <li>$options['savepoint_format'] -> string: pattern for auto generated savepoint names</li>
1109     *  <li>$options['statement_format'] -> string: pattern for prepared statement names</li>
1110     *  <li>$options['seqcol_name'] -> string: sequence column name</li>
1111     *  <li>$options['quote_identifier'] -> boolean: if identifier quoting should be done when check_option is used</li>
1112     *  <li>$options['use_transactions'] -> boolean: if transaction use should be enabled</li>
1113     *  <li>$options['decimal_places'] -> integer: number of decimal places to handle</li>
1114     *  <li>$options['portability'] -> integer: portability constant</li>
1115     *  <li>$options['modules'] -> array: short to long module name mapping for __call()</li>
1116     *  <li>$options['emulate_prepared'] -> boolean: force prepared statements to be emulated</li>
1117     *  <li>$options['datatype_map'] -> array: map user defined datatypes to other primitive datatypes</li>
1118     *  <li>$options['datatype_map_callback'] -> array: callback function/method that should be called</li>
1119     * </ul>
1120     *
1121     * @var     array
1122     * @access  public
1123     * @see     MDB2::connect()
1124     * @see     MDB2::factory()
1125     * @see     MDB2::singleton()
1126     * @see     MDB2_Driver_Common::setOption()
1127     */
1128    var $options = array(
1129        'ssl' => false,
1130        'field_case' => CASE_LOWER,
1131        'disable_query' => false,
1132        'result_class' => 'MDB2_Result_%s',
1133        'buffered_result_class' => 'MDB2_BufferedResult_%s',
1134        'result_wrap_class' => false,
1135        'result_buffering' => true,
1136        'fetch_class' => 'stdClass',
1137        'persistent' => false,
1138        'debug' => 0,
1139        'debug_handler' => 'MDB2_defaultDebugOutput',
1140        'debug_expanded_output' => false,
1141        'default_text_field_length' => 4096,
1142        'lob_buffer_length' => 8192,
1143        'log_line_break' => "\n",
1144        'idxname_format' => '%s_idx',
1145        'seqname_format' => '%s_seq',
1146        'savepoint_format' => 'MDB2_SAVEPOINT_%s',
1147        'statement_format' => 'MDB2_STATEMENT_%1$s_%2$s',
1148        'seqcol_name' => 'sequence',
1149        'quote_identifier' => false,
1150        'use_transactions' => true,
1151        'decimal_places' => 2,
1152        'portability' => MDB2_PORTABILITY_ALL,
1153        'modules' => array(
1154            'ex' => 'Extended',
1155            'dt' => 'Datatype',
1156            'mg' => 'Manager',
1157            'rv' => 'Reverse',
1158            'na' => 'Native',
1159            'fc' => 'Function',
1160        ),
1161        'emulate_prepared' => false,
1162        'datatype_map' => array(),
1163        'datatype_map_callback' => array(),
1164        'nativetype_map_callback' => array(),
1165    );
1166
1167    /**
1168     * string array
1169     * @var     string
1170     * @access  protected
1171     */
1172    var $string_quoting = array('start' => "'", 'end' => "'", 'escape' => false, 'escape_pattern' => false);
1173
1174    /**
1175     * identifier quoting
1176     * @var     array
1177     * @access  protected
1178     */
1179    var $identifier_quoting = array('start' => '"', 'end' => '"', 'escape' => '"');
1180
1181    /**
1182     * sql comments
1183     * @var     array
1184     * @access  protected
1185     */
1186    var $sql_comments = array(
1187        array('start' => '--', 'end' => "\n", 'escape' => false),
1188        array('start' => '/*', 'end' => '*/', 'escape' => false),
1189    );
1190
1191    /**
1192     * comparision wildcards
1193     * @var     array
1194     * @access  protected
1195     */
1196    var $wildcards = array('%', '_');
1197
1198    /**
1199     * column alias keyword
1200     * @var     string
1201     * @access  protected
1202     */
1203    var $as_keyword = ' AS ';
1204
1205    /**
1206     * warnings
1207     * @var     array
1208     * @access  protected
1209     */
1210    var $warnings = array();
1211
1212    /**
1213     * string with the debugging information
1214     * @var     string
1215     * @access  public
1216     */
1217    var $debug_output = '';
1218
1219    /**
1220     * determine if there is an open transaction
1221     * @var     bool
1222     * @access  protected
1223     */
1224    var $in_transaction = false;
1225
1226    /**
1227     * the smart transaction nesting depth
1228     * @var     int
1229     * @access  protected
1230     */
1231    var $nested_transaction_counter = null;
1232
1233    /**
1234     * the first error that occured inside a nested transaction
1235     * @var     MDB2_Error|bool
1236     * @access  protected
1237     */
1238    var $has_transaction_error = false;
1239
1240    /**
1241     * result offset used in the next query
1242     * @var     int
1243     * @access  protected
1244     */
1245    var $offset = 0;
1246
1247    /**
1248     * result limit used in the next query
1249     * @var     int
1250     * @access  protected
1251     */
1252    var $limit = 0;
1253
1254    /**
1255     * Database backend used in PHP (mysql, odbc etc.)
1256     * @var     string
1257     * @access  public
1258     */
1259    var $phptype;
1260
1261    /**
1262     * Database used with regards to SQL syntax etc.
1263     * @var     string
1264     * @access  public
1265     */
1266    var $dbsyntax;
1267
1268    /**
1269     * the last query sent to the driver
1270     * @var     string
1271     * @access  public
1272     */
1273    var $last_query;
1274
1275    /**
1276     * the default fetchmode used
1277     * @var     int
1278     * @access  protected
1279     */
1280    var $fetchmode = MDB2_FETCHMODE_ORDERED;
1281
1282    /**
1283     * array of module instances
1284     * @var     array
1285     * @access  protected
1286     */
1287    var $modules = array();
1288
1289    /**
1290     * determines of the PHP4 destructor emulation has been enabled yet
1291     * @var     array
1292     * @access  protected
1293     */
1294    var $destructor_registered = true;
1295
1296    // }}}
1297    // {{{ constructor: function __construct()
1298
1299    /**
1300     * Constructor
1301     */
1302    function __construct()
1303    {
1304        end($GLOBALS['_MDB2_databases']);
1305        $db_index = key($GLOBALS['_MDB2_databases']) + 1;
1306        $GLOBALS['_MDB2_databases'][$db_index] = &$this;
1307        $this->db_index = $db_index;
1308    }
1309
1310    // }}}
1311    // {{{ function MDB2_Driver_Common()
1312
1313    /**
1314     * PHP 4 Constructor
1315     */
1316    function MDB2_Driver_Common()
1317    {
1318        $this->destructor_registered = false;
1319        $this->__construct();
1320    }
1321
1322    // }}}
1323    // {{{ destructor: function __destruct()
1324
1325    /**
1326     *  Destructor
1327     */
1328    function __destruct()
1329    {
1330        $this->disconnect(false);
1331    }
1332
1333    // }}}
1334    // {{{ function free()
1335
1336    /**
1337     * Free the internal references so that the instance can be destroyed
1338     *
1339     * @return  bool    true on success, false if result is invalid
1340     *
1341     * @access  public
1342     */
1343    function free()
1344    {
1345        unset($GLOBALS['_MDB2_databases'][$this->db_index]);
1346        unset($this->db_index);
1347        return MDB2_OK;
1348    }
1349
1350    // }}}
1351    // {{{ function __toString()
1352
1353    /**
1354     * String conversation
1355     *
1356     * @return  string representation of the object
1357     *
1358     * @access  public
1359     */
1360    function __toString()
1361    {
1362        $info = get_class($this);
1363        $info.= ': (phptype = '.$this->phptype.', dbsyntax = '.$this->dbsyntax.')';
1364        if ($this->connection) {
1365            $info.= ' [connected]';
1366        }
1367        return $info;
1368    }
1369
1370    // }}}
1371    // {{{ function errorInfo($error = null)
1372
1373    /**
1374     * This method is used to collect information about an error
1375     *
1376     * @param   mixed   error code or resource
1377     *
1378     * @return  array   with MDB2 errorcode, native error code, native message
1379     *
1380     * @access  public
1381     */
1382    function errorInfo($error = null)
1383    {
1384        return array($error, null, null);
1385    }
1386
1387    // }}}
1388    // {{{ function &raiseError($code = null, $mode = null, $options = null, $userinfo = null)
1389
1390    /**
1391     * This method is used to communicate an error and invoke error
1392     * callbacks etc.  Basically a wrapper for PEAR::raiseError
1393     * without the message string.
1394     *
1395     * @param   mixed   integer error code, or a PEAR error object (all other
1396     *                  parameters are ignored if this parameter is an object
1397     * @param   int     error mode, see PEAR_Error docs
1398     * @param   mixed   If error mode is PEAR_ERROR_TRIGGER, this is the
1399         *              error level (E_USER_NOTICE etc).  If error mode is
1400     *                  PEAR_ERROR_CALLBACK, this is the callback function,
1401     *                  either as a function name, or as an array of an
1402     *                  object and method name.  For other error modes this
1403     *                  parameter is ignored.
1404     * @param   string  Extra debug information.  Defaults to the last
1405     *                  query and native error code.
1406     * @param   string  name of the method that triggered the error
1407     *
1408     * @return PEAR_Error   instance of a PEAR Error object
1409     *
1410     * @access  public
1411     * @see     PEAR_Error
1412     */
1413    function &raiseError($code = null, $mode = null, $options = null, $userinfo = null, $method = null)
1414    {
1415        $userinfo = "[Error message: $userinfo]\n";
1416        // The error is yet a MDB2 error object
1417        if (PEAR::isError($code)) {
1418            // because we use the static PEAR::raiseError, our global
1419            // handler should be used if it is set
1420            if (is_null($mode) && !empty($this->_default_error_mode)) {
1421                $mode    = $this->_default_error_mode;
1422                $options = $this->_default_error_options;
1423            }
1424            if (is_null($userinfo)) {
1425                $userinfo = $code->getUserinfo();
1426            }
1427            $code = $code->getCode();
1428        } elseif ($code == MDB2_ERROR_NOT_FOUND) {
1429            // extension not loaded: don't call $this->errorInfo() or the script
1430            // will die
1431        } elseif (isset($this->connection)) {
1432            if (!empty($this->last_query)) {
1433                $userinfo.= "[Last executed query: {$this->last_query}]\n";
1434            }
1435            $native_errno = $native_msg = null;
1436            list($code, $native_errno, $native_msg) = $this->errorInfo($code);
1437            if (!is_null($native_errno) && $native_errno !== '') {
1438                $userinfo.= "[Native code: $native_errno]\n";
1439            }
1440            if (!is_null($native_msg) && $native_msg !== '') {
1441                $userinfo.= "[Native message: ". strip_tags($native_msg) ."]\n";
1442            }
1443            if (!is_null($method)) {
1444                $userinfo = $method.': '.$userinfo;
1445            }
1446        }
1447
1448        $err =& PEAR::raiseError(null, $code, $mode, $options, $userinfo, 'MDB2_Error', true);
1449        if ($err->getMode() !== PEAR_ERROR_RETURN
1450            && isset($this->nested_transaction_counter) && !$this->has_transaction_error) {
1451            $this->has_transaction_error =& $err;
1452        }
1453        return $err;
1454    }
1455
1456    // }}}
1457    // {{{ function resetWarnings()
1458
1459    /**
1460     * reset the warning array
1461     *
1462     * @return void
1463     *
1464     * @access  public
1465     */
1466    function resetWarnings()
1467    {
1468        $this->warnings = array();
1469    }
1470
1471    // }}}
1472    // {{{ function getWarnings()
1473
1474    /**
1475     * Get all warnings in reverse order.
1476     * This means that the last warning is the first element in the array
1477     *
1478     * @return  array   with warnings
1479     *
1480     * @access  public
1481     * @see     resetWarnings()
1482     */
1483    function getWarnings()
1484    {
1485        return array_reverse($this->warnings);
1486    }
1487
1488    // }}}
1489    // {{{ function setFetchMode($fetchmode, $object_class = 'stdClass')
1490
1491    /**
1492     * Sets which fetch mode should be used by default on queries
1493     * on this connection
1494     *
1495     * @param   int     MDB2_FETCHMODE_ORDERED, MDB2_FETCHMODE_ASSOC
1496     *                               or MDB2_FETCHMODE_OBJECT
1497     * @param   string  the class name of the object to be returned
1498     *                               by the fetch methods when the
1499     *                               MDB2_FETCHMODE_OBJECT mode is selected.
1500     *                               If no class is specified by default a cast
1501     *                               to object from the assoc array row will be
1502     *                               done.  There is also the possibility to use
1503     *                               and extend the 'MDB2_row' class.
1504     *
1505     * @return  mixed   MDB2_OK or MDB2 Error Object
1506     *
1507     * @access  public
1508     * @see     MDB2_FETCHMODE_ORDERED, MDB2_FETCHMODE_ASSOC, MDB2_FETCHMODE_OBJECT
1509     */
1510    function setFetchMode($fetchmode, $object_class = 'stdClass')
1511    {
1512        switch ($fetchmode) {
1513        case MDB2_FETCHMODE_OBJECT:
1514            $this->options['fetch_class'] = $object_class;
1515        case MDB2_FETCHMODE_ORDERED:
1516        case MDB2_FETCHMODE_ASSOC:
1517            $this->fetchmode = $fetchmode;
1518            break;
1519        default:
1520            return $this->raiseError(MDB2_ERROR_UNSUPPORTED, null, null,
1521                'invalid fetchmode mode', __FUNCTION__);
1522        }
1523
1524        return MDB2_OK;
1525    }
1526
1527    // }}}
1528    // {{{ function setOption($option, $value)
1529
1530    /**
1531     * set the option for the db class
1532     *
1533     * @param   string  option name
1534     * @param   mixed   value for the option
1535     *
1536     * @return  mixed   MDB2_OK or MDB2 Error Object
1537     *
1538     * @access  public
1539     */
1540    function setOption($option, $value)
1541    {
1542        if (array_key_exists($option, $this->options)) {
1543            $this->options[$option] = $value;
1544            return MDB2_OK;
1545        }
1546        return $this->raiseError(MDB2_ERROR_UNSUPPORTED, null, null,
1547            "unknown option $option", __FUNCTION__);
1548    }
1549
1550    // }}}
1551    // {{{ function getOption($option)
1552
1553    /**
1554     * Returns the value of an option
1555     *
1556     * @param   string  option name
1557     *
1558     * @return  mixed   the option value or error object
1559     *
1560     * @access  public
1561     */
1562    function getOption($option)
1563    {
1564        if (array_key_exists($option, $this->options)) {
1565            return $this->options[$option];
1566        }
1567        return $this->raiseError(MDB2_ERROR_UNSUPPORTED, null, null,
1568            "unknown option $option", __FUNCTION__);
1569    }
1570
1571    // }}}
1572    // {{{ function debug($message, $scope = '', $is_manip = null)
1573
1574    /**
1575     * set a debug message
1576     *
1577     * @param   string  message that should be appended to the debug variable
1578     * @param   string  usually the method name that triggered the debug call:
1579     *                  for example 'query', 'prepare', 'execute', 'parameters',
1580     *                  'beginTransaction', 'commit', 'rollback'
1581     * @param   array   contains context information about the debug() call
1582     *                  common keys are: is_manip, time, result etc.
1583     *
1584     * @return void
1585     *
1586     * @access  public
1587     */
1588    function debug($message, $scope = '', $context = array())
1589    {
1590        if ($this->options['debug'] && $this->options['debug_handler']) {
1591            if (!$this->options['debug_expanded_output']) {
1592                if (!empty($context['when']) && $context['when'] !== 'pre') {
1593                    return null;
1594                }
1595                $context = empty($context['is_manip']) ? false : $context['is_manip'];
1596            }
1597            return call_user_func_array($this->options['debug_handler'], array(&$this, $scope, $message, $context));
1598        }
1599        return null;
1600    }
1601
1602    // }}}
1603    // {{{ function getDebugOutput()
1604
1605    /**
1606     * output debug info
1607     *
1608     * @return  string  content of the debug_output class variable
1609     *
1610     * @access  public
1611     */
1612    function getDebugOutput()
1613    {
1614        return $this->debug_output;
1615    }
1616
1617    // }}}
1618    // {{{ function escape($text)
1619
1620    /**
1621     * Quotes a string so it can be safely used in a query. It will quote
1622     * the text so it can safely be used within a query.
1623     *
1624     * @param   string  the input string to quote
1625     * @param   bool    escape wildcards
1626     *
1627     * @return  string  quoted string
1628     *
1629     * @access  public
1630     */
1631    function escape($text, $escape_wildcards = false)
1632    {
1633        if ($escape_wildcards) {
1634            $text = $this->escapePattern($text);
1635        }
1636
1637        $text = str_replace($this->string_quoting['end'], $this->string_quoting['escape'] . $this->string_quoting['end'], $text);
1638        return $text;
1639    }
1640
1641    // }}}
1642    // {{{ function escapePattern($text)
1643
1644    /**
1645     * Quotes pattern (% and _) characters in a string)
1646     *
1647     * EXPERIMENTAL
1648     *
1649     * WARNING: this function is experimental and may change signature at
1650     * any time until labelled as non-experimental
1651     *
1652     * @param   string  the input string to quote
1653     *
1654     * @return  string  quoted string
1655     *
1656     * @access  public
1657     */
1658    function escapePattern($text)
1659    {
1660        if ($this->string_quoting['escape_pattern']) {
1661            $text = str_replace($this->string_quoting['escape_pattern'], $this->string_quoting['escape_pattern'] . $this->string_quoting['escape_pattern'], $text);
1662            foreach ($this->wildcards as $wildcard) {
1663                $text = str_replace($wildcard, $this->string_quoting['escape_pattern'] . $wildcard, $text);
1664            }
1665        }
1666        return $text;
1667    }
1668
1669    // }}}
1670    // {{{ function quoteIdentifier($str, $check_option = false)
1671
1672    /**
1673     * Quote a string so it can be safely used as a table or column name
1674     *
1675     * Delimiting style depends on which database driver is being used.
1676     *
1677     * NOTE: just because you CAN use delimited identifiers doesn't mean
1678     * you SHOULD use them.  In general, they end up causing way more
1679     * problems than they solve.
1680     *
1681     * Portability is broken by using the following characters inside
1682     * delimited identifiers:
1683     *   + backtick (<kbd>`</kbd>) -- due to MySQL
1684     *   + double quote (<kbd>"</kbd>) -- due to Oracle
1685     *   + brackets (<kbd>[</kbd> or <kbd>]</kbd>) -- due to Access
1686     *
1687     * Delimited identifiers are known to generally work correctly under
1688     * the following drivers:
1689     *   + mssql
1690     *   + mysql
1691     *   + mysqli
1692     *   + oci8
1693     *   + pgsql
1694     *   + sqlite
1695     *
1696     * InterBase doesn't seem to be able to use delimited identifiers
1697     * via PHP 4.  They work fine under PHP 5.
1698     *
1699     * @param   string  identifier name to be quoted
1700     * @param   bool    check the 'quote_identifier' option
1701     *
1702     * @return  string  quoted identifier string
1703     *
1704     * @access  public
1705     */
1706    function quoteIdentifier($str, $check_option = false)
1707    {
1708        if ($check_option && !$this->options['quote_identifier']) {
1709            return $str;
1710        }
1711        $str = str_replace($this->identifier_quoting['end'], $this->identifier_quoting['escape'] . $this->identifier_quoting['end'], $str);
1712        return $this->identifier_quoting['start'] . $str . $this->identifier_quoting['end'];
1713    }
1714
1715    // }}}
1716    // {{{ function getAsKeyword()
1717
1718    /**
1719     * Gets the string to alias column
1720     *
1721     * @return string to use when aliasing a column
1722     */
1723    function getAsKeyword()
1724    {
1725        return $this->as_keyword;
1726    }
1727
1728    // }}}
1729    // {{{ function getConnection()
1730
1731    /**
1732     * Returns a native connection
1733     *
1734     * @return  mixed   a valid MDB2 connection object,
1735     *                  or a MDB2 error object on error
1736     *
1737     * @access  public
1738     */
1739    function getConnection()
1740    {
1741        $result = $this->connect();
1742        if (PEAR::isError($result)) {
1743            return $result;
1744        }
1745        return $this->connection;
1746    }
1747
1748     // }}}
1749    // {{{ function _fixResultArrayValues(&$row, $mode)
1750
1751    /**
1752     * Do all necessary conversions on result arrays to fix DBMS quirks
1753     *
1754     * @param   array   the array to be fixed (passed by reference)
1755     * @param   array   bit-wise addition of the required portability modes
1756     *
1757     * @return  void
1758     *
1759     * @access  protected
1760     */
1761    function _fixResultArrayValues(&$row, $mode)
1762    {
1763        switch ($mode) {
1764        case MDB2_PORTABILITY_EMPTY_TO_NULL:
1765            foreach ($row as $key => $value) {
1766                if ($value === '') {
1767                    $row[$key] = null;
1768                }
1769            }
1770            break;
1771        case MDB2_PORTABILITY_RTRIM:
1772            foreach ($row as $key => $value) {
1773                if (is_string($value)) {
1774                    $row[$key] = rtrim($value);
1775                }
1776            }
1777            break;
1778        case MDB2_PORTABILITY_FIX_ASSOC_FIELD_NAMES:
1779            $tmp_row = array();
1780            foreach ($row as $key => $value) {
1781                $tmp_row[preg_replace('/^(?:.*\.)?([^.]+)$/', '\\1', $key)] = $value;
1782            }
1783            $row = $tmp_row;
1784            break;
1785        case (MDB2_PORTABILITY_RTRIM + MDB2_PORTABILITY_EMPTY_TO_NULL):
1786            foreach ($row as $key => $value) {
1787                if ($value === '') {
1788                    $row[$key] = null;
1789                } elseif (is_string($value)) {
1790                    $row[$key] = rtrim($value);
1791                }
1792            }
1793            break;
1794        case (MDB2_PORTABILITY_RTRIM + MDB2_PORTABILITY_FIX_ASSOC_FIELD_NAMES):
1795            $tmp_row = array();
1796            foreach ($row as $key => $value) {
1797                if (is_string($value)) {
1798                    $value = rtrim($value);
1799                }
1800                $tmp_row[preg_replace('/^(?:.*\.)?([^.]+)$/', '\\1', $key)] = $value;
1801            }
1802            $row = $tmp_row;
1803            break;
1804        case (MDB2_PORTABILITY_EMPTY_TO_NULL + MDB2_PORTABILITY_FIX_ASSOC_FIELD_NAMES):
1805            $tmp_row = array();
1806            foreach ($row as $key => $value) {
1807                if ($value === '') {
1808                    $value = null;
1809                }
1810                $tmp_row[preg_replace('/^(?:.*\.)?([^.]+)$/', '\\1', $key)] = $value;
1811            }
1812            $row = $tmp_row;
1813            break;
1814        case (MDB2_PORTABILITY_RTRIM + MDB2_PORTABILITY_EMPTY_TO_NULL + MDB2_PORTABILITY_FIX_ASSOC_FIELD_NAMES):
1815            $tmp_row = array();
1816            foreach ($row as $key => $value) {
1817                if ($value === '') {
1818                    $value = null;
1819                } elseif (is_string($value)) {
1820                    $value = rtrim($value);
1821                }
1822                $tmp_row[preg_replace('/^(?:.*\.)?([^.]+)$/', '\\1', $key)] = $value;
1823            }
1824            $row = $tmp_row;
1825            break;
1826        }
1827    }
1828
1829    // }}}
1830    // {{{ function &loadModule($module, $property = null, $phptype_specific = null)
1831
1832    /**
1833     * loads a module
1834     *
1835     * @param   string  name of the module that should be loaded
1836     *                  (only used for error messages)
1837     * @param   string  name of the property into which the class will be loaded
1838     * @param   bool    if the class to load for the module is specific to the
1839     *                  phptype
1840     *
1841     * @return  object  on success a reference to the given module is returned
1842     *                  and on failure a PEAR error
1843     *
1844     * @access  public
1845     */
1846    function &loadModule($module, $property = null, $phptype_specific = null)
1847    {
1848        if (!$property) {
1849            $property = strtolower($module);
1850        }
1851
1852        if (!isset($this->{$property})) {
1853            $version = $phptype_specific;
1854            if ($phptype_specific !== false) {
1855                $version = true;
1856                $class_name = 'MDB2_Driver_'.$module.'_'.$this->phptype;
1857                $file_name = str_replace('_', DIRECTORY_SEPARATOR, $class_name).'.php';
1858            }
1859            if ($phptype_specific === false
1860                || (!MDB2::classExists($class_name) && !MDB2::fileExists($file_name))
1861            ) {
1862                $version = false;
1863                $class_name = 'MDB2_'.$module;
1864                $file_name = str_replace('_', DIRECTORY_SEPARATOR, $class_name).'.php';
1865            }
1866
1867            $err = MDB2::loadClass($class_name, $this->getOption('debug'));
1868            if (PEAR::isError($err)) {
1869                return $err;
1870            }
1871
1872            // load modul in a specific version
1873            if ($version) {
1874                if (method_exists($class_name, 'getClassName')) {
1875                    $class_name_new = call_user_func(array($class_name, 'getClassName'), $this->db_index);
1876                    if ($class_name != $class_name_new) {
1877                        $class_name = $class_name_new;
1878                        $err = MDB2::loadClass($class_name, $this->getOption('debug'));
1879                        if (PEAR::isError($err)) {
1880                            return $err;
1881                        }
1882                    }
1883                }
1884            }
1885
1886            if (!MDB2::classExists($class_name)) {
1887                $err =& $this->raiseError(MDB2_ERROR_LOADMODULE, null, null,
1888                    "unable to load module '$module' into property '$property'", __FUNCTION__);
1889                return $err;
1890            }
1891            $this->{$property} =& new $class_name($this->db_index);
1892            $this->modules[$module] =& $this->{$property};
1893            if ($version) {
1894                // this will be used in the connect method to determine if the module
1895                // needs to be loaded with a different version if the server
1896                // version changed in between connects
1897                $this->loaded_version_modules[] = $property;
1898            }
1899        }
1900
1901        return $this->{$property};
1902    }
1903
1904    // }}}
1905    // {{{ function __call($method, $params)
1906
1907    /**
1908     * Calls a module method using the __call magic method
1909     *
1910     * @param   string  Method name.
1911     * @param   array   Arguments.
1912     *
1913     * @return  mixed   Returned value.
1914     */
1915    function __call($method, $params)
1916    {
1917        $module = null;
1918        if (preg_match('/^([a-z]+)([A-Z])(.*)$/', $method, $match)
1919            && isset($this->options['modules'][$match[1]])
1920        ) {
1921            $module = $this->options['modules'][$match[1]];
1922            $method = strtolower($match[2]).$match[3];
1923            if (!isset($this->modules[$module]) || !is_object($this->modules[$module])) {
1924                $result =& $this->loadModule($module);
1925                if (PEAR::isError($result)) {
1926                    return $result;
1927                }
1928            }
1929        } else {
1930            foreach ($this->modules as $key => $foo) {
1931                if (is_object($this->modules[$key])
1932                    && method_exists($this->modules[$key], $method)
1933                ) {
1934                    $module = $key;
1935                    break;
1936                }
1937            }
1938        }
1939        if (!is_null($module)) {
1940            return call_user_func_array(array(&$this->modules[$module], $method), $params);
1941        }
1942        trigger_error(sprintf('Call to undefined function: %s::%s().', get_class($this), $method), E_USER_ERROR);
1943    }
1944
1945    // }}}
1946    // {{{ function beginTransaction($savepoint = null)
1947
1948    /**
1949     * Start a transaction or set a savepoint.
1950     *
1951     * @param   string  name of a savepoint to set
1952     * @return  mixed   MDB2_OK on success, a MDB2 error on failure
1953     *
1954     * @access  public
1955     */
1956    function beginTransaction($savepoint = null)
1957    {
1958        $this->debug('Starting transaction', __FUNCTION__, array('is_manip' => true, 'savepoint' => $savepoint));
1959        return $this->raiseError(MDB2_ERROR_UNSUPPORTED, null, null,
1960            'transactions are not supported', __FUNCTION__);
1961    }
1962
1963    // }}}
1964    // {{{ function commit($savepoint = null)
1965
1966    /**
1967     * Commit the database changes done during a transaction that is in
1968     * progress or release a savepoint. This function may only be called when
1969     * auto-committing is disabled, otherwise it will fail. Therefore, a new
1970     * transaction is implicitly started after committing the pending changes.
1971     *
1972     * @param   string  name of a savepoint to release
1973     * @return  mixed   MDB2_OK on success, a MDB2 error on failure
1974     *
1975     * @access  public
1976     */
1977    function commit($savepoint = null)
1978    {
1979        $this->debug('Committing transaction/savepoint', __FUNCTION__, array('is_manip' => true, 'savepoint' => $savepoint));
1980        return $this->raiseError(MDB2_ERROR_UNSUPPORTED, null, null,
1981            'commiting transactions is not supported', __FUNCTION__);
1982    }
1983
1984    // }}}
1985    // {{{ function rollback($savepoint = null)
1986
1987    /**
1988     * Cancel any database changes done during a transaction or since a specific
1989     * savepoint that is in progress. This function may only be called when
1990     * auto-committing is disabled, otherwise it will fail. Therefore, a new
1991     * transaction is implicitly started after canceling the pending changes.
1992     *
1993     * @param   string  name of a savepoint to rollback to
1994     * @return  mixed   MDB2_OK on success, a MDB2 error on failure
1995     *
1996     * @access  public
1997     */
1998    function rollback($savepoint = null)
1999    {
2000        $this->debug('Rolling back transaction/savepoint', __FUNCTION__, array('is_manip' => true, 'savepoint' => $savepoint));
2001        return $this->raiseError(MDB2_ERROR_UNSUPPORTED, null, null,
2002            'rolling back transactions is not supported', __FUNCTION__);
2003    }
2004
2005    // }}}
2006    // {{{ function inTransaction($ignore_nested = false)
2007
2008    /**
2009     * If a transaction is currently open.
2010     *
2011     * @param   bool    if the nested transaction count should be ignored
2012     * @return  int|bool    - an integer with the nesting depth is returned if a
2013     *                      nested transaction is open
2014     *                      - true is returned for a normal open transaction
2015     *                      - false is returned if no transaction is open
2016     *
2017     * @access  public
2018     */
2019    function inTransaction($ignore_nested = false)
2020    {
2021        if (!$ignore_nested && isset($this->nested_transaction_counter)) {
2022            return $this->nested_transaction_counter;
2023        }
2024        return $this->in_transaction;
2025    }
2026
2027    // }}}
2028    // {{{ function setTransactionIsolation($isolation)
2029
2030    /**
2031     * Set the transacton isolation level.
2032     *
2033     * @param   string  standard isolation level
2034     *                  READ UNCOMMITTED (allows dirty reads)
2035     *                  READ COMMITTED (prevents dirty reads)
2036     *                  REPEATABLE READ (prevents nonrepeatable reads)
2037     *                  SERIALIZABLE (prevents phantom reads)
2038     * @param   array some transaction options:
2039     *                  'wait' => 'WAIT' | 'NO WAIT'
2040     *                  'rw'   => 'READ WRITE' | 'READ ONLY'
2041     * @return  mixed   MDB2_OK on success, a MDB2 error on failure
2042     *
2043     * @access  public
2044     * @since   2.1.1
2045     */
2046    function setTransactionIsolation($isolation, $options = array())
2047    {
2048        $this->debug('Setting transaction isolation level', __FUNCTION__, array('is_manip' => true));
2049        return $this->raiseError(MDB2_ERROR_UNSUPPORTED, null, null,
2050            'isolation level setting is not supported', __FUNCTION__);
2051    }
2052
2053    // }}}
2054    // {{{ function beginNestedTransaction($savepoint = false)
2055
2056    /**
2057     * Start a nested transaction.
2058     *
2059     * EXPERIMENTAL
2060     *
2061     * WARNING: this function is experimental and may change signature at
2062     * any time until labelled as non-experimental
2063     *
2064     * @return  mixed   MDB2_OK on success/savepoint name, a MDB2 error on failure
2065     *
2066     * @access  public
2067     * @since   2.1.1
2068     */
2069    function beginNestedTransaction()
2070    {
2071        if ($this->in_transaction) {
2072            ++$this->nested_transaction_counter;
2073            $savepoint = sprintf($this->options['savepoint_format'], $this->nested_transaction_counter);
2074            if ($this->supports('savepoints') && $savepoint) {
2075                return $this->beginTransaction($savepoint);
2076            }
2077            return MDB2_OK;
2078        }
2079        $this->has_transaction_error = false;
2080        $result = $this->beginTransaction();
2081        $this->nested_transaction_counter = 1;
2082        return $result;
2083    }
2084
2085    // }}}
2086    // {{{ function completeNestedTransaction($force_rollback = false, $release = false)
2087
2088    /**
2089     * Finish a nested transaction by rolling back if an error occured or
2090     * committing otherwise.
2091     *
2092     * EXPERIMENTAL
2093     *
2094     * WARNING: this function is experimental and may change signature at
2095     * any time until labelled as non-experimental
2096     *
2097     * @param   bool    if the transaction should be rolled back regardless
2098     *                  even if no error was set within the nested transaction
2099     * @return  mixed   MDB_OK on commit/counter decrementing, false on rollback
2100     *                  and a MDB2 error on failure
2101     *
2102     * @access  public
2103     * @since   2.1.1
2104     */
2105    function completeNestedTransaction($force_rollback = false)
2106    {
2107        if ($this->nested_transaction_counter > 1) {
2108            $savepoint = sprintf($this->options['savepoint_format'], $this->nested_transaction_counter);
2109            if ($this->supports('savepoints') && $savepoint) {
2110                if ($force_rollback || $this->has_transaction_error) {
2111                    $result = $this->rollback($savepoint);
2112                    if (!PEAR::isError($result)) {
2113                        $result = false;
2114                        $this->has_transaction_error = false;
2115                    }
2116                } else {
2117                    $result = $this->commit($savepoint);
2118                }
2119            } else {
2120                $result = MDB2_OK;
2121            }
2122            --$this->nested_transaction_counter;
2123            return $result;
2124        }
2125
2126        $this->nested_transaction_counter = null;
2127        $result = MDB2_OK;
2128
2129        // transaction has not yet been rolled back
2130        if ($this->in_transaction) {
2131            if ($force_rollback || $this->has_transaction_error) {
2132                $result = $this->rollback();
2133                if (!PEAR::isError($result)) {
2134                    $result = false;
2135                }
2136            } else {
2137                $result = $this->commit();
2138            }
2139        }
2140        $this->has_transaction_error = false;
2141        return $result;
2142    }
2143
2144    // }}}
2145    // {{{ function failNestedTransaction($error = null, $immediately = false)
2146
2147    /**
2148     * Force setting nested transaction to failed.
2149     *
2150     * EXPERIMENTAL
2151     *
2152     * WARNING: this function is experimental and may change signature at
2153     * any time until labelled as non-experimental
2154     *
2155     * @param   mixed   value to return in getNestededTransactionError()
2156     * @param   bool    if the transaction should be rolled back immediately
2157     * @return  bool    MDB2_OK
2158     *
2159     * @access  public
2160     * @since   2.1.1
2161     */
2162    function failNestedTransaction($error = null, $immediately = false)
2163    {
2164        if (is_null($error)) {
2165            $error = $this->has_transaction_error ? $this->has_transaction_error : true;
2166        } elseif (!$error) {
2167            $error = true;
2168        }
2169        $this->has_transaction_error = $error;
2170        if (!$immediately) {
2171            return MDB2_OK;
2172        }
2173        return $this->rollback();
2174    }
2175
2176    // }}}
2177    // {{{ function getNestedTransactionError()
2178
2179    /**
2180     * The first error that occured since the transaction start.
2181     *
2182     * EXPERIMENTAL
2183     *
2184     * WARNING: this function is experimental and may change signature at
2185     * any time until labelled as non-experimental
2186     *
2187     * @return  MDB2_Error|bool     MDB2 error object if an error occured or false.
2188     *
2189     * @access  public
2190     * @since   2.1.1
2191     */
2192    function getNestedTransactionError()
2193    {
2194        return $this->has_transaction_error;
2195    }
2196
2197    // }}}
2198    // {{{ connect()
2199
2200    /**
2201     * Connect to the database
2202     *
2203     * @return true on success, MDB2 Error Object on failure
2204     */
2205    function connect()
2206    {
2207        return $this->raiseError(MDB2_ERROR_UNSUPPORTED, null, null,
2208            'method not implemented', __FUNCTION__);
2209    }
2210
2211    // }}}
2212    // {{{ setCharset($charset, $connection = null)
2213
2214    /**
2215     * Set the charset on the current connection
2216     *
2217     * @param string    charset
2218     * @param resource  connection handle
2219     *
2220     * @return true on success, MDB2 Error Object on failure
2221     */
2222    function setCharset($charset, $connection = null)
2223    {
2224        return $this->raiseError(MDB2_ERROR_UNSUPPORTED, null, null,
2225            'method not implemented', __FUNCTION__);
2226    }
2227
2228    // }}}
2229    // {{{ function disconnect($force = true)
2230
2231    /**
2232     * Log out and disconnect from the database.
2233     *
2234     * @param   bool    if the disconnect should be forced even if the
2235     *                  connection is opened persistently
2236     *
2237     * @return  mixed   true on success, false if not connected and error
2238     *                  object on error
2239     *
2240     * @access  public
2241     */
2242    function disconnect($force = true)
2243    {
2244        $this->connection = 0;
2245        $this->connected_dsn = array();
2246        $this->connected_database_name = '';
2247        $this->opened_persistent = null;
2248        $this->connected_server_info = '';
2249        $this->in_transaction = null;
2250        $this->nested_transaction_counter = null;
2251        return MDB2_OK;
2252    }
2253
2254    // }}}
2255    // {{{ function setDatabase($name)
2256
2257    /**
2258     * Select a different database
2259     *
2260     * @param   string  name of the database that should be selected
2261     *
2262     * @return  string  name of the database previously connected to
2263     *
2264     * @access  public
2265     */
2266    function setDatabase($name)
2267    {
2268        $previous_database_name = (isset($this->database_name)) ? $this->database_name : '';
2269        $this->database_name = $name;
2270        $this->disconnect(false);
2271        return $previous_database_name;
2272    }
2273
2274    // }}}
2275    // {{{ function getDatabase()
2276
2277    /**
2278     * Get the current database
2279     *
2280     * @return  string  name of the database
2281     *
2282     * @access  public
2283     */
2284    function getDatabase()
2285    {
2286        return $this->database_name;
2287    }
2288
2289    // }}}
2290    // {{{ function setDSN($dsn)
2291
2292    /**
2293     * set the DSN
2294     *
2295     * @param   mixed   DSN string or array
2296     *
2297     * @return  MDB2_OK
2298     *
2299     * @access  public
2300     */
2301    function setDSN($dsn)
2302    {
2303        $dsn_default = $GLOBALS['_MDB2_dsninfo_default'];
2304        $dsn = MDB2::parseDSN($dsn);
2305        if (array_key_exists('database', $dsn)) {
2306            $this->database_name = $dsn['database'];
2307            unset($dsn['database']);
2308        }
2309        $this->dsn = array_merge($dsn_default, $dsn);
2310        return $this->disconnect(false);
2311    }
2312
2313    // }}}
2314    // {{{ function getDSN($type = 'string', $hidepw = false)
2315
2316    /**
2317     * return the DSN as a string
2318     *
2319     * @param   string  format to return ("array", "string")
2320     * @param   string  string to hide the password with
2321     *
2322     * @return  mixed   DSN in the chosen type
2323     *
2324     * @access  public
2325     */
2326    function getDSN($type = 'string', $hidepw = false)
2327    {
2328        $dsn = array_merge($GLOBALS['_MDB2_dsninfo_default'], $this->dsn);
2329        $dsn['phptype'] = $this->phptype;
2330        $dsn['database'] = $this->database_name;
2331        if ($hidepw) {
2332            $dsn['password'] = $hidepw;
2333        }
2334        switch ($type) {
2335        // expand to include all possible options
2336        case 'string':
2337           $dsn = $dsn['phptype'].
2338               ($dsn['dbsyntax'] ? ('('.$dsn['dbsyntax'].')') : '').
2339               '://'.$dsn['username'].':'.
2340                $dsn['password'].'@'.$dsn['hostspec'].
2341                ($dsn['port'] ? (':'.$dsn['port']) : '').
2342                '/'.$dsn['database'];
2343            break;
2344        case 'array':
2345        default:
2346            break;
2347        }
2348        return $dsn;
2349    }
2350
2351    // }}}
2352    // {{{ function &standaloneQuery($query, $types = null, $is_manip = false)
2353
2354   /**
2355     * execute a query as database administrator
2356     *
2357     * @param   string  the SQL query
2358     * @param   mixed   array that contains the types of the columns in
2359     *                        the result set
2360     * @param   bool    if the query is a manipulation query
2361     *
2362     * @return  mixed   MDB2_OK on success, a MDB2 error on failure
2363     *
2364     * @access  public
2365     */
2366    function &standaloneQuery($query, $types = null, $is_manip = false)
2367    {
2368        $offset = $this->offset;
2369        $limit = $this->limit;
2370        $this->offset = $this->limit = 0;
2371        $query = $this->_modifyQuery($query, $is_manip, $limit, $offset);
2372
2373        $connection = $this->getConnection();
2374        if (PEAR::isError($connection)) {
2375            return $connection;
2376        }
2377
2378        $result =& $this->_doQuery($query, $is_manip, $connection, false);
2379        if (PEAR::isError($result)) {
2380            return $result;
2381        }
2382
2383        if ($is_manip) {
2384            $affected_rows =  $this->_affectedRows($connection, $result);
2385            return $affected_rows;
2386        }
2387        $result =& $this->_wrapResult($result, $types, true, false, $limit, $offset);
2388        return $result;
2389    }
2390
2391    // }}}
2392    // {{{ function _modifyQuery($query, $is_manip, $limit, $offset)
2393
2394    /**
2395     * Changes a query string for various DBMS specific reasons
2396     *
2397     * @param   string  query to modify
2398     * @param   bool    if it is a DML query
2399     * @param   int  limit the number of rows
2400     * @param   int  start reading from given offset
2401     *
2402     * @return  string  modified query
2403     *
2404     * @access  protected
2405     */
2406    function _modifyQuery($query, $is_manip, $limit, $offset)
2407    {
2408        return $query;
2409    }
2410
2411    // }}}
2412    // {{{ function &_doQuery($query, $is_manip = false, $connection = null, $database_name = null)
2413
2414    /**
2415     * Execute a query
2416     * @param   string  query
2417     * @param   bool    if the query is a manipulation query
2418     * @param   resource connection handle
2419     * @param   string  database name
2420     *
2421     * @return  result or error object
2422     *
2423     * @access  protected
2424     */
2425    function &_doQuery($query, $is_manip = false, $connection = null, $database_name = null)
2426    {
2427        $this->last_query = $query;
2428        $result = $this->debug($query, 'query', array('is_manip' => $is_manip, 'when' => 'pre'));
2429        if ($result) {
2430            if (PEAR::isError($result)) {
2431                return $result;
2432            }
2433            $query = $result;
2434        }
2435        $err =& $this->raiseError(MDB2_ERROR_UNSUPPORTED, null, null,
2436            'method not implemented', __FUNCTION__);
2437        return $err;
2438    }
2439
2440    // }}}
2441    // {{{ function _affectedRows($connection, $result = null)
2442
2443    /**
2444     * Returns the number of rows affected
2445     *
2446     * @param   resource result handle
2447     * @param   resource connection handle
2448     *
2449     * @return  mixed   MDB2 Error Object or the number of rows affected
2450     *
2451     * @access  private
2452     */
2453    function _affectedRows($connection, $result = null)
2454    {
2455        return $this->raiseError(MDB2_ERROR_UNSUPPORTED, null, null,
2456            'method not implemented', __FUNCTION__);
2457    }
2458
2459    // }}}
2460    // {{{ function &exec($query)
2461
2462    /**
2463     * Execute a manipulation query to the database and return the number of affected rows
2464     *
2465     * @param   string  the SQL query
2466     *
2467     * @return  mixed   number of affected rows on success, a MDB2 error on failure
2468     *
2469     * @access  public
2470     */
2471    function &exec($query)
2472    {
2473        $offset = $this->offset;
2474        $limit = $this->limit;
2475        $this->offset = $this->limit = 0;
2476        $query = $this->_modifyQuery($query, true, $limit, $offset);
2477
2478        $connection = $this->getConnection();
2479        if (PEAR::isError($connection)) {
2480            return $connection;
2481        }
2482
2483        $result =& $this->_doQuery($query, true, $connection, $this->database_name);
2484        if (PEAR::isError($result)) {
2485            return $result;
2486        }
2487
2488        $affectedRows = $this->_affectedRows($connection, $result);
2489        return $affectedRows;
2490    }
2491
2492    // }}}
2493    // {{{ function &query($query, $types = null, $result_class = true, $result_wrap_class = false)
2494
2495    /**
2496     * Send a query to the database and return any results
2497     *
2498     * @param   string  the SQL query
2499     * @param   mixed   array that contains the types of the columns in
2500     *                        the result set
2501     * @param   mixed   string which specifies which result class to use
2502     * @param   mixed   string which specifies which class to wrap results in
2503     *
2504     * @return mixed   an MDB2_Result handle on success, a MDB2 error on failure
2505     *
2506     * @access  public
2507     */
2508    function &query($query, $types = null, $result_class = true, $result_wrap_class = false)
2509    {
2510        $offset = $this->offset;
2511        $limit = $this->limit;
2512        $this->offset = $this->limit = 0;
2513        $query = $this->_modifyQuery($query, false, $limit, $offset);
2514
2515        $connection = $this->getConnection();
2516        if (PEAR::isError($connection)) {
2517            return $connection;
2518        }
2519
2520        $result =& $this->_doQuery($query, false, $connection, $this->database_name);
2521        if (PEAR::isError($result)) {
2522            return $result;
2523        }
2524
2525        $result =& $this->_wrapResult($result, $types, $result_class, $result_wrap_class, $limit, $offset);
2526        return $result;
2527    }
2528
2529    // }}}
2530    // {{{ function &_wrapResult($result, $types = array(), $result_class = true, $result_wrap_class = false, $limit = null, $offset = null)
2531
2532    /**
2533     * wrap a result set into the correct class
2534     *
2535     * @param   resource result handle
2536     * @param   mixed   array that contains the types of the columns in
2537     *                        the result set
2538     * @param   mixed   string which specifies which result class to use
2539     * @param   mixed   string which specifies which class to wrap results in
2540     * @param   string  number of rows to select
2541     * @param   string  first row to select
2542     *
2543     * @return mixed   an MDB2_Result, a MDB2 error on failure
2544     *
2545     * @access  protected
2546     */
2547    function &_wrapResult($result, $types = array(), $result_class = true,
2548        $result_wrap_class = false, $limit = null, $offset = null)
2549    {
2550        if ($types === true) {
2551            if ($this->supports('result_introspection')) {
2552                $this->loadModule('Reverse', null, true);
2553                $tableInfo = $this->reverse->tableInfo($result);
2554                if (PEAR::isError($tableInfo)) {
2555                    return $tableInfo;
2556                }
2557                $types = array();
2558                foreach ($tableInfo as $field) {
2559                    $types[] = $field['mdb2type'];
2560                }
2561            } else {
2562                $types = null;
2563            }
2564        }
2565
2566        if ($result_class === true) {
2567            $result_class = $this->options['result_buffering']
2568                ? $this->options['buffered_result_class'] : $this->options['result_class'];
2569        }
2570
2571        if ($result_class) {
2572            $class_name = sprintf($result_class, $this->phptype);
2573            if (!MDB2::classExists($class_name)) {
2574                $err =& $this->raiseError(MDB2_ERROR_NOT_FOUND, null, null,
2575                    'result class does not exist '.$class_name, __FUNCTION__);
2576                return $err;
2577            }
2578            $result =& new $class_name($this, $result, $limit, $offset);
2579            if (!MDB2::isResultCommon($result)) {
2580                $err =& $this->raiseError(MDB2_ERROR_NOT_FOUND, null, null,
2581                    'result class is not extended from MDB2_Result_Common', __FUNCTION__);
2582                return $err;
2583            }
2584            if (!empty($types)) {
2585                $err = $result->setResultTypes($types);
2586                if (PEAR::isError($err)) {
2587                    $result->free();
2588                    return $err;
2589                }
2590            }
2591        }
2592        if ($result_wrap_class === true) {
2593            $result_wrap_class = $this->options['result_wrap_class'];
2594        }
2595        if ($result_wrap_class) {
2596            if (!MDB2::classExists($result_wrap_class)) {
2597                $err =& $this->raiseError(MDB2_ERROR_NOT_FOUND, null, null,
2598                    'result wrap class does not exist '.$result_wrap_class, __FUNCTION__);
2599                return $err;
2600            }
2601            $result =& new $result_wrap_class($result, $this->fetchmode);
2602        }
2603        return $result;
2604    }
2605
2606    // }}}
2607    // {{{ function getServerVersion($native = false)
2608
2609    /**
2610     * return version information about the server
2611     *
2612     * @param   bool    determines if the raw version string should be returned
2613     *
2614     * @return  mixed   array with version information or row string
2615     *
2616     * @access  public
2617     */
2618    function getServerVersion($native = false)
2619    {
2620        return $this->raiseError(MDB2_ERROR_UNSUPPORTED, null, null,
2621            'method not implemented', __FUNCTION__);
2622    }
2623
2624    // }}}
2625    // {{{ function setLimit($limit, $offset = null)
2626
2627    /**
2628     * set the range of the next query
2629     *
2630     * @param   string  number of rows to select
2631     * @param   string  first row to select
2632     *
2633     * @return  mixed   MDB2_OK on success, a MDB2 error on failure
2634     *
2635     * @access  public
2636     */
2637    function setLimit($limit, $offset = null)
2638    {
2639        if (!$this->supports('limit_queries')) {
2640            return $this->raiseError(MDB2_ERROR_UNSUPPORTED, null, null,
2641                'limit is not supported by this driver', __FUNCTION__);
2642        }
2643        $limit = (int)$limit;
2644        if ($limit < 0) {
2645            return $this->raiseError(MDB2_ERROR_SYNTAX, null, null,
2646                'it was not specified a valid selected range row limit', __FUNCTION__);
2647        }
2648        $this->limit = $limit;
2649        if (!is_null($offset)) {
2650            $offset = (int)$offset;
2651            if ($offset < 0) {
2652                return $this->raiseError(MDB2_ERROR_SYNTAX, null, null,
2653                    'it was not specified a valid first selected range row', __FUNCTION__);
2654            }
2655            $this->offset = $offset;
2656        }
2657        return MDB2_OK;
2658    }
2659
2660    // }}}
2661    // {{{ function subSelect($query, $type = false)
2662
2663    /**
2664     * simple subselect emulation: leaves the query untouched for all RDBMS
2665     * that support subselects
2666     *
2667     * @param   string  the SQL query for the subselect that may only
2668     *                      return a column
2669     * @param   string  determines type of the field
2670     *
2671     * @return  string  the query
2672     *
2673     * @access  public
2674     */
2675    function subSelect($query, $type = false)
2676    {
2677        if ($this->supports('sub_selects') === true) {
2678            return $query;
2679        }
2680
2681        if (!$this->supports('sub_selects')) {
2682            return $this->raiseError(MDB2_ERROR_UNSUPPORTED, null, null,
2683                'method not implemented', __FUNCTION__);
2684        }
2685
2686        $col = $this->queryCol($query, $type);
2687        if (PEAR::isError($col)) {
2688            return $col;
2689        }
2690        if (!is_array($col) || count($col) == 0) {
2691            return 'NULL';
2692        }
2693        if ($type) {
2694            $this->loadModule('Datatype', null, true);
2695            return $this->datatype->implodeArray($col, $type);
2696        }
2697        return implode(', ', $col);
2698    }
2699
2700    // }}}
2701    // {{{ function replace($table, $fields)
2702
2703    /**
2704     * Execute a SQL REPLACE query. A REPLACE query is identical to a INSERT
2705     * query, except that if there is already a row in the table with the same
2706     * key field values, the REPLACE query just updates its values instead of
2707     * inserting a new row.
2708     *
2709     * The REPLACE type of query does not make part of the SQL standards. Since
2710     * practically only MySQL and SQLite implement it natively, this type of
2711     * query isemulated through this method for other DBMS using standard types
2712     * of queries inside a transaction to assure the atomicity of the operation.
2713     *
2714     * @param   string  name of the table on which the REPLACE query will
2715     *       be executed.
2716     * @param   array   associative array   that describes the fields and the
2717     *       values that will be inserted or updated in the specified table. The
2718     *       indexes of the array are the names of all the fields of the table.
2719     *       The values of the array are also associative arrays that describe
2720     *       the values and other properties of the table fields.
2721     *
2722     *       Here follows a list of field properties that need to be specified:
2723     *
2724     *       value
2725     *           Value to be assigned to the specified field. This value may be
2726     *           of specified in database independent type format as this
2727     *           function can perform the necessary datatype conversions.
2728     *
2729     *           Default: this property is required unless the Null property is
2730     *           set to 1.
2731     *
2732     *       type
2733     *           Name of the type of the field. Currently, all types MDB2
2734     *           are supported except for clob and blob.
2735     *
2736     *           Default: no type conversion
2737     *
2738     *       null
2739     *           bool    property that indicates that the value for this field
2740     *           should be set to null.
2741     *
2742     *           The default value for fields missing in INSERT queries may be
2743     *           specified the definition of a table. Often, the default value
2744     *           is already null, but since the REPLACE may be emulated using
2745     *           an UPDATE query, make sure that all fields of the table are
2746     *           listed in this function argument array.
2747     *
2748     *           Default: 0
2749     *
2750     *       key
2751     *           bool    property that indicates that this field should be
2752     *           handled as a primary key or at least as part of the compound
2753     *           unique index of the table that will determine the row that will
2754     *           updated if it exists or inserted a new row otherwise.
2755     *
2756     *           This function will fail if no key field is specified or if the
2757     *           value of a key field is set to null because fields that are
2758     *           part of unique index they may not be null.
2759     *
2760     *           Default: 0
2761     *
2762     * @return  mixed   MDB2_OK on success, a MDB2 error on failure
2763     *
2764     * @access  public
2765     */
2766    function replace($table, $fields)
2767    {
2768        if (!$this->supports('replace')) {
2769            return $this->raiseError(MDB2_ERROR_UNSUPPORTED, null, null,
2770                'replace query is not supported', __FUNCTION__);
2771        }
2772        $count = count($fields);
2773        $condition = $values = array();
2774        for ($colnum = 0, reset($fields); $colnum < $count; next($fields), $colnum++) {
2775            $name = key($fields);
2776            if (isset($fields[$name]['null']) && $fields[$name]['null']) {
2777                $value = 'NULL';
2778            } else {
2779                $type = isset($fields[$name]['type']) ? $fields[$name]['type'] : null;
2780                $value = $this->quote($fields[$name]['value'], $type);
2781            }
2782            $values[$name] = $value;
2783            if (isset($fields[$name]['key']) && $fields[$name]['key']) {
2784                if ($value === 'NULL') {
2785                    return $this->raiseError(MDB2_ERROR_CANNOT_REPLACE, null, null,
2786                        'key value '.$name.' may not be NULL', __FUNCTION__);
2787                }
2788                $condition[] = $name . '=' . $value;
2789            }
2790        }
2791        if (empty($condition)) {
2792            return $this->raiseError(MDB2_ERROR_CANNOT_REPLACE, null, null,
2793                'not specified which fields are keys', __FUNCTION__);
2794        }
2795
2796        $result = null;
2797        $in_transaction = $this->in_transaction;
2798        if (!$in_transaction && PEAR::isError($result = $this->beginTransaction())) {
2799            return $result;
2800        }
2801
2802        $connection = $this->getConnection();
2803        if (PEAR::isError($connection)) {
2804            return $connection;
2805        }
2806
2807        $condition = ' WHERE '.implode(' AND ', $condition);
2808        $query = "DELETE FROM $table$condition";
2809        $result =& $this->_doQuery($query, true, $connection);
2810        if (!PEAR::isError($result)) {
2811            $affected_rows = $this->_affectedRows($connection, $result);
2812            $insert = implode(', ', array_keys($values));
2813            $values = implode(', ', $values);
2814            $query = "INSERT INTO $table ($insert) VALUES ($values)";
2815            $result =& $this->_doQuery($query, true, $connection);
2816            if (!PEAR::isError($result)) {
2817                $affected_rows += $this->_affectedRows($connection, $result);;
2818            }
2819        }
2820
2821        if (!$in_transaction) {
2822            if (PEAR::isError($result)) {
2823                $this->rollback();
2824            } else {
2825                $result = $this->commit();
2826            }
2827        }
2828
2829        if (PEAR::isError($result)) {
2830            return $result;
2831        }
2832
2833        return $affected_rows;
2834    }
2835
2836    // }}}
2837    // {{{ function &prepare($query, $types = null, $result_types = null, $lobs = array())
2838
2839    /**
2840     * Prepares a query for multiple execution with execute().
2841     * With some database backends, this is emulated.
2842     * prepare() requires a generic query as string like
2843     * 'INSERT INTO numbers VALUES(?,?)' or
2844     * 'INSERT INTO numbers VALUES(:foo,:bar)'.
2845     * The ? and :[a-zA-Z] and  are placeholders which can be set using
2846     * bindParam() and the query can be send off using the execute() method.
2847     *
2848     * @param   string  the query to prepare
2849     * @param   mixed   array that contains the types of the placeholders
2850     * @param   mixed   array that contains the types of the columns in
2851     *                        the result set or MDB2_PREPARE_RESULT, if set to
2852     *                        MDB2_PREPARE_MANIP the query is handled as a manipulation query
2853     * @param   mixed   key (field) value (parameter) pair for all lob placeholders
2854     *
2855     * @return  mixed   resource handle for the prepared query on success,
2856     *                  a MDB2 error on failure
2857     *
2858     * @access  public
2859     * @see     bindParam, execute
2860     */
2861    function &prepare($query, $types = null, $result_types = null, $lobs = array())
2862    {
2863        $is_manip = ($result_types === MDB2_PREPARE_MANIP);
2864        $offset = $this->offset;
2865        $limit = $this->limit;
2866        $this->offset = $this->limit = 0;
2867        $result = $this->debug($query, __FUNCTION__, array('is_manip' => $is_manip, 'when' => 'pre'));
2868        if ($result) {
2869            if (PEAR::isError($result)) {
2870                return $result;
2871            }
2872            $query = $result;
2873        }
2874        $placeholder_type_guess = $placeholder_type = null;
2875        $question = '?';
2876        $colon = ':';
2877        $positions = array();
2878        $position = 0;
2879        $ignores = $this->sql_comments;
2880        $ignores[] = $this->string_quoting;
2881        $ignores[] = $this->identifier_quoting;
2882        while ($position < strlen($query)) {
2883            $q_position = strpos($query, $question, $position);
2884            $c_position = strpos($query, $colon, $position);
2885            if ($q_position && $c_position) {
2886                $p_position = min($q_position, $c_position);
2887            } elseif ($q_position) {
2888                $p_position = $q_position;
2889            } elseif ($c_position) {
2890                $p_position = $c_position;
2891            } else {
2892                break;
2893            }
2894            if (is_null($placeholder_type)) {
2895                $placeholder_type_guess = $query[$p_position];
2896            }
2897
2898            $new_pos = $this->_skipDelimitedStrings($query, $position, $p_position);
2899            if (PEAR::isError($new_pos)) {
2900                return $new_pos;
2901            }
2902            if ($new_pos != $position) {
2903                $position = $new_pos;
2904                continue; //evaluate again starting from the new position
2905            }
2906
2907            if ($query[$position] == $placeholder_type_guess) {
2908                if (is_null($placeholder_type)) {
2909                    $placeholder_type = $query[$p_position];
2910                    $question = $colon = $placeholder_type;
2911                    if (!empty($types) && is_array($types)) {
2912                        if ($placeholder_type == ':') {
2913                            if (is_int(key($types))) {
2914                                $types_tmp = $types;
2915                                $types = array();
2916                                $count = -1;
2917                            }
2918                        } else {
2919                            $types = array_values($types);
2920                        }
2921                    }
2922                }
2923                if ($placeholder_type == ':') {
2924                    $parameter = preg_replace('/^.{'.($position+1).'}([a-z0-9_]+).*$/si', '\\1', $query);
2925                    if ($parameter === '') {
2926                        $err =& $this->raiseError(MDB2_ERROR_SYNTAX, null, null,
2927                            'named parameter with an empty name', __FUNCTION__);
2928                        return $err;
2929                    }
2930                    $positions[$p_position] = $parameter;
2931                    $query = substr_replace($query, '?', $position, strlen($parameter)+1);
2932                    // use parameter name in type array
2933                    if (isset($count) && isset($types_tmp[++$count])) {
2934                        $types[$parameter] = $types_tmp[$count];
2935                    }
2936                } else {
2937                    $positions[$p_position] = count($positions);
2938                }
2939                $position = $p_position + 1;
2940            } else {
2941                $position = $p_position;
2942            }
2943        }
2944        $class_name = 'MDB2_Statement_'.$this->phptype;
2945        $statement = null;
2946        $obj =& new $class_name($this, $statement, $positions, $query, $types, $result_types, $is_manip, $limit, $offset);
2947        $this->debug($query, __FUNCTION__, array('is_manip' => $is_manip, 'when' => 'post', 'result' => $obj));
2948        return $obj;
2949    }
2950
2951    // }}}
2952    // {{{ function _skipDelimitedStrings($query, $position, $p_position)
2953   
2954    /**
2955     * Utility method, used by prepare() to avoid replacing placeholders within delimited strings.
2956     * Check if the placeholder is contained within a delimited string.
2957     * If so, skip it and advance the position, otherwise return the current position,
2958     * which is valid
2959     *
2960     * @param string $query
2961     * @param integer $position current string cursor position
2962     * @param integer $p_position placeholder position
2963     *
2964     * @return mixed integer $new_position on success
2965     *               MDB2_Error on failure
2966     *
2967     * @access  protected
2968     */
2969    function _skipDelimitedStrings($query, $position, $p_position)
2970    {
2971        $ignores = $this->sql_comments;
2972        $ignores[] = $this->string_quoting;
2973        $ignores[] = $this->identifier_quoting;
2974       
2975        foreach ($ignores as $ignore) {
2976            if (!empty($ignore['start'])) {
2977                if (is_int($start_quote = strpos($query, $ignore['start'], $position)) && $start_quote < $p_position) {
2978                    $end_quote = $start_quote;
2979                    do {
2980                        if (!is_int($end_quote = strpos($query, $ignore['end'], $end_quote + 1))) {
2981                            if ($ignore['end'] === "\n") {
2982                                $end_quote = strlen($query) - 1;
2983                            } else {
2984                                $err =& $this->raiseError(MDB2_ERROR_SYNTAX, null, null,
2985                                    'query with an unterminated text string specified', __FUNCTION__);
2986                                return $err;
2987                            }
2988                        }
2989                    } while ($ignore['escape'] && $query[($end_quote - 1)] == $ignore['escape']);
2990                    $position = $end_quote + 1;
2991                    return $position;
2992                }
2993            }
2994        }
2995        return $position;
2996    }
2997   
2998    // }}}
2999    // {{{ function quote($value, $type = null, $quote = true)
3000
3001    /**
3002     * Convert a text value into a DBMS specific format that is suitable to
3003     * compose query statements.
3004     *
3005     * @param   string  text string value that is intended to be converted.
3006     * @param   string  type to which the value should be converted to
3007     * @param   bool    quote
3008     * @param   bool    escape wildcards
3009     *
3010     * @return  string  text string that represents the given argument value in
3011     *       a DBMS specific format.
3012     *
3013     * @access  public
3014     */
3015    function quote($value, $type = null, $quote = true, $escape_wildcards = false)
3016    {
3017        $result = $this->loadModule('Datatype', null, true);
3018        if (PEAR::isError($result)) {
3019            return $result;
3020        }
3021
3022        return $this->datatype->quote($value, $type, $quote, $escape_wildcards);
3023    }
3024
3025    // }}}
3026    // {{{ function getDeclaration($type, $name, $field)
3027
3028    /**
3029     * Obtain DBMS specific SQL code portion needed to declare
3030     * of the given type
3031     *
3032     * @param   string  type to which the value should be converted to
3033     * @param   string  name the field to be declared.
3034     * @param   string  definition of the field
3035     *
3036     * @return  string  DBMS specific SQL code portion that should be used to
3037     *                 declare the specified field.
3038     *
3039     * @access  public
3040     */
3041    function getDeclaration($type, $name, $field)
3042    {
3043        $result = $this->loadModule('Datatype', null, true);
3044        if (PEAR::isError($result)) {
3045            return $result;
3046        }
3047        return $this->datatype->getDeclaration($type, $name, $field);
3048    }
3049
3050    // }}}
3051    // {{{ function compareDefinition($current, $previous)
3052
3053    /**
3054     * Obtain an array of changes that may need to applied
3055     *
3056     * @param   array   new definition
3057     * @param   array   old definition
3058     *
3059     * @return  array   containing all changes that will need to be applied
3060     *
3061     * @access  public
3062     */
3063    function compareDefinition($current, $previous)
3064    {
3065        $result = $this->loadModule('Datatype', null, true);
3066        if (PEAR::isError($result)) {
3067            return $result;
3068        }
3069        return $this->datatype->compareDefinition($current, $previous);
3070    }
3071
3072    // }}}
3073    // {{{ function supports($feature)
3074
3075    /**
3076     * Tell whether a DB implementation or its backend extension
3077     * supports a given feature.
3078     *
3079     * @param   string  name of the feature (see the MDB2 class doc)
3080     *
3081     * @return  bool|string if this DB implementation supports a given feature
3082     *                      false means no, true means native,
3083     *                      'emulated' means emulated
3084     *
3085     * @access  public
3086     */
3087    function supports($feature)
3088    {
3089        if (array_key_exists($feature, $this->supported)) {
3090            return $this->supported[$feature];
3091        }
3092        return $this->raiseError(MDB2_ERROR_UNSUPPORTED, null, null,
3093            "unknown support feature $feature", __FUNCTION__);
3094    }
3095
3096    // }}}
3097    // {{{ function getSequenceName($sqn)
3098
3099    /**
3100     * adds sequence name formatting to a sequence name
3101     *
3102     * @param   string  name of the sequence
3103     *
3104     * @return  string  formatted sequence name
3105     *
3106     * @access  public
3107     */
3108    function getSequenceName($sqn)
3109    {
3110        return sprintf($this->options['seqname_format'],
3111            preg_replace('/[^a-z0-9_\$.]/i', '_', $sqn));
3112    }
3113
3114    // }}}
3115    // {{{ function getIndexName($idx)
3116
3117    /**
3118     * adds index name formatting to a index name
3119     *
3120     * @param   string  name of the index
3121     *
3122     * @return  string  formatted index name
3123     *
3124     * @access  public
3125     */
3126    function getIndexName($idx)
3127    {
3128        return sprintf($this->options['idxname_format'],
3129            preg_replace('/[^a-z0-9_\$]/i', '_', $idx));
3130    }
3131
3132    // }}}
3133    // {{{ function nextID($seq_name, $ondemand = true)
3134
3135    /**
3136     * Returns the next free id of a sequence
3137     *
3138     * @param   string  name of the sequence
3139     * @param   bool    when true missing sequences are automatic created
3140     *
3141     * @return  mixed   MDB2 Error Object or id
3142     *
3143     * @access  public
3144     */
3145    function nextID($seq_name, $ondemand = true)
3146    {
3147        return $this->raiseError(MDB2_ERROR_UNSUPPORTED, null, null,
3148            'method not implemented', __FUNCTION__);
3149    }
3150
3151    // }}}
3152    // {{{ function lastInsertID($table = null, $field = null)
3153
3154    /**
3155     * Returns the autoincrement ID if supported or $id or fetches the current
3156     * ID in a sequence called: $table.(empty($field) ? '' : '_'.$field)
3157     *
3158     * @param   string  name of the table into which a new row was inserted
3159     * @param   string  name of the field into which a new row was inserted
3160     *
3161     * @return  mixed   MDB2 Error Object or id
3162     *
3163     * @access  public
3164     */
3165    function lastInsertID($table = null, $field = null)
3166    {
3167        return $this->raiseError(MDB2_ERROR_UNSUPPORTED, null, null,
3168            'method not implemented', __FUNCTION__);
3169    }
3170
3171    // }}}
3172    // {{{ function currID($seq_name)
3173
3174    /**
3175     * Returns the current id of a sequence
3176     *
3177     * @param   string  name of the sequence
3178     *
3179     * @return  mixed   MDB2 Error Object or id
3180     *
3181     * @access  public
3182     */
3183    function currID($seq_name)
3184    {
3185        $this->warnings[] = 'database does not support getting current
3186            sequence value, the sequence value was incremented';
3187        return $this->nextID($seq_name);
3188    }
3189
3190    // }}}
3191    // {{{ function queryOne($query, $type = null, $colnum = 0)
3192
3193    /**
3194     * Execute the specified query, fetch the value from the first column of
3195     * the first row of the result set and then frees
3196     * the result set.
3197     *
3198     * @param   string  the SELECT query statement to be executed.
3199     * @param   string  optional argument that specifies the expected
3200     *       datatype of the result set field, so that an eventual conversion
3201     *       may be performed. The default datatype is text, meaning that no
3202     *       conversion is performed
3203     * @param   int     the column number to fetch
3204     *
3205     * @return  mixed   MDB2_OK or field value on success, a MDB2 error on failure
3206     *
3207     * @access  public
3208     */
3209    function queryOne($query, $type = null, $colnum = 0)
3210    {
3211        $result = $this->query($query, $type);
3212        if (!MDB2::isResultCommon($result)) {
3213            return $result;
3214        }
3215
3216        $one = $result->fetchOne($colnum);
3217        $result->free();
3218        return $one;
3219    }
3220
3221    // }}}
3222    // {{{ function queryRow($query, $types = null, $fetchmode = MDB2_FETCHMODE_DEFAULT)
3223
3224    /**
3225     * Execute the specified query, fetch the values from the first
3226     * row of the result set into an array and then frees
3227     * the result set.
3228     *
3229     * @param   string  the SELECT query statement to be executed.
3230     * @param   array   optional array argument that specifies a list of
3231     *       expected datatypes of the result set columns, so that the eventual
3232     *       conversions may be performed. The default list of datatypes is
3233     *       empty, meaning that no conversion is performed.
3234     * @param   int     how the array data should be indexed
3235     *
3236     * @return  mixed   MDB2_OK or data array on success, a MDB2 error on failure
3237     *
3238     * @access  public
3239     */
3240    function queryRow($query, $types = null, $fetchmode = MDB2_FETCHMODE_DEFAULT)
3241    {
3242        $result = $this->query($query, $types);
3243        if (!MDB2::isResultCommon($result)) {
3244            return $result;
3245        }
3246
3247        $row = $result->fetchRow($fetchmode);
3248        $result->free();
3249        return $row;
3250    }
3251
3252    // }}}
3253    // {{{ function queryCol($query, $type = null, $colnum = 0)
3254
3255    /**
3256     * Execute the specified query, fetch the value from the first column of
3257     * each row of the result set into an array and then frees the result set.
3258     *
3259     * @param   string  the SELECT query statement to be executed.
3260     * @param   string  optional argument that specifies the expected
3261     *       datatype of the result set field, so that an eventual conversion
3262     *       may be performed. The default datatype is text, meaning that no
3263     *       conversion is performed
3264     * @param   int     the row number to fetch
3265     *
3266     * @return  mixed   MDB2_OK or data array on success, a MDB2 error on failure
3267     *
3268     * @access  public
3269     */
3270    function queryCol($query, $type = null, $colnum = 0)
3271    {
3272        $result = $this->query($query, $type);
3273        if (!MDB2::isResultCommon($result)) {
3274            return $result;
3275        }
3276
3277        $col = $result->fetchCol($colnum);
3278        $result->free();
3279        return $col;
3280    }
3281
3282    // }}}
3283    // {{{ function queryAll($query, $types = null, $fetchmode = MDB2_FETCHMODE_DEFAULT, $rekey = false, $force_array = false, $group = false)
3284
3285    /**
3286     * Execute the specified query, fetch all the rows of the result set into
3287     * a two dimensional array and then frees the result set.
3288     *
3289     * @param   string  the SELECT query statement to be executed.
3290     * @param   array   optional array argument that specifies a list of
3291     *       expected datatypes of the result set columns, so that the eventual
3292     *       conversions may be performed. The default list of datatypes is
3293     *       empty, meaning that no conversion is performed.
3294     * @param   int     how the array data should be indexed
3295     * @param   bool    if set to true, the $all will have the first
3296     *       column as its first dimension
3297     * @param   bool    used only when the query returns exactly
3298     *       two columns. If true, the values of the returned array will be
3299     *       one-element arrays instead of scalars.
3300     * @param   bool    if true, the values of the returned array is
3301     *       wrapped in another array.  If the same key value (in the first
3302     *       column) repeats itself, the values will be appended to this array
3303     *       instead of overwriting the existing values.
3304     *
3305     * @return  mixed   MDB2_OK or data array on success, a MDB2 error on failure
3306     *
3307     * @access  public
3308     */
3309    function queryAll($query, $types = null, $fetchmode = MDB2_FETCHMODE_DEFAULT,
3310        $rekey = false, $force_array = false, $group = false)
3311    {
3312        $result = $this->query($query, $types);
3313        if (!MDB2::isResultCommon($result)) {
3314            return $result;
3315        }
3316
3317        $all = $result->fetchAll($fetchmode, $rekey, $force_array, $group);
3318        $result->free();
3319        return $all;
3320    }
3321
3322    // }}}
3323}
3324
3325// }}}
3326// {{{ class MDB2_Result
3327
3328/**
3329 * The dummy class that all user space result classes should extend from
3330 *
3331 * @package     MDB2
3332 * @category    Database
3333 * @author      Lukas Smith <smith@pooteeweet.org>
3334 */
3335class MDB2_Result
3336{
3337}
3338
3339// }}}
3340// {{{ class MDB2_Result_Common extends MDB2_Result
3341
3342/**
3343 * The common result class for MDB2 result objects
3344 *
3345 * @package     MDB2
3346 * @category    Database
3347 * @author      Lukas Smith <smith@pooteeweet.org>
3348 */
3349class MDB2_Result_Common extends MDB2_Result
3350{
3351    // {{{ Variables (Properties)
3352
3353    var $db;
3354    var $result;
3355    var $rownum = -1;
3356    var $types = array();
3357    var $values = array();
3358    var $offset;
3359    var $offset_count = 0;
3360    var $limit;
3361    var $column_names;
3362
3363    // }}}
3364    // {{{ constructor: function __construct(&$db, &$result, $limit = 0, $offset = 0)
3365
3366    /**
3367     * Constructor
3368     */
3369    function __construct(&$db, &$result, $limit = 0, $offset = 0)
3370    {
3371        $this->db =& $db;
3372        $this->result =& $result;
3373        $this->offset = $offset;
3374        $this->limit = max(0, $limit - 1);
3375    }
3376
3377    // }}}
3378    // {{{ function MDB2_Result_Common(&$db, &$result, $limit = 0, $offset = 0)
3379
3380    /**
3381     * PHP 4 Constructor
3382     */
3383    function MDB2_Result_Common(&$db, &$result, $limit = 0, $offset = 0)
3384    {
3385        $this->__construct($db, $result, $limit, $offset);
3386    }
3387
3388    // }}}
3389    // {{{ function setResultTypes($types)
3390
3391    /**
3392     * Define the list of types to be associated with the columns of a given
3393     * result set.
3394     *
3395     * This function may be called before invoking fetchRow(), fetchOne(),
3396     * fetchCol() and fetchAll() so that the necessary data type
3397     * conversions are performed on the data to be retrieved by them. If this
3398     * function is not called, the type of all result set columns is assumed
3399     * to be text, thus leading to not perform any conversions.
3400     *
3401     * @param   array   variable that lists the
3402     *       data types to be expected in the result set columns. If this array
3403     *       contains less types than the number of columns that are returned
3404     *       in the result set, the remaining columns are assumed to be of the
3405     *       type text. Currently, the types clob and blob are not fully
3406     *       supported.
3407     *
3408     * @return  mixed   MDB2_OK on success, a MDB2 error on failure
3409     *
3410     * @access  public
3411     */
3412    function setResultTypes($types)
3413    {
3414        $load = $this->db->loadModule('Datatype', null, true);
3415        if (PEAR::isError($load)) {
3416            return $load;
3417        }
3418        $types = $this->db->datatype->checkResultTypes($types);
3419        if (PEAR::isError($types)) {
3420            return $types;
3421        }
3422        $this->types = $types;
3423        return MDB2_OK;
3424    }
3425
3426    // }}}
3427    // {{{ function seek($rownum = 0)
3428
3429    /**
3430     * Seek to a specific row in a result set
3431     *
3432     * @param   int     number of the row where the data can be found
3433     *
3434     * @return  mixed   MDB2_OK on success, a MDB2 error on failure
3435     *
3436     * @access  public
3437     */
3438    function seek($rownum = 0)
3439    {
3440        $target_rownum = $rownum - 1;
3441        if ($this->rownum > $target_rownum) {
3442            return $this->db->raiseError(MDB2_ERROR_UNSUPPORTED, null, null,
3443                'seeking to previous rows not implemented', __FUNCTION__);
3444        }
3445        while ($this->rownum < $target_rownum) {
3446            $this->fetchRow();
3447        }
3448        return MDB2_OK;
3449    }
3450
3451    // }}}
3452    // {{{ function &fetchRow($fetchmode = MDB2_FETCHMODE_DEFAULT, $rownum = null)
3453
3454    /**
3455     * Fetch and return a row of data
3456     *
3457     * @param   int     how the array data should be indexed
3458     * @param   int     number of the row where the data can be found
3459     *
3460     * @return  int     data array on success, a MDB2 error on failure
3461     *
3462     * @access  public
3463     */
3464    function &fetchRow($fetchmode = MDB2_FETCHMODE_DEFAULT, $rownum = null)
3465    {
3466        $err =& $this->db->raiseError(MDB2_ERROR_UNSUPPORTED, null, null,
3467            'method not implemented', __FUNCTION__);
3468        return $err;
3469    }
3470
3471    // }}}
3472    // {{{ function fetchOne($colnum = 0)
3473
3474    /**
3475     * fetch single column from the next row from a result set
3476     *
3477     * @param   int     the column number to fetch
3478     * @param   int     number of the row where the data can be found
3479     *
3480     * @return  string  data on success, a MDB2 error on failure
3481     *
3482     * @access  public
3483     */
3484    function fetchOne($colnum = 0, $rownum = null)
3485    {
3486        $fetchmode = is_numeric($colnum) ? MDB2_FETCHMODE_ORDERED : MDB2_FETCHMODE_ASSOC;
3487        $row = $this->fetchRow($fetchmode, $rownum);
3488        if (!is_array($row) || PEAR::isError($row)) {
3489            return $row;
3490        }
3491        if (!array_key_exists($colnum, $row)) {
3492            return $this->db->raiseError(MDB2_ERROR_TRUNCATED, null, null,
3493                'column is not defined in the result set: '.$colnum, __FUNCTION__);
3494        }
3495        return $row[$colnum];
3496    }
3497
3498    // }}}
3499    // {{{ function fetchCol($colnum = 0)
3500
3501    /**
3502     * Fetch and return a column from the current row pointer position
3503     *
3504     * @param   int     the column number to fetch
3505     *
3506     * @return  mixed   data array on success, a MDB2 error on failure
3507     *
3508     * @access  public
3509     */
3510    function fetchCol($colnum = 0)
3511    {
3512        $column = array();
3513        $fetchmode = is_numeric($colnum) ? MDB2_FETCHMODE_ORDERED : MDB2_FETCHMODE_ASSOC;
3514        $row = $this->fetchRow($fetchmode);
3515        if (is_array($row)) {
3516            if (!array_key_exists($colnum, $row)) {
3517                return $this->db->raiseError(MDB2_ERROR_TRUNCATED, null, null,
3518                    'column is not defined in the result set: '.$colnum, __FUNCTION__);
3519            }
3520            do {
3521                $column[] = $row[$colnum];
3522            } while (is_array($row = $this->fetchRow($fetchmode)));
3523        }
3524        if (PEAR::isError($row)) {
3525            return $row;
3526        }
3527        return $column;
3528    }
3529
3530    // }}}
3531    // {{{ function fetchAll($fetchmode = MDB2_FETCHMODE_DEFAULT, $rekey = false, $force_array = false, $group = false)
3532
3533    /**
3534     * Fetch and return all rows from the current row pointer position
3535     *
3536     * @param   int     $fetchmode  the fetch mode to use:
3537     *                            + MDB2_FETCHMODE_ORDERED
3538     *                            + MDB2_FETCHMODE_ASSOC
3539     *                            + MDB2_FETCHMODE_ORDERED | MDB2_FETCHMODE_FLIPPED
3540     *                            + MDB2_FETCHMODE_ASSOC | MDB2_FETCHMODE_FLIPPED
3541     * @param   bool    if set to true, the $all will have the first
3542     *       column as its first dimension
3543     * @param   bool    used only when the query returns exactly
3544     *       two columns. If true, the values of the returned array will be
3545     *       one-element arrays instead of scalars.
3546     * @param   bool    if true, the values of the returned array is
3547     *       wrapped in another array.  If the same key value (in the first
3548     *       column) repeats itself, the values will be appended to this array
3549     *       instead of overwriting the existing values.
3550     *
3551     * @return  mixed   data array on success, a MDB2 error on failure
3552     *
3553     * @access  public
3554     * @see     getAssoc()
3555     */
3556    function fetchAll($fetchmode = MDB2_FETCHMODE_DEFAULT, $rekey = false,
3557        $force_array = false, $group = false)
3558    {
3559        $all = array();
3560        $row = $this->fetchRow($fetchmode);
3561        if (PEAR::isError($row)) {
3562            return $row;
3563        } elseif (!$row) {
3564            return $all;
3565        }
3566
3567        $shift_array = $rekey ? false : null;
3568        if (!is_null($shift_array)) {
3569            if (is_object($row)) {
3570                $colnum = count(get_object_vars($row));
3571            } else {
3572                $colnum = count($row);
3573            }
3574            if ($colnum < 2) {
3575                return $this->db->raiseError(MDB2_ERROR_TRUNCATED, null, null,
3576                    'rekey feature requires atleast 2 column', __FUNCTION__);
3577            }
3578            $shift_array = (!$force_array && $colnum == 2);
3579        }
3580
3581        if ($rekey) {
3582            do {
3583                if (is_object($row)) {
3584                    $arr = get_object_vars($row);
3585                    $key = reset($arr);
3586                    unset($row->{$key});
3587                } else {
3588                    if ($fetchmode & MDB2_FETCHMODE_ASSOC) {
3589                        $key = reset($row);
3590                        unset($row[key($row)]);
3591                    } else {
3592                        $key = array_shift($row);
3593                    }
3594                    if ($shift_array) {
3595                        $row = array_shift($row);
3596                    }
3597                }
3598                if ($group) {
3599                    $all[$key][] = $row;
3600                } else {
3601                    $all[$key] = $row;
3602                }
3603            } while (($row = $this->fetchRow($fetchmode)));
3604        } elseif ($fetchmode & MDB2_FETCHMODE_FLIPPED) {
3605            do {
3606                foreach ($row as $key => $val) {
3607                    $all[$key][] = $val;
3608                }
3609            } while (($row = $this->fetchRow($fetchmode)));
3610        } else {
3611            do {
3612                $all[] = $row;
3613            } while (($row = $this->fetchRow($fetchmode)));
3614        }
3615
3616        return $all;
3617    }
3618
3619    // }}}
3620    // {{{ function rowCount()
3621    /**
3622     * Returns the actual row number that was last fetched (count from 0)
3623     * @return  int
3624     *
3625     * @access  public
3626     */
3627    function rowCount()
3628    {
3629        return $this->rownum + 1;
3630    }
3631
3632    // }}}
3633    // {{{ function numRows()
3634
3635    /**
3636     * Returns the number of rows in a result object
3637     *
3638     * @return  mixed   MDB2 Error Object or the number of rows
3639     *
3640     * @access  public
3641     */
3642    function numRows()
3643    {
3644        return $this->db->raiseError(MDB2_ERROR_UNSUPPORTED, null, null,
3645            'method not implemented', __FUNCTION__);
3646    }
3647
3648    // }}}
3649    // {{{ function nextResult()
3650
3651    /**
3652     * Move the internal result pointer to the next available result
3653     *
3654     * @return  true on success, false if there is no more result set or an error object on failure
3655     *
3656     * @access  public
3657     */
3658    function nextResult()
3659    {
3660        return $this->db->raiseError(MDB2_ERROR_UNSUPPORTED, null, null,
3661            'method not implemented', __FUNCTION__);
3662    }
3663
3664    // }}}
3665    // {{{ function getColumnNames()
3666
3667    /**
3668     * Retrieve the names of columns returned by the DBMS in a query result or
3669     * from the cache.
3670     *
3671     * @param   bool    If set to true the values are the column names,
3672     *                  otherwise the names of the columns are the keys.
3673     * @return  mixed   Array variable that holds the names of columns or an
3674     *                  MDB2 error on failure.
3675     *                  Some DBMS may not return any columns when the result set
3676     *                  does not contain any rows.
3677     *
3678     * @access  public
3679     */
3680    function getColumnNames($flip = false)
3681    {
3682        if (!isset($this->column_names)) {
3683            $result = $this->_getColumnNames();
3684            if (PEAR::isError($result)) {
3685                return $result;
3686            }
3687            $this->column_names = $result;
3688        }
3689        if ($flip) {
3690            return array_flip($this->column_names);
3691        }
3692        return $this->column_names;
3693    }
3694
3695    // }}}
3696    // {{{ function _getColumnNames()
3697
3698    /**
3699     * Retrieve the names of columns returned by the DBMS in a query result.
3700     *
3701     * @return  mixed   Array variable that holds the names of columns as keys
3702     *                  or an MDB2 error on failure.
3703     *                  Some DBMS may not return any columns when the result set
3704     *                  does not contain any rows.
3705     *
3706     * @access  private
3707     */
3708    function _getColumnNames()
3709    {
3710        return $this->db->raiseError(MDB2_ERROR_UNSUPPORTED, null, null,
3711            'method not implemented', __FUNCTION__);
3712    }
3713
3714    // }}}
3715    // {{{ function numCols()
3716
3717    /**
3718     * Count the number of columns returned by the DBMS in a query result.
3719     *
3720     * @return  mixed   integer value with the number of columns, a MDB2 error
3721     *       on failure
3722     *
3723     * @access  public
3724     */
3725    function numCols()
3726    {
3727        return $this->db->raiseError(MDB2_ERROR_UNSUPPORTED, null, null,
3728            'method not implemented', __FUNCTION__);
3729    }
3730
3731    // }}}
3732    // {{{ function getResource()
3733
3734    /**
3735     * return the resource associated with the result object
3736     *
3737     * @return  resource
3738     *
3739     * @access  public
3740     */
3741    function getResource()
3742    {
3743        return $this->result;
3744    }
3745
3746    // }}}
3747    // {{{ function bindColumn($column, &$value, $type = null)
3748
3749    /**
3750     * Set bind variable to a column.
3751     *
3752     * @param   int     column number or name
3753     * @param   mixed   variable reference
3754     * @param   string  specifies the type of the field
3755     *
3756     * @return  mixed   MDB2_OK on success, a MDB2 error on failure
3757     *
3758     * @access  public
3759     */
3760    function bindColumn($column, &$value, $type = null)
3761    {
3762        if (!is_numeric($column)) {
3763            $column_names = $this->getColumnNames();
3764            if ($this->db->options['portability'] & MDB2_PORTABILITY_FIX_CASE) {
3765                if ($this->db->options['field_case'] == CASE_LOWER) {
3766                    $column = strtolower($column);
3767                } else {
3768                    $column = strtoupper($column);
3769                }
3770            }
3771            $column = $column_names[$column];
3772        }
3773        $this->values[$column] =& $value;
3774        if (!is_null($type)) {
3775            $this->types[$column] = $type;
3776        }
3777        return MDB2_OK;
3778    }
3779
3780    // }}}
3781    // {{{ function _assignBindColumns($row)
3782
3783    /**
3784     * Bind a variable to a value in the result row.
3785     *
3786     * @param   array   row data
3787     *
3788     * @return  mixed   MDB2_OK on success, a MDB2 error on failure
3789     *
3790     * @access  private
3791     */
3792    function _assignBindColumns($row)
3793    {
3794        $row = array_values($row);
3795        foreach ($row as $column => $value) {
3796            if (array_key_exists($column, $this->values)) {
3797                $this->values[$column] = $value;
3798            }
3799        }
3800        return MDB2_OK;
3801    }
3802
3803    // }}}
3804    // {{{ function free()
3805
3806    /**
3807     * Free the internal resources associated with result.
3808     *
3809     * @return  bool    true on success, false if result is invalid
3810     *
3811     * @access  public
3812     */
3813    function free()
3814    {
3815        $this->result = false;
3816        return MDB2_OK;
3817    }
3818
3819    // }}}
3820}
3821
3822// }}}
3823// {{{ class MDB2_Row
3824
3825/**
3826 * The simple class that accepts row data as an array
3827 *
3828 * @package     MDB2
3829 * @category    Database
3830 * @author      Lukas Smith <smith@pooteeweet.org>
3831 */
3832class MDB2_Row
3833{
3834    // {{{ constructor: function __construct(&$row)
3835
3836    /**
3837     * constructor
3838     *
3839     * @param   resource    row data as array
3840     */
3841    function __construct(&$row)
3842    {
3843        foreach ($row as $key => $value) {
3844            $this->$key = &$row[$key];
3845        }
3846    }
3847
3848    // }}}
3849    // {{{ function MDB2_Row(&$row)
3850
3851    /**
3852     * PHP 4 Constructor
3853     *
3854     * @param   resource    row data as array
3855     */
3856    function MDB2_Row(&$row)
3857    {
3858        $this->__construct($row);
3859    }
3860
3861    // }}}
3862}
3863
3864// }}}
3865// {{{ class MDB2_Statement_Common
3866
3867/**
3868 * The common statement class for MDB2 statement objects
3869 *
3870 * @package     MDB2
3871 * @category    Database
3872 * @author      Lukas Smith <smith@pooteeweet.org>
3873 */
3874class MDB2_Statement_Common
3875{
3876    // {{{ Variables (Properties)
3877
3878    var $db;
3879    var $statement;
3880    var $query;
3881    var $result_types;
3882    var $types;
3883    var $values = array();
3884    var $limit;
3885    var $offset;
3886    var $is_manip;
3887
3888    // }}}
3889    // {{{ constructor: function __construct(&$db, &$statement, $positions, $query, $types, $result_types, $is_manip = false, $limit = null, $offset = null)
3890
3891    /**
3892     * Constructor
3893     */
3894    function __construct(&$db, &$statement, $positions, $query, $types, $result_types, $is_manip = false, $limit = null, $offset = null)
3895    {
3896        $this->db =& $db;
3897        $this->statement =& $statement;
3898        $this->positions = $positions;
3899        $this->query = $query;
3900        $this->types = (array)$types;
3901        $this->result_types = (array)$result_types;
3902        $this->limit = $limit;
3903        $this->is_manip = $is_manip;
3904        $this->offset = $offset;
3905    }
3906
3907    // }}}
3908    // {{{ function MDB2_Statement_Common(&$db, &$statement, $positions, $query, $types, $result_types, $is_manip = false, $limit = null, $offset = null)
3909
3910    /**
3911     * PHP 4 Constructor
3912     */
3913    function MDB2_Statement_Common(&$db, &$statement, $positions, $query, $types, $result_types, $is_manip = false, $limit = null, $offset = null)
3914    {
3915        $this->__construct($db, $statement, $positions, $query, $types, $result_types, $is_manip, $limit, $offset);
3916    }
3917
3918    // }}}
3919    // {{{ function bindValue($parameter, &$value, $type = null)
3920
3921    /**
3922     * Set the value of a parameter of a prepared query.
3923     *
3924     * @param   int     the order number of the parameter in the query
3925     *       statement. The order number of the first parameter is 1.
3926     * @param   mixed   value that is meant to be assigned to specified
3927     *       parameter. The type of the value depends on the $type argument.
3928     * @param   string  specifies the type of the field
3929     *
3930     * @return  mixed   MDB2_OK on success, a MDB2 error on failure
3931     *
3932     * @access  public
3933     */
3934    function bindValue($parameter, $value, $type = null)
3935    {
3936        if (!is_numeric($parameter)) {
3937            $parameter = preg_replace('/^:(.*)$/', '\\1', $parameter);
3938        }
3939        if (!in_array($parameter, $this->positions)) {
3940            return $this->db->raiseError(MDB2_ERROR_NOT_FOUND, null, null,
3941                'Unable to bind to missing placeholder: '.$parameter, __FUNCTION__);
3942        }
3943        $this->values[$parameter] = $value;
3944        if (!is_null($type)) {
3945            $this->types[$parameter] = $type;
3946        }
3947        return MDB2_OK;
3948    }
3949
3950    // }}}
3951    // {{{ function bindValueArray($values, $types = null)
3952
3953    /**
3954     * Set the values of multiple a parameter of a prepared query in bulk.
3955     *
3956     * @param   array   specifies all necessary information
3957     *       for bindValue() the array elements must use keys corresponding to
3958     *       the number of the position of the parameter.
3959     * @param   array   specifies the types of the fields
3960     *
3961     * @return  mixed   MDB2_OK on success, a MDB2 error on failure
3962     *
3963     * @access  public
3964     * @see     bindParam()
3965     */
3966    function bindValueArray($values, $types = null)
3967    {
3968        $types = is_array($types) ? array_values($types) : array_fill(0, count($values), null);
3969        $parameters = array_keys($values);
3970        foreach ($parameters as $key => $parameter) {
3971            $err = $this->bindValue($parameter, $values[$parameter], $types[$key]);
3972            if (PEAR::isError($err)) {
3973                return $err;
3974            }
3975        }
3976        return MDB2_OK;
3977    }
3978
3979    // }}}
3980    // {{{ function bindParam($parameter, &$value, $type = null)
3981
3982    /**
3983     * Bind a variable to a parameter of a prepared query.
3984     *
3985     * @param   int     the order number of the parameter in the query
3986     *       statement. The order number of the first parameter is 1.
3987     * @param   mixed   variable that is meant to be bound to specified
3988     *       parameter. The type of the value depends on the $type argument.
3989     * @param   string  specifies the type of the field
3990     *
3991     * @return  mixed   MDB2_OK on success, a MDB2 error on failure
3992     *
3993     * @access  public
3994     */
3995    function bindParam($parameter, &$value, $type = null)
3996    {
3997        if (!is_numeric($parameter)) {
3998            $parameter = preg_replace('/^:(.*)$/', '\\1', $parameter);
3999        }
4000        if (!in_array($parameter, $this->positions)) {
4001            return $this->db->raiseError(MDB2_ERROR_NOT_FOUND, null, null,
4002                'Unable to bind to missing placeholder: '.$parameter, __FUNCTION__);
4003        }
4004        $this->values[$parameter] =& $value;
4005        if (!is_null($type)) {
4006            $this->types[$parameter] = $type;
4007        }
4008        return MDB2_OK;
4009    }
4010
4011    // }}}
4012    // {{{ function bindParamArray(&$values, $types = null)
4013
4014    /**
4015     * Bind the variables of multiple a parameter of a prepared query in bulk.
4016     *
4017     * @param   array   specifies all necessary information
4018     *       for bindParam() the array elements must use keys corresponding to
4019     *       the number of the position of the parameter.
4020     * @param   array   specifies the types of the fields
4021     *
4022     * @return  mixed   MDB2_OK on success, a MDB2 error on failure
4023     *
4024     * @access  public
4025     * @see     bindParam()
4026     */
4027    function bindParamArray(&$values, $types = null)
4028    {
4029        $types = is_array($types) ? array_values($types) : array_fill(0, count($values), null);
4030        $parameters = array_keys($values);
4031        foreach ($parameters as $key => $parameter) {
4032            $err = $this->bindParam($parameter, $values[$parameter], $types[$key]);
4033            if (PEAR::isError($err)) {
4034                return $err;
4035            }
4036        }
4037        return MDB2_OK;
4038    }
4039
4040    // }}}
4041    // {{{ function &execute($values = null, $result_class = true, $result_wrap_class = false)
4042
4043    /**
4044     * Execute a prepared query statement.
4045     *
4046     * @param   array   specifies all necessary information
4047     *       for bindParam() the array elements must use keys corresponding to
4048     *       the number of the position of the parameter.
4049     * @param   mixed   specifies which result class to use
4050     * @param   mixed   specifies which class to wrap results in
4051     *
4052     * @return  mixed   a result handle or MDB2_OK on success, a MDB2 error on failure
4053     *
4054     * @access  public
4055     */
4056    function &execute($values = null, $result_class = true, $result_wrap_class = false)
4057    {
4058        if (is_null($this->positions)) {
4059            return $this->db->raiseError(MDB2_ERROR, null, null,
4060                'Prepared statement has already been freed', __FUNCTION__);
4061        }
4062
4063        $values = (array)$values;
4064        if (!empty($values)) {
4065            $err = $this->bindValueArray($values);
4066            if (PEAR::isError($err)) {
4067                return $this->db->raiseError(MDB2_ERROR, null, null,
4068                                            'Binding Values failed with message: ' . $err->getMessage(), __FUNCTION__);
4069            }
4070        }
4071        $result =& $this->_execute($result_class, $result_wrap_class);
4072        return $result;
4073    }
4074
4075    // }}}
4076    // {{{ function &_execute($result_class = true, $result_wrap_class = false)
4077
4078    /**
4079     * Execute a prepared query statement helper method.
4080     *
4081     * @param   mixed   specifies which result class to use
4082     * @param   mixed   specifies which class to wrap results in
4083     *
4084     * @return  mixed   MDB2_Result or integer on success, a MDB2 error on failure
4085     *
4086     * @access  private
4087     */
4088    function &_execute($result_class = true, $result_wrap_class = false)
4089    {
4090        $this->last_query = $this->query;
4091        $query = '';
4092        $last_position = 0;
4093        foreach ($this->positions as $current_position => $parameter) {
4094            if (!array_key_exists($parameter, $this->values)) {
4095                return $this->db->raiseError(MDB2_ERROR_NOT_FOUND, null, null,
4096                    'Unable to bind to missing placeholder: '.$parameter, __FUNCTION__);
4097            }
4098            $value = $this->values[$parameter];
4099            $query.= substr($this->query, $last_position, $current_position - $last_position);
4100            if (!isset($value)) {
4101                $value_quoted = 'NULL';
4102            } else {
4103                $type = !empty($this->types[$parameter]) ? $this->types[$parameter] : null;
4104                $value_quoted = $this->db->quote($value, $type);
4105                if (PEAR::isError($value_quoted)) {
4106                    return $value_quoted;
4107                }
4108            }
4109            $query.= $value_quoted;
4110            $last_position = $current_position + 1;
4111        }
4112        $query.= substr($this->query, $last_position);
4113
4114        $this->db->offset = $this->offset;
4115        $this->db->limit = $this->limit;
4116        if ($this->is_manip) {
4117            $result = $this->db->exec($query);
4118        } else {
4119            $result =& $this->db->query($query, $this->result_types, $result_class, $result_wrap_class);
4120        }
4121        return $result;
4122    }
4123
4124    // }}}
4125    // {{{ function free()
4126
4127    /**
4128     * Release resources allocated for the specified prepared query.
4129     *
4130     * @return  mixed   MDB2_OK on success, a MDB2 error on failure
4131     *
4132     * @access  public
4133     */
4134    function free()
4135    {
4136        if (is_null($this->positions)) {
4137            return $this->db->raiseError(MDB2_ERROR, null, null,
4138                'Prepared statement has already been freed', __FUNCTION__);
4139        }
4140
4141        $this->statement = null;
4142        $this->positions = null;
4143        $this->query = null;
4144        $this->types = null;
4145        $this->result_types = null;
4146        $this->limit = null;
4147        $this->is_manip = null;
4148        $this->offset = null;
4149        $this->values = null;
4150
4151        return MDB2_OK;
4152    }
4153
4154    // }}}
4155}
4156
4157// }}}
4158// {{{ class MDB2_Module_Common
4159
4160/**
4161 * The common modules class for MDB2 module objects
4162 *
4163 * @package     MDB2
4164 * @category    Database
4165 * @author      Lukas Smith <smith@pooteeweet.org>
4166 */
4167class MDB2_Module_Common
4168{
4169    // {{{ Variables (Properties)
4170
4171    /**
4172     * contains the key to the global MDB2 instance array of the associated
4173     * MDB2 instance
4174     *
4175     * @var     int
4176     * @access  protected
4177     */
4178    var $db_index;
4179
4180    // }}}
4181    // {{{ constructor: function __construct($db_index)
4182
4183    /**
4184     * Constructor
4185     */
4186    function __construct($db_index)
4187    {
4188        $this->db_index = $db_index;
4189    }
4190
4191    // }}}
4192    // {{{ function MDB2_Module_Common($db_index)
4193
4194    /**
4195     * PHP 4 Constructor
4196     */
4197    function MDB2_Module_Common($db_index)
4198    {
4199        $this->__construct($db_index);
4200    }
4201
4202    // }}}
4203    // {{{ function &getDBInstance()
4204
4205    /**
4206     * Get the instance of MDB2 associated with the module instance
4207     *
4208     * @return  object  MDB2 instance or a MDB2 error on failure
4209     *
4210     * @access  public
4211     */
4212    function &getDBInstance()
4213    {
4214        if (isset($GLOBALS['_MDB2_databases'][$this->db_index])) {
4215            $result =& $GLOBALS['_MDB2_databases'][$this->db_index];
4216        } else {
4217            $result =& MDB2::raiseError(MDB2_ERROR_NOT_FOUND, null, null,
4218                'could not find MDB2 instance');
4219        }
4220        return $result;
4221    }
4222
4223    // }}}
4224}
4225
4226// }}}
4227// {{{ function MDB2_closeOpenTransactions()
4228
4229/**
4230 * Close any open transactions form persistent connections
4231 *
4232 * @return  void
4233 *
4234 * @access  public
4235 */
4236
4237function MDB2_closeOpenTransactions()
4238{
4239    reset($GLOBALS['_MDB2_databases']);
4240    while (next($GLOBALS['_MDB2_databases'])) {
4241        $key = key($GLOBALS['_MDB2_databases']);
4242        if ($GLOBALS['_MDB2_databases'][$key]->opened_persistent
4243            && $GLOBALS['_MDB2_databases'][$key]->in_transaction
4244        ) {
4245            $GLOBALS['_MDB2_databases'][$key]->rollback();
4246        }
4247    }
4248}
4249
4250// }}}
4251// {{{ function MDB2_defaultDebugOutput(&$db, $scope, $message, $is_manip = null)
4252
4253/**
4254 * default debug output handler
4255 *
4256 * @param   object  reference to an MDB2 database object
4257 * @param   string  usually the method name that triggered the debug call:
4258 *                  for example 'query', 'prepare', 'execute', 'parameters',
4259 *                  'beginTransaction', 'commit', 'rollback'
4260 * @param   string  message that should be appended to the debug variable
4261 * @param   array   contains context information about the debug() call
4262 *                  common keys are: is_manip, time, result etc.
4263 *
4264 * @return  void|string optionally return a modified message, this allows
4265 *                      rewriting a query before being issued or prepared
4266 *
4267 * @access  public
4268 */
4269function MDB2_defaultDebugOutput(&$db, $scope, $message, $context = array())
4270{
4271    $db->debug_output.= $scope.'('.$db->db_index.'): ';
4272    $db->debug_output.= $message.$db->getOption('log_line_break');
4273    return $message;
4274}
4275
4276// }}}
4277?>
Note: See TracBrowser for help on using the repository browser.