doc-fr/reference/oci8/functions/oci-rollback.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 5a3f0c18ac46e6d4313367e44866527badac5b73 Maintainer: yannick Status: ready -->
<!-- Reviewed: yes -->

<refentry xml:id="function.oci-rollback" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>oci_rollback</refname>
  <refpurpose>Annule les transactions Oracle en cours</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>oci_rollback</methodname>
   <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
  </methodsynopsis>
  <para>
   Annule toutes les modifications non validées pour une
   connexion <parameter>connection</parameter> Oracle
   et met fin à la transaction courante. Tous les verrous seront
   également libérés. Tous les points de sauvegarde Oracle
   (<literal>SAVEPOINTS</literal>) seront supprimés.
  </para>
  <para>
   Une transaction commence lorsque la première requête SQL
   qui modifie des données est exécuté avec la fonction
   <function>oci_execute</function> en utilisant le drapeau
   <constant>OCI_NO_AUTO_COMMIT</constant>. Les modifications suivantes
   effectuées par d'autres requêtes deviennent partie intégrante de la
   même transaction. Les modifications effectuées lors d'une transaction sont
   temporaires tant que la transaction n'a pas été validée ou annulée.
   Les autres utilisateurs de la base de données ne verront ces modifications
   que lors de la validation de la transaction.
  </para>
  <para>
   Lors de l'insertion ou de la mise à jour de données, l'utilisation
   des transactions est fortement recommandée afin de garantir la consistence
   relationnelle des données, mais aussi pour des raisons de performance.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>connection</parameter></term>
     <listitem>
      <para>
       Un identifiant de connexion Oracle, retourné par la fonction
       <function>oci_connect</function>, <function>oci_pconnect</function>
       ou <function>oci_new_connect</function>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemple avec <function>oci_rollback</function></title>
    <programlisting role="php">
<![CDATA[
<?php

// Insertion dans plusieurs tables, puis, annulation des modifications si des erreurs surviennent

$conn = oci_connect('hr', 'welcome', 'localhost/XE');

$stid = oci_parse($conn, "INSERT INTO mysalary (id, name) VALUES (1, 'Chris')");

// Le drapeau OCI_NO_AUTO_COMMIT indique à Oracle de ne pas valider l'insertion immédiatement.
// Utilisez le drapeau OCI_DEFAULT en PHP <= 5.3.1. Les 2 sont identiques.
$r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
if (!$r) {    
    $e = oci_error($stid);
    trigger_error(htmlentities($e['message']), E_USER_ERROR);
}

$stid = oci_parse($conn, 'INSERT INTO myschedule (startday) VALUES (12)');
$r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
if (!$r) {    
    $e = oci_error($stid);
    oci_rollback($conn);  // Annulation des modifications sur les 2 tables
    trigger_error(htmlentities($e['message']), E_USER_ERROR);
}

// Validation des modifications sur les 2 tables
$r = oci_commit($conn);
if (!r) {
    $e = oci_error($conn);
    trigger_error(htmlentities($e['message']), E_USER_ERROR);
}

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Exemple de retour à un point de sauvegarde (<literal>SAVEPOINT</literal>)</title>
    <programlisting role="php">
<![CDATA[
<?php
$stid = oci_parse($conn, 'UPDATE mytab SET id = 1111');
oci_execute($stid, OCI_NO_AUTO_COMMIT);

// création du point de sauvegarde
$stid = oci_parse($conn, 'SAVEPOINT mysavepoint');
oci_execute($stid, OCI_NO_AUTO_COMMIT);

$stid = oci_parse($conn, 'UPDATE mytab SET id = 2222');
oci_execute($stid, OCI_NO_AUTO_COMMIT);

// utilise une requête SQL explicite pour effectuer le retour au point de sauvegarde
$stid = oci_parse($conn, 'ROLLBACK TO SAVEPOINT mysavepoint');
oci_execute($stid, OCI_NO_AUTO_COMMIT);

oci_commit($conn);  // mytab a maintenant un id de 1111
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Les transactions sont automatiquement annulées lorsque vous fermez
    la connexion, ou lorsque le script se termine, un des deux arrivant le premier.
    Vous devez explicitement appeler la fonction <function>oci_commit</function>
    pour valider la connexion.
   </para>
   <para>
    Tous les appels à la fonction <function>oci_execute</function> qui utilisent
    le mode <constant>OCI_COMMIT_ON_SUCCESS</constant>, qui se soit par défaut ou
    de façon explicite, valideront toutes les transactions en attente.
   </para>
   <para>
    Toutes les requêtes Oracle comme <literal>CREATE</literal>
    ou <literal>DROP</literal> valideront également, automatiquement,
    toutes les transactions en attente.
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>oci_commit</function></member>
    <member><function>oci_execute</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
-->