*     * @param mixed  $nativecode  the native error code, as returned by the     * backend database extension (string or integer)     *     * @return int a portable DB error code, or DB_ERROR if this DB     * implementation has no mapping for the given error code.     *     * @access public     */    function errorCode($nativecode)    {        if (isset($this->errorcode_map[$nativecode])) {            return $this->errorcode_map[$nativecode];        }        // Fall back to DB_ERROR if there was no mapping.        return DB_ERROR;    }    // }}}    // {{{ errorMessage()    /**     * Map a DB error code to a textual message.  This is actually     * just a wrapper for DB::errorMessage()     *     * @param integer $dbcode the DB error code     *     * @return string the corresponding error message, of false     * if the error code was unknown     *     * @access public     */    function errorMessage($dbcode)    {        return DB::errorMessage($this->errorcode_map[$dbcode]);    }    // }}}    // {{{ raiseError()    /**     * Communicate an error and invoke error callbacks, etc     *     * Basically a wrapper for PEAR::raiseError without the message string.     *     * @param mixed    integer error code, or a PEAR error object (all     *                 other parameters are ignored if this parameter is     *                 an object     *     * @param int      error mode, see PEAR_Error docs     *     * @param mixed    If error mode is PEAR_ERROR_TRIGGER, this is the     *                 error level (E_USER_NOTICE etc).  If error mode is     *                 PEAR_ERROR_CALLBACK, this is the callback function,     *                 either as a function name, or as an array of an     *                 object and method name.  For other error modes this     *                 parameter is ignored.     *     * @param string   Extra debug information.  Defaults to the last     *                 query and native error code.     *     * @param mixed    Native error code, integer or string depending the     *                 backend.     *     * @return object  a PEAR error object     *     * @access public     * @see PEAR_Error     */    function &raiseError($code = DB_ERROR, $mode = null, $options = null,                         $userinfo = null, $nativecode = null)    {        // The error is yet a DB error object        if (is_object($code)) {            // because we the static PEAR::raiseError, our global            // handler should be used if it is set            if ($mode === null && !empty($this->_default_error_mode)) {                $mode    = $this->_default_error_mode;                $options = $this->_default_error_options;            }            $tmp = PEAR::raiseError($code, null, $mode, $options, null, null, true);            return $tmp;        }        if ($userinfo === null) {            $userinfo = $this->last_query;        }        if ($nativecode) {            $userinfo .= ' [nativecode=' . trim($nativecode) . ']';        }        $tmp = PEAR::raiseError(null, $code, $mode, $options, $userinfo,                                'DB_Error', true);        return $tmp;    }    // }}}    // {{{ setFetchMode()    /**     * Sets which fetch mode should be used by default on queries     * on this connection     *     * @param integer $fetchmode DB_FETCHMODE_ORDERED or     *        DB_FETCHMODE_ASSOC, possibly bit-wise OR'ed with     *        DB_FETCHMODE_FLIPPED.     *     * @param string $object_class The class of the object     *                      to be returned by the fetch methods when     *                      the DB_FETCHMODE_OBJECT mode is selected.     *                      If no class is specified by default a cast     *                      to object from the assoc array row will be done.     *                      There is also the posibility to use and extend the     *                      'DB_row' class.     *     * @see DB_FETCHMODE_ORDERED     * @see DB_FETCHMODE_ASSOC     * @see DB_FETCHMODE_FLIPPED     * @see DB_FETCHMODE_OBJECT     * @see DB_row::DB_row()     * @access public     */    function setFetchMode($fetchmode, $object_class = 'stdClass')    {        switch ($fetchmode) {            case DB_FETCHMODE_OBJECT:                $this->fetchmode_object_class = $object_class;            case DB_FETCHMODE_ORDERED:            case DB_FETCHMODE_ASSOC:                $this->fetchmode = $fetchmode;                break;            default:                return $this->raiseError('invalid fetchmode mode');        }    }    // }}}    // {{{ setOption()    /**     * Set run-time configuration options for PEAR DB     *     * Options, their data types, default values and description:     * <ul>     * <li>     * <var>autofree</var> <kbd>boolean</kbd> = <samp>false</samp>     *      <br />should results be freed automatically when there are no     *            more rows?     * </li><li>     * <var>debug</var> <kbd>integer</kbd> = <samp>0</samp>     *      <br />debug level     * </li><li>     * <var>persistent</var> <kbd>boolean</kbd> = <samp>false</samp>     *      <br />should the connection be persistent?     * </li><li>     * <var>portability</var> <kbd>integer</kbd> = <samp>DB_PORTABILITY_NONE</samp>     *      <br />portability mode constant (see below)     * </li><li>     * <var>seqname_format</var> <kbd>string</kbd> = <samp>%s_seq</samp>     *      <br />the sprintf() format string used on sequence names.  This     *            format is applied to sequence names passed to     *            createSequence(), nextID() and dropSequence().     * </li><li>     * <var>ssl</var> <kbd>boolean</kbd> = <samp>false</samp>     *      <br />use ssl to connect?     * </li>     * </ul>     *     * -----------------------------------------     *     * PORTABILITY MODES     *     * These modes are bitwised, so they can be combined using <kbd>|</kbd>     * and removed using <kbd>^</kbd>.  See the examples section below on how     * to do this.     *     * <samp>DB_PORTABILITY_NONE</samp>     * turn off all portability features     *     * This mode gets automatically turned on if the deprecated     * <var>optimize</var> option gets set to <samp>performance</samp>.     *     *     * <samp>DB_PORTABILITY_LOWERCASE</samp>     * convert names of tables and fields to lower case when using     * <kbd>get*()</kbd>, <kbd>fetch*()</kbd> and <kbd>tableInfo()</kbd>     *     * This mode gets automatically turned on in the following databases     * if the deprecated option <var>optimize</var> gets set to     * <samp>portability</samp>:     * + oci8     *     *     * <samp>DB_PORTABILITY_RTRIM</samp>     * right trim the data output by <kbd>get*()</kbd> <kbd>fetch*()</kbd>     *     *     * <samp>DB_PORTABILITY_DELETE_COUNT</samp>     * force reporting the number of rows deleted     *     * Some DBMS's don't count the number of rows deleted when performing     * simple <kbd>DELETE FROM tablename</kbd> queries.  This portability     * mode tricks such DBMS's into telling the count by adding     * <samp>WHERE 1=1</samp> to the end of <kbd>DELETE</kbd> queries.     *     * This mode gets automatically turned on in the following databases     * if the deprecated option <var>optimize</var> gets set to     * <samp>portability</samp>:     * + fbsql     * + mysql     * + mysqli     * + sqlite     *     *     * <samp>DB_PORTABILITY_NUMROWS</samp>     * enable hack that makes <kbd>numRows()</kbd> work in Oracle     *     * This mode gets automatically turned on in the following databases     * if the deprecated option <var>optimize</var> gets set to     * <samp>portability</samp>:     * + oci8     *     *     * <samp>DB_PORTABILITY_ERRORS</samp>     * makes certain error messages in certain drivers compatible     * with those from other DBMS's     *     * + mysql, mysqli:  change unique/primary key constraints     *   DB_ERROR_ALREADY_EXISTS -> DB_ERROR_CONSTRAINT     *     * + odbc(access):  MS's ODBC driver reports 'no such field' as code     *   07001, which means 'too few parameters.'  When this option is on     *   that code gets mapped to DB_ERROR_NOSUCHFIELD.     *   DB_ERROR_MISMATCH -> DB_ERROR_NOSUCHFIELD     *     *     * <samp>DB_PORTABILITY_NULL_TO_EMPTY</samp>     * convert null values to empty strings in data output by get*() and     * fetch*().  Needed because Oracle considers empty strings to be null,     * while most other DBMS's know the difference between empty and null.     *     *     * <samp>DB_PORTABILITY_ALL</samp>     * turn on all portability features     *     * -----------------------------------------     *     * Example 1. Simple setOption() example     * <code> <?php     * $dbh->setOption('autofree', true);     * ?></code>     *     * Example 2. Portability for lowercasing and trimming     * <code> <?php     * $dbh->setOption('portability',     *                  DB_PORTABILITY_LOWERCASE | DB_PORTABILITY_RTRIM);     * ?></code>     *     * Example 3. All portability options except trimming     * <code> <?php     * $dbh->setOption('portability',     *                  DB_PORTABILITY_ALL ^ DB_PORTABILITY_RTRIM);     * ?></code>     *     * @param string $option option name     * @param mixed  $value value for the option     *     * @return int  DB_OK on success.  DB_Error object on failure.     *     * @see DB_common::$options     */    function setOption($option, $value)    {        if (isset($this->options[$option])) {            $this->options[$option] = $value;            /*             * Backwards compatibility check for the deprecated 'optimize'             * option.  Done here in case settings change after connecting.             */            if ($option == 'optimize') {                if ($value == 'portability') {                    switch ($this->phptype) {                        case 'oci8':                            $this->options['portability'] =                                    DB_PORTABILITY_LOWERCASE |                                    DB_PORTABILITY_NUMROWS;                            break;                        case 'fbsql':                        case 'mysql':                        case 'mysqli':                        case 'sqlite':                            $this->options['portability'] =                                    DB_PORTABILITY_DELETE_COUNT;                            break;                    }                } else {                    $this->options['portability'] = DB_PORTABILITY_NONE;                }            }            return DB_OK;        }        return $this->raiseError("unknown option $option");    }    // }}}    // {{{ getOption()    /**     * Returns the value of an option     *     * @param string $option option name     *     * @return mixed the option value     */    function getOption($option)    {        if (isset($this->options[$option])) {            return $this->options[$option];        }        return $this->raiseError("unknown option $option");    }    // }}}    // {{{ prepare()    /**     * Prepares a query for multiple execution with execute()     *     * Creates a query that can be run multiple times.  Each time it is run,     * the placeholders, if any, will be replaced by the contents of     * execute()'s $data argument.     *     * Three types of placeholders can be used:     *   + <kbd>?</kbd>  scalar value (i.e. strings, integers).  The system     *                   will automatically quote and escape the data.     *   + <kbd>!</kbd>  value is inserted 'as is'     *   + <kbd>&</kbd>  requires a file name.  The file's contents get     *                   inserted into the query (i.e. saving binary     *                   data in a db)     *     * Example 1.     * <code> <?php     * $sth = $dbh->prepare('INSERT INTO tbl (a, b, c) VALUES (?, !, &)');     * $data = array(     *     "John's text",     *     "'it''s good'",     *     'filename.txt'     * );     * $res = $dbh->execute($sth, $data);     * ?></code>     *     * Use backslashes to escape placeholder characters if you don't want     * them to be interpreted as placeholders:     * <pre>     *    "UPDATE foo SET col=? WHERE col='over \& under'"     * </pre>     *     * With some database backends, this is emulated.     *     * {@internal ibase and oci8 have their own prepare() methods.}}     *     * @param string $query query to be prepared     *     * @return mixed DB statement resource on success. DB_Error on failure.     *     * @see DB_common::execute()     * @access public     */    function prepare($query)    {        $tokens   = preg_split('/((?<!\\\)[&?!])/', $query, -1,                               PREG_SPLIT_DELIM_CAPTURE);        $token     = 0;        $types     = array();        $newtokens = array();        foreach ($tokens as $val) {            switch ($val) {                case '?':                    $types[$token++] = DB_PARAM_SCALAR;                    break;                case '&':                    $types[$token++] = DB_PARAM_OPAQUE;                    break;                case '!':                    $types[$token++] = DB_PARAM_MISC;                    break;                default:                    $newtokens[] = preg_replace('/\\\([&?!])/', "\\1", $val);            }        }        $this->prepare_tokens[] = &$newtokens;        end($this->prepare_tokens);        $k = key($this->prepare_tokens);        $this->prepare_types[$k] = $types;        $this->prepared_queries[$k] = implode(' ', $newtokens);        return $k;    }    // }}}