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