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