[Phpgroupware-cvs] phpgwapi/inc/class.db_mysql.inc.php, 1.30.2.3.2.11

[nomail]

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

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

Log Message:
phpdoc update
=====================================================================
Index: phpgwapi/inc/class.db_mysql.inc.php
diff -u phpgwapi/inc/class.db_mysql.inc.php:1.30.2.3.2.10 
phpgwapi/inc/class.db_mysql.inc.php:1.30.2.3.2.11
--- phpgwapi/inc/class.db_mysql.inc.php:1.30.2.3.2.10   Tue Feb 10 13:51:18 2004
+++ phpgwapi/inc/class.db_mysql.inc.php Mon Jun 28 07:08:09 2004
@@ -20,16 +20,37 @@
        */
        class db extends db_
        {
-               /* public: this is an api revision, not a CVS revision. */
+        /**
+         * @var string $type Connection type
+         */
                var $type     = 'mysql';
+               /**
+               * API revision
+               *
+               * @internal This is an api revision, not a CVS revision
+               * @access public
+               */
                var $revision = '1.2';
 
+               /**
+               * Constructor
+               *
+               * @param $query SQL query
+               */
                function db($query = '')
                {
                        $this->db_($query);
                }
 
-               /* public: connection management */
+               /**
+                * 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 */
@@ -77,7 +98,12 @@
                        return $this->Link_ID;
                }
 
-               /* This only affects systems not using persistant connections */
+               /**
+               * Disconnect from database
+               *
+               * @return integer 1: successful; 0: already disconnected
+               * @internal This only affects systems not using persistant 
connections
+               */
                function disconnect()
                {
                        if($this->Link_ID <> 0)
@@ -92,11 +118,23 @@
                        }
                }
 
+        /**
+         * Convert a unix timestamp to a rdms specific timestamp
+         *
+         * @param int unix timestamp
+         * @return string rdms specific timestamp
+         */
                function to_timestamp($epoch)
                {
                        return date('Y-m-d H:i:s',$epoch);
                }
 
+        /**
+         * Convert a rdms specific timestamp to a unix timestamp
+         *
+         * @param string rdms specific timestamp
+         * @return int unix timestamp
+         */
                function from_timestamp($timestamp)
                {
                        ereg('([0-9]{4})-([0-9]{2})-([0-9]{2}) 
([0-9]{2}):([0-9]{2}):([0-9]{2})',$timestamp,$parts);
@@ -104,15 +142,23 @@
                        return 
mktime($parts[4],$parts[5],$parts[6],$parts[2],$parts[3],$parts[1]);
                }
 
-               /* public: discard the query result */
+        /**
+         * Discard the current query result
+         */
                function free()
                {
                        @mysql_free_result($this->Query_ID);
                        $this->Query_ID = 0;
                }
 
-               /* public: perform a query */
-               /* I added the line and file section so we can have better 
error reporting. (jengo) */
+        /**
+         * 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
+         */
                function query($Query_String, $line = '', $file = '')
                {
                        /* No empty queries, please, since PHP4 chokes on them. 
*/
@@ -155,7 +201,16 @@
                        return $this->Query_ID;
                }
 
-               // public: perform a query with limited result set
+        /**
+         * Execute a query with limited result set
+         *
+         * @param string $Query_String the query to be executed
+         * @param integer $offset row to start from
+         * @param mixed $line the line method was called from - use __LINE__
+         * @param string $file the file method was called from - use __FILE__
+         * @param int $num_rows number of rows to return (optional), if unset 
will use $GLOBALS['phpgw_info']['user']['preferences']['common']['maxmatchs']
+         * @return integer Current result if sucesful and null if failed
+         */
                function limit_query($Query_String, $offset, $line = '', $file 
= '', $num_rows = 0)
                {
                        $offset         = intval($offset);
@@ -184,7 +239,11 @@
                        return $this->query($Query_String, $line, $file);
                }
 
-               /* public: walk result set */
+        /**
+         * Move to the next row in the results set
+         *
+         * @return boolean was another row found?
+         */
                function next_record()
                {
                        if (!$this->Query_ID)
@@ -206,7 +265,12 @@
                        return $stat;
                }
 
-               /* public: position in result set */
+        /**
+         * 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
+         */
                function seek($pos = 0)
                {
                        $status = @mysql_data_seek($this->Query_ID, $pos);
@@ -228,6 +292,13 @@
                        return 1;
                }
 
+        /**
+         * Find the primary key of the last insertion on the current db 
connection
+         *
+         * @param string $table name of table the insert was performed on
+         * @param string $field the autoincrement primary key of the table
+         * @return integer The id, -1 if failed
+         */
                function get_last_insert_id($table, $field)
                {
                        /* This will get the last insert ID created on the 
current connection.  Should only be called
@@ -244,7 +315,13 @@
                        return @mysql_insert_id($this->Link_ID);
                }
 
-               /* public: table locking */
+        /**
+         * 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')
                {
                        $this->connect();
@@ -278,6 +355,11 @@
                        return $res;
                }
 
+        /**
+         * Unlock a table
+         *
+         * @return boolean True if sucessful, False if failed
+         */
                function unlock()
                {
                        $this->connect();
@@ -292,23 +374,42 @@
                }
 
 
-               /* public: evaluate the result (size, width) */
+        /**
+         * Get the number of rows affected by last update
+         *
+         * @return integer number of affected rows
+         */
                function affected_rows()
                {
                        return @mysql_affected_rows($this->Link_ID);
                }
 
+        /**
+         * Number of rows in current result set
+         *
+         * @return integer number of rows
+         */
                function num_rows()
                {
                        return @mysql_num_rows($this->Query_ID);
                }
 
+        /**
+         * Number of fields in current row
+         *
+         * @return integer number of fields
+         */
                function num_fields()
                {
                        return @mysql_num_fields($this->Query_ID);
                }
 
-               /* public: sequence numbers */
+        /**
+         * 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();
@@ -352,7 +453,13 @@
                        return $nextid;
                }
 
-               /* public: return table metadata */
+        /**
+         * 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;
@@ -417,7 +524,13 @@
                        return $res;
                }
 
-               /* 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)
+         */
                function halt($msg, $line = '', $file = '')
                {
                        $this->Error = @mysql_error($this->Link_ID);    // need 
to be BEFORE unlock,
@@ -449,6 +562,11 @@
                        }
                }
 
+        /** 
+         * Display database error
+         *
+         * @param string $msg Error message
+         */
                function haltmsg($msg)
                {
                        printf("<b>Database error:</b> %s<br>\n", $msg);
@@ -458,6 +576,11 @@
                        }
                }
 
+        /**
+         * Get a list of table names in the current database
+         *
+         * @return array List of the tables
+         */
                function table_names()
                {
                        if (!$this->Link_ID)
@@ -481,6 +604,12 @@
                        return $return;
                }
 
+        /**
+         * Create a new database
+         *
+         * @param string $adminname Name of database administrator user 
(optional)
+         * @param string $adminpasswd Password for the database administrator 
user (optional)
+         */
                function create_database($adminname = '', $adminpasswd = '')
                {
                        $currentUser = $this->User;