From 739c68b9a41584499e191af3245f36f0c1e884bf Mon Sep 17 00:00:00 2001
From: Jeroen van Wolffelaar <jeroen@php.net>
Date: Wed, 16 May 2001 15:25:31 +0000
Subject: [PATCH] - Fixed types - Removed outdated para - Added some return
 description, and comments where still undocumented

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@47586 c90b9560-bf6c-de11-be94-00142212c4b1
---
 functions/mysql.xml | 170 ++++++++++++++++++--------------------------
 1 file changed, 70 insertions(+), 100 deletions(-)

diff --git a/functions/mysql.xml b/functions/mysql.xml
index a85bcecfcc..12d2c4d5cd 100644
--- a/functions/mysql.xml
+++ b/functions/mysql.xml
@@ -38,7 +38,7 @@
     <funcsynopsis>
      <funcprototype>
       <funcdef>int <function>mysql_affected_rows</function></funcdef>
-      <paramdef>int 
+      <paramdef>resource 
        <parameter>
         <optional>link_identifier</optional>
        </parameter>
@@ -107,7 +107,7 @@
         <optional>database</optional>
        </parameter>
       </paramdef>
-      <paramdef>int 
+      <paramdef>resource 
        <parameter>
         <optional>link_identifier</optional>
        </parameter>
@@ -121,6 +121,9 @@
      specified, this will default or current database after the user
      has been changed.  If the new user and password authorization fails, 
      the current connected user stays active.</para>
+     
+     <!-- what is returned? bool -> succes/failure i suppose? -->
+     
      <note><para>This function was introduced in PHP 3.0.13 and
      requires MySQL 3.23.3 or higher.
     </para></note>
@@ -136,8 +139,8 @@
     <title>Description</title>
     <funcsynopsis>
      <funcprototype>
-      <funcdef>int <function>mysql_close</function></funcdef>
-      <paramdef>int 
+      <funcdef>bool <function>mysql_close</function></funcdef>
+      <paramdef>resource 
        <parameter>
         <optional>link_identifier</optional>                   
        </parameter>
@@ -155,7 +158,9 @@
     <para>
      Using <function>mysql_close</function> isn't usually necessary,
      as non-persistent open links are automatically closed at the end
-     of the script's execution.
+     of the script's execution. See also 
+     <link linkend="language.types.resource.self-destruct">freeing 
+     resources</link>.
     </para>
     <note>
      <para> 
@@ -190,7 +195,7 @@
     <title>Description</title>
     <funcsynopsis>
      <funcprototype>
-      <funcdef>int <function>mysql_connect</function></funcdef>
+      <funcdef>resource <function>mysql_connect</function></funcdef>
       <paramdef>string 
        <parameter>
         <optional>hostname
@@ -212,8 +217,7 @@
      </funcprototype>
     </funcsynopsis>
     <para> 
-     Returns a positive MySQL link identifier on success, or an error
-     message on failure.
+     Returns a MySQL link identifier on success, or FALSE on failure.
     </para>
     <para>
      <function>mysql_connect</function> establishes a connection
@@ -283,7 +287,7 @@
      <funcprototype>
       <funcdef>int <function>mysql_create_db</function></funcdef>
       <paramdef>string <parameter>database name</parameter></paramdef>
-      <paramdef>int 
+      <paramdef>resource 
        <parameter>
         <optional>link_identifier</optional>
        </parameter>
@@ -295,6 +299,7 @@
      database on the server associated with the specified link
      identifier.
     </para>
+    <!-- returns?? bool -> succes? -->
     <example>
      <title>MySQL create database example</title>
      <programlisting role="php">
@@ -328,8 +333,8 @@
     <title>Description</title>
     <funcsynopsis>
      <funcprototype>
-      <funcdef>int <function>mysql_data_seek</function></funcdef>
-      <paramdef>int <parameter>result_identifier</parameter></paramdef>
+      <funcdef>bool <function>mysql_data_seek</function></funcdef>
+      <paramdef>resource <parameter>result_identifier</parameter></paramdef>
       <paramdef>int <parameter>row_number</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
@@ -364,14 +369,14 @@
 
     for ($i = mysql_num_rows ($result) - 1; $i >=0; $i--) {
         if (!mysql_data_seek ($result, $i)) {
-            printf ("Cannot seek to row %d\n", $i);
+            echo "Cannot seek to row $i\n";
             continue;
         }
 
         if(!($row = mysql_fetch_object ($result)))
             continue;
 
-        printf ("%s %s&lt;BR>\n", $row->last_name, $row->first_name);
+        echo ("$row-&gt;last_name $row-&gt;first_name&lt;BR&gt;\n";
     }
 
     mysql_free_result ($result);
@@ -390,8 +395,8 @@
     <title>Description</title>
     <funcsynopsis>
      <funcprototype>
-      <funcdef>int <function>mysql_db_name</function></funcdef>
-      <paramdef>int <parameter>result</parameter></paramdef>
+      <funcdef>string <function>mysql_db_name</function></funcdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
       <paramdef>int <parameter>row</parameter></paramdef>
       <paramdef>mixed 
        <parameter>
@@ -451,10 +456,10 @@ while ($i &lt; $cnt) {
     <title>Description</title>
     <funcsynopsis>
      <funcprototype>
-      <funcdef>int <function>mysql_db_query</function></funcdef>
+      <funcdef>resource <function>mysql_db_query</function></funcdef>
       <paramdef>string <parameter>database</parameter></paramdef>
       <paramdef>string <parameter>query</parameter></paramdef>
-      <paramdef>int 
+      <paramdef>resource 
        <parameter>
         <optional>link_identifier</optional>
        </parameter>
@@ -462,7 +467,7 @@ while ($i &lt; $cnt) {
      </funcprototype>
     </funcsynopsis>
     <para> 
-     Returns: A positive MySQL result identifier to the query result,
+     Returns: A positive MySQL result resource to the query result,
      or false on error.
     </para>
     <para> 
@@ -474,8 +479,7 @@ while ($i &lt; $cnt) {
      arguments
     </para>
     <para> 
-     See also <function>mysql_connect</function> and
-     <function>mysql_query</function>.
+     See also <function>mysql_connect</function>.
     </para>
     <para>
      For downwards
@@ -493,9 +497,9 @@ while ($i &lt; $cnt) {
     <title>Description</title>
     <funcsynopsis>
      <funcprototype>
-      <funcdef>int <function>mysql_drop_db</function></funcdef>
+      <funcdef>bool <function>mysql_drop_db</function></funcdef>
       <paramdef>string <parameter>database_name</parameter></paramdef>
-      <paramdef>int 
+      <paramdef>resource 
        <parameter>
         <optional>link_identifier</optional>
        </parameter>
@@ -528,7 +532,7 @@ while ($i &lt; $cnt) {
     <funcsynopsis>
      <funcprototype>
       <funcdef>int <function>mysql_errno</function></funcdef>
-      <paramdef>int 
+      <paramdef>resource 
        <parameter>
         <optional>link_identifier</optional>
        </parameter>
@@ -578,7 +582,7 @@ echo mysql_errno().": ".mysql_error()."&lt;BR>";
     <funcsynopsis>
      <funcprototype>
       <funcdef>string <function>mysql_error</function></funcdef>
-      <paramdef>int 
+      <paramdef>resource 
        <parameter>
         <optional>link_identifier</optional>
        </parameter>
@@ -628,7 +632,7 @@ echo mysql_errno().": ".mysql_error()."&lt;BR>";
     <funcsynopsis>
      <funcprototype>
       <funcdef>array <function>mysql_fetch_array</function></funcdef>
-      <paramdef>int <parameter>result</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
       <paramdef>int
        <parameter>
         <optional>result_type</optional>
@@ -703,7 +707,7 @@ mysql_free_result ($result);
     <funcsynopsis>
      <funcprototype>
       <funcdef>array <function>mysql_fetch_assoc</function></funcdef>
-      <paramdef>int <parameter>result</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para> 
@@ -762,7 +766,7 @@ mysql_free_result ($result);
     <funcsynopsis>
      <funcprototype>
       <funcdef>object <function>mysql_fetch_field</function></funcdef>
-      <paramdef>int <parameter>result</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
       <paramdef>int 
        <parameter>
         <optional>field_offset</optional>
@@ -898,7 +902,7 @@ mysql_free_result ($result);
     <funcsynopsis>
      <funcprototype>
       <funcdef>array <function>mysql_fetch_lengths</function></funcdef>
-      <paramdef>int <parameter>result</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para> 
@@ -930,7 +934,7 @@ mysql_free_result ($result);
     <funcsynopsis>
      <funcprototype>
       <funcdef>object <function>mysql_fetch_object</function></funcdef>
-      <paramdef>int <parameter>result</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
       <paramdef>int
        <parameter>
         <optional>result_type</optional>
@@ -991,7 +995,7 @@ mysql_free_result ($result);
     <funcsynopsis>
      <funcprototype>
       <funcdef>array <function>mysql_fetch_row</function></funcdef>
-      <paramdef>int <parameter>result</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para> 
@@ -1031,7 +1035,7 @@ mysql_free_result ($result);
     <funcsynopsis>
      <funcprototype>
       <funcdef>string <function>mysql_field_flags</function></funcdef>
-      <paramdef>int <parameter>result</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
       <paramdef>int <parameter>field_offset</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
@@ -1065,7 +1069,7 @@ mysql_free_result ($result);
     <funcsynopsis>
      <funcprototype>
       <funcdef>string <function>mysql_field_name</function></funcdef>
-      <paramdef>int <parameter>result</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
       <paramdef>int <parameter>field_index</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
@@ -1128,7 +1132,7 @@ password
     <funcsynopsis>
      <funcprototype>
       <funcdef>int <function>mysql_field_len</function></funcdef>
-      <paramdef>int <parameter>result</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
       <paramdef>int <parameter>field_offset</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
@@ -1155,7 +1159,7 @@ password
     <funcsynopsis>
      <funcprototype>
       <funcdef>int <function>mysql_field_seek</function></funcdef>
-      <paramdef>int <parameter>result</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
       <paramdef>int <parameter>field_offset</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
@@ -1183,7 +1187,7 @@ password
     <funcsynopsis>
      <funcprototype>
       <funcdef>string <function>mysql_field_table</function></funcdef>
-      <paramdef>int <parameter>result</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
       <paramdef>int <parameter>field_offset</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
@@ -1210,7 +1214,7 @@ password
     <funcsynopsis>
      <funcprototype>
       <funcdef>string <function>mysql_field_type</function></funcdef>
-      <paramdef>int <parameter>result</parameter></paramdef>
+      <paramdef>iresource <parameter>result</parameter></paramdef>
       <paramdef>int <parameter>field_offset</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
@@ -1266,7 +1270,7 @@ mysql_close();
     <funcsynopsis>
      <funcprototype>
       <funcdef>int <function>mysql_free_result</function></funcdef>
-      <paramdef>int <parameter>result</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
@@ -1278,7 +1282,9 @@ mysql_close();
      you are concerned about how much memory is being used for queries
      that return large result sets.  All associated result memory is
      automatically freed at the end of the script's execution.
+     <!-- TODO and as of PHP4 before, see freeing resources -->
     </para>
+    <!-- returns?? -->
     <para>
      For downward compatibility <function>mysql_freeresult</function>
      can also be used.
@@ -1298,7 +1304,7 @@ mysql_close();
     <funcsynopsis>
      <funcprototype>
       <funcdef>int <function>mysql_insert_id</function></funcdef>
-      <paramdef>int 
+      <paramdef>resource 
        <parameter>
         <optional>link_identifier</optional>
        </parameter>
@@ -1352,8 +1358,8 @@ mysql_close();
     <title>Description</title>
     <funcsynopsis>
      <funcprototype>
-      <funcdef>int <function>mysql_list_dbs</function></funcdef>
-      <paramdef>int 
+      <funcdef>resource <function>mysql_list_dbs</function></funcdef>
+      <paramdef>resource 
        <parameter>
         <optional>link_identifier</optional>
        </parameter>
@@ -1400,6 +1406,7 @@ database3
      For downward compatibility <function>mysql_listdbs</function> can
      also be used.
     </para>
+    <para>See also <function>mysql_db_name</function></para>
    </refsect1>
   </refentry>
 
@@ -1412,10 +1419,10 @@ database3
     <title>Description</title>
     <funcsynopsis>
      <funcprototype>
-      <funcdef>int <function>mysql_list_fields</function></funcdef>
+      <funcdef>resource <function>mysql_list_fields</function></funcdef>
       <paramdef>string <parameter>database_name</parameter></paramdef>
       <paramdef>string <parameter>table_name</parameter></paramdef>
-      <paramdef>int 
+      <paramdef>resource 
        <parameter>
         <optional>link_identifier</optional>
        </parameter>
@@ -1431,13 +1438,15 @@ database3
      <function>mysql_field_name</function>, and
      <function>mysql_field_type</function>.
     </para>
+    <!-- 
+      this is very outdated, and now incorrect 
     <para>
-     A result identifier is a positive integer. The function returns
+      A result identifier is a positive integer. The function returns
      -1 if a error occurs. A string describing the error will be
      placed in <literal>$phperrmsg</literal>, and unless the function
      was called as <literal>@mysql()</literal> then this error string
      will also be printed out.
-    </para>
+    </para> -->
     <para>
      <example>
       <title><function>mysql_list_fields</function> example</title>
@@ -1468,6 +1477,10 @@ field3
      For downward compatibility <function>mysql_listfields</function>
      can also be used.
     </para>
+    <!-- TODO: this is equiv. with 'select * from $table where FALSE,'
+         which implies you can better use the field-research functions
+         on a real query, that saves you one mysql-query. 
+         -->
    </refsect1>
   </refentry>
 
@@ -1480,9 +1493,9 @@ field3
     <title>Description</title>
     <funcsynopsis>
      <funcprototype>
-      <funcdef>int <function>mysql_list_tables</function></funcdef>
+      <funcdef>resource <function>mysql_list_tables</function></funcdef>
       <paramdef>string <parameter>database</parameter></paramdef>
-      <paramdef>int 
+      <paramdef>resource 
        <parameter>
         <optional>link_identifier</optional>
        </parameter>
@@ -1513,7 +1526,7 @@ field3
     <funcsynopsis>
      <funcprototype>
       <funcdef>int <function>mysql_num_fields</function></funcdef>
-      <paramdef>int <parameter>result</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para> 
@@ -1543,7 +1556,7 @@ field3
     <funcsynopsis>
      <funcprototype>
       <funcdef>int <function>mysql_num_rows</function></funcdef>
-      <paramdef>int <parameter>result</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
@@ -1593,7 +1606,7 @@ echo "$num_rows Rows\n";
     <title>Description</title>
     <funcsynopsis>
      <funcprototype>
-      <funcdef>int <function>mysql_pconnect</function></funcdef>
+      <funcdef>resource <function>mysql_pconnect</function></funcdef>
       <paramdef>string 
        <parameter>
         <optional>hostname
@@ -1636,6 +1649,8 @@ echo "$num_rows Rows\n";
       </para>
      </note>
     </para>     
+    
+    <!-- TODO move the story to features.persistent, and refer to that -->
     <para>
      <function>mysql_pconnect</function> acts very much like
      <function>mysql_connect</function> with two major differences.
@@ -1667,9 +1682,9 @@ echo "$num_rows Rows\n";
     <title>Description</title>
     <funcsynopsis>
      <funcprototype>
-      <funcdef>int <function>mysql_query</function></funcdef>
+      <funcdef>resource <function>mysql_query</function></funcdef>
       <paramdef>string <parameter>query</parameter></paramdef>
-      <paramdef>int 
+      <paramdef>resource 
        <parameter><optional>link_identifier</optional></parameter>
       </paramdef>
      </funcprototype>
@@ -1749,7 +1764,6 @@ $result = mysql_query ("SELECT my_col FROM my_tbl")
     <para>
      See also: <function>mysql_affected_rows</function>,
      <function>mysql_db_query</function>,
-     <function>mysql_unbuffered_query</function>,
      <function>mysql_free_result</function>,
      <function>mysql_result</function>,
      <function>mysql_select_db</function>, and
@@ -1758,50 +1772,6 @@ $result = mysql_query ("SELECT my_col FROM my_tbl")
    </refsect1>
   </refentry>
 
-  <refentry id="function.mysql-unbuffered-query">
-   <refnamediv>
-    <refname>mysql_unbuffered_query</refname>
-    <refpurpose>Send an SQL query to MySQL, without fetching and buffering the result rows</refpurpose>
-   </refnamediv>
-   <refsect1>
-    <title>Description</title>
-    <funcsynopsis>
-     <funcprototype>
-      <funcdef>int <function>mysql_unbuffered_query</function></funcdef>
-      <paramdef>string <parameter>query</parameter></paramdef>
-      <paramdef>int 
-       <parameter><optional>link_identifier</optional></parameter>
-      </paramdef>
-      <paramdef>int 
-       <parameter><optional>result_mode</optional></parameter>
-      </paramdef>
-     </funcprototype>
-    </funcsynopsis>
-    <para> 
-     <function>mysql_unbuffered_query</function> sends a SQL query to MySQL, 
-     without fetching and buffering the result rows automatically, as 
-     <function>mysql_query</function> does.
-     On the one hand, this saves a considerable amount of memory with SQL 
-     queries that produce large result sets. On the other hand, you can start 
-     working on the result set immediately after the first row has been 
-     retrieved: you don't have to wait until the complete SQL query has been 
-     performed.
-    </para>
-    <note>
-     <para>
-      The benefits of <function>mysql_unbuffered_query</function> come at a 
-      cost: You cannot use <function>mysql_num_rows</function> on a result set 
-      returned from <function>mysql_unbuffered_query</function>. You also have 
-      to fetch all result rows from an unbuffered SQL query, before you can 
-      send a new SQL query to MySQL.
-     </para>
-    </note>
-    <para>
-     See also: <function>mysql_query</function>.
-    </para>
-   </refsect1>
-  </refentry>
-
   <refentry id="function.mysql-result">
    <refnamediv>
     <refname>mysql_result</refname>
@@ -1812,7 +1782,7 @@ $result = mysql_query ("SELECT my_col FROM my_tbl")
     <funcsynopsis>
      <funcprototype>
       <funcdef>mixed <function>mysql_result</function></funcdef>
-      <paramdef>int <parameter>result</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
       <paramdef>int <parameter>row</parameter></paramdef>
       <paramdef>mixed 
        <parameter>
@@ -1860,9 +1830,9 @@ $result = mysql_query ("SELECT my_col FROM my_tbl")
     <title>Description</title>
     <funcsynopsis>
      <funcprototype>
-      <funcdef>int <function>mysql_select_db</function></funcdef>
+      <funcdef>bool <function>mysql_select_db</function></funcdef>
       <paramdef>string <parameter>database_name</parameter></paramdef>
-      <paramdef>int 
+      <paramdef>resource 
        <parameter>
         <optional>link_identifier</optional>
        </parameter>
@@ -1906,7 +1876,7 @@ $result = mysql_query ("SELECT my_col FROM my_tbl")
     <funcsynopsis>
      <funcprototype>
       <funcdef>string <function>mysql_tablename</function></funcdef>
-      <paramdef>int <parameter>result</parameter></paramdef>
+      <paramdef>resource <parameter>result</parameter></paramdef>
       <paramdef>int <parameter>i</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>