php-doc-en/reference/mysql/functions/mysql-affected-rows.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.17 $ -->
<!-- splitted from ./en/functions/mysql.xml, last change in rev 1.2 -->
  <refentry id="function.mysql-affected-rows">
   <refnamediv>
    <refname>mysql_affected_rows</refname>
    <refpurpose>Get number of affected rows in previous MySQL
     operation</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mysql_affected_rows</methodname>
      <methodparam choice="opt"><type>resource</type><parameter>
        link_identifier
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>mysql_affected_rows</function> returns the number
     of rows affected by the last INSERT, UPDATE or DELETE query
     associated with <parameter>link_identifier</parameter>.  If the
     link identifier isn't specified, the last link opened by
     <function>mysql_connect</function> is assumed.
    </para>
    <note>
     <para>
      If you are using transactions, you need to call
      <function>mysql_affected_rows</function> after your INSERT,
      UPDATE, or DELETE query, not after the commit.
     </para>
    </note>
    <para>
     If the last query was a DELETE query with no WHERE clause, all
     of the records will have been deleted from the table but this
     function will return zero.
    </para>
    <note>
     <para>
      When using UPDATE, MySQL will not update columns where the new
      value is the same as the old value.  This creates the possibility
      that <function>mysql_affected_rows</function> may not actually
      equal the number of rows matched, only the number of rows that
      were literally affected by the query.
     </para>
     <para>
      The REPLACE statement first deletes the record with the same primary key and
      then inserts the new record. This function returns the number of deleted
      records plus the number of inserted records.
     </para>
    </note>
    <para>
     To retrieve the number of rows returned by a SELECT, it is possible to
     use also <function>mysql_num_rows</function>.
    </para>
    <para>
     If the last query failed, this function will return -1.
     <example>
      <title>Delete-Query</title>
      <programlisting role="php">
<![CDATA[
<?php
/* connect to database */
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
    die('Could not connect: ' . mysql_error());
}
mysql_select_db('mydb');

/* this should return the correct numbers of deleted records */
mysql_query('DELETE FROM mytable WHERE id < 10');
printf("Records deleted: %d\n", mysql_affected_rows());

/* with a where clause that is never true, it should return 0 */
mysql_query('DELETE FROM mytable WHERE 0');
printf("Records deleted: %d\n", mysql_affected_rows());
?>
]]>
      </programlisting>
      <para>
       The above example would produce the following output:
      </para>
      <screen>
<![CDATA[
Records deleted: 10
Records deleted: 0
]]>
      </screen>
     </example>
    </para>
    <para>
     <example>
      <title>Update-Query</title>
      <programlisting role="php">
<![CDATA[
<?php
/* connect to database */
mysql_connect("localhost", "mysql_user", "mysql_password") or
    die("Could not connect: " . mysql_error());
mysql_select_db("mydb");

/* Update records */
mysql_query("UPDATE mytable SET used=1 WHERE id < 10");
printf ("Updated records: %d\n", mysql_affected_rows());
mysql_query("COMMIT");
?>
]]>
      </programlisting>
      <para>
       The above example would produce the following output:
      </para>
      <screen>
<![CDATA[
Updated Records: 10
]]>
      </screen>
     </example> 
    </para>
    <para>
     See also <function>mysql_num_rows</function>, and
     <function>mysql_info</function>.
    </para>
   </refsect1>
  </refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->