[Phpgroupware-cvs] phpgwapi/inc/class.db_oracle.inc.php, 1.6.2.1.2.4

[nomail]

Update of /phpgwapi/inc
Modified Files:
        Branch: Version-0_9_16-branch
          class.db_oracle.inc.php

date: 2004/06/28 07:08:09;  author: powerstat;  state: Exp;  lines: +125 -29

Log Message:
phpdoc update
=====================================================================
Index: phpgwapi/inc/class.db_oracle.inc.php
diff -u phpgwapi/inc/class.db_oracle.inc.php:1.6.2.1.2.3 
phpgwapi/inc/class.db_oracle.inc.php:1.6.2.1.2.4
--- phpgwapi/inc/class.db_oracle.inc.php:1.6.2.1.2.3    Tue Feb 10 13:51:18 2004
+++ phpgwapi/inc/class.db_oracle.inc.php        Mon Jun 28 07:08:09 2004
@@ -16,6 +16,7 @@
        * 
        * @package phpgwapi
        * @subpackage database
+       * @ignore
        */
        class db
        {
@@ -23,17 +24,34 @@
 
                var $ora_no_next_fetch = False;
 
-               /* copied from db_mysql for completeness */
-               /* public: identification constant. never change this. */
+        /**
+         * @var string $type Connection type
+         */
                var $type     = 'oracle';
+               /**
+                * @var string $revision Api revision 
+                */
                var $revision = '1.2';
 
-               /* public: constructor */
+               /**
+               * Constructor
+               *
+               * @param $query SQL query
+               */
                function db($query = '')
                {
                        $this->db_($query);
                }
 
+               /**
+                * Connect to database
+                * 
+                * @param string $Database Database name
+                * @param string $Host Database host
+                * @param string $User Database user
+                * @param string $Password Database users password
+                * @return resource Database connection_id
+                */
                function connect($Database = '', $Host = '', $User = '', 
$Password = '')
                {
                        /* Handle defaults */
@@ -120,16 +138,22 @@
                        }
                }
 
-               ## In order to increase the # of cursors per system/user go 
edit the
-               ## init.ora file and increase the max_open_cursors parameter. 
Yours is on
-               ## the default value, 100 per user.
-               ## We tried to change the behaviour of query() in a way, that 
it tries
-               ## to safe cursors, but on the other side be carefull with 
this, that you
-               ## don't use an old result.
-               ## 
-               ## You can also make extensive use of ->disconnect()!
-               ## The unused QueryIDs will be recycled sometimes. 
-
+        /**
+        * Execute a query
+        *
+        * @param string $Query_String the query to be executed
+        * @param mixed $line the line method was called from - use __LINE__
+        * @param string $file the file method was called from - use __FILE__
+        * @return integer Current result if sucesful and null if failed
+               * @internal In order to increase the # of cursors per 
system/user go edit the
+               * @internal init.ora file and increase the max_open_cursors 
parameter. Yours is on
+               * @internal the default value, 100 per user.
+               * @internal We tried to change the behaviour of query() in a 
way, that it tries
+               * @internal to safe cursors, but on the other side be carefull 
with this, that you
+               * @internal don't use an old result.
+               * @internal You can also make extensive use of ->disconnect()!
+               * @internal The unused QueryIDs will be recycled sometimes.
+        */
                function query($Query_String)
                {
                        /* No empty queries, please, since PHP4 chokes on them. 
*/
@@ -177,6 +201,11 @@
                        return $this->Query_ID;
                }
 
+        /**
+         * Move to the next row in the results set
+         *
+         * @return boolean was another row found?
+         */
                function next_record()
                {
                        if (!$this->no_next_fetch && 
@@ -225,9 +254,15 @@
                        return $stat;
                }
 
-               ## seek() works only for $pos - 1 and $pos
-               ## Perhaps I make a own implementation, but my
-               ## opinion is, that this should be done by PHP3
+               /**
+        * Move to position in result set
+        *
+        * @param integer $pos Required row (optional), default first row
+        * @return integer 1 if sucessful or 0 if not found
+               * @internal seek() works only for $pos - 1 and $pos
+               * @internal Perhaps I make a own implementation, but my
+               * @internal opinion is, that this should be done by PHP3
+        */
                function seek($pos)
                {
                        if($this->Row - 1 == $pos)
@@ -250,6 +285,13 @@
                        $this->Row=$pos;
                }
 
+        /**
+         * Lock a table
+         *
+         * @param string $table name of table to lock
+         * @param string $mode type of lock required (optional), default write
+         * @return boolean True if sucessful, False if failed
+         */
                function lock($table, $mode = 'write')
                {
                        if ($mode == 'write')
@@ -263,11 +305,23 @@
                        return $result;
                }
 
+        /**
+         * Unlock a table
+         *
+         * @return boolean True if sucessful, False if failed
+         */
                function unlock()
                {
                        return ora_do($this->Link_ID, 'commit');
                }
 
+        /**
+         * Get description of a table
+         *
+         * @param string $table name of table to describe
+         * @param boolean $full optional, default False summary information, 
True full information
+         * @return array Table meta data
+         */
                function metadata($table,$full=false)
                {
                        $count = 0;
@@ -362,7 +416,12 @@
                        return $res;
                }
 
-               ## THIS FUNCTION IS UNSTESTED!
+        /**
+        * Get the number of rows affected by last update
+        *
+        * @return integer number of affected rows
+               * @internal THIS FUNCTION IS UNSTESTED!
+        */
                function affected_rows()
                {
                        if ($Debug)
@@ -372,15 +431,19 @@
                        return ora_numrows($this->Query_ID);
                }
 
-               ## Known bugs: It will not work for SELECT DISTINCT and any
-               ## other constructs which are depending on the resulting rows.
-               ## So you *really need* to check every query you make, if it
-               ## will work with it.
-               ##
-               ## Also, for a qualified replacement you need to parse the
-               ## selection, cause this will fail: 'SELECT id, from FROM ...').
-               ## 'FROM' is - as far as I know a keyword in Oracle, so it can
-               ## only be used in this way. But you have been warned.
+        /**
+        * Number of rows in current result set
+        *
+        * @return integer number of rows
+               * @internal Known bugs: It will not work for SELECT DISTINCT 
and any
+               * @internal other constructs which are depending on the 
resulting rows.
+               * @internal So you *really need* to check every query you make, 
if it
+               * @internal will work with it.
+               * @internal Also, for a qualified replacement you need to parse 
the
+               * @internal selection, cause this will fail: 'SELECT id, from 
FROM ...').
+               * @internal 'FROM' is - as far as I know a keyword in Oracle, 
so it can
+               * @internal only be used in this way. But you have been warned.
+        */
                function num_rows()
                {
                        $curs=ora_open($this->Link_ID);
@@ -406,6 +469,11 @@
                        }
                }
 
+        /**
+         * Number of fields in current row
+         *
+         * @return integer number of fields
+         */
                function num_fields()
                {
                        if ($Debug)
@@ -415,7 +483,12 @@
                        return ora_numcols($this->Query_ID);
                }
 
-               /* public: sequence number */
+        /**
+         * Get the id for the next sequence
+         *
+         * @param string $seq_name Name of the sequence
+         * @return integer sequence id
+         */
                function nextid($seq_name)
                {
                        $this->connect();
@@ -453,6 +526,12 @@
                        return $next_id;
                }
 
+               /**
+                * Disconnect database connection
+                *
+                * This only affects systems not using persistant connections 
+                * @return integer 1: ok; 0: not possible/already closed
+                */
                function disconnect()
                {
                        if($this->Debug)
@@ -468,7 +547,14 @@
                        $this->Query_ID=0;
                }
 
-               /* private: error handling */
+        /**
+        * Error handler
+        *
+        * @param string $msg error message
+        * @param integer $line line of calling method/function (optional)
+        * @param string $file file of calling method/function (optional)
+               * @access private
+        */
                function halt($msg)
                {
                        if ($this->Halt_On_Error == 'no')
@@ -484,6 +570,11 @@
                        }
                }
 
+        /** 
+         * Display database error
+         *
+         * @param string $msg Error message
+         */
                function haltmsg($msg)
                {
                        printf("<b>Database error:</b> %s<br>\n", $msg);
@@ -492,6 +583,11 @@
                        $this->Error);
                }
 
+        /**
+         * Get a list of table names in the current database
+         *
+         * @return array List of the tables
+         */
                function table_names()
                {
                        $this->connect();