root/releases/0.9rc2/lib/adodb/adodb-connection.inc.php

<?php
/** 
 * @version V3.40 7 April 2003 (c) 2000-2003 John Lim (jlim@natsoft.com.my). All rights reserved.
 * Released under both BSD license and Lesser GPL library license. 
 * Whenever there is any discrepancy between the two licenses, 
 * the BSD license will take precedence. 
 *
 * Set tabs to 4 for best viewing.
 * 
 * Latest version is available at http://php.weblogs.com
 *
 */

    
    function ADODB_TransMonitor($dbms, $fn, $errno, $errmsg, $p1, $p2, &$thisConnection)
    {
        /* print "Errorno ($fn errno=$errno m=$errmsg) "; */
        
        $thisConnection->_transOK = false;
        if ($thisConnection->_oldRaiseFn) {
            $fn = $thisConnection->_oldRaiseFn;
            $fn($dbms, $fn, $errno, $errmsg, $p1, $p2,$thisConnection);
        }
    }
    
    
    /**
     * Connection object. For connecting to databases, and executing queries.
     */ 
    class ADOConnection {
    /*  */
    /*  PUBLIC VARS  */
    /*  */
    var $dataProvider = 'native';
    var $databaseType = '';     /* / RDBMS currently in use, eg. odbc, mysql, mssql                 */
    var $database = '';         /* / Name of database to be used.   */
    var $host = '';         /* / The hostname of the database server    */
    var $user = '';         /* / The username which is used to connect to the database server.  */
    var $password = '';     /* / Password for the username. For security, we no longer store it. */
    var $debug = false;     /* / if set to true will output sql statements */
    var $maxblobsize = 256000;  /* / maximum size of blobs or large text fields -- some databases die otherwise like foxpro */
    var $concat_operator = '+'; /* / default concat operator -- change to || for Oracle/Interbase     */
    var $fmtDate = "'Y-m-d'";   /* / used by DBDate() as the default date format used by the database */
    var $fmtTimeStamp = "'Y-m-d, h:i:s A'"; /* / used by DBTimeStamp as the default timestamp fmt. */
    var $true = '1';            /* / string that represents TRUE for a database */
    var $false = '0';           /* / string that represents FALSE for a database */
    var $replaceQuote = "\\'";  /* / string to use to replace quotes */
    var $charSet=false;     /* / character set to use - only for interbase */
    var $metaTablesSQL = '';
    /* -- */
    var $hasInsertID = false;       /* / supports autoincrement ID? */
    var $hasAffectedRows = false;   /* / supports affected rows for update/delete? */
    var $hasTop = false;            /* / support mssql/access SELECT TOP 10 * FROM TABLE */
    var $hasLimit = false;          /* / support pgsql/mysql SELECT * FROM TABLE LIMIT 10 */
    var $readOnly = false;          /* / this is a readonly database - used by phpLens */
    var $hasMoveFirst = false;  /* / has ability to run MoveFirst(), scrolling backwards */
    var $hasGenID = false;      /* / can generate sequences using GenID(); */
    var $hasTransactions = true; /* / has transactions */
    /* -- */
    var $genID = 0;         /* / sequence id used by GenID(); */
    var $raiseErrorFn = false;  /* / error function to call */
    var $upperCase = false; /* / uppercase function to call for searching/where */
    var $isoDates = false; /* / accepts dates in ISO format */
    var $cacheSecs = 3600; /* / cache for 1 hour */
    var $sysDate = false; /* / name of function that returns the current date */
    var $sysTimeStamp = false; /* / name of function that returns the current timestamp */
    var $arrayClass = 'ADORecordSet_array'; /* / name of class used to generate array recordsets, which are pre-downloaded recordsets */
    
    var $noNullStrings = false; /* / oracle specific stuff - if true ensures that '' is converted to ' ' */
    var $numCacheHits = 0; 
    var $numCacheMisses = 0;
    var $pageExecuteCountRows = true;
    var $uniqueSort = false; /* / indicates that all fields in order by must be unique */
    var $leftOuter = false; /* / operator to use for left outer join in WHERE clause */
    var $rightOuter = false; /* / operator to use for right outer join in WHERE clause */
    var $ansiOuter = false; /* / whether ansi outer join syntax supported */
    var $autoRollback = false; /*  autoRollback on PConnect(). */
    var $poorAffectedRows = false; /*  affectedRows not working or unreliable */
    
    var $fnExecute = false;
    var $fnCacheExecute = false;
    var $blobEncodeType = false; /*  false=not required, 'I'=encode to integer, 'C'=encode to char */
    var $dbxDriver = false;
    
     /*  */
     /*  PRIVATE VARS */
     /*  */
    var $_oldRaiseFn =  false;
    var $_transOK = null;
    var $_connectionID = false; /* / The returned link identifier whenever a successful database connection is made.    */
    var $_errorMsg = '';    /* / A variable which was used to keep the returned last error message.  The value will */
                                /* / then returned by the errorMsg() function     */
                        
    var $_queryID = false;  /* / This variable keeps the last created result link identifier */
    
    var $_isPersistentConnection = false;   /* / A boolean variable to state whether its a persistent connection or normal connection.  */
    var $_bindInputArray = false; /* / set to true if ADOConnection.Execute() permits binding of array parameters. */
    var $autoCommit = true; /* / do not modify this yourself - actually private */
    var $transOff = 0;  /* / temporarily disable transactions */
    var $transCnt = 0;  /* / count of nested transactions */
    
    var $fetchMode=false;
    
    /**
     * Constructor
     */
    function ADOConnection()
    {
        die('Virtual Class -- cannot instantiate');
    }
    
    /**
        Get server version info...
        
        @returns An array with 2 elements: $arr['string'] is the description string, 
            and $arr[version] is the version (also a string).
    */
    function ServerInfo()
    {
        return array('description' => '', 'version' => '');
    }
    
    function _findvers($str)
    {
        if (preg_match('/([0-9]+\.([0-9\.])+)/',$str, $arr)) return $arr[1];
        else return '';
    }
    
    /**
    * All error messages go through this bottleneck function.
    * You can define your own handler by defining the function name in ADODB_OUTP.
    */
    function outp($msg,$newline=true)
    {
    global $HTTP_SERVER_VARS;
    
        if (defined('ADODB_OUTP')) {
            $fn = ADODB_OUTP;
            $fn($msg,$newline);
            return;
        }
        
        if ($newline) $msg .= "<br />\n";
        
        if (isset($HTTP_SERVER_VARS['HTTP_USER_AGENT'])) echo $msg;
        else echo strip_tags($msg);
        flush();
    }
    
    /**
     * Connect to database
     *
     * @param [argHostname]        Host to connect to
     * @param [argUsername]        Userid to login
     * @param [argPassword]        Associated password
     * @param [argDatabaseName]    database
     * @param [forceNew]        force new connection
     *
     * @return true or false
     */      
    function Connect($argHostname = "", $argUsername = "", $argPassword = "", $argDatabaseName = "", $forceNew = false) 
    {
        if ($argHostname != "") $this->host = $argHostname;
        if ($argUsername != "") $this->user = $argUsername;
        if ($argPassword != "") $this->password = $argPassword; /*  not stored for security reasons */
        if ($argDatabaseName != "") $this->database = $argDatabaseName;
        
        $this->_isPersistentConnection = false;    
        if ($fn = $this->raiseErrorFn) {
            if ($forceNew) {
                if ($this->_nconnect($this->host, $this->user, $this->password, $this->database)) return true;
            } else {
                 if ($this->_connect($this->host, $this->user, $this->password, $this->database)) return true;
            }
            $err = $this->ErrorMsg();
            if (empty($err)) $err = "Connection error to server '$argHostname' with user '$argUsername'";
            $fn($this->databaseType,'CONNECT',$this->ErrorNo(),$err,$this->host,$this->database,$this);
        } else {
            if ($forceNew) {
                if ($this->_nconnect($this->host, $this->user, $this->password, $this->database)) return true;
            } else {
                if ($this->_connect($this->host, $this->user, $this->password, $this->database)) return true;
            }
        }
        if ($this->debug) ADOConnection::outp( $this->host.': '.$this->ErrorMsg());
        
        return false;
    }    
    
     function _nconnect($argHostname, $argUsername, $argPassword, $argDatabaseName)
     {
         return $this->_connect($argHostname, $argUsername, $argPassword, $argDatabaseName);
     }
    
    
    /**
     * Always force a new connection to database - currently only works with oracle
     *
     * @param [argHostname]        Host to connect to
     * @param [argUsername]        Userid to login
     * @param [argPassword]        Associated password
     * @param [argDatabaseName]    database
     *
     * @return true or false
     */      
    function NConnect($argHostname = "", $argUsername = "", $argPassword = "", $argDatabaseName = "") 
    {
        return $this->Connect($argHostname, $argUsername, $argPassword, $argDatabaseName, true);
    }
    
    /**
     * Establish persistent connect to database
     *
     * @param [argHostname]        Host to connect to
     * @param [argUsername]        Userid to login
     * @param [argPassword]        Associated password
     * @param [argDatabaseName]    database
     *
     * @return return true or false
     */    
    function PConnect($argHostname = "", $argUsername = "", $argPassword = "", $argDatabaseName = "")
    {
        if (defined('ADODB_NEVER_PERSIST')) 
            return $this->Connect($argHostname,$argUsername,$argPassword,$argDatabaseName);
        
        if ($argHostname != "") $this->host = $argHostname;
        if ($argUsername != "") $this->user = $argUsername;
        if ($argPassword != "") $this->password = $argPassword;
        if ($argDatabaseName != "") $this->database = $argDatabaseName;
            
        $this->_isPersistentConnection = true;
        
        if ($fn = $this->raiseErrorFn) {
            if ($this->_pconnect($this->host, $this->user, $this->password, $this->database)) return true;
            $err = $this->ErrorMsg();
            if (empty($err)) $err = "Connection error to server '$argHostname' with user '$argUsername'";
            $fn($this->databaseType,'PCONNECT',$this->ErrorNo(),$err,$this->host,$this->database,$this);
        } else 
            if ($this->_pconnect($this->host, $this->user, $this->password, $this->database)) return true;

        if ($this->debug) ADOConnection::outp( $this->host.': '.$this->ErrorMsg());
        
        return false;
    }

    /*  Format date column in sql string given an input format that understands Y M D */
    function SQLDate($fmt, $col=false)
    {    
        if (!$col) $col = $this->sysDate;
        return $col; /*  child class implement */
    }
    
    /**
     * Should prepare the sql statement and return the stmt resource.
     * For databases that do not support this, we return the $sql. To ensure
     * compatibility with databases that do not support prepare:
     *
     *   $stmt = $db->Prepare("insert into table (id, name) values (?,?)");
     *   $db->Execute($stmt,array(1,'Jill')) or die('insert failed');
     *   $db->Execute($stmt,array(2,'Joe')) or die('insert failed');
     *
     * @param sql   SQL to send to database
     *
     * @return return FALSE, or the prepared statement, or the original sql if
     *          if the database does not support prepare.
     *
     */    
    function Prepare($sql)
    {
        return $sql;
    }

    /**
     * Some databases, eg. mssql require a different function for preparing
     * stored procedures. So we cannot use Prepare().
     *
     * Should prepare the stored procedure  and return the stmt resource.
     * For databases that do not support this, we return the $sql. To ensure
     * compatibility with databases that do not support prepare:
     *
     * @param sql   SQL to send to database
     *
     * @return return FALSE, or the prepared statement, or the original sql if
     *          if the database does not support prepare.
     *
     */    
    function PrepareSP($sql)
    {
        return $this->Prepare($sql);
    }
    
    /**
    * PEAR DB Compat
    */
    function Quote($s)
    {
        return $this->qstr($s,false);
    }

    
    /**
    * PEAR DB Compat - do not use internally. 
    */
    function ErrorNative()
    {
        return $this->ErrorNo();
    }

    
   /**
    * PEAR DB Compat - do not use internally. 
    */
    function nextId($seq_name)
    {
        return $this->GenID($seq_name);
    }

    /**
    *   Lock a row, will escalate and lock the table if row locking not supported
    *   will normally free the lock at the end of the transaction
    *
    *  @param $table    name of table to lock
    *  @param $where    where clause to use, eg: "WHERE row=12". If left empty, will escalate to table lock
    */
    function RowLock($table,$where)
    {
        return false;
    }
    
    function CommitLock($table)
    {
        return $this->CommitTrans();
    }
    
    function RollbackLock($table)
    {
        return $this->RollbackTrans();
    }
    
    /**
    * PEAR DB Compat - do not use internally. 
    *
    * The fetch modes for NUMERIC and ASSOC for PEAR DB and ADODB are identical
    *   for easy porting :-)
    *
    * @param mode   The fetchmode ADODB_FETCH_ASSOC or ADODB_FETCH_NUM
    * @returns      The previous fetch mode
    */
    function SetFetchMode($mode)
    {    
        $old = $this->fetchMode;
        $this->fetchMode = $mode;
        
        if ($old === false) {
        global $ADODB_FETCH_MODE;
            return $ADODB_FETCH_MODE;
        }
        return $old;
    }
    

    /**
    * PEAR DB Compat - do not use internally. 
    */
    function &Query($sql, $inputarr=false)
    {
        $rs = &$this->Execute($sql, $inputarr);
        if (!$rs && defined('ADODB_PEAR')) return ADODB_PEAR_Error();
        return $rs;
    }

    
    /**
    * PEAR DB Compat - do not use internally
    */
    function &LimitQuery($sql, $offset, $count)
    {
        $rs = &$this->SelectLimit($sql, $count, $offset); /*  swap  */
        if (!$rs && defined('ADODB_PEAR')) return ADODB_PEAR_Error();
        return $rs;
    }

    
    /**
    * PEAR DB Compat - do not use internally
    */
    function Disconnect()
    {
        return $this->Close();
    }

    /* 
    Usage in oracle
        $stmt = $db->Prepare('select * from table where id =:myid and group=:group');
        $db->Parameter($stmt,$id,'myid');
        $db->Parameter($stmt,$group,'group',64);
        $db->Execute();
        
        @param $stmt Statement returned by Prepare() or PrepareSP().
        @param $var PHP variable to bind to
        @param $name Name of stored procedure variable name to bind to.
        @param [$isOutput] Indicates direction of parameter 0/false=IN  1=OUT  2= IN/OUT. This is ignored in oci8.
        @param [$maxLen] Holds an maximum length of the variable.
        @param [$type] The data type of $var. Legal values depend on driver.

    */
    function Parameter(&$stmt,&$var,$name,$isOutput=false,$maxLen=4000,$type=false)
    {
        return false;
    }
    
    /**
        Improved method of initiating a transaction. Used together with CompleteTrans().
        Advantages include:
        
        a. StartTrans/CompleteTrans is nestable, unlike BeginTrans/CommitTrans/RollbackTrans.
           Only the outermost block is treated as a transaction.<br />
        b. CompleteTrans auto-detects SQL errors, and will rollback on errors, commit otherwise.<br />
        c. All BeginTrans/CommitTrans/RollbackTrans inside a StartTrans/CompleteTrans block
           are disabled, making it backward compatible.
    */
    function StartTrans($errfn = 'ADODB_TransMonitor')
    {
        
        if ($this->transOff > 0) {
            $this->transOff += 1;
            return;
        }
        
        $this->_oldRaiseFn = $this->raiseErrorFn;
        $this->raiseErrorFn = $errfn;
        $this->_transOK = true;
        
        if ($this->debug && $this->transCnt > 0) ADOConnection::outp("Bad Transaction: StartTrans called within BeginTrans");
        $this->BeginTrans();
        $this->transOff = 1;
    }
    
    /**
        Used together with StartTrans() to end a transaction. Monitors connection
        for sql errors, and will commit or rollback as appropriate.
        
        @autoComplete if true, monitor sql errors and commit and rollback as appropriate, 
        and if set to false force rollback even if no SQL error detected.
        @returns true on commit, false on rollback.
    */
    function CompleteTrans($autoComplete = true)
    {
        if ($this->transOff > 1) {
            $this->transOff -= 1;
            return true;
        }
        $this->raiseErrorFn = $this->_oldRaiseFn;
        
        $this->transOff = 0;
        if ($this->_transOK && $autoComplete) $this->CommitTrans();
        else $this->RollbackTrans();
        
        return $this->_transOK;
    }
    
    /*
        At the end of a StartTrans/CompleteTrans block, perform a rollback.
    */
    function FailTrans()
    {
        if ($this->debug && $this->transOff == 0) {
            ADOConnection::outp("FailTrans outside StartTrans/CompleteTrans");
        }
        $this->_transOK = false;
    }
    /**
     * Execute SQL 
     *
     * @param sql        SQL statement to execute, or possibly an array holding prepared statement ($sql[0] will hold sql text)
     * @param [inputarr]    holds the input data to bind to. Null elements will be set to null.
     * @param [arg3]    reserved for john lim for future use
     * @return         RecordSet or false
     */
    function &Execute($sql,$inputarr=false,$arg3=false) 
    {
        if ($this->fnExecute) {
            $fn = $this->fnExecute;
            $fn($this,$sql,$inputarr);
        }
        if (!$this->_bindInputArray && $inputarr) {
            $sqlarr = explode('?',$sql);
            $sql = '';
            $i = 0;
            foreach($inputarr as $v) {

                $sql .= $sqlarr[$i];
                /*  from Ron Baldwin <ron.baldwin@sourceprose.com> */
                /*  Only quote string types     */
                if (gettype($v) == 'string')
                    $sql .= $this->qstr($v);
                else if ($v === null)
                    $sql .= 'NULL';
                else
                    $sql .= $v;
                $i += 1;
    
            }
            $sql .= $sqlarr[$i];
            if ($i+1 != sizeof($sqlarr))    
                ADOConnection::outp( "Input Array does not match ?: ".htmlspecialchars($sql));
            $inputarr = false;
        }
        /*  debug version of query */
        if ($this->debug) {
        global $HTTP_SERVER_VARS