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

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept xml:lang="en" id="GUID-1D836FB1-9BCA-53B5-8334-08CD59064227"><title>What are transactions</title><shortdesc>This topic describes the purpose of transactions when accessing the Comms Database. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> <p>The CommsDat API provides the behaviour known as transactions. Tools and applications use transactions to make sure that read and write operations are consistent. </p> <p>More than one application can use the Comms Database at the same time. Transactions implement a lock that allows applications to perform a set of read and write operations safely. In a transaction, other applications cannot change the data. </p> <p>The <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBSession</apiname></xref> class provides the functions that implement transactions. </p> <p>You must create a session with the Comms Database before you start your first transaction. </p> <p>A transaction starts with a call to <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBSession::OpenTransactionL()</apiname></xref>, and ends with a call to <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBSession::CommitTransactionL()</apiname></xref> or <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBSession::RollbackTransactionL()</apiname></xref>. </p> <p>A call to <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBSession::OpenTransactionL()</apiname></xref> starts a transaction. </p> <p>A call to <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBSession::CommitTransactionL()</apiname></xref> or <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBSession::RollbackTransactionL()</apiname></xref> ends a transaction. </p> <p>Between the start and end of a transaction, the CommsDat API makes sure that: </p> <ul><li id="GUID-B5C8B70D-00D0-5494-B5F4-F9AACD9EFD82"><p>a write operation started by another session cannot interrupt a read operation or a read/write operation started by this session. </p> </li> <li id="GUID-5B44CDC8-8209-5D0D-AEEB-93561B8BAFC6"><p>all read/write operations succeed after a succesful call to <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBSession::CommitTransactionL()</apiname></xref>. </p> </li> <li id="GUID-E11D6C59-92AB-54A6-BFFE-D2252ADDC531"><p>all read/write operations are discarded after a successful call to <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBSession::RollbackTransactionL()</apiname></xref> / </p> </li> <li id="GUID-70FC20C5-F311-5565-84D5-39364B0A44FC"><p>the changes are visible only to the tool or application that started the transaction. To the tool or application, the changes appear to have been written to the Comms Database. </p> </li> <li id="GUID-95086549-87D6-5B4D-B9C1-182512CE0603"><p>other users of the Comms Database cannot see the changes made by a transaction until that transaction is committed. </p> </li> </ul> <p>The CommsDat API cannot make other guarantees. Tools and applications must not make assumptions about the lock mechanism used by the implementation of the Comms Database. </p> <p>Tools and applications must make sure that transactions are short. The Comms Database is a shared resource, and long transactions cause performance problems. The Comms Database implements a timeout to protect the database. The Comms Database can terminate very long transactions. The timeout does not affect the normal operation. </p> <p>It is more efficient to wrap several write operations in one transaction, because data is only written to the Comms Database in a call to <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBSession::CommitTransactionL()</apiname></xref>. Tools and applications must not hold a transaction open for longer than is necessary. </p> <p>All read and write functions provided by <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>MMetaDatabase</apiname></xref> use transactions internally and are consistent. </p> </conbody></concept>