|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE task |
|
11 PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd"> |
|
12 <task id="GUID-5F641F7A-AEAA-5C3E-9179-C3707F10E6DC" xml:lang="en"><title>Starting |
|
13 and Finishing Transactions: Tutorial</title><shortdesc>This topic shows you how to start, finish and roll back a transaction |
|
14 with the Comms Database. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody> |
|
15 |
|
16 |
|
17 <prereq id="GUID-17B4987D-BD5C-5CD8-8E51-251431BD4E70"><p>Before you start, |
|
18 you must understand: </p> <ul> |
|
19 <li id="GUID-CE226134-308A-5B1C-BE3F-8AD1976CA1F0"><p>the general concept |
|
20 of the Comms Database </p> </li> |
|
21 <li id="GUID-5616BB6A-1FAE-56C3-B996-6AA7A1D41A75"><p>the specific concept |
|
22 of Comms Database Transactions </p> </li> |
|
23 <li id="GUID-F546E315-A6F2-5612-9DB2-66C6037E0FC3"><p>how to write and build |
|
24 application code to run on Symbian platform </p> </li> |
|
25 </ul> </prereq> |
|
26 <context id="GUID-47D01F8A-228E-5D1B-8764-13AC73E99950"><p>A transaction is |
|
27 a sequence of read and write operations. In a transaction all operations must |
|
28 be successful to make sure of the integrity of the data. </p> <p>A tool or |
|
29 application must mark the start of a transaction. The tool or application |
|
30 must also mark the end of a transaction. </p> <p>A transaction ends normally |
|
31 or the transaction is rolled back. A transaction is rolled back when one of |
|
32 the read or write operations fails. Other events can cause the tool or application |
|
33 to abandon the transaction. Other events depend on the purpose of the tool |
|
34 or application. </p> <p>Create a session with the Comms Database before you |
|
35 start a transaction. </p> <p>There are many ways to implement transactions. |
|
36 The procedure below is one method. The method shows the principle of transactions. |
|
37 The method you use depends on the organisation of your code. </p> </context> |
|
38 <steps id="GUID-012CB103-90DC-54F1-A4B4-512498EBC563"> |
|
39 <step id="GUID-1E102596-F9BE-57BD-84A4-4C51BCD8A340"><cmd>Make sure that you |
|
40 have created a session before you start your first transaction. </cmd> |
|
41 </step> |
|
42 <step id="GUID-02951E12-339B-52D2-B42F-4977DC543090"><cmd>Start the transaction |
|
43 before you start the operations that access the database. Commit the transaction |
|
44 if all operations are successful. Rollback the transaction if any operation |
|
45 fails. </cmd> |
|
46 |
|
47 <info>The code uses the functions: <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBSession::OpenTransactionL()</apiname></xref>, <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBSession::CommitTransactionL()</apiname></xref> and <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBSession::RollbackTransactionL()</apiname></xref>. </info> |
|
48 <stepxmp><codeblock id="GUID-FAD16FB7-AC98-5579-AF89-848633BA7D10" xml:space="preserve">... |
|
49 |
|
50 // This code fragment assumes that a session with the Comms Database has been created. |
|
51 // iDb is a pointer to a CMDBSession object |
|
52 |
|
53 TInt rc; |
|
54 |
|
55 TRAP(rc,PerformSequenceOfOperationsL()); |
|
56 if (!rc) |
|
57 { |
|
58 // Sequence of read and write operations has failed. |
|
59 iDb->RollbackTransactionL(); |
|
60 ... |
|
61 } |
|
62 ...</codeblock> </stepxmp> |
|
63 <stepxmp><codeblock id="GUID-B7D81AF6-6D77-5CE9-A91A-E8093BA2802E" xml:space="preserve">... |
|
64 void PerformSequenceOfOperationsL() |
|
65 { |
|
66 // Start a transaction |
|
67 iDb->OpenTransactionL(); |
|
68 ... |
|
69 // Sequence of read and write operations |
|
70 ... |
|
71 // Commit the changes to the Comms Database. This assumes that |
|
72 // all operations have completed successfully, and no other event has |
|
73 // caused the sequence of operations to be abandoned. |
|
74 iDb->CommitTransactionL() |
|
75 ... |
|
76 } |
|
77 ...</codeblock> </stepxmp> |
|
78 </step> |
|
79 </steps> |
|
80 </taskbody><related-links> |
|
81 <link href="GUID-1AFDDD6F-CB99-587D-A0B5-D3F5B27F7135.dita"><linktext>Comms Database |
|
82 concepts</linktext></link> |
|
83 </related-links></task> |