mysql-affected-rows.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 65e697ff671608989432a6e6bf8ae8128b2be2c7 Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->

<refentry xml:id="function.mysql-affected-rows" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>mysql_affected_rows</refname>
  <refpurpose>
   Retourne le nombre de lignes affectées lors de la dernière opération 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>
   Retourne le nombre de lignes affectées lors de la dernière
   requête INSERT, UPDATE, REPLACE ou DELETE avec
   <parameter>link_identifier</parameter>.
  </para>
 </refsect1>

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

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Retourne le nombre de lignes affectées en cas de succès et -1 si la
   dernière requête a échoué.
  </para>
  <para>
   Si la dernière requête était un DELETE sans clause WHERE, tous
   les enregistrements ont été effacés, mais cette fonction va
   retourner 0 avec les versions de MySQL antérieures à 4.1.2.
  </para>
  <para>
   Lorsque vous utilisez UPDATE, MySQL ne mettra pas à jour les colonnes si
   la nouvelle valeur est identique à l'ancienne. Il est donc possible que 
   <function>mysql_affected_rows</function> ne représente pas forcément
   le nombre de lignes correspondantes mais plutôt le nombre de lignes
   qui ont été réellement affectées par la requête.
  </para>
  <para>
   La requête REPLACE commence par effacer les enregistrements possédant la même
   clé primaire et ensuite, insert les nouveaux enregistrements. Cette fonction retourne le
   nombre d'enregistrements effacés ainsi que le nombre d'enregistrements insérés.
  </para>
  <para>
   Dans le cas d'une requête "INSERT ... ON DUPLICATE KEY UPDATE", la valeur
   retournée sera <literal>1</literal> si une insertion a été effectuée,
   ou <literal>2</literal> si une mise à jour d'une ligne existante a été réalisée.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemple avec <function>mysql_affected_rows</function></title>
    <programlisting role="php">
<![CDATA[
<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
     die('Impossible de se connecter : ' . mysql_error());
}
mysql_select_db('mydb');

/* Ceci devrait retourner le nombre correct de lignes effacées */
mysql_query('DELETE FROM mytable WHERE id < 10');
printf("Lignes effacées : %d\n", mysql_affected_rows());

/* avec la clause where qui n'est jamais vraie, on devrait obtenir 0 */
mysql_query('DELETE FROM mytable WHERE 0');
printf("Lignes effacées : %d\n", mysql_affected_rows());
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
Lignes effacées : 10
Lignes effacées : 0
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Exemple avec <function>mysql_affected_rows</function> en utilisant
    les transactions</title>
    <programlisting role="php">
<![CDATA[
<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
     die('Impossible de se connecter : ' . mysql_error());
}
mysql_select_db('mydb');

/* Mise à jour des lignes */
mysql_query("UPDATE mytable SET used=1 WHERE id < 10");
printf ("Lignes modifiées : %d\n", mysql_affected_rows());
mysql_query("COMMIT");
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
Lignes modifiées : 10
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <title>Transactions</title>
   <para>
    Si vous utilisez des transactions, vous devez appeler
    <function>mysql_affected_rows</function> après votre requête INSERT,
    UPDATE ou DELETE et non après le COMMIT.
   </para>
  </note>
  <note>
   <title>Requêtes SELECT</title>
   <para>
    Pour obtenir le nombre de lignes retournées par un SELECT, il est possible
    d'utiliser <function>mysql_num_rows</function>.
   </para>
  </note>
  <note>
   <title>Clés étrangères en cascade</title>
   <para>
     <function>mysql_affected_rows</function> ne compte pas les enregistrements affectés
     implicitement par un ON DELETE CASCADE et/ou un ON UPDATE CASCADE, concernant les
     clés étrangères.
   </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
-->