doc/ref-transaction.xml

   1 <?xml version='1.0' ?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4 <!ENTITY % myents SYSTEM "entities.inc">
   5 %myents;
   6 ]>
   7
   8 <!-- Transaction handling -->
   9
  10 <reference id="ref-transaction">
  11   <title>Transaction Handling</title>
  12     <partintro>
  13     <para>
  14       This section describes the interface provided by &clsql; for
  15       handling database transactions. The interface allows for opening
  16       transaction blocks, committing or rolling back changes made and
  17       controlling autocommit behaviour.
  18     </para>
  19     <note>
  20       In contrast to &commonsql;, &clsql;, by default, starts in
  21       transaction AUTOCOMMIT mode (see <link
  22       linkend="set-autocommit"><function>set-autocommit</function></link>).
  23       To begin a transaction in autocommit mode, <link
  24       linkend="start-transaction"><function>start-transaction</function></link>
  25       has to be called explicitly.
  26     </note>
  27   </partintro>
  28
  29   <refentry id="start-transaction">
  30     <refmeta>
  31       <refentrytitle>START-TRANSACTION</refentrytitle>
  32     </refmeta>
  33     <refnamediv>
  34       <refname><emphasis>Function</emphasis> <emphasis role="bold">START-TRANSACTION</emphasis></refname>
  35       <refpurpose>Open a transaction block.</refpurpose>
  36       <refclass>Function</refclass>
  37     </refnamediv>
  38     <refsect1>
  39       <title>Syntax</title>
  40       <synopsis>
  41       <function>start-transaction</function> &amp;key <replaceable>database</replaceable> => <returnvalue>&nil;</returnvalue></synopsis>
  42     </refsect1>
  43     <refsect1>
  44       <title>Arguments and Values</title>
  45       <variablelist>
  46         <varlistentry>
  47           <term><parameter>database</parameter></term>
  48           <listitem>
  49             <para>A
  50             <glossterm linkend="gloss-database-object">database
  51             object</glossterm>. This will default to the value
  52             of <symbol>*default-database*</symbol>.</para>
  53           </listitem>
  54         </varlistentry>
  55       </variablelist>
  56     </refsect1>
  57     <refsect1>
  58       <title>Description</title>
  59       <para>Starts a transaction block on
  60       <parameter>database</parameter> which defaults to
  61       <symbol>*default-database*</symbol> and which continues until
  62       <function>rollback</function> or <function>commit</function> are
  63       called.
  64       </para>
  65     </refsect1>
  66     <refsect1>
  67       <title>Examples</title>
  68       <screen>
  69 (in-transaction-p)
  70 => NIL
  71 (select [*] :from [foo] :field-names nil)
  72 => NIL
  73 (start-transaction)
  74 => NIL
  75 (in-transaction-p)
  76 => T
  77 (insert-records :into [foo] :av-pairs '(([bar] 1) ([baz] "one")))
  78 =>
  79 (select [*] :from [foo] :field-names nil)
  80 => ((1 "one"))
  81 (rollback)
  82 => NIL
  83 (in-transaction-p)
  84 => NIL
  85 (select [*] :from [foo] :field-names nil)
  86 => NIL
  87       </screen>
  88     </refsect1>
  89     <refsect1>
  90       <title>Side Effects</title>
  91       <para>
  92         Autocommit mode is disabled and if
  93         <parameter>database</parameter> is currently within the scope
  94         of a transaction, all commit and rollback hooks are removed
  95         and the transaction level associated with
  96         <parameter>database</parameter> is modified.
  97       </para>
  98     </refsect1>
  99     <refsect1>
 100       <title>Affected by</title>
 101       <para>
 102         None.
 103       </para>
 104     </refsect1>
 105     <refsect1>
 106       <title>Exceptional Situations</title>
 107       <para>
 108         Signals an error of type <symbol>sql-database-error</symbol>
 109         if <parameter>database</parameter> is not a database object.
 110       </para>
 111     </refsect1>
 112     <refsect1>
 113       <title>See Also</title>
 114       <simplelist>
 115         <member><link linkend="commit"><function>commit</function></link></member>
 116         <member><link linkend="rollback"><function>rollback</function></link></member>
 117         <member><link linkend="in-transaction-p"><function>in-transaction-p</function></link></member>
 118         <member><link linkend="set-autocommit"><function>set-autocommit</function></link></member>
 119         <member><link linkend="with-transaction"><function>with-transaction</function></link></member>
 120       </simplelist>
 121     </refsect1>
 122     <refsect1>
 123       <title>Notes</title>
 124       <para>
 125         <function>start-transaction</function> is a &clsql; extension.
 126       </para>
 127     </refsect1>
 128   </refentry>
 129
 130   <refentry id="commit">
 131     <refmeta>
 132       <refentrytitle>COMMIT</refentrytitle>
 133     </refmeta>
 134     <refnamediv>
 135       <refname><emphasis>Function</emphasis> <emphasis role="bold">COMMIT</emphasis></refname>
 136       <refpurpose>Commit modifications made in the current transaction.</refpurpose>
 137       <refclass>Function</refclass>
 138     </refnamediv>
 139     <refsect1>
 140       <title>Syntax</title>
 141       <synopsis>
 142       <function>commit</function> &amp;key <replaceable>database</replaceable> => <returnvalue>&nil;</returnvalue></synopsis>
 143     </refsect1>
 144     <refsect1>
 145       <title>Arguments and Values</title>
 146       <variablelist>
 147         <varlistentry>
 148           <term><parameter>database</parameter></term>
 149           <listitem>
 150             <para>A
 151             <glossterm linkend="gloss-database-object">database
 152             object</glossterm>. This will default to the value
 153             of <symbol>*default-database*</symbol>.</para>
 154           </listitem>
 155         </varlistentry>
 156       </variablelist>
 157     </refsect1>
 158     <refsect1>
 159       <title>Description</title>
 160       <para>If <parameter>database</parameter>, which defaults to
 161       <symbol>*default-database*</symbol>, is currently within the
 162       scope of a transaction, commits changes made since the
 163       transaction began.
 164       </para>
 165     </refsect1>
 166     <refsect1>
 167       <title>Examples</title>
 168       <screen>
 169 (in-transaction-p)
 170 => NIL
 171 (select [*] :from [foo] :field-names nil)
 172 => NIL
 173 (start-transaction)
 174 => NIL
 175 (in-transaction-p)
 176 => T
 177 (insert-records :into [foo] :av-pairs '(([bar] 1) ([baz] "one")))
 178 =>
 179 (select [*] :from [foo] :field-names nil)
 180 => ((1 "one"))
 181 (commit)
 182 => NIL
 183 (in-transaction-p)
 184 => NIL
 185 (select [*] :from [foo] :field-names nil)
 186 => ((1 "one"))
 187       </screen>
 188     </refsect1>
 189     <refsect1>
 190       <title>Side Effects</title>
 191       <para>
 192         Changes made within the scope of the current transaction are
 193         committed in the underlying database and the transaction level
 194         of <parameter>database</parameter> is reset.
 195       </para>
 196     </refsect1>
 197     <refsect1>
 198       <title>Affected by</title>
 199       <para>
 200         The transaction level of <parameter>database</parameter> which
 201         indicates whether a transaction has been initiated by a call to
 202         <function>start-transaction</function> since the last call to
 203         <function>rollback</function> or <function>commit</function>.
 204       </para>
 205     </refsect1>
 206     <refsect1>
 207       <title>Exceptional Situations</title>
 208       <para>
 209         Signals an error of type <symbol>sql-database-error</symbol>
 210         if <parameter>database</parameter> is not a database object. A
 211         warning of type <symbol>sql-warning</symbol> is signalled if there
 212         is no transaction in progress.
 213         </para>
 214     </refsect1>
 215     <refsect1>
 216       <title>See Also</title>
 217       <simplelist>
 218         <member><link linkend="start-transaction"><function>start-transaction</function></link></member>
 219         <member><link linkend="rollback"><function>rollback</function></link></member>
 220         <member><link linkend="in-transaction-p"><function>in-transaction-p</function></link></member>
 221         <member><link linkend="add-transaction-commit-hook"><function>add-transaction-commit-hook</function></link></member>
 222         <member><link linkend="set-autocommit"><function>set-autocommit</function></link></member>
 223         <member><link linkend="with-transaction"><function>with-transaction</function></link></member>
 224       </simplelist>
 225     </refsect1>
 226     <refsect1>
 227       <title>Notes</title>
 228       <para>
 229         None.
 230       </para>
 231     </refsect1>
 232   </refentry>
 233
 234   <refentry id="rollback">
 235     <refmeta>
 236       <refentrytitle>ROLLBACK</refentrytitle>
 237     </refmeta>
 238     <refnamediv>
 239       <refname><emphasis>Function</emphasis> <emphasis role="bold">ROLLBACK</emphasis></refname>
 240       <refpurpose>Roll back modifications made in the current transaction.</refpurpose>
 241       <refclass>Function</refclass>
 242     </refnamediv>
 243     <refsect1>
 244       <title>Syntax</title>
 245       <synopsis>
 246       <function>rollback</function> &amp;key <replaceable>database</replaceable> => <returnvalue>&nil;</returnvalue></synopsis>
 247     </refsect1>
 248     <refsect1>
 249       <title>Arguments and Values</title>
 250       <variablelist>
 251         <varlistentry>
 252           <term><parameter>database</parameter></term>
 253           <listitem>
 254             <para>A
 255             <glossterm linkend="gloss-database-object">database
 256             object</glossterm>. This will default to the value
 257             of <symbol>*default-database*</symbol>.</para>
 258           </listitem>
 259         </varlistentry>
 260       </variablelist>
 261     </refsect1>
 262     <refsect1>
 263       <title>Description</title>
 264       <para>If <parameter>database</parameter>, which defaults to
 265       <symbol>*default-database*</symbol>, is currently within the
 266       scope of a transaction, rolls back changes made since the
 267       transaction began.
 268       </para>
 269     </refsect1>
 270     <refsect1>
 271       <title>Examples</title>
 272       <screen>
 273 (in-transaction-p)
 274 => NIL
 275 (select [*] :from [foo] :field-names nil)
 276 => NIL
 277 (start-transaction)
 278 => NIL
 279 (in-transaction-p)
 280 => T
 281 (insert-records :into [foo] :av-pairs '(([bar] 1) ([baz] "one")))
 282 =>
 283 (select [*] :from [foo] :field-names nil)
 284 => ((1 "one"))
 285 (rollback)
 286 => NIL
 287 (in-transaction-p)
 288 => NIL
 289 (select [*] :from [foo] :field-names nil)
 290 => NIL
 291       </screen>
 292     </refsect1>
 293     <refsect1>
 294       <title>Side Effects</title>
 295       <para>
 296        Changes made within the scope of the current transaction are
 297        reverted in the underlying database and the transaction level
 298        of <parameter>database</parameter> is reset.  </para>
 299     </refsect1>
 300     <refsect1>
 301       <title>Affected by</title>
 302       <para>
 303         The transaction level of <parameter>database</parameter> which
 304         indicates whether a transaction has been initiated by a call to
 305         <function>start-transaction</function> since the last call to
 306         <function>rollback</function> or <function>commit</function>.
 307       </para>
 308     </refsect1>
 309     <refsect1>
 310       <title>Exceptional Situations</title>
 311       <para>
 312         Signals an error of type <symbol>sql-database-error</symbol>
 313         if <parameter>database</parameter> is not a database object. A
 314         warning of type <symbol>sql-warning</symbol> is signalled if
 315         there is no transaction in progress.
 316       </para>
 317     </refsect1>
 318     <refsect1>
 319       <title>See Also</title>
 320       <simplelist>
 321         <member><link linkend="start-transaction"><function>start-transaction</function></link></member>
 322         <member><link linkend="commit"><function>commit</function></link></member>
 323         <member><link linkend="in-transaction-p"><function>in-transaction-p</function></link></member>
 324         <member><link linkend="add-transaction-rollback-hook"><function>add-transaction-rollback-hook</function></link></member>
 325         <member><link linkend="set-autocommit"><function>set-autocommit</function></link></member>
 326         <member><link linkend="with-transaction"><function>with-transaction</function></link></member>
 327       </simplelist>
 328     </refsect1>
 329     <refsect1>
 330       <title>Notes</title>
 331       <para>
 332         None.
 333       </para>
 334     </refsect1>
 335   </refentry>
 336
 337   <refentry id="in-transaction-p">
 338     <refmeta>
 339       <refentrytitle>IN-TRANSACTION-P</refentrytitle>
 340     </refmeta>
 341     <refnamediv>
 342       <refname><emphasis>Function</emphasis> <emphasis role="bold">IN-TRANSACTION-P</emphasis></refname>
 343       <refpurpose>A predicate for testing whether a transaction is currently in progress.</refpurpose>
 344       <refclass>Function</refclass>
 345     </refnamediv>
 346     <refsect1>
 347       <title>Syntax</title>
 348       <synopsis>
 349       <function>in-transaction-p</function> &amp;key <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
 350     </refsect1>
 351     <refsect1>
 352       <title>Arguments and Values</title>
 353       <variablelist>
 354         <varlistentry>
 355           <term><parameter>database</parameter></term>
 356           <listitem>
 357             <para>A
 358             <glossterm linkend="gloss-database-object">database
 359             object</glossterm>. This will default to the value
 360             of <symbol>*default-database*</symbol>.</para>
 361           </listitem>
 362         </varlistentry>
 363         <varlistentry>
 364           <term><parameter>result</parameter></term>
 365           <listitem>
 366             <para>A Boolean.</para>
 367           </listitem>
 368         </varlistentry>
 369       </variablelist>
 370     </refsect1>
 371     <refsect1>
 372       <title>Description</title>
 373       <para>A predicate to test whether
 374       <parameter>database</parameter>, which defaults to
 375       <symbol>*default-database*</symbol>, is currently within the
 376       scope of a transaction.
 377       </para>
 378     </refsect1>
 379     <refsect1>
 380       <title>Examples</title>
 381       <screen>
 382 (in-transaction-p)
 383 => NIL
 384 (start-transaction)
 385 => NIL
 386 (in-transaction-p)
 387 => T
 388 (commit)
 389 => NIL
 390 (in-transaction-p)
 391 => NIL
 392       </screen>
 393     </refsect1>
 394     <refsect1>
 395       <title>Side Effects</title>
 396       <para>
 397         None.
 398       </para>
 399     </refsect1>
 400     <refsect1>
 401       <title>Affected by</title>
 402       <para>
 403         None.
 404       </para>
 405     </refsect1>
 406     <refsect1>
 407       <title>Exceptional Situations</title>
 408       <para>
 409         None.
 410       </para>
 411     </refsect1>
 412     <refsect1>
 413       <title>See Also</title>
 414       <simplelist>
 415         <member><link linkend="start-transaction"><function>start-transaction</function></link></member>
 416         <member><link linkend="commit"><function>commit</function></link></member>
 417         <member><link linkend="rollback"><function>rollback</function></link></member>
 418         <member><link linkend="set-autocommit"><function>set-autocommit</function></link></member>
 419       </simplelist>
 420     </refsect1>
 421     <refsect1>
 422       <title>Notes</title>
 423       <para>
 424         <function>in-transaction-p</function> is a &clsql; extension.
 425       </para>
 426     </refsect1>
 427   </refentry>
 428
 429   <refentry id="add-transaction-commit-hook">
 430     <refmeta>
 431       <refentrytitle>ADD-TRANSACTION-COMMIT-HOOK</refentrytitle>
 432     </refmeta>
 433     <refnamediv>
 434       <refname><emphasis>Function</emphasis> <emphasis role="bold">ADD-TRANSACTION-COMMIT-HOOK</emphasis></refname>
 435       <refpurpose>Specify hooks to be run when committing changes.</refpurpose>
 436       <refclass>Function</refclass>
 437     </refnamediv>
 438     <refsect1>
 439       <title>Syntax</title>
 440       <synopsis>
 441       <function>add-transaction-commit-hook</function> <replaceable>commit-hook</replaceable> &amp;key <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
 442     </refsect1>
 443     <refsect1>
 444       <title>Arguments and Values</title>
 445       <variablelist>
 446         <varlistentry>
 447           <term><parameter>commit-hook</parameter></term>
 448           <listitem>
 449             <para>A designator for a function with no required arguments.</para>
 450           </listitem>
 451         </varlistentry>
 452         <varlistentry>
 453           <term><parameter>database</parameter></term>
 454           <listitem>
 455             <para>A
 456             <glossterm linkend="gloss-database-object">database
 457             object</glossterm>. This will default to the value
 458             of <symbol>*default-database*</symbol>.</para>
 459           </listitem>
 460         </varlistentry>
 461         <varlistentry>
 462           <term><parameter>result</parameter></term>
 463           <listitem>
 464             <para>The list of currently defined commit hooks for
 465             <parameter>database</parameter>.
 466             </para>
 467           </listitem>
 468         </varlistentry>
 469       </variablelist>
 470     </refsect1>
 471     <refsect1>
 472       <title>Description</title>
 473       <para>
 474         Adds <parameter>commit-hook</parameter>, which should a
 475         designator for a function with no required arguments, to the
 476         list of hooks run when <function>commit</function> is called
 477         on <parameter>database</parameter> which defaults to
 478         <symbol>*default-database*</symbol>.
 479       </para>
 480     </refsect1>
 481     <refsect1>
 482       <title>Examples</title>
 483       <screen>
 484 (start-transaction)
 485 => NIL
 486 (add-transaction-commit-hook #'(lambda () (print "Successfully committed.")))
 487 => (#&lt;Interpreted Function (LAMBDA # #) {48E2E689}>)
 488 (commit)
 489 "Successfully committed."
 490 => NIL
 491       </screen>
 492     </refsect1>
 493     <refsect1>
 494       <title>Side Effects</title>
 495       <para>
 496         <parameter>commit-hook</parameter> is added to the list of
 497         commit hooks for <parameter>database</parameter>.
 498       </para>
 499     </refsect1>
 500     <refsect1>
 501       <title>Affected by</title>
 502       <para>
 503         None.
 504       </para>
 505     </refsect1>
 506     <refsect1>
 507       <title>Exceptional Situations</title>
 508       <para>
 509         If <parameter>commit-hook</parameter> has one or more required
 510         arguments, an error will be signalled when
 511         <function>commit</function> is called.
 512       </para>
 513     </refsect1>
 514     <refsect1>
 515       <title>See Also</title>
 516       <simplelist>
 517         <member><link linkend="commit"><function>commit</function></link></member>
 518         <member><link linkend="rollback"><function>rollback</function></link></member>
 519         <member><link linkend="add-transaction-rollback-hook"><function>add-transaction-rollback-hook</function></link></member>
 520         <member><link linkend="with-transaction"><function>with-transaction</function></link></member>
 521       </simplelist>
 522     </refsect1>    <refsect1>
 523       <title>Notes</title>
 524       <para>
 525         <function>add-transaction-commit-hook</function> is a &clsql; extension.
 526       </para>
 527     </refsect1>
 528   </refentry>
 529
 530   <refentry id="add-transaction-rollback-hook">
 531     <refmeta>
 532       <refentrytitle>ADD-TRANSACTION-ROLLBACK-HOOK</refentrytitle>
 533     </refmeta>
 534     <refnamediv>
 535       <refname><emphasis>Function</emphasis> <emphasis role="bold">ADD-TRANSACTION-ROLLBACK-HOOK</emphasis></refname>
 536       <refpurpose>Specify hooks to be run when rolling back changes.</refpurpose>
 537       <refclass>Function</refclass>
 538     </refnamediv>
 539     <refsect1>
 540       <title>Syntax</title>
 541       <synopsis>
 542       <function>add-transaction-rollback-hook</function> <replaceable>rollback-hook</replaceable> &amp;key <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
 543     </refsect1>
 544     <refsect1>
 545       <title>Arguments and Values</title>
 546       <variablelist>
 547         <varlistentry>
 548           <term><parameter>rollback-hook</parameter></term>
 549           <listitem>
 550             <para>A designator for a function with no required arguments.</para>
 551           </listitem>
 552         </varlistentry>
 553         <varlistentry>
 554           <term><parameter>database</parameter></term>
 555           <listitem>
 556             <para>A
 557             <glossterm linkend="gloss-database-object">database
 558             object</glossterm>. This will default to the value
 559             of <symbol>*default-database*</symbol>.</para>
 560           </listitem>
 561         </varlistentry>
 562         <varlistentry>
 563           <term><parameter>result</parameter></term>
 564           <listitem>
 565             <para>The list of currently defined rollback hooks for
 566             <parameter>database</parameter>.
 567             </para>
 568           </listitem>
 569         </varlistentry>
 570       </variablelist>
 571     </refsect1>
 572     <refsect1>
 573       <title>Description</title>
 574       <para>
 575         Adds <parameter>rollback-hook</parameter>, which should a
 576         designator for a function with no required arguments, to the
 577         list of hooks run when <function>rollback</function> is called
 578         on <parameter>database</parameter> which defaults to
 579         <symbol>*default-database*</symbol>.  </para>
 580     </refsect1>
 581     <refsect1>
 582       <title>Examples</title>
 583       <screen>
 584 (start-transaction)
 585 => NIL
 586 (add-transaction-rollback-hook #'(lambda () (print "Successfully rolled back.")))
 587 => (#&lt;Interpreted Function (LAMBDA # #) {48E37C31}>)
 588 (rollback)
 589 "Successfully rolled back."
 590 => NIL
 591       </screen>
 592     </refsect1>
 593     <refsect1>
 594       <title>Side Effects</title>
 595       <para>
 596         <parameter>rollback-hook</parameter> is added to the list of
 597         rollback hooks for <parameter>database</parameter>.
 598       </para>
 599     </refsect1>
 600     <refsect1>
 601       <title>Affected by</title>
 602       <para>
 603         None.
 604       </para>
 605     </refsect1>
 606     <refsect1>
 607       <title>Exceptional Situations</title>
 608       <para>
 609         If <parameter>rollback-hook</parameter> has one or more
 610         required arguments, an error will be signalled when
 611         <function>rollback</function> is called.
 612       </para>
 613     </refsect1>
 614 <refsect1>
 615       <title>See Also</title>
 616       <simplelist>
 617         <member><link linkend="commit"><function>commit</function></link></member>
 618         <member><link linkend="rollback"><function>rollback</function></link></member>
 619         <member><link linkend="add-transaction-commit-hook"><function>add-transaction-commit-hook</function></link></member>
 620       </simplelist>
 621     </refsect1>
 622     <refsect1>
 623       <title>Notes</title>
 624       <para>
 625         <function>add-transaction-rollback-hook</function> is a &clsql; extension.
 626       </para>
 627     </refsect1>
 628   </refentry>
 629
 630   <refentry id="set-autocommit">
 631     <refmeta>
 632       <refentrytitle>SET-AUTOCOMMIT</refentrytitle>
 633     </refmeta>
 634     <refnamediv>
 635       <refname><emphasis>Function</emphasis> <emphasis role="bold">SET-AUTOCOMMIT</emphasis></refname>
 636       <refpurpose>Turn on or off autocommit for a database.</refpurpose>
 637       <refclass>Function</refclass>
 638     </refnamediv>
 639     <refsect1>
 640       <title>Syntax</title>
 641       <synopsis>
 642       <function>set-autocommit</function> <replaceable>value</replaceable> &amp;key <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
 643     </refsect1>
 644     <refsect1>
 645       <title>Arguments and Values</title>
 646       <variablelist>
 647         <varlistentry>
 648           <term><parameter>value</parameter></term>
 649           <listitem>
 650             <para>A Boolean specifying the desired autocommit
 651             behaviour for <parameter>database</parameter>.
 652             </para>
 653           </listitem>
 654         </varlistentry>
 655         <varlistentry>
 656           <term><parameter>database</parameter></term>
 657           <listitem>
 658             <para>A
 659             <glossterm linkend="gloss-database-object">database
 660             object</glossterm>. This will default to the value
 661             of <symbol>*default-database*</symbol>.</para>
 662           </listitem>
 663         </varlistentry>
 664         <varlistentry>
 665           <term><parameter>result</parameter></term>
 666           <listitem>
 667             <para>The previous autocommit value for
 668             <parameter>database</parameter>.
 669             </para>
 670           </listitem>
 671         </varlistentry>
 672       </variablelist>
 673     </refsect1>
 674     <refsect1>
 675       <title>Description</title>
 676       <para>Turns autocommit off for <parameter>database</parameter>
 677       if <parameter>value</parameter> is &nil;, and otherwise turns it
 678       on. Returns the old value of autocommit flag.
 679       </para>
 680       <para>
 681         For RDBMS (such as Oracle) which don't automatically commit
 682         changes, turning autocommit on has the effect of explicitly
 683         committing changes made whenever SQL statements are executed.
 684       </para>
 685       <para>
 686         Autocommit is turned on by default.
 687       </para>
 688     </refsect1>
 689     <refsect1>
 690       <title>Examples</title>
 691       <screen>
 692         <!-- examples -->
 693       </screen>
 694     </refsect1>
 695     <refsect1>
 696       <title>Side Effects</title>
 697       <para>
 698         <parameter>database</parameter> is associated with the specified
 699         autocommit mode.
 700       </para>
 701     </refsect1>
 702     <refsect1>
 703       <title>Affected by</title>
 704       <para>
 705         None.
 706       </para>
 707     </refsect1>
 708     <refsect1>
 709       <title>Exceptional Situations</title>
 710       <para>
 711         None.
 712       </para>
 713     </refsect1>
 714     <refsect1>
 715       <title>See Also</title>
 716       <simplelist>
 717         <member><link linkend="start-transaction"><function>start-transaction</function></link></member>
 718         <member><link linkend="commit"><function>commit</function></link></member>
 719         <member><link linkend="add-transaction-commit-hook"><function>add-transaction-commit-hook</function></link></member>
 720         <member><link linkend="with-transaction"><function>with-transaction</function></link></member>
 721       </simplelist>
 722     </refsect1>
 723     <refsect1>
 724       <title>Notes</title>
 725       <para>
 726         <function>set-autocommit</function> is a &clsql; extension.
 727       </para>
 728     </refsect1>
 729   </refentry>
 730
 731   <refentry id="with-transaction">
 732     <refmeta>
 733       <refentrytitle>WITH-TRANSACTION</refentrytitle>
 734     </refmeta>
 735     <refnamediv>
 736       <refname><emphasis>Macro</emphasis> <emphasis role="bold">WITH-TRANSACTION</emphasis></refname>
 737       <refpurpose>Execute a body of code within a transaction.</refpurpose>
 738       <refclass>Macro</refclass>
 739     </refnamediv>
 740     <refsect1>
 741       <title>Syntax</title>
 742       <synopsis>
 743       <function>with-transaction</function> &amp;key <replaceable>database</replaceable> &amp;rest <replaceable>body</replaceable> => <returnvalue>result</returnvalue></synopsis>
 744     </refsect1>
 745     <refsect1>
 746       <title>Arguments and Values</title>
 747       <variablelist>
 748         <varlistentry>
 749           <term><parameter>database</parameter></term>
 750           <listitem>
 751             <para>A
 752             <glossterm linkend="gloss-database-object">database
 753             object</glossterm>. This will default to the value
 754             of <symbol>*default-database*</symbol>.</para>
 755           </listitem>
 756 <varlistentry>
 757           <term><parameter>body</parameter></term>
 758           <listitem>
 759             <para>
 760               A body of Lisp code.
 761             </para>
 762           </listitem>
 763         </varlistentry>
 764         <varlistentry>
 765           <term><parameter>result</parameter></term>
 766           <listitem>
 767             <para>The result of executing <parameter>body</parameter>.</para>
 768           </listitem>
 769         </varlistentry>
 770         </varlistentry>
 771       </variablelist>
 772     </refsect1>
 773     <refsect1>
 774       <title>Description</title>
 775       <para>Starts a transaction in the database specified by
 776       <parameter>database</parameter>, which is
 777       <symbol>*default-database*</symbol> by default, and executes
 778       <parameter>body</parameter> within that transaction. If
 779       <parameter>body</parameter> aborts or throws,
 780       <parameter>database</parameter> is rolled back and otherwise the
 781       transaction is committed.
 782       </para>
 783     </refsect1>
 784     <refsect1>
 785       <title>Examples</title>
 786       <screen>
 787 (in-transaction-p)
 788 => NIL
 789 (select [email] :from [employee] :where [= [emplid] 1] :flatp t :field-names nil)
 790 => ("lenin@soviet.org")
 791 (with-transaction ()
 792    (update-records [employee]
 793                    :av-pairs '((email "lenin-nospam@soviet.org"))
 794                    :where [= [emplid] 1]))
 795 => NIL
 796 (select [email] :from [employee] :where [= [emplid] 1] :flatp t :field-names nil)
 797 => ("lenin-nospam@soviet.org")
 798 (in-transaction-p)
 799 => NIL
 800       </screen>
 801     </refsect1>
 802     <refsect1>
 803       <title>Side Effects</title>
 804       <para>
 805         Changes specified in <parameter>body</parameter> may be made
 806         to the underlying database if <parameter>body</parameter>
 807         completes successfully.
 808       </para>
 809     </refsect1>
 810     <refsect1>
 811       <title>Affected by</title>
 812       <para>
 813         None.
 814       </para>
 815     </refsect1>
 816     <refsect1>
 817       <title>Exceptional Situations</title>
 818       <para>
 819         Signals an error of type <symbol>sql-database-error</symbol>
 820         if <parameter>database</parameter> is not a database object.
 821         </para>
 822     </refsect1>
 823     <refsect1>
 824       <title>See Also</title>
 825       <simplelist>
 826         <member><link linkend="start-transaction"><function>start-transaction</function></link></member>
 827         <member><link linkend="commit"><function>commit</function></link></member>
 828         <member><link linkend="rollback"><function>rollback</function></link></member>
 829         <member><link linkend="add-transaction-commit-hook"><function>add-transaction-commit-hook</function></link></member>
 830         <member><link linkend="add-transaction-rollback-hook"><function>add-transaction-rollback-hook</function></link></member>
 831       </simplelist>
 832     </refsect1>
 833     <refsect1>
 834       <title>Notes</title>
 835       <para>
 836         None.
 837       </para>
 838     </refsect1>
 839   </refentry>
 840
 841
 842 </reference>