Source for file oci8_class.php

Documentation is available at oci8_class.php

  1. <?php
  2. /**
  3.  * Oracle Database Class.
  4.  *
  5.  * Database Class provides a consistent API to communicate with MySQL or Oracle Databases.
  6.  * This one implements the OCI8 API.
  7.  * Requires dbdefs.inc.php for global access data (user,pw,host,appname)
  8.  *
  9.  * - Connect() / Disconnect()
  10.  * - Print_Error() / GetErrorText()
  11.  * - Query() / QueryResult() / FetchResult() / FreeResult()
  12.  * - Version() / GetClassVersion() / GetQueryCount()
  13.  * - Commit() / Rollback()
  14.  * - SetDebug() / PrintDebug() / SQLDebug()
  15.  * - GetBindVars() - PRIVATE!
  16.  * - DescTable()
  17.  * - Prepare() / Execute() / ExecuteHash()
  18.  * - SearchQueryCache() / RemoveFromQueryCache()
  19.  * - checkSock()
  20.  * - GetConnectionHandle() / SetConnectionHandle()
  21.  * - QueryHash() / QueryResultHash()
  22.  * - AffectedRows()
  23.  * - setErrorHandling() / getSQLError()
  24.  * - setPrefetch()
  25.  * - getOutputHash() / setOutputHash() / clearOutputHash()
  26.  * - SendEmailOnError()
  27.  * - setPConnect()
  28.  * - setConnectRetries() / getConnectRetries()
  29.  * @package db_oci8
  30.  * @author Sascha 'SieGeL' Pfalz <php@saschapfalz.de>
  31.  * @version 0.78 (28-Mar-2009)
  32.  *  $Id: oci8_class.php,v 1.14 2009/09/22 20:11:42 siegel Exp $
  33.  * @license http://opensource.org/licenses/bsd-license.php BSD License
  34.  * @filesource
  35.  */
  36. /**
  37.  * DEBUG: No Debug Info
  38.  */
  39. if(!defined('DBOF_DEBUGOFF'))
  40.   {
  41.   define('DBOF_DEBUGOFF'    , (1 << 0));
  42.   }
  43.  
  44. /**
  45.  * DEBUG: Debug on-screen
  46.  */
  47. if(!defined('DBOF_DEBUGSCREEN'))
  48.   {
  49.   define('DBOF_DEBUGSCREEN' , (1 << 1));
  50.   }
  51. /**
  52.  * DEBUG: Debug to error_log()
  53.  */
  54. if(!defined('DBOF_DEBUGFILE'))
  55.   {
  56.   define('DBOF_DEBUGFILE'   , (1 << 2));
  57.   }
  58.  
  59. /**#@+
  60.  * These defines are used in DescTable()
  61.  * @see DescTable
  62.  */
  63. define('DBOF_COLNAME', 0);
  64. define('DBOF_COLTYPE', 1);
  65. define('DBOF_COLSIZE', 2);
  66. define('DBOF_COLPREC', 3);
  67. /**#@-*/
  68.  
  69. /**#@+
  70.  * Used for Query Cache (V0.38+)
  71.  */
  72. if(!defined('DBOF_CACHE_QUERY'))
  73.   {
  74.   define('DBOF_CACHE_QUERY'     , 0);
  75.   }
  76. if(!defined('DBOF_CACHE_STATEMENT'))
  77.   {
  78.   define('DBOF_CACHE_STATEMENT' , 1);
  79.   }
  80. /**#@-*/
  81.  
  82. /**#@+
  83.  * Connect and error handling (V0.57+).
  84.  * If NO_ERRORS is set and an error occures, the class still reports an
  85.  * an error of course but the error shown is reduced to avoid showing
  86.  * sensible informations in a productive environment.
  87.  * Set RETURN_ALL_ERRORS if you want to handle errors yourself.
  88.  */
  89. if(!defined('DBOF_SHOW_NO_ERRORS'))
  90.   {
  91.   define('DBOF_SHOW_NO_ERRORS'    , 0);
  92.   define('DBOF_SHOW_ALL_ERRORS'   , 1);
  93.   define('DBOF_RETURN_ALL_ERRORS' , 2);
  94.   }
  95. /**#@-*/
  96.  
  97. /**
  98.  * OCI8 Database Class.
  99.  * @package db_oci8
  100.  */
  101. class db_oci8
  102.   {
  103.   /** @var mixed $sock Internal connection handle. */
  104.   var $sock;
  105.   /** @var string $host The TNS name of the target database. */
  106.   var $host;
  107.   /** @var string $user The username used to connect to database. */
  108.   var $user;
  109.   /** @var string $user The password used to connect to database. */
  110.   var $password;
  111.   /** @var string $database Currently not in use. */
  112.   var $database;
  113.   /** @var integer $querycounter Counts amount of queries executed. */
  114.   var $querycounter;
  115.   /** @var float $querytime Contains the total SQL execution time in microseconds. */
  116.   var $querytime;
  117.   /** @var mixed $stmt Stores active statement handle. */
  118.   var $stmt;
  119.   /** @var string $appname Name of application that uses this class. */
  120.   var $appname;
  121.   /** @var integer $debug Debugstate, default is OFF. */
  122.   var $debug;
  123.   /** @var string $sqlerr Contains possible SQL query that failed. */
  124.   var $sqlerr;
  125.   /** @var string $sqlerrmsg Contains ocierror['message'] info in case of an error. */
  126.   var $sqlerrmsg;
  127.   /** @var array $sqlcache Internal Cache for Prepare()/Execute() calls. */
  128.   var $sqlcache;
  129.   /** @var string All passed variables except QUERY and Flags. */
  130.   var $errvars;
  131.   /** @var integer Set to 1 to not auto-exit on error (Default is 0) */
  132.   var $no_exit;
  133.   /** @var integer How many SQL queries have been executed */
  134.   var $sqlcount;
  135.   /** @var integer How many Rows where affected by previous DML operation */
  136.   var $AffectedRows;
  137.   /** @var integer Flag indates level of error information shown */
  138.   var $showError;
  139.   /** @var string Email Address for the administrator of this project */
  140.   var $AdminEmail;
  141.   /** @var string The SAPI type of php (used to detect CLI sapi) */
  142.   var $SAPI_type;
  143.   /** @var array A hash array with all output parameters (used in QueryHash()) */
  144.   var $output_hash;
  145.   /** @var boolean TRUE = Connect() uses Persistant connection, else new one (Default) */
  146.   var $usePConnect;
  147.   /**
  148.    * @var integer How many connection retries we should try. Defaults to 1
  149.    * @since 0.75
  150.    */
  151.   var $connectRetries;
  152.  
  153.   /**
  154.    * Class Constructor.
  155.    * Whenever you instantiate this class the file dbdefs.inc.php will be included automatically.
  156.    * This file contains the default login data and other configuration options, see description
  157.    * inside this file for further informations.
  158.    * Since V0.72 you may optionally give an alternate file as configuration file. If no file is
  159.    * given inside the constructor the class still uses the file "dbdefs.inc.php" as default
  160.    * configuration file.
  161.    * @param string $extconfig Full path to dbdefs.inc.php, if empty class searches in current dir for dbdefs.inc.php
  162.    * @see dbdefs.inc.php
  163.    */
  164.   function db_oci8($extconfig='')
  165.     {
  166.     if($extconfig == '')
  167.       {
  168.       include_once('dbdefs.inc.php');
  169.       }
  170.     else
  171.       {
  172.       include($extconfig);
  173.       }
  174.     $this->classversion   = '0.78';                   // Version of our class
  175.     $this->host           = '';                       // TNS Name of DB to connect to
  176.     $this->user           = '';                       // Username
  177.     $this->pass           = '';                       // Password
  178.     $this->appname        = OCIAPPNAME;               // Name of our Application
  179.     $this->database       = '';                       // Oracle does not use this
  180.     $this->sock           = 0;                        // Internal database handle
  181.     $this->querycounter   = 0;                        // How many queries where executed
  182.     $this->querytime      = 0.000;                    // Time required for all queries
  183.     $this->stmt           = NULL;                     // Oracle Statement handler
  184.     $this->debug          = 0;                        // Debug is off per default
  185.     $this->sqlcache       = array();                  // Internal SQL cache for Prepare()/Execute()
  186.     $this->sqlerr         = '';                       // Contains possible SQL query that failed
  187.     $this->sqlerrmsg      = '';                       // Contains ocierror['message'] info
  188.     $this->errvars        = array();                  // All passed variables except QUERY and Flags
  189.     $this->no_exit        = 0;                        // Flag for Prepare/Execute pair to indicate if we should exit
  190.     $this->sqlcount       = 0;                        // Counter for Prepare/Execute pair to reference correct query
  191.     $this->AffectedRows   = 0;                        // Amount of rows processed during statement execution
  192.     $this->showError      = 0;                        // Flag for Error processing.
  193.     $this->AdminEmail     = (isset($_SERVER['SERVER_ADMIN'])) ? $_SERVER['SERVER_ADMIN'] : ''; // Defaults to Webadministrator of Server
  194.     $this->SAPI_type      = @php_sapi_name();         // May contain 'cli', in this case disable HTML errors!
  195.     $this->output_hash    = array();                  // Set to empty array in initial call
  196.     $this->usePConnect    = FALSE;                    // Set to TRUE to use Persistant connections
  197.     $this->connectRetries = 1;                        // How many retries we should perform when connecting to Oracle.
  198.  
  199.     if(!defined('OCIAPPNAME'))
  200.       {
  201.       $this->setErrorHandling(DBOF_SHOW_ALL_ERRORS);
  202.       $this->Print_Error('dbdefs.inc.php is wrong configured! Please check Class installation!');
  203.       }
  204.     if(defined('DB_ERRORMODE'))                     // You can set a default behavour for error handling in dbdefs.inc.php
  205.       {
  206.       $this->setErrorHandling(DB_ERRORMODE);
  207.       }
  208.     else
  209.       {
  210.       $this->setErrorHandling(DBOF_SHOW_NO_ERRORS); // Default is not to show too much informations
  211.       }
  212.     if(defined('OCIDB_ADMINEMAIL'))
  213.       {
  214.       $this->AdminEmail = OCIDB_ADMINEMAIL;         // If set use this address instead of default webmaster
  215.       }
  216.     if(defined('OCIDB_USE_PCONNECT') && OCIDB_USE_PCONNECT != 0)
  217.       {
  218.       $this->usePConnect = TRUE;
  219.       }
  220.     if(defined('OCIDB_CONNECT_RETRIES') && OCIDB_CONNECT_RETRIES > 1)
  221.       {
  222.       $this->connectRetries = OCIDB_CONNECT_RETRIES;
  223.       }
  224.     }
  225.  
  226.   /**
  227.    * Performs the connection to Oracle.
  228.    * If anything goes wrong calls Print_Error().
  229.    * Also an Oracle procedure is called to register the Application name
  230.    * as defined in dbdefs.inc.php, This helps DBAs to better fine tune
  231.    * their databases according to application needs.
  232.    * @see dbdefs.inc.php
  233.    * @see Print_Error()
  234.    * @param string $user Username used to connect to DB
  235.    * @param string $pass Password to use for given username
  236.    * @param string $host Hostname of database to connect to
  237.    * @param integer $exit_on_error If set to 1 Class will automatically exit with error code, else return error array
  238.    * @return mixed Either the DB connection handle or an error array/exit, depending how $exit_on_error is set
  239.    * @see oci_logon
  240.    * @see oci_plogon
  241.    */
  242.   function Connect($user=NULL,$pass=NULL,$host=NULL,$exit_on_error = 1)
  243.     {
  244.     $connquery = '';
  245.     $connretry = 0;
  246.  
  247.     if($this->sock)
  248.       {
  249.       return($this->sock);
  250.       }
  251.     if(isset($user) && $user!=NULL)
  252.       {
  253.       $this->user = $user;
  254.       }
  255.     else
  256.       {
  257.       $this->user = OCIDB_USER;
  258.       }
  259.     if(isset($pass) && $pass!=NULL)
  260.       {
  261.       $this->pass = $pass;
  262.       }
  263.     else
  264.       {
  265.       $this->pass = OCIDB_PASS;
  266.       }
  267.     if(isset($host) && $host!=NULL)
  268.       {
  269.       $this->host = $host;
  270.       }
  271.     else
  272.       {
  273.       $this->host = OCIDB_HOST;
  274.       }
  275.     $this->printDebug('OCILogon('.sprintf("%s/%s@%s",$this->user,$this->pass,$this->host).')');
  276.     $start = $this->getmicrotime();
  277.     do
  278.       {
  279.       if($this->usePConnect == TRUE)
  280.         {
  281.         $this->sock = @OCIPLogon($this->user,$this->pass,$this->host);
  282.         }
  283.       else
  284.         {
  285.         $this->sock = @OCILogon($this->user,$this->pass,$this->host);
  286.         }
  287.       if(!$this->sock && $this->connectRetries > 1)
  288.         {
  289.         sleep(2);   // Wait short time and retry:
  290.         }
  291.       $connretry++;
  292.       }while($connretry < $this->connectRetries);
  293.     if(!$this->sock)
  294.       {
  295.       $this->Print_Error('Connection to "'.$this->host.'" failed!',NULL,$exit_on_error);
  296.       return(0);
  297.       }
  298.     if(defined('DB_REGISTER') && DB_REGISTER == 1)
  299.       {
  300.       $connquery.= " DBMS_APPLICATION_INFO.SET_MODULE('".$this->appname."',NULL); ";
  301.       }
  302.     if(defined('DB_SET_NUMERIC') && DB_SET_NUMERIC == 1)
  303.       {
  304.       if(!defined('DB_NUM_DECIMAL') || !defined('DB_NUM_GROUPING'))
  305.         {
  306.         $this->Disconnect();
  307.         $this->setErrorHandling(DBOF_SHOW_ALL_ERRORS);
  308.         $this->Print_Error('You have to define DB_NUM_DECIMAL/DB_NUM_GROUPING in dbdefs.inc.php first !!!');
  309.         exit;
  310.         }
  311.       $connquery.= " EXECUTE IMMEDIATE 'ALTER SESSION SET NLS_NUMERIC_CHARACTERS = ''".DB_NUM_DECIMAL.DB_NUM_GROUPING."'''; ";
  312.       }
  313.     if($connquery != "")
  314.       {
  315.       $dummy = "BEGIN ";
  316.       $dummy.= $connquery;
  317.       $dummy.= " END;";
  318.       $this->Query($dummy,OCI_ASSOC,0);
  319.       }
  320.     $this->querytime+= ($this->getmicrotime() - $start);
  321.     return($this->sock);
  322.     }
  323.  
  324.   /**
  325.    * Disconnects from Oracle.
  326.    * You may optionally pass an external link identifier
  327.    * @param mixed $other_sock Optionally your own connection handle to close,
  328.    *  else internal socket will be used.
  329.    * @see OCI_Logoff
  330.    */
  331.   function Disconnect($other_sock=-1)
  332.     {
  333.     $start = $this->getmicrotime();
  334.     if($other_sock!=-1)
  335.       {
  336.       @OCILogoff($other_sock);
  337.       }
  338.     else
  339.       {
  340.       if($this->sock)
  341.         {
  342.         @OCILogoff($this->sock);
  343.         $this->sock = 0;
  344.         }
  345.       }
  346.     $this->querytime+= ($this->getmicrotime() - $start);
  347.     $this->AffectedRows = 0;
  348.     $this->sqlerr       = 0;
  349.     $this->sqlerrmsg    = '';
  350.     }
  351.  
  352.   /**
  353.    * Prints out an Oracle error.
  354.    * Tries to highlight the buggy SQL part of the query and dumps out
  355.    * as much informations as possible. This may lead however to
  356.    * security problems, in this case you can set DBOF_SHOW_NO_ERRORS
  357.    * and the Error informations are returned to the callee instead of
  358.    * being displayed on-screen.
  359.    * Since V0.64 the class is able to send an email error message, see dbdefs.inc.php
  360.    *
  361.    * @param string $ustr Optional user-error string to be displayed
  362.    * @param mixed $var2dump Optional a variable to be dumped out via print_r()
  363.    * @param integer $exit_on_error If set to default of 1 this function terminates
  364.    *  execution of the script by calling exit, else it simply returns.
  365.    * @see print_r
  366.    * @see oci_error
  367.    */
  368.   function Print_Error($ustr='',$var2dump=NULL, $exit_on_error = 1)
  369.     {
  370.     if($this->stmt)
  371.       {
  372.       $earr = @OCIError($this->stmt);
  373.       }
  374.     elseif($this->sock)
  375.       {
  376.       $earr = @OCIError($this->sock);
  377.       }
  378.     else
  379.       {
  380.       $earr = @OCIError();
  381.       }
  382.     $errstr   = $earr['message'];
  383.     $errnum   = $earr['code'];
  384.     $sqltext  = $earr['sqltext'];
  385.     $sqlerrpos= intval($earr['offset']);
  386.     if($errnum == '')
  387.       {
  388.       $errnum = -1;
  389.       }
  390.     if($errstr == '')
  391.       {
  392.       $errstr = 'N/A';
  393.       }
  394.     if($sqltext=="")
  395.       {
  396.       if($this->sqlerr!='')
  397.         {
  398.         $sqltext = $this->sqlerr;
  399.         }
  400.       else
  401.         {
  402.         $sqltext = 'N/A';
  403.         }
  404.       }
  405.     $this->sqlerrmsg = $errstr;
  406.     if($this->showError == DBOF_RETURN_ALL_ERRORS)
  407.       {
  408.       return($errnum);      // Return the error number
  409.       }
  410.     $this->SendMailOnError($earr);
  411.     $filename = basename($_SERVER['SCRIPT_FILENAME']);
  412.     if($this->sock)
  413.       {
  414.       $this->Rollback();
  415.       $this->Disconnect();
  416.       }
  417.     $crlf = "\n";
  418.     $space= " ";
  419.     if($this->SAPI_type != 'cli')
  420.       {
  421.       $crlf = "<br>\n";
  422.       $space= "&nbsp;";
  423.       echo("<br>\n<div align=\"left\" style=\"background-color: #EEEEEE; color:#000000\" class=\"TB\">\n");
  424.       echo("<font color=\"red\" face=\"Arial, Sans-Serif\"><b>".$this->appname.": Database Error occured!</b></font><br>\n<br>\n<code>\n");
  425.       }
  426.     else
  427.       {
  428.       echo("\n!!! ".$this->appname.": Database Error occured !!!\n\n");
  429.       }
  430.     echo('CODE: '.$errnum.$crlf);
  431.     echo('DESC: '.rtrim($errstr).$crlf);
  432.     echo('FILE: '.$filename.$crlf);
  433.     if($this->showError == DBOF_SHOW_ALL_ERRORS)
  434.       {
  435.       if($ustr!='')
  436.         {
  437.         echo('INFO: '.$ustr.$crlf);
  438.         }
  439.       if($sqlerrpos)
  440.         {
  441.         if($this->SAPI_type != 'cli')
  442.           {
  443.           $dummy = substr($sqltext,0,$sqlerrpos);
  444.           $dummy.='<font color="red">'.substr($sqltext,$sqlerrpos).'</font>';
  445.           $errquery = $dummy;
  446.           }
  447.         else
  448.           {
  449.           $errquery = $sqltext;
  450.           }
  451.         }
  452.       else
  453.         {
  454.         $errquery = $sqltext;
  455.         }
  456.       echo($space."SQL: ".$errquery.$crlf);
  457.       echo($space."POS: ".$sqlerrpos.$crlf);
  458.       echo("QCNT: ".$this->querycounter.$crlf);
  459.       if(count($this->errvars))
  460.         {
  461.         echo("VALS: ");
  462.         reset($this->errvars);
  463.         $i = 0;
  464.         $errbuf = '';
  465.         while(list($key,$val) = each($this->errvars))
  466.           {
  467.           if(!is_numeric($key))
  468.             {
  469.             $errbuf.=sprintf("P['%s']=>'%s' [%d]".$crlf,($key),$val,strlen($val));
  470.             }
  471.           else
  472.             {
  473.             $errbuf.=sprintf("P[%d]='%s'".$crlf,($i+1),$val);
  474.             }
  475.           $i++;
  476.           }
  477.         echo($errbuf.$crlf);
  478.         }
  479.       if(isset($var2dump))
  480.         {
  481.         if($this->SAPI_type != 'cli')
  482.           {
  483.           echo("DUMP: <pre>");
  484.           print_r($var2dump);
  485.           echo("</pre>");
  486.           }
  487.         else
  488.           {
  489.           echo("DUMP:\n");
  490.           print_r($var2dump);
  491.           }
  492.         }
  493.       }
  494.     if($this->SAPI_type != 'cli')
  495.       {
  496.       echo("<br>\nPlease inform <a href=\"mailto:".$this->AdminEmail."\">".$this->AdminEmail."</a> about this problem.");
  497.       echo("</code>\n");
  498.       echo("</div>\n");
  499.       echo("<div align=\"right\"><small>PHP V".phpversion()." / OCI8 Class v".$this->classversion."</small></div>\n");
  500.       @error_log($this->appname.': Error in '.$filename.': '.$ustr.' ('.chop($errstr).')',0);
  501.       }
  502.     else
  503.       {
  504.       echo("\nPlease inform ".$this->AdminEmail." about this problem.\n\nRunning on PHP V".phpversion()." / OCI8 Class v".$this->classversion."\n");
  505.       }
  506.     if($exit_on_error) exit;
  507.     }
  508.  
  509.   /**
  510.    * Performs a single row query with Bindvar support.
  511.    * Resflag can be OCI_NUM or OCI_ASSOC depending on what kind of array you want to be returned.
  512.    * Remember to pass all required variables for all defined bind vars after
  513.    * the $no_exit parameter, else you will recieve errors because of wrong parameter count!
  514.    * @param string $querystring The query to be executed against the RDBMS
  515.    * @param integer $resflag OCI_NUM for numeric array or OCI_ASSOC (default) for associative array result
  516.    * @param integer $no_exit 1 => Function returns errorcode instead of calling Print_Error() or 0 => Will always call Print_Error()
  517.    * @return array The result of the query as either associative or numeric array.
  518.    *  In case of an error can be also an assoc. array of error informations.
  519.    */
  520.   function Query($querystring, $resflag = OCI_ASSOC, $no_exit = 0)
  521.     {
  522.     $querystring        = ltrim($querystring);    // Leading spaces seems to be a problem??
  523.     $resarr             = array();
  524.     $this->errvars      = array();
  525.     $funcargs           = @func_num_args();
  526.     $this->sqlerr       = $querystring;
  527.     $this->AffectedRows = 0;
  528.     $stmt               = NULL;
  529.  
  530.     $this->checkSock();
  531.     if($querystring == '')
  532.       {
  533.       return($this->Print_Error('Query(): No querystring was supplied!'));
  534.       }
  535.     if($funcargs > 3)
  536.       {
  537.       $this->errvars = array_slice(func_get_args(),3);
  538.       $res = $this->GetBindVars($querystring);
  539.       if(($funcargs-3) != count($res))
  540.         {
  541.         return($this->Print_Error("Query(): Parameter count does not match bind var count in query! (Defined: ".count($res)." - Supplied: ".($funcargs).")",$res));
  542.         exit;
  543.         }
  544.       }
  545.     if($this->debug)
  546.       {
  547.       $this->PrintDebug($querystring);
  548.       }
  549.     $start = $this->getmicrotime();
  550.     $stmt = @OCIParse($this->sock,$querystring);
  551.     if(!$stmt)
  552.       {
  553.       return($this->Print_Error('Query(): Parse failed!'));
  554.       exit;
  555.       }
  556.     if($funcargs > 3)
  557.       {
  558.       for($i = 3; $i < $funcargs; $i++)
  559.         {
  560.         $arg[$i] = @func_get_arg($i);
  561.         @OCIBindByName($stmt,$res[$i-3],$arg[$i],-1);
  562.         }
  563.       }
  564.     if(!@OCIExecute($stmt,OCI_DEFAULT))
  565.       {
  566.       if($no_exit)
  567.         {
  568.         $err = @OCIError($stmt);
  569.         $this->sqlerrmsg = $err['message'];
  570.         return($err['code']);
  571.         }
  572.       else
  573.         {
  574.         $this->stmt = $stmt;
  575.         return($this->Print_Error('Query(): Execute failed!'));
  576.         exit;
  577.         }
  578.       }
  579.     $this->querycounter++;
  580.     if(StriStr(substr($querystring,0,6),"SELECT"))
  581.       {
  582.       @OCIFetchInto($stmt,$resarr,$resflag+OCI_RETURN_NULLS+OCI_RETURN_LOBS);
  583.       }
  584.     else
  585.       {
  586.       $res = 0;
  587.       }
  588.     $this->AffectedRows = @OCIRowCount($stmt);
  589.     @OCIFreeStatement($stmt);
  590.     $this->querytime+= ($this->getmicrotime() - $start);
  591.     $this->errvars = array();
  592.     return($resarr);
  593.     }
  594.  
  595.   /**
  596.    * Performs a multirow-query and returns result handle.
  597.    * Required if you want to fetch many data rows. Does not return in case
  598.    * of error, so no further checking is required.
  599.    * Supports also binding, see Query() for further details.
  600.    * @param string $querystring SQL-Statement to be executed
  601.    * @return mixed Returns the statement handle or an error array in case of an error.
  602.    * @see Query
  603.    * @see FetchResult
  604.    * @see FreeResult
  605.    */
  606.   function QueryResult($querystring)
  607.     {
  608.     $querystring        = ltrim($querystring);    // Leading spaces seems to be a problem??
  609.     $funcargs           = @func_num_args();
  610.     $this->sqlerr       = $querystring;
  611.     $this->errvars      = array();
  612.     $this->AffectedRows = 0;
  613.     $stmt               = NULL;
  614.  
  615.     $this->checkSock();
  616.     if($querystring == "")
  617.       {
  618.       return($this->Print_Error('QueryResult(): No querystring was supplied!'));
  619.       }
  620.     if($funcargs > 1)
  621.       {
  622.       $this->errvars = array_slice(func_get_args(),1);
  623.       $res = $this->GetBindVars($querystring);
  624.       if(($funcargs-1) != count($res))
  625.         {
  626.         return($this->Print_Error("QueryResult(): Parameter count does not match bind var count in query! (Defined:".count($res)." - Supplied: ".($funcargs).")",$res));
  627.         }
  628.       }
  629.     if($this->debug)
  630.       {
  631.       $this->PrintDebug($querystring);
  632.       }
  633.     $start = $this->getmicrotime();
  634.     $stmt = @OCIParse($this->sock,$querystring);
  635.     if(!$stmt)
  636.       {
  637.       return($this->Print_Error('QueryResult(): Parse failed!'));
  638.       }
  639.  
  640.     // Check if user wishes to set a default prefetching value:
  641.  
  642.     if(defined('DB_DEFAULT_PREFETCH'))
  643.       {
  644.       $this->setPrefetch(DB_DEFAULT_PREFETCH);
  645.       }
  646.  
  647.     // If we have any of the bind vars given, bind them NOW:
  648.  
  649.     if($funcargs > 1)
  650.       {
  651.       for($i = 1; $i < $funcargs; $i++)
  652.         {
  653.         $arg[$i] = @func_get_arg($i);
  654.         @OCIBindByName($stmt,$res[$i-1],$arg[$i],-1);
  655.         }
  656.       }
  657.     if(!@OCIExecute($stmt,OCI_DEFAULT))
  658.       {
  659.       $this->stmt = $stmt;
  660.       return($this->Print_Error('QueryResult(): Execute failed!'));
  661.       }
  662.     $this->querycounter++;
  663.     $this->querytime+= ($this->getmicrotime() - $start);
  664.     $this->sqlcache[$this->sqlcount][DBOF_CACHE_QUERY]     = $querystring;
  665.     $this->sqlcache[$this->sqlcount][DBOF_CACHE_STATEMENT] = $stmt;
  666.     $this->sqlcount++;
  667.     // Result set is returned, so we return it to the caller and also store it into internal class variable if another stmt isn't already stored there:
  668.     if(is_null($this->stmt))
  669.       {
  670.       $this->stmt = $stmt;
  671.       }
  672.     return($stmt);
  673.     }
  674.  
  675.   /**
  676.    * Fetches next datarow.
  677.    * Returns either numeric (OCI_NUM) or associative (OCI_ASSOC) array
  678.    * for one data row as pointed to by either internal or passed result var.
  679.    * @param integer $resflag OCI_ASSOC => Return associative array or OCI_NUM => Return numeric array
  680.    * @param mixed $extstmt If != -1 then we try to fetch from that passed handle, else the class uses
  681.    *  internal saved handle. Useful if you want to perform a lot of different queries.
  682.    * @return array The fetched datarow or NULL if no more data exist.
  683.    * @see QueryResult
  684.    * @see FreeResult
  685.    */
  686.   function FetchResult($resflag = OCI_ASSOC,$extstmt = -1)
  687.     {
  688.     if($extstmt == -1)
  689.       {
  690.       $mystate = $this->stmt;
  691.       }
  692.     else
  693.       {
  694.       $mystate = $extstmt;
  695.       }
  696.     $start = $this->getmicrotime();
  697.     @OCIFetchInto($mystate, $res, $resflag+OCI_RETURN_NULLS+OCI_RETURN_LOBS);
  698.     $this->querytime+= ($this->getmicrotime() - $start);
  699.     return($res);
  700.     }
  701.  
  702.   /**
  703.    * Frees result obtained by QueryResult().
  704.    * You may optionally pass external Result handle, if you omit this parameter
  705.    * the internal handle is freed. This function also checks the built-in statement
  706.    * cache for the handle and removes it from cache, too.
  707.    * @param mixed $extstmt Optional your external saved handle to be freed.
  708.    * @return mixed The result of OCIFreeStatement() is returned.
  709.    * @see QueryResult
  710.    * @see FetchResult
  711.    * @see SearchQueryCache
  712.    * @see RemoveFromQueryCache
  713.    * @see OCI_Free_Statement
  714.    */
  715.   function FreeResult($extstmt = -1)
  716.     {
  717.     if($extstmt == -1)
  718.       {
  719.       $mystate = $this->stmt;
  720.       $this->stmt = NULL;
  721.       }
  722.     else
  723.       {
  724.       $mystate = $extstmt;
  725.       $fq = $this->SearchQueryCache($extstmt);
  726.       if($fq != -1)
  727.         {
  728.         $this->RemoveFromQueryCache($fq);
  729.         }
  730.       }
  731.     $this->errvars = array();
  732.     $this->no_exit = 0;
  733.     if($mystate)
  734.       {
  735.       $start = $this->getmicrotime();
  736.       $this->AffectedRows = @OCIRowCount($mystate);
  737.       return(@OCIFreeStatement($mystate));
  738.       $this->querytime+= ($this->getmicrotime() - $start);
  739.       }
  740.     }
  741.  
  742.   /**
  743.    * Returns Oracle Server Version.
  744.    * Opens an own connection if no active one exists.
  745.    * @return string The Oracle Release Version string
  746.    */
  747.   function Version()
  748.     {
  749.     $weopen = 0;
  750.     if(!$this->sock)
  751.       {
  752.       $this->Connect();
  753.       $weopen = 1;
  754.       }
  755.     if($this->debug)
  756.       {
  757.       $this->PrintDebug('Version() called - Self-Connect: '.$weopen);
  758.       }
  759.     $start = $this->getmicrotime();
  760.     $ver = @OCIServerVersion($this->sock);
  761.     $ret = explode("-",$ver);
  762.     if($weopen) $this->Disconnect();
  763.     $this->querycounter++;
  764.     $this->querytime+= ($this->getmicrotime() - $start);
  765.     return(trim($ret[0]));
  766.     }
  767.  
  768.   /**
  769.    * Returns amount of queries executed by this class.
  770.    * @return integer How many queries are executed currently by this class.
  771.    */
  772.   function GetQueryCount()
  773.     {
  774.     if($this->debug)
  775.       {
  776.       $this->PrintDebug('GetQueryCount() called');
  777.       }
  778.     return(intval($this->querycounter));
  779.     }
  780.  
  781.   /**
  782.    * Returns amount of time spend on queries executed by this class.
  783.    * @return float Time in seconds.msecs spent in executing SQL statements.
  784.    * @since 0.68
  785.    */
  786.   function GetQueryTime()
  787.     {
  788.     return($this->querytime);
  789.     }
  790.  
  791.   /**
  792.    * Commits current transaction.
  793.    * @return integer The value of OCICommit() is returned.
  794.    * @see oci_commit
  795.    */
  796.   function Commit()
  797.     {
  798.     $this->checkSock();
  799.     if($this->debug)
  800.       {
  801.       $this->PrintDebug('COMMIT called');
  802.       }
  803.     $start = $this->getmicrotime();
  804.     $rc = @OCICommit($this->sock);
  805.     $this->querytime+= ($this->getmicrotime() - $start);
  806.     return($rc);
  807.     }
  808.  
  809.   /**
  810.    * Rollback current transaction.
  811.    * @return integer The value of OCIRollback() is returned.
  812.    * @see oci_rollback
  813.    */
  814.   function Rollback()
  815.     {
  816.     $this->checkSock();
  817.     if($this->debug)
  818.       {
  819.       $this->PrintDebug('ROLLBACK called');
  820.       }
  821.     $start = $this->getmicrotime();
  822.     $rc = @OCIRollback($this->sock);
  823.     $this->querytime+= ($this->getmicrotime() - $start);
  824.     return($rc);
  825.     }
  826.  
  827.   /**
  828.    * Function extracts all bind vars out of given query.
  829.    * To avoid wrong determined bind vars this function first kills out all TO_*() functions
  830.    * together with their (possible) format strings which results in a query
  831.    * containing only valid bind vars, format tags or other similar constructed
  832.    * tags are removed.
  833.    * @param string $query The query to check for bind vars.
  834.    * @return array Returns an array with all found bind vars in the order they are defined inside the query.
  835.    */
  836.   function GetBindVars($query)
  837.     {
  838.     $pattern = array("/(TO_.*?\()(.*?)(,)(.*?\))/is","/(TO_.*?\('.*?'\))/is","/(TO_.*?\()(.*?\))/is");
  839.     $replace = array("$2","","$2");
  840.     $mydummy = $query;    // Make copy of current SQL
  841.  
  842.     $mydummy = @preg_replace($pattern,$replace,$mydummy);
  843.     @preg_match_all('/[,|\W]?(:\w+)[,|\W]?/i',$mydummy,$res);
  844.     return($res[1]);
  845.     }
  846.  
  847.   /**
  848.    * Function allows debugging of SQL Queries.
  849.    * $state can have these values:
  850.    * - DBOF_DEBUGOFF    = Turn off debugging
  851.    * - DBOF_DEBUGSCREEN = Turn on debugging on screen (every Query will be dumped on screen)
  852.    * - DBOF_DEBUFILE    = Turn on debugging on PHP errorlog
  853.    * You can mix the debug levels by adding the according defines!
  854.    * @param integer $state The DEBUG level to set
  855.    */
  856.   function SetDebug($state)
  857.     {
  858.     $this->debug = $state;
  859.     }
  860.  
  861.   /**
  862.    * Handles debug output according to internal debug flag.
  863.    * @param string $msg The string to be send out to selected output.
  864.    */
  865.   function PrintDebug($msg)
  866.     {
  867.     if(!$this->debug) return;
  868.     $errbuf = '';
  869.     if($this->SAPI_type != 'cli')
  870.       {
  871.       $crlf   = '<br>';
  872.       $header = "<div align=\"left\" style=\"background-color:#ffffff; color:#000000\"><pre>DEBUG: %s%s</pre></div>\n";
  873.       }
  874.     else
  875.       {
  876.       $crlf   = "\n";
  877.       $header = "DEBUG: %s%s\n";
  878.       }
  879.     if($this->errvars)
  880.       {
  881.       $errbuf = $crlf.'VARS: ';
  882.       reset($this->errvars);
  883.       while(list($key,$val) = each($this->errvars))
  884.         {
  885.         if(!is_numeric($key))
  886.           {
  887.           $errbuf.=sprintf("P(%s)='%s' [%d]".$crlf,($key),$val,strlen($val));
  888.           }
  889.         else
  890.           {
  891.           $errbuf.=sprintf("P%d='%s'".$crlf,($i+1),$val);
  892.           }
  893.         $i++;
  894.         }
  895.       }
  896.     if($this->debug & DBOF_DEBUGSCREEN)
  897.       {
  898.       printf($header,$msg,$errbuf);
  899.       }
  900.     if($this->debug & DBOF_DEBUGFILE)
  901.       {
  902.       @error_log('DEBUG: '.$msg,0);
  903.       if($errbuf!="")
  904.         {
  905.         @error_log('DEBUG: '.strip_tags($errbuf),0);
  906.         }
  907.       }
  908.     }
  909.  
  910.   /**
  911.    * Allows to en- or disable the SQL_TRACE feature of Oracle.
  912.    * Pass TRUE to enable or FALSE to disable. When enabled all Statements of your
  913.    * session are saved in a tracefile stored in
  914.    * $ORACLE_BASE/admin/<DBNAME>/udump/*.trc
  915.    * After your session disconnects use the tkprof tool to generate
  916.    * Human-readable output from the tracefile, i.e.:
  917.    * $> tkprof oracle_ora_7527.trc out.txt
  918.    * Now read 'out.txt' and see what happen in Oracle!
  919.    * @param boolean $state TRUE to enable or FALSE to disable the SQL_TRACE feature.
  920.    */
  921.   function SQLDebug($state)
  922.     {
  923.     switch($state)
  924.       {
  925.       case  TRUE:   $sdebug = 'TRUE';
  926.                     break;
  927.       case  FALSE:  $sdebug = 'FALSE';
  928.                     break;
  929.       default:      return;
  930.       }
  931.     if($this->sock)
  932.       {
  933.       $this->Query('ALTER SESSION SET SQL_TRACE = '.$sdebug);
  934.       }
  935.     }
  936.  
  937.   /**
  938.    * Returns version of this class.
  939.    * @return string The version string in format "major.minor"
  940.    */
  941.   function GetClassVersion()
  942.     {
  943.     return($this->classversion);
  944.     }
  945.  
  946.   /**
  947.    * Describes a table by returning an array with all table info.
  948.    * @param string $tablename Name of table you want to describe.
  949.    * @return array A 2-dimensional array with table informations.
  950.    */
  951.   function DescTable($tablename)
  952.     {
  953.     $retarr = array();
  954.     $weopen = 0;
  955.     if(!$this->sock)
  956.       {
  957.       $this->Connect();
  958.       $weopen = 1;
  959.       }
  960.     if($this->debug)
  961.       {
  962.       $this->PrintDebug('DescTable('.$tablename.') called - Self-Connect: '.$weopen);
  963.       }
  964.     $start = $this->getmicrotime();
  965.     $stmt = @OCIParse($this->sock,"SELECT * FROM ".$tablename." WHERE ROWNUM < 1");
  966.     @OCIExecute($stmt);
  967.     $this->querycounter++;
  968.     $ncols = @OCINumCols($stmt);
  969.     for ($i = 1; $i <= $ncols; $i++)
  970.       {
  971.       $retarr[$i-1][DBOF_COLNAME] = @OCIColumnName($stmt, $i);
  972.       $retarr[$i-1][DBOF_COLTYPE] = @OCIColumnType($stmt, $i);
  973.       $retarr[$i-1][DBOF_COLSIZE] = @OCIColumnSize($stmt, $i);
  974.       $retarr[$i-1][DBOF_COLPREC] = @OCIColumnPrecision($stmt,$i);
  975.       }
  976.     @OCIFreeStatement($stmt);
  977.     if($weopen) $this->Disconnect();
  978.     $this->querytime+= ($this->getmicrotime() - $start);
  979.     return($retarr);
  980.     }
  981.  
  982.   /**
  983.    * Preparses a query but do not execute it (yet).
  984.    * This allows to use a compiled query inside loops without having to parse it everytime
  985.    * Since 0.38 all prepared() queries will be put into our own QueryCache() so
  986.    * we can use the Prepare()/Execute()/ExecuteHash() pair for more than one query at once.
  987.    * @param string $querystring The Query you want to prepare (can contain bind variables).
  988.    * @param integer $no_exit 1 => Function returns errorcode instead of calling Print_Error() or 0 => Will always call Print_Error()
  989.    * @return mixed Either the statement handle on success or an error code / calling print_error().
  990.    */
  991.   function Prepare($querystring, $no_exit = 0)
  992.     {
  993.     $querystring    = ltrim($querystring);    // Leading spaces seems to be a problem??
  994.     $this->no_exit  = $no_exit;
  995.     $this->sqlerr   = $querystring;
  996.  
  997.     $this->checkSock();
  998.     $start = $this->getmicrotime();
  999.     $stmt = @OCIParse($this->sock,$querystring);
  1000.     if(!$stmt)
  1001.       {
  1002.       if($no_exit)
  1003.         {
  1004.         $err = @OCIError($this->sock);
  1005.         $this->sqlerrmsg = $err['message'];
  1006.         return($err['code']);
  1007.         }
  1008.       else
  1009.         {
  1010.         return($this->Print_Error('Prepare(): Parse failed!'));
  1011.         }
  1012.       }
  1013.     if($this->debug)
  1014.       {
  1015.       $this->PrintDebug("PREPARE: #".$this->sqlcount." ".$this->sqlerr);
  1016.       }
  1017.     $this->sqlcache[$this->sqlcount][DBOF_CACHE_QUERY]     = $querystring;
  1018.     $this->sqlcache[$this->sqlcount][DBOF_CACHE_STATEMENT] = $stmt;
  1019.     $this->sqlcount++;
  1020.     $this->querytime+= ($this->getmicrotime() - $start);
  1021.     return($stmt);
  1022.     }
  1023.  
  1024.   /**
  1025.    * Executes a prepare()d statement and returns the result.
  1026.    * You may then Fetch rows with FetchResult() or call FreeResult() to free your allocated result.
  1027.    * V0.38: Execute() searches first our QueryCache before executing, this
  1028.    * way we can use almost unlimited Queries at once in the Prepare/Execute pair
  1029.    * @param mixed $stmt The statement handle to be executed.
  1030.    * @return mixed Returns result set read for FetchResult() usage or an error state depending on class setting in case of an error.
  1031.    * @see Prepare
  1032.    */
  1033.   function Execute($stmt)
  1034.     {
  1035.     $f = $this->SearchQueryCache($stmt);
  1036.     if($f == -1)
  1037.       {
  1038.       return($this->Print_Error("Cannot find query for given statement #".$stmt." inside query cache!!!"));
  1039.       }
  1040.     $this->sqlerr  = $this->sqlcache[$f][DBOF_CACHE_QUERY];
  1041.     $this->errvars = array();
  1042.     $funcargs = @func_num_args();
  1043.     if($funcargs > 1)
  1044.       {
  1045.       $this->errvars = @array_slice(@func_get_args(),1);
  1046.       $res = $this->GetBindVars($this->sqlcache[$f][DBOF_CACHE_QUERY]);
  1047.       if(($funcargs-1) != count($res))
  1048.         {
  1049.         $this->stmt = $stmt;
  1050.         return($this->Print_Error("Execute(): Parameter count does not match bind var count in query! (Defined:".count($res)." - Supplied: ".($funcargs).")",$res));
  1051.         }
  1052.       }
  1053.     $start = $this->getmicrotime();
  1054.     if($funcargs > 1)
  1055.       {
  1056.       for($i = 1; $i < $funcargs; $i++)
  1057.         {
  1058.         $arg[$i] = @func_get_arg($i);
  1059.         @OCIBindByName($stmt,$res[$i-1],$arg[$i],-1);
  1060.         }
  1061.       }
  1062.     if($this->debug)
  1063.       {
  1064.       $this->PrintDebug($this->sqlerr);
  1065.       }
  1066.     if(!@OCIExecute($stmt,OCI_DEFAULT))
  1067.       {
  1068.       if($this->no_exit)
  1069.         {
  1070.         $err = @OCIError($stmt);
  1071.         $this->sqlerrmsg = $err['message'];
  1072.         return($err['code']);
  1073.         }
  1074.       else
  1075.         {
  1076.         $this->stmt = $stmt;
  1077.         return($this->Print_Error('Execute(): Execute failed!'));
  1078.         }
  1079.       }
  1080.     $this->querycounter++;
  1081.     $this->querytime+= ($this->getmicrotime() - $start);
  1082.     return($stmt);
  1083.     }
  1084.  
  1085.   /**
  1086.    * Searches internal query cache for given statement id.
  1087.    * Returns index of found statement id or -1 to indicate an error.
  1088.    * This function is considered private and should NOT (!) be called from outside this class!
  1089.    * @param mixed $stmt The statement handle to search for
  1090.    * @return integer The index number of the found statement or -1 if no handle could be found.
  1091.    * @since 0.38
  1092.    */
  1093.   function SearchQueryCache($stmt)
  1094.     {
  1095.     $f = 0;
  1096.     for($i = 0; $i < $this->sqlcount; $i++)
  1097.       {
  1098.       if($this->sqlcache[$i][DBOF_CACHE_STATEMENT] === $stmt)
  1099.         {
  1100.         return($i);
  1101.         }
  1102.       }
  1103.     return(-1);
  1104.     }
  1105.  
  1106.   /**
  1107.    * Removes query from cache.
  1108.    * Tries to remove a query from cache that was found by a previous call
  1109.    * to SearchQueryCache().
  1110.    * @param integer $nr Number of statement handle to be removed from cache.
  1111.    * @since 0.38
  1112.    */
  1113.   function RemoveFromQueryCache($nr)
  1114.     {
  1115.     $newdata = array();
  1116.     $lv = 0;
  1117.     for($i = 0; $i < $this->sqlcount; $i++)
  1118.       {
  1119.       if($i != $nr)
  1120.         {
  1121.         $newdata[$lv][DBOF_CACHE_QUERY]    = $this->sqlcache[$i][DBOF_CACHE_QUERY];
  1122.         $newdata[$lv][DBOF_CACHE_STATEMENT]= $this->sqlcache[$i][DBOF_CACHE_STATEMENT];
  1123.         $lv++;
  1124.         }
  1125.       }
  1126.     $this->sqlcache = $newdata;
  1127.     $this->sqlcount--;
  1128.     }
  1129.  
  1130.   /**
  1131.    * Checks if we are already connected to our database.
  1132.    * If not terminates by calling Print_Error().
  1133.    * @see Print_Error
  1134.    * @since 0.40
  1135.    */
  1136.   function checkSock()
  1137.     {
  1138.     if(!$this->sock)
  1139.       {
  1140.       return($this->Print_Error('<b>!!! NOT CONNECTED TO AN ORACLE DATABASE !!!</b>'));
  1141.       }
  1142.     }
  1143.  
  1144.   /**
  1145.    * Allows to save a file to a binary object field (BLOB).
  1146.    * Does not commit!
  1147.    * @param string $file_to_save Full path and filename of file to save
  1148.    * @param string $blob_table Name of Table where the blobfield resides
  1149.    * @param string $blob_field Name of BLOB field
  1150.    * @param string $where_clause Criteria to get the right row (i.e. WHERE ROWID=ABCDEF12345)
  1151.    * @return integer If all is okay returns 0 else an oracle error code.
  1152.    * @since 0.41
  1153.    */
  1154.   function SaveBLOB($file_to_save, $blob_table, $blob_field, $where_clause)
  1155.     {
  1156.     $this->checkSock();
  1157.     if($where_clause == '')
  1158.       {
  1159.       return($this->Print_Error("SaveBLOB(): WHERE clause must be non-empty, else ALL rows would be updated!!!"));
  1160.       }
  1161.     $q1 = "UPDATE ".$blob_table." SET ".$blob_field."=EMPTY_BLOB() ".$where_clause." RETURNING ".$blob_field." INTO :oralob";
  1162.     $this->sqlerr = $q1;
  1163.     $start = $this->getmicrotime();
  1164.     $lobptr = @OCINewDescriptor($this->sock, OCI_D_LOB);
  1165.     if(!($lobstmt = @OCIParse($this->sock,$q1)))
  1166.       {
  1167.       return($this->Print_Error("SaveBLOB(): Unable to parse query !!!"));
  1168.       }
  1169.     @OCIBindByName($lobstmt, ":oralob", $lobptr, -1, OCI_B_BLOB);
  1170.     if(!@OCIExecute($lobstmt, OCI_DEFAULT))
  1171.       {
  1172.       @OCIFreeStatement($lobstmt);
  1173.       @OCIFreeDesc($lobptr);
  1174.       return($this->Print_Error("SaveBLOB(): Unable to retrieve empty LOB locator !!!"));
  1175.       }
  1176.     if(!$lobptr->savefile($file_to_save))
  1177.       {
  1178.       @OCIFreeStatement($lobstmt);
  1179.       @OCIFreeDesc($lobptr);
  1180.       return($this->Print_Error("SaveBLOB(): Cannot save LOB data !!!"));
  1181.       }
  1182.     @OCIFreeDesc($lobptr);
  1183.     @OCIFreeStatement($lobstmt);
  1184.     $this->query_counter++;
  1185.     $this->querytime+= ($this->getmicrotime() - $start);
  1186.     return(0);
  1187.     }
  1188.  
  1189.   /**
  1190.    * Returns current connection handle.
  1191.    * Returns either the internal connection socket or -1 if no active handle exists.
  1192.    * Useful if you want to work with OCI* functions in parallel to this class.
  1193.    * @return mixed Internal socket value
  1194.    * @since 0.42
  1195.    */
  1196.   function GetConnectionHandle()
  1197.     {
  1198.     return($this->sock);
  1199.     }
  1200.  
  1201.   /**
  1202.    * Allows to set internal socket to external value.
  1203.    * Note that the internal socket descriptor is only overriden if the class has
  1204.    * no active connection stored! If already a connection was performed the class
  1205.    * does not override it's internal handle to avoid problems!
  1206.    * @param mixed $extsock The connection handle as returned from OCILogon().
  1207.    * @since 0.49
  1208.    */
  1209.   function SetConnectionHandle($extsock)
  1210.     {
  1211.     if(!$this->sock) $this->sock = $extsock;
  1212.     }
  1213.  
  1214.   /**
  1215.    * Executes a query with parameters passed as hash values.
  1216.    * Also IN/OUT and RETURNING INTO <...> clauses are supported.
  1217.    * You have to use FetchResult()/FreeResult() after using this function.
  1218.    * @param string $query The Query to be executed.
  1219.    * @param array &$inhash The bind vars as associative array (keys = bindvar names, values = bindvar values)
  1220.    * @return mixed Either the statement handle or an error code / calling Print_Error().
  1221.    * @see FetchResult
  1222.    * @see FreeResult
  1223.    * @since 0.44
  1224.    */
  1225.   function QueryResultHash($query,&$inhash)
  1226.     {
  1227.     $this->checkSock();
  1228.     $query        = ltrim($query);    // Leading spaces seems to be a problem??
  1229.     $this->sqlerr = $query;
  1230.     if($this->debug)
  1231.       {
  1232.       $this->PrintDebug($query);
  1233.       }
  1234.     $start = $this->getmicrotime();
  1235.     if(!($stmt = @OCIParse($this->sock,$query)))
  1236.       {
  1237.       return($this->Print_Error("QueryResultHash(): Unable to parse query !!!"));
  1238.       }
  1239.     if(is_array($inhash))
  1240.       {
  1241.       $this->errvars = $inhash;
  1242.       reset($inhash);
  1243.       while(list($key,$val) = each($inhash))
  1244.         {
  1245.         @OCIBindByName($stmt,$key,$inhash[$key],-1);
  1246.         }
  1247.       }
  1248.     if(!@OCIExecute($stmt,OCI_DEFAULT))
  1249.       {
  1250.       $this->stmt = $stmt;
  1251.       return($this->Print_Error("QueryResultHash(): Execute query failed!"));
  1252.       }
  1253.     $this->querycounter++;
  1254.     $this->querytime+= ($this->getmicrotime() - $start);
  1255.     if(is_null($this->stmt))
  1256.       {
  1257.       $this->stmt = $stmt;
  1258.       }
  1259.     return($stmt);
  1260.     }
  1261.  
  1262.   /**
  1263.    * This function tries to get the description for a given error message.
  1264.    * Simply pass the $err['message'] field to this function, it tries to
  1265.    * extract the required informations and call $ORACLE_HOME/bin/oerr to
  1266.    * get the error description. If either the exterr or the internal sqlerrmsg
  1267.    * variables are empty this function returns: "No error found."
  1268.    * @param string The error string from oracle. Maybe empty, in this case uses internal sqlerrmsg field.
  1269.    * @return string The extracted error text.
  1270.    */
  1271.   function GetErrorText($exterr = "")
  1272.     {
  1273.     if($exterr != "")
  1274.       {
  1275.       $checkem = $exterr;
  1276.       }
  1277.     else
  1278.       {
  1279.       $checkem = $this->sqlerrmsg;
  1280.       }
  1281.     if($checkem=="")
  1282.       {
  1283.       return("No error found as error text is empty!");
  1284.       }
  1285.     $dummy = explode(":",$checkem);   // Oracle stores errors as: XXX-YYYY: ZZZZZZZ
  1286.     if($dummy[0] == $checkem)
  1287.       {
  1288.       return("No valid error description found! (".$checkem.")");
  1289.       }
  1290.     $test   = str_replace("-"," ",$dummy[0]);
  1291.     $cmdstr = "NLS_LANG=AMERICAN_AMERICA.WE8ISO8859P1; \$ORACLE_HOME/bin/oerr ".$test;
  1292.     $data   = @exec($cmdstr,$retdata,$retcode);
  1293.     $dummy  = @explode(",",$retdata[0]);     // Oracle stores: 01721, 00000, "..."
  1294.     return(@trim(@preg_replace("/\"/","",$dummy[2])));
  1295.     }
  1296.  
  1297.   /**
  1298.    * Returns count of affected rows.
  1299.    * Info is set in Query() and QueryResult() / FreeResult()
  1300.    * and should return the amount of rows affected by previous DML command
  1301.    * @return integer Number of affected rows of previous DML command
  1302.    */
  1303.   function AffectedRows()
  1304.     {
  1305.     return($this->AffectedRows);
  1306.     }
  1307.  
  1308.   /**
  1309.    * Returns hash with error informations from last query.
  1310.    * @return array Assoc. array with error informations.
  1311.    * @since 0.55
  1312.    */
  1313.   function getSQLError()
  1314.     {
  1315.     $ehash['err'] = $this->sqlerr;
  1316.     $ehash['msg'] = $this->sqlerrmsg;
  1317.     return($ehash);
  1318.     }
  1319.  
  1320.   /**
  1321.    * Allows to set the handling of errors.
  1322.    *
  1323.    * - DBOF_SHOW_NO_ERRORS    => Show no security-relevant informations
  1324.    * - DBOF_SHOW_ALL_ERRORS   => Show all errors (useful for develop)
  1325.    * - DBOF_RETURN_ALL_ERRORS => No error/autoexit, just return the mysql_error code.
  1326.    * @param integer $val The Error Handling mode you wish to use.
  1327.    * @since 0.57
  1328.    */
  1329.   function setErrorHandling($val)
  1330.     {
  1331.     $this->showError = $val;
  1332.     }
  1333.  
  1334.   /**
  1335.    * Allows to set the prefetch value when returning results.
  1336.    * Default is 1 which may lead to performance problems when data is transmitted via WAN.
  1337.    * @param integer $rows Amount of rows to be used for prefetching.
  1338.    * @param mixed $extstmt Optionally your own statement handle. If you omit this parameter the internal statement handle is used.
  1339.    * @return boolean Return value of OCISetPrefetch()
  1340.    * @see OCISetPrefetch()
  1341.    */
  1342.   function setPrefetch($rows,$extstmt=-1)
  1343.     {
  1344.     if($extstmt == -1)
  1345.       {
  1346.       $st = $this->stmt;
  1347.       }
  1348.     else
  1349.       {
  1350.       $st = $extstmt;
  1351.       }
  1352.     if($st < 0) return($st);
  1353.     return(@OCISetPrefetch($st,$rows));
  1354.     }
  1355.  
  1356.   /**
  1357.    * Performs a single row query with Bindvar support passed as associative hash.
  1358.    * Resflag can be OCI_NUM or OCI_ASSOC depending on what kind of array you want to be returned.
  1359.    * Remember to pass all required variables for all defined bind vars after the $no_exit parameter
  1360.    * as an assoc. array (Key = name of bindvar without ':', value = value to add).
  1361.    * @param string $querystring The query to be executed against the RDBMS
  1362.    * @param integer $resflag OCI_NUM for numeric array or OCI_ASSOC (default) for associative array result
  1363.    * @param integer $no_exit 1 => Function returns errorcode instead of calling Print_Error() or 0 => Will always call Print_Error()
  1364.    * @param array &$bindvarhash The bind vars as associative array (keys = bindvar names, values = bindvar values)
  1365.    * @return array The result of the query as either associative or numeric array.
  1366.    *  In case of an error can be also an assoc. array of error informations.
  1367.    * @see setOutputHash
  1368.    * @see getOutputHash
  1369.    * @see clearOutputHash
  1370.    * @since 0.62
  1371.    */
  1372.   function QueryHash($querystring, $resflag = OCI_ASSOC, $no_exit = 0, &$bindvarhash)
  1373.     {
  1374.     $querystring        = ltrim($querystring);    // Leading spaces seems to be a problem??
  1375.     $resarr             = array();
  1376.     $this->errvars      = array();
  1377.     $funcargs           = @func_num_args();
  1378.     $this->sqlerr       = $querystring;
  1379.     $this->AffectedRows = 0;
  1380.  
  1381.     $this->checkSock();
  1382.     if($querystring == '')
  1383.       {
  1384.       return($this->Print_Error('QueryHash(): No querystring was supplied!'));
  1385.       }
  1386.     if($this->debug)
  1387.       {
  1388.       $this->PrintDebug($querystring);
  1389.       }
  1390.     $start = $this->getmicrotime();
  1391.     $stmt = @OCIParse($this->sock,$querystring);
  1392.     if(!$stmt)
  1393.       {
  1394.       return($this->Print_Error('QueryHash(): Parse failed!'));
  1395.       exit;
  1396.       }
  1397.     if(is_array($bindvarhash))
  1398.       {
  1399.       reset($bindvarhash);
  1400.       $this->errvars = $bindvarhash;
  1401.       while(list($key,$val) = each($bindvarhash))
  1402.         {
  1403.         @OCIBindByName($stmt,$key,$bindvarhash[$key],-1);
  1404.         }
  1405.       }
  1406.     if(count($this->output_hash))
  1407.       {
  1408.       reset($this->output_hash);
  1409.       while(list($key,$val) = each($this->output_hash))
  1410.         {
  1411.         @OCIBindByName($stmt,$key,$this->output_hash[$key],$val);
  1412.         }
  1413.       }
  1414.     $ret = @OCIExecute($stmt,OCI_DEFAULT);
  1415.     if($ret === FALSE)
  1416.       {
  1417.       if($no_exit)
  1418.         {
  1419.         $err = @OCIError($stmt);
  1420.         $this->sqlerrmsg = $err['message'];
  1421.         return($err['code']);
  1422.         }
  1423.       else
  1424.         {
  1425.         $this->stmt = $stmt;
  1426.         return($this->Print_Error('QueryHash(): Execute failed!'));
  1427.         exit;
  1428.         }
  1429.       }
  1430.     $this->querycounter++;
  1431.     if(StriStr(substr($querystring,0,6),"SELECT"))
  1432.       {
  1433.       @OCIFetchInto($stmt,$resarr,$resflag+OCI_RETURN_NULLS+OCI_RETURN_LOBS);
  1434.       }
  1435.     else
  1436.       {
  1437.       $res = 0;
  1438.       }
  1439.     $this->AffectedRows = @OCIRowCount($stmt);
  1440.     @OCIFreeStatement($stmt);
  1441.     $this->querytime+= ($this->getmicrotime() - $start);
  1442.     $this->errvars = array();
  1443.     return($resarr);
  1444.     }
  1445.  
  1446.   /**
  1447.    * Use this function to pass output hash data to QueryHash() function.
  1448.    * This is only required if you are using RETURNING INTO clauses or OUT variables,
  1449.    * if you only use the bind variables for input (IN) you do not need to set this.
  1450.    * WARNING: You are responsible to clear the array by using clearOutputHash()!
  1451.    * @param array &$outputhash The assoc. array to use for bind var return variables
  1452.    * @see getOutputHash
  1453.    */
  1454.   function setOutputHash(&$outputhash)
  1455.     {
  1456.     $this->output_hash = &$outputhash;
  1457.     }
  1458.  
  1459.   /**
  1460.    * Returns the contents of the output_hash variable.
  1461.    * @return array The contents of the internal output_hash variable.
  1462.    * @see setOutputHash
  1463.    */
  1464.   function getOutputHash()
  1465.     {
  1466.     return($this->output_hash);
  1467.     }
  1468.  
  1469.   /**
  1470.    * Clears the internal output hash array.
  1471.    * You are responsible to manage this yourself, the class only uses the variable!
  1472.    * @see setOutputHash
  1473.    * @see getOutputHash
  1474.    */
  1475.   function clearOutputHash()
  1476.     {
  1477.     $this->output_hash = array();
  1478.     }
  1479.  
  1480.   /**
  1481.    * Sends an error email.
  1482.    * If OCIDB_SENTMAILONERROR is defined and != 0 the class sent out an error report
  1483.    * to the configured email address in case of an error.
  1484.    * @param array $errarray The error array from Oracle as returned by getSQLError()
  1485.    * @see getSQLError
  1486.    */
  1487.   function SendMailOnError($errarray)
  1488.     {
  1489.     if(!defined('OCIDB_SENTMAILONERROR') || OCIDB_SENTMAILONERROR == 0)
  1490.       {
  1491.       return;
  1492.       }
  1493.     $server  = $_SERVER['SERVER_NAME']." (".$_SERVER['SERVER_ADDR'].")";
  1494.     if($server == '()' || $server == '')
  1495.       {
  1496.       $server = 'n/a';
  1497.       }
  1498.     $uagent  = (isset($_SERVER['HTTP_USER_AGENT'])) ? $_SERVER['HTTP_USER_AGENT'] : '';
  1499.     if($uagent == '')
  1500.       {
  1501.       $uagent = 'n/a';
  1502.       }
  1503.     $message = "OCI8 Class: Error occured on ".date('r')." !!!\n\n";
  1504.     $message.= "  AFFECTED SERVER: ".$server."\n";
  1505.     $message.= "       USER AGENT: ".$uagent."\n";
  1506.     $message.= "       PHP SCRIPT: ".$_SERVER['SCRIPT_FILENAME']."\n";
  1507.     $message.= "   REMOTE IP ADDR: ".$_SERVER['REMOTE_ADDR']." (".@gethostbyaddr($_SERVER['REMOTE_ADDR']).")\n";
  1508.     $message.= "    DATABASE DATA: ".$this->user." @ ".$this->host."\n";
  1509.     $message.= "SQL ERROR MESSAGE: ".preg_replace("/\n|\r/","",$errarray['message'])."\n";
  1510.     $message.= "   SQL ERROR CODE: ".$errarray['code']."\n";
  1511.     $message.= "    QUERY COUNTER: ".$this->querycounter."\n";
  1512.     $message.= "        SQL QUERY:\n";
  1513.     $message.= "------------------------------------------------------------------------------------\n";
  1514.     $message.= $errarray['sqltext']."\n";
  1515.     $message.= "------------------------------------------------------------------------------------\n";
  1516.     if($this->sqlerr != $errarray['sqltext'])
  1517.       {
  1518.       $message.= "     THIS->SQLERR: ".$this->sqlerr."\n";
  1519.       }
  1520.     if(count($this->errvars))
  1521.       {
  1522.       $errbuf = '';
  1523.       reset($this->errvars);
  1524.       $i = 0;
  1525.       while(list($key,$val) = each($this->errvars))
  1526.         {
  1527.         if(!is_numeric($key))
  1528.           {
  1529.           $errbuf.=sprintf("  P['%s'] => '%s'\n",($key),$val);
  1530.           }
  1531.         else
  1532.           {
  1533.           $errbuf.=sprintf("  P[%d] = '%s'\n",($i+1),$val);
  1534.           }
  1535.         $i++;
  1536.         }
  1537.       $errbuf = substr($errbuf,0,strlen($errbuf)-1);
  1538.       $message.= "    THIS->ERRVARS: ".$errbuf."\n";
  1539.       }
  1540.     if(defined('OCIDB_MAIL_EXTRAARGS') && OCIDB_MAIL_EXTRAARGS != '')
  1541.       {
  1542.       @mail($this->AdminEmail,'OCI8 Class v'.$this->classversion.' ERROR #'.$errarray['code'].' OCCURED!',$message,OCIDB_MAIL_EXTRAARGS);
  1543.       }
  1544.     else
  1545.       {
  1546.       @mail($this->AdminEmail,'OCI8 Class v'.$this->classversion.' ERROR #'.$errarray['code'].' OCCURED!',$message);
  1547.       }
  1548.     }
  1549.  
  1550.   /**
  1551.    * Returns microtime in format s.mmmmm.
  1552.    * Used to measure SQL execution time.
  1553.    * @return float the current time in microseconds.
  1554.    */
  1555.   function getmicrotime()
  1556.     {
  1557.     list($usec, $sec) = explode(" ",microtime());
  1558.     return (floatval($usec) + floatval($sec));
  1559.     }
  1560.  
  1561.   /**
  1562.    * Sets connection behavour.
  1563.    * If FALSE class uses oci_logon to connect.
  1564.    * If TRUE class uses oci_plogon to connect (Persistant connection)
  1565.    * @param boolean $conntype TRUE => Enable persistant connections, FALSE => Disable persistant connections
  1566.    * @return boolean The previous state
  1567.    * @since 0.73
  1568.    */
  1569.   function setPConnect($conntype)
  1570.    {
  1571.    if(is_bool($conntype)==FALSE)
  1572.      {
  1573.      return($this->usePConnect);
  1574.      }
  1575.    $oldtype = $this->usePConnect;
  1576.    $this->usePConnect = $conntype;
  1577.    return($oldtype);
  1578.    }
  1579.  
  1580.   /**
  1581.    * Executes a prepare()d statement and returns the result.
  1582.    * You may then fetch rows with FetchResult() or call FreeResult() to free your allocated result.
  1583.    * This method is almost identical to "Execute()", however the bind variables used are passed as an associative array
  1584.    * instead of "guessing" them from query and given parameter. This is now the prefered way to use bind variables!
  1585.    * @param mixed $stmt The statement handle to be executed.
  1586.    * @param array &$bindvarhash The bind variables as associative array (key = bindvar name, value = bindvar value).
  1587.    * @return mixed Returns result set read for FetchResult() usage or an error state depending on class setting in case of an error.
  1588.    * @since 0.77
  1589.    * @see Prepare
  1590.    */
  1591.   function ExecuteHash($stmt,&$bindvarhash)
  1592.     {
  1593.     $f = $this->SearchQueryCache($stmt);
  1594.     if($f == -1)
  1595.       {
  1596.       return($this->Print_Error("Cannot find query for given statement #".$stmt." inside query cache!!!"));
  1597.       }
  1598.     $this->sqlerr  = $this->sqlcache[$f][DBOF_CACHE_QUERY];
  1599.     $this->errvars = array();
  1600.     if(is_array($bindvarhash))
  1601.       {
  1602.       reset($bindvarhash);
  1603.       $this->errvars = $bindvarhash;
  1604.       while(list($key,$val) = each($bindvarhash))
  1605.         {
  1606.         @OCIBindByName($stmt,$key,$bindvarhash[$key],-1);
  1607.         }
  1608.       }
  1609.     $start = $this->getmicrotime();
  1610.     if($this->debug)
  1611.       {
  1612.       $this->PrintDebug($this->sqlerr);
  1613.       }
  1614.     if(!@OCIExecute($stmt,OCI_DEFAULT))
  1615.       {
  1616.       if($this->no_exit)
  1617.         {
  1618.         $err = @OCIError($stmt);
  1619.         $this->sqlerrmsg = $err['message'];
  1620.         return($err['code']);
  1621.         }
  1622.       else
  1623.         {
  1624.         $this->stmt = $stmt;
  1625.         return($this->Print_Error('ExecuteHash(): Execute failed!'));
  1626.         }
  1627.       }
  1628.     $this->querycounter++;
  1629.     $this->querytime+= ($this->getmicrotime() - $start);
  1630.     return($stmt);
  1631.     }
  1632.  
  1633.   /**
  1634.    * Returns the number of retries in case of connection problems.
  1635.    * This value can be set globally inside the dbdefs.inc.php file
  1636.    * via the OCIDB_CONNECT_RETRIES define but may be changed run-time
  1637.    * also via the "setConnectRetries()" method.
  1638.    * @return integer The retry counter value currently set.
  1639.    * @since V0.78
  1640.    */
  1641.   function getConnectRetries()
  1642.     {
  1643.     return($this->connectRetries);
  1644.     }
  1645.  
  1646.   /**
  1647.    * Change the number of retries the class performs in case of connection problems.
  1648.    * This value is globally setable in the dbdefs.inc.php script (see define OCIDB_CONNECT_RETRIES)
  1649.    * but can be set also run-time via this method.
  1650.    * @param integer $retcnt The new number of connect retries.
  1651.    * @return integer The previous value
  1652.    * @since V0.78
  1653.    */
  1654.   function setConnectRetries($retcnt)
  1655.     {
  1656.     $oldval = $this->getConnectRetries();
  1657.     $this->connectRetries = intval($retcnt);
  1658.     return($oldval);
  1659.     }
  1660.  
  1661.   } // EOF
  1662. ?>

Documentation generated on Tue, 22 Sep 2009 22:17:38 +0200 by phpDocumentor 1.4.2