<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE task

  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

<task id="GUID-5F641F7A-AEAA-5C3E-9179-C3707F10E6DC" xml:lang="en"><title>Starting

and Finishing Transactions: Tutorial</title><shortdesc>This topic shows you how to start, finish and roll back a transaction

with the Comms Database. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>

<prereq id="GUID-17B4987D-BD5C-5CD8-8E51-251431BD4E70"><p>Before you start,

you must understand: </p> <ul>

<li id="GUID-CE226134-308A-5B1C-BE3F-8AD1976CA1F0"><p>the general concept

of the Comms Database </p> </li>

<li id="GUID-5616BB6A-1FAE-56C3-B996-6AA7A1D41A75"><p>the specific concept

of Comms Database Transactions </p> </li>

<li id="GUID-F546E315-A6F2-5612-9DB2-66C6037E0FC3"><p>how to write and build

application code to run on Symbian platform </p> </li>

</ul> </prereq>

<context id="GUID-47D01F8A-228E-5D1B-8764-13AC73E99950"><p>A transaction is

a sequence of read and write operations. In a transaction all operations must

be successful to make sure of the integrity of the data. </p> <p>A tool or

application must mark the start of a transaction. The tool or application

must also mark the end of a transaction. </p> <p>A transaction ends normally

or the transaction is rolled back. A transaction is rolled back when one of

the read or write operations fails. Other events can cause the tool or application

to abandon the transaction. Other events depend on the purpose of the tool

or application. </p> <p>Create a session with the Comms Database before you

start a transaction. </p> <p>There are many ways to implement transactions.

The procedure below is one method. The method shows the principle of transactions.

The method you use depends on the organisation of your code. </p> </context>

<steps id="GUID-012CB103-90DC-54F1-A4B4-512498EBC563">

<step id="GUID-1E102596-F9BE-57BD-84A4-4C51BCD8A340"><cmd>Make sure that you

have created a session before you start your first transaction. </cmd>

</step>

<step id="GUID-02951E12-339B-52D2-B42F-4977DC543090"><cmd>Start the transaction

before you start the operations that access the database. Commit the transaction

if all operations are successful. Rollback the transaction if any operation

fails. </cmd>

<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>

<stepxmp><codeblock id="GUID-FAD16FB7-AC98-5579-AF89-848633BA7D10" xml:space="preserve">...

// This code fragment assumes that a session with the Comms Database has been created.

// iDb is a pointer to a CMDBSession object

TInt rc;

TRAP(rc,PerformSequenceOfOperationsL());

if (!rc)

    {

    // Sequence of read and write operations has failed.

    iDb->RollbackTransactionL();

    ...

    }

...</codeblock> </stepxmp>

<stepxmp><codeblock id="GUID-B7D81AF6-6D77-5CE9-A91A-E8093BA2802E" xml:space="preserve">...

void PerformSequenceOfOperationsL()

    {

    // Start a transaction

    iDb->OpenTransactionL();

    ...

    // Sequence of read and write operations

    ...

    // Commit the changes to the Comms Database. This assumes that

    // all operations have completed successfully, and no other event has

    // caused the sequence of operations to be abandoned.

    iDb->CommitTransactionL()

    ...

    }

...</codeblock> </stepxmp>

</step>

</steps>

</taskbody><related-links>

<link href="GUID-1AFDDD6F-CB99-587D-A0B5-D3F5B27F7135.dita"><linktext>Comms Database

                concepts</linktext></link>

</related-links></task>