mysql-affected-rows.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 65e697ff671608989432a6e6bf8ae8128b2be2c7 Maintainer: HonestQiao Status: ready -->
<!-- Reviewed: no Maintainer: HonestQiao -->
<!-- CREDITS: dallas -->
<refentry xml:id="function.mysql-affected-rows" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>mysql_affected_rows</refname>
  <refpurpose>取得前一次 MySQL 操作所影响的记录行数</refpurpose>
 </refnamediv>
 
 
 <refsynopsisdiv>
  <warning>
   &mysql.alternative.note;
   <simplelist role="alternatives">
    <member><function>mysqli_affected_rows</function></member>
    <member><methodname>PDOStatement::rowCount</methodname></member>
   </simplelist>
  </warning>
 </refsynopsisdiv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>int</type><methodname>mysql_affected_rows</methodname>
   <methodparam choice="opt"><type>resource</type><parameter>link_identifier</parameter><initializer>NULL</initializer></methodparam>
  </methodsynopsis>
  <para>
   取得最近一次与 <parameter>link_identifier</parameter> 关联的
   INSERT，UPDATE 或 DELETE 查询所影响的记录行数。
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    &mysql.linkid.description;
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   执行成功则返回受影响的行的数目，如果最近一次查询失败的话，函数返回 -1。
  </para>
  <para>
   如果最近一次操作是没有任何条件（WHERE）的 DELETE
   查询，在表中所有的记录都会被删除，但本函数返回值在 4.1.2 版之前都为 0。
  </para>
  <para>
   当使用 UPDATE 查询，MySQL 不会将原值和新值一样的列更新。这样使得
   <function>mysql_affected_rows</function>
   函数返回值不一定就是查询条件所符合的记录数，只有真正被修改的记录数才会被返回。
  </para>
  <para>
   REPLACE 语句首先删除具有相同主键的记录，然后插入一个新记录。本函数返回的是被删除的记录数加上被插入的记录数。
  </para>
  <para>
   "INSERT ... ON DUPLICATE KEY UPDATE" 这种情况的查询，当执行了一次 INSERT 返回的值会是 <literal>1</literal>；如果是对已经存在的记录执行一次 UPDATE 将返回 <literal>2</literal>。 
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>mysql_affected_rows</function> 例子</title>
    <programlisting role="php">
<![CDATA[
<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
    die('Could not connect: ' . mysql_error());
}
mysql_select_db('mydb');

/* 本例返回被删除记录的准确数目 */
mysql_query('DELETE FROM mytable WHERE id < 10');
printf("Records deleted: %d\n", mysql_affected_rows());

/* 对于非真值的 WHERE 子句，应返回 0 */
mysql_query('DELETE FROM mytable WHERE 0');
printf("Records deleted: %d\n", mysql_affected_rows());
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
Records deleted: 10
Records deleted: 0
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>使用事务处理的 <function>mysql_affected_rows</function> 例子</title>
    <programlisting role="php">
<![CDATA[
<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
    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>
    &example.outputs.similar;
    <screen>
<![CDATA[
Updated Records: 10
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <title>事务处理</title>
   <para>
    如果使用事务处理（transactions），需要在 INSERT，UPDATE 或 DELETE 查询后调用
    <function>mysql_affected_rows</function> 函数，而不是在 COMMIT 命令之后。
   </para>
  </note>
  <note>
   <title>SELECT 语句</title>
   <para>
    要获取 SELECT 所返回的行数，可以用
    <function>mysql_num_rows</function>。
   </para>
  </note>
  <note>
   <title>Cascaded 外键</title>
   <para>
     <function>mysql_affected_rows</function> does not count rows affected
     implicitly through the use of ON DELETE CASCADE and/or ON UPDATE CASCADE 
     in foreign key constraints.
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>mysql_num_rows</function></member>
    <member><function>mysql_info</function></member>
   </simplelist>
  </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:"~/.phpdoc/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
-->