begintransaction.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="pdo.begintransaction" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>PDO::beginTransaction</refname>
  <refpurpose>
   Initiates a transaction
  </refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>public</modifier> <type>bool</type><methodname>PDO::beginTransaction</methodname>
   <void/>
  </methodsynopsis>
  <para>
   Turns off autocommit mode.  While autocommit mode is turned off, changes
   made to the database via the PDO object instance are not committed until
   you end the transaction by calling <function>PDO::commit</function>.
   Calling <function>PDO::rollBack</function> will roll back all changes to
   the database and return the connection to autocommit mode.
  </para>
  <para>
   Some databases, including MySQL, automatically issue an implicit
   COMMIT when a database definition language (DDL) statement such as
   DROP TABLE or CREATE TABLE is issued within a transaction. The implicit
   COMMIT will prevent you from rolling back any other changes within the
   transaction boundary.
  </para>

 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  &no.function.parameters;
 </refsect1>

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

 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   Throws a <classname>PDOException</classname> if there is already a transaction started or the driver does not support transactions.
  </para>
  &pdo.errors.exception-not-errmode;
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example><title>Roll back a transaction</title>
    <para>
     The following example begins a transaction and issues two statements
     that modify the database before rolling back the changes. On MySQL,
     however, the DROP TABLE statement automatically commits the
     transaction so that none of the changes in the transaction are rolled
     back.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
/* Begin a transaction, turning off autocommit */
$dbh->beginTransaction();

/* Change the database schema and data */
$sth = $dbh->exec("DROP TABLE fruit");
$sth = $dbh->exec("UPDATE dessert
    SET name = 'hamburger'");

/* Recognize mistake and roll back changes */
$dbh->rollBack();

/* Database connection is now back in autocommit mode */
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>PDO::commit</function></member>
    <member><function>PDO::rollBack</function></member>
    <member><link linkend="pdo.transactions">Transactions and auto-commit</link></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
-->