<?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 id="GUID-FF28B015-DFC5-5656-9066-FBCCBA2818AF" xml:lang="en"><title>Transactions

and locks</title><shortdesc>Describes transactions and locks. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>When multiple clients can access the same database, transactions ensure

that only one client can change data at a time.</p>

<p>DBMS transactions do not provide any form of isolation between clients;

while one client is updating a table within a transaction, other clients can

see the changes as they are made. For example, if a client retrieves two separate

rows from a database, there is no automatic guarantee that the data being

retrieved has not been changed between the reads; this can lead to an ‘inconsistent

read’. A client can prevent an update while retrieving related rows by enclosing

the individual reads within a transaction. Such a transaction does not modify

the database and only operates as a read-lock; the <codeph>Commit()</codeph> or <codeph>Rollback()</codeph> member

functions of the abstract base class <codeph>RDbDatabase</codeph> releases

such a lock and does not affect the database in any way.</p>

<p>In practice:</p>

<ul>

<li id="GUID-472055B2-90BF-523F-B1D7-22A8D45EDBC2"><p>calling <codeph>Begin()</codeph> (a

member of <codeph>RDbDatabase</codeph>) on a shared database attempts to get

a shared read-lock on the database; this fails if <i>any</i> other client

already has an exclusive write-lock. Other clients with read-locks will not

cause this operation to fail.</p> </li>

<li id="GUID-419F8999-E7A4-5C0E-8CAB-A21C59BCCFD1"><p>any operation which

modifies the database, tries to gain an exclusive write-lock on it; this fails

if any other client has <i>any kind</i> of lock on that database. If the current

client already has a read-lock as a result of calling <codeph>Begin()</codeph>,

then the lock is upgraded to an exclusive write-lock.</p> </li>

<li id="GUID-73E720B6-DEFC-5A5B-9B0F-14B1C470A072"><p>calling <codeph>Commit()</codeph> or <codeph>Rollback()</codeph> after

a read-lock has been acquired (but not a write-lock) releases the client's

lock. The database is only considered to be unlocked when <i>all</i> such

locks are removed by <i>all</i> clients, when it will report a <codeph>RDbNotifier::EUnlock</codeph> database

event to any change notifier.</p> </li>

<li id="GUID-FD4EECEB-0B67-5490-841A-C57A3BC189E9"><p>calling <codeph>Commit()</codeph> or <codeph>Rollback()</codeph> after

a write-lock has been acquired releases the client's lock and reports a <codeph>RDbNotifier::ECommit</codeph> or

a <codeph>RDbNotifier::ERollback</codeph> database event to any change notifier.</p> </li>

<li id="GUID-6EF537DD-D7CA-52A4-9164-E78EC961AF0A"><p>automatic transactions

are used if updates are made outside of explicit transactions; such updates

can also fail if an exclusive lock cannot be acquired.</p> </li>

</ul>

<p>Sharing read-locks enables greater concurrency while providing some safe

guard against inconsistent reads. However, there is the possibility of a deadlock

occurring. If two clients want to update a database and both <codeph>Begin()</codeph> a

transaction before either of them starts an update, then one client's read-lock

will prevent the other from upgrading to a write lock and vice versa. The

only way out of this is to code the clients in such a way as to back out of

such a deadlock situation, rather than retry forever without releasing the

locks.</p>

<p>To prevent a single transaction from containing both data modification

and data definition statements, all affected cursors are invalidated when

the definition of their underlying table is changed. Such a cursor reports

a <codeph>KErrDisconnected</codeph> error in this state and can only be closed

and the rowset re-generated once the DDL (SQL schema update) statement has

completed. Calling <codeph>Reset()</codeph> on such a cursor has no effect.

It is impossible to update rows while changing the schema.</p>

<p>A client can change the database schema while other clients are using that

database provided that they have no locks on it. However, those other clients

may find that their rowsets are invalidated asynchronously.</p>