From 7cc925a924dc27087fdc575e771cc1a2a85fd0bf Mon Sep 17 00:00:00 2001
From: Gabor Hojtsy <goba@php.net>
Date: Sat, 17 Nov 2001 12:59:11 +0000
Subject: [PATCH] Adding more see also information, description of MYSQL_...
 constants, more cross references, using &return.success; where applicable,
 more discussion of mysql_query() return value, etc.

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

diff --git a/functions/mysql.xml b/functions/mysql.xml
index c171843d0a..81f77cddb5 100644
--- a/functions/mysql.xml
+++ b/functions/mysql.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.72 $ -->
+<!-- $Revision: 1.73 $ -->
  <reference id="ref.mysql">
   <title>MySQL Functions</title>
   <titleabbrev>MySQL</titleabbrev>
@@ -324,7 +324,7 @@ mysql_close($link);
     <title>Description</title>
     <funcsynopsis>
      <funcprototype>
-      <funcdef>int <function>mysql_create_db</function></funcdef>
+      <funcdef>bool <function>mysql_create_db</function></funcdef>
       <paramdef>string <parameter>database name</parameter></paramdef>
       <paramdef>resource 
        <parameter>
@@ -338,7 +338,9 @@ mysql_close($link);
      database on the server associated with the specified link
      identifier.
     </para>
-    <!-- returns?? bool -> succes? -->
+    <para>
+     &return.success;
+    </para>
     <example>
      <title>MySQL create database example</title>
      <programlisting role="php">
@@ -355,7 +357,7 @@ mysql_close($link);
     </example>
     <para> 
      For downwards compatibility <function>mysql_createdb</function>
-     can also be used.
+     can also be used. This is deprecated, however.
     </para>
     <para> 
      See also: <function>mysql_drop_db</function>.
@@ -377,8 +379,8 @@ mysql_close($link);
       <paramdef>int <parameter>row_number</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
-    <para> 
-     Returns: &true; on success, &false; on failure.
+    <para>
+     &return.success; 
     </para>
     <para> 
      <function>mysql_data_seek</function> moves the internal row
@@ -403,7 +405,7 @@ mysql_close($link);
     $result = mysql_query ($query)
         or die ("Query failed");
 
-    # fetch rows in reverse order
+    // fetch rows in reverse order
 
     for ($i = mysql_num_rows ($result) - 1; $i >=0; $i--) {
         if (!mysql_data_seek ($result, $i)) {
@@ -501,7 +503,7 @@ while ($i &lt; $cnt) {
      </funcprototype>
     </funcsynopsis>
     <para> 
-     Returns: A positive MySQL result resource to the query result,
+     Returns a positive MySQL result resource to the query result,
      or &false; on error.
     </para>
     <para> 
@@ -547,16 +549,19 @@ while ($i &lt; $cnt) {
      </funcprototype>
     </funcsynopsis>
     <para> 
-     Returns: &true; on success, &false; on failure.
+     &return.succes;
     </para>  
     <para> 
      <function>mysql_drop_db</function> attempts to drop (remove) an
      entire database from the server associated with the specified
      link identifier.
     </para>
+    <para>
+     For downward compatibility <function>mysql_dropdb</function>
+     can also be used. This is deprecated, however.
+    </para>
     <para> 
-     See also: <function>mysql_create_db</function>. For downward
-     compatibility <function>mysql_dropdb</function> can also be used.
+     See also: <function>mysql_create_db</function>.
     </para>
    </refsect1>
   </refentry>
@@ -724,25 +729,36 @@ echo mysql_errno().": ".mysql_error()."&lt;BR>";
     <para>
      If two or more columns of the result have the same field names,
      the last column will take precedence. To access the other column(s)
-     of the same name, you must the numeric index of the column or
-     make an alias for the column.
+     of the same name, you must use the numeric index of the column or
+     make an alias for the column. For aliased columns, you cannot
+     access the contents with the original column name (by using
+     <literal>'field'<literal> in this example).
      <informalexample>
       <programlisting>
-select t1.f1 as foo t2.f1 as bar from t1, t2
+select tone.field as foo ttwo.field as bar from tone, ttwo
       </programlisting>
      </informalexample>
     </para>
     <para>
      An important thing to note is that using
-     <function>mysql_fetch_array</function> is NOT significantly
-     slower than using <function>mysql_fetch_row</function>, while it
-     provides a significant added value.
+     <function>mysql_fetch_array</function> is <emphasis>not
+     significantly</emphasis> slower than using
+     <function>mysql_fetch_row</function>, while it provides
+     a significant added value.
     </para>
     <para>
      The optional second argument <parameter>result_type</parameter>
      in <function>mysql_fetch_array</function> is a constant and can
      take the following values: MYSQL_ASSOC, MYSQL_NUM, and
-     MYSQL_BOTH. (This feature was added in PHP 3.0.7)
+     MYSQL_BOTH. This feature was added in PHP 3.0.7. MYSQL_BOTH
+     is the default for this argument.
+    </para>
+    <para>
+     By using MYSQL_BOTH, you'll get an array with both associative
+     and number indices. Using MYSQL_ASSOC, you only get associative
+     indices (as <function>mysql_fetch_assoc</function> works),
+     using MYSQL_NUM, you only get number indices (as
+     <function>mysql_fetch_row</function> works).
     </para>
     <para>
      For further details, see also
@@ -797,14 +813,17 @@ mysql_free_result ($result);
     <para>
      If two or more columns of the result have the same field names,
      the last column will take precedence. To access the other
-     column(s) of the same name, you must use
-     <function>mysql_fetch_array</function> and have it return the
-     numeric indices as well.
+     column(s) of the same name, you either need to access the
+     result with numeric indices by using
+     <function>mysql_fetch_row<function> or add alias names.
+     See the example at the <function>mysql_fetch_array</function>
+     description about aliases.
     </para>
     <para>
      An important thing to note is that using
-     <function>mysql_fetch_assoc</function> is NOT significantly
-     slower than using <function>mysql_fetch_row</function>, while it
+     <function>mysql_fetch_assoc</function> is <emphasis>not
+     significantly</emphasis> slower than using
+     <function>mysql_fetch_row</function>, while it
      provides a significant added value.
     </para>
     <para>
@@ -981,7 +1000,7 @@ mysql_free_result ($result);
      </funcprototype>
     </funcsynopsis>
     <para> 
-     Returns: An array that corresponds to the lengths of each field
+     Returns an array that corresponds to the lengths of each field
      in the last row fetched by <function>mysql_fetch_row</function>,
      or &false; on error.
     </para>  
@@ -1031,7 +1050,9 @@ mysql_free_result ($result);
     <para>
      The optional argument <parameter>result_type</parameter> is a
      constant and can take the following values: MYSQL_ASSOC,
-     MYSQL_NUM, and MYSQL_BOTH.
+     MYSQL_NUM, and MYSQL_BOTH. See
+     <function>mysql_fetch_array</function> for explanation
+     of these constants.
     </para>
     <para>
      Speed-wise, the function is identical to
@@ -1074,7 +1095,7 @@ mysql_free_result ($result);
      </funcprototype>
     </funcsynopsis>
     <para> 
-     Returns: An array that corresponds to the fetched row, or &false;
+     Returns an array that corresponds to the fetched row, or &false;
      if there are no more rows.
     </para>
     <para>
@@ -1127,7 +1148,7 @@ mysql_free_result ($result);
     </para>
     <para> 
      For downward compatibility <function>mysql_fieldflags</function>
-     can also be used.
+     can also be used. This is deprecated, however.
     </para>
    </refsect1>
   </refentry>
@@ -1190,7 +1211,7 @@ password
     </para>
     <para>
      For downwards compatibility <function>mysql_fieldname</function>
-     can also be used.
+     can also be used. This is deprecated, however.
     </para>
    </refsect1>
   </refentry>
@@ -1217,7 +1238,7 @@ password
     </para>
     <para>
      For downward compatibility <function>mysql_fieldlen</function>
-     can also be used.
+     can also be used. This is deprecated, however.
     </para>
    </refsect1>
   </refentry>
@@ -1272,7 +1293,7 @@ password
     </para>
     <para>
      For downward compatibility <function>mysql_fieldtable</function>
-     can also be used.
+     can also be used. This is deprecated, however.
     </para>
    </refsect1>
   </refentry>
@@ -1330,7 +1351,7 @@ mysql_close();
     </para>
     <para> 
      For downward compatibility <function>mysql_fieldtype</function>
-     can also be used.
+     can also be used. This is deprecated, however.
     </para>
    </refsect1>
   </refentry>
@@ -1344,7 +1365,7 @@ mysql_close();
     <title>Description</title>
     <funcsynopsis>
      <funcprototype>
-      <funcdef>int <function>mysql_free_result</function></funcdef>
+      <funcdef>bool <function>mysql_free_result</function></funcdef>
       <paramdef>resource <parameter>result</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
@@ -1359,10 +1380,12 @@ mysql_close();
      automatically freed at the end of the script's execution.
      <!-- TODO and as of PHP4 before, see freeing resources -->
     </para>
-    <!-- returns?? -->
+    <para>
+     &returns.success;
+    </para>
     <para>
      For downward compatibility <function>mysql_freeresult</function>
-     can also be used.
+     can also be used. This is deprecated, however.
     </para>
    </refsect1>
   </refentry>
@@ -1396,8 +1419,9 @@ mysql_close();
     <para>
      <function>mysql_insert_id</function> returns 0 if the previous
      query does not generate an AUTO_INCREMENT value. If you need to
-     save the value for later, be sure to call mysql_insert_id()
-     immediately after the query that generates the value.
+     save the value for later, be sure to call
+     <function>mysql_insert_id</function> immediately after the
+     query that generates the value.
     </para>
     <note>
      <para>
@@ -1412,11 +1436,11 @@ mysql_close();
       <function>mysql_insert_id</function> converts the return type of
       the native MySQL C API function
       <literal>mysql_insert_id()</literal> to a type of
-      <literal>long</literal>.  If your AUTO_INCREMENT column has
-      a column type of BIGINT, the value returned by
-      <function>mysql_insert_id</function> will be incorrect.
-      Instead, use the internal MySQL SQL function
-      <literal>LAST_INSERT_ID()</literal>.
+      <literal>long</literal> (named <type>int</type> in PHP).
+      If your AUTO_INCREMENT column has a column type of BIGINT,
+      the value returned by <function>mysql_insert_id</function>
+      will be incorrect. Instead, use the internal MySQL SQL function
+      <literal>LAST_INSERT_ID()</literal> in an SQL query.
      </para>
     </warning>
    </refsect1>
@@ -1445,7 +1469,7 @@ mysql_close();
      <function>mysql_list_dbs</function> will return a result pointer
      containing the databases available from the current mysql
      daemon. Use the <function>mysql_tablename</function> function to
-     traverse this result pointer.
+     traverse this result pointer, or any function for result tables.
     </para>
     <para>
      <example>
@@ -1479,7 +1503,7 @@ database3
     </note>
     <para>
      For downward compatibility <function>mysql_listdbs</function> can
-     also be used.
+     also be used. This is deprecated however.
     </para>
     <para>
      See also <function>mysql_db_name</function>.
@@ -1515,15 +1539,6 @@ 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
-     -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>
      <example>
       <title><function>mysql_list_fields</function> example</title>
@@ -1552,7 +1567,7 @@ field3
     </para>
     <para>
      For downward compatibility <function>mysql_listfields</function>
-     can also be used.
+     can also be used. This is deprecated however.
     </para>
     <!-- TODO: this is equiv. with 'select * from $table where &false;,'
          which implies you can better use the field-research functions
@@ -1582,13 +1597,14 @@ field3
     <para> 
      <function>mysql_list_tables</function> takes a database name and
      returns a result pointer much like the
-     <function>mysql_db_query</function> function.  The
-     <function>mysql_tablename</function> function should be used to
-     extract the actual table names from the result pointer.
+     <function>mysql_db_query</function> function. You can use the
+     <function>mysql_tablename</function> function to extract the
+     actual table names from the result pointer, or any other result
+     table function.
     </para>
     <para>
      For downward compatibility <function>mysql_listtables</function>
-     can also be used.
+     can also be used. This is deprecated however.
     </para>
    </refsect1>
   </refentry>
@@ -1618,7 +1634,7 @@ field3
      <function>mysql_num_rows</function>.</para>
     <para>
      For downward compatibility <function>mysql_numfields</function>
-     can also be used.
+     can also be used. This is deprecated however.
     </para>
    </refsect1>
   </refentry>
@@ -1639,7 +1655,7 @@ field3
     <para>
      <function>mysql_num_rows</function> returns the number of rows in
      a result set. This command is only valid for SELECT statements. 
-     To retrieve the number of rows returned from a INSERT, UPDATE or 
+     To retrieve the number of rows affected by a INSERT, UPDATE or 
      DELETE query, use <function>mysql_affected_rows</function>.
      <example>
       <title><function>mysql_num_rows</function> example</title>
@@ -1667,7 +1683,7 @@ echo "$num_rows Rows\n";
     </para>
     <para>
      For downward compatibility <function>mysql_numrows</function> can
-     also be used.
+     also be used. This is deprecated however.
     </para>
    </refsect1>
   </refentry>
@@ -1676,7 +1692,7 @@ echo "$num_rows Rows\n";
    <refnamediv>
     <refname>mysql_pconnect</refname> 
     <refpurpose>
-     Open a persistent connection to a MySQL Server
+     Open a persistent connection to a MySQL server
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -1698,7 +1714,7 @@ echo "$num_rows Rows\n";
      </funcprototype>
     </funcsynopsis>
     <para> 
-     Returns: A positive MySQL persistent link identifier on success,
+     Returns a positive MySQL persistent link identifier on success,
      or &false; on error.
     </para>
     <para>
@@ -1744,6 +1760,14 @@ echo "$num_rows Rows\n";
     <para> 
      This type of links is therefore called 'persistent'.
     </para>
+    <note>
+     <para>
+      Note, that these kind of links only work if you are using
+      a module version of PHP. See the
+      <link linkend="features.persistent-connections">Persistent
+      Database Connections</link> section for more information.
+     </para>
+    </note>
    </refsect1>
   </refentry>
 
@@ -1778,9 +1802,12 @@ echo "$num_rows Rows\n";
      </para>
     </note>
     <para>
-     <function>mysql_query</function> returns &true; (non-zero) or &false;
-     to indicate whether or not the query succeeded.  A return value
-     of &true; means that the query was legal and could be executed by
+     Only for SELECT statements <function>mysql_query</function>
+     returns a resource identifier or &false; if the query was
+     not executed correctly. For other type of SQL statements,
+     <function>mysql_query</function> returns &true; on success
+     and &false; on error. A non-&false; return value
+     means that the query was legal and could be executed by
      the server.  It does not indicate anything about the number of
      rows affected or returned. It is perfectly possible for a query
      to succeed but affect no rows or return no rows.
@@ -1829,17 +1856,22 @@ $result = mysql_query ("SELECT my_col FROM my_tbl")
     <para>
      Only for SELECT statements, <function>mysql_query</function>
      returns a new result identifier that you can pass to
-     <function>mysql_result</function>.  When you are done with the
+     <function>mysql_fetch_array</function> and other
+     functions dealing with result tables. When you are done with the
      result set, you can free the resources associated with it by
-     calling <function>mysql_free_result</function>.  Although, the
+     calling <function>mysql_free_result</function>. Although, the
      memory will automatically be freed at the end of the script's
      execution.
     </para>
     <para>
-     See also: <function>mysql_affected_rows</function>,
+     See also: <function>mysql_num_rows</function>
+     <function>mysql_affected_rows</function>,
      <function>mysql_db_query</function>,
      <function>mysql_unbuffered_query</function>,
      <function>mysql_free_result</function>,
+     <function>mysql_fetch_array</function>,
+     <function>mysql_fetch_row</function>,
+     <function>mysql_fetch_assoc</function>,
      <function>mysql_result</function>,
      <function>mysql_select_db</function>, and
      <function>mysql_connect</function>.
@@ -1963,7 +1995,7 @@ $result = mysql_query ("SELECT my_col FROM my_tbl")
      </funcprototype>
     </funcsynopsis>
     <para> 
-     Returns: &true; on success, &false; on error.
+     &return.success;
     </para>
     <para> 
      <function>mysql_select_db</function> sets the current active
@@ -1971,7 +2003,7 @@ $result = mysql_query ("SELECT my_col FROM my_tbl")
      identifier.  If no link identifier is specified, the last opened
      link is assumed.  If no link is open, the function will try to
      establish a link as if <function>mysql_connect</function> was
-     called, and use it.
+     called without arguments, and use it.
     </para>
     <para>
      Every subsequent call to <function>mysql_query</function> will be
@@ -1984,7 +2016,7 @@ $result = mysql_query ("SELECT my_col FROM my_tbl")
     </para>
     <para>
      For downward compatibility <function>mysql_selectdb</function>
-     can also be used.
+     can also be used. This is deprecated however.
     </para>
    </refsect1>
   </refentry>