<?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-1F12E3F5-45B2-55EC-B021-00338277C608" xml:lang="en"><title>SQL

DB overview </title><shortdesc>Used to access and query relational databases using the SQL query

language.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-CC2C3F55-C82D-41CA-9035-DA3DEA45C2C8"><title>Purpose</title> <p>The SQL DB library allows developers to

access and query relational databases using the SQL query language. It also

provides functionality for securing databases and maintaining data integrity. </p> <p><b>Intended audience:</b> </p> <p>This document is intended to be used by

Symbian platform licensees and third party application developers. </p> <p><b>SQL DB library details</b> </p> <p>The DLL that provides the functionality

and the library to which your code must link is identified below. </p> <table id="GUID-590E4683-542E-54D2-95FC-7FF83C728B95">

<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>

<thead>

<row>

<entry>DLL</entry>

<entry>LIB</entry>

<entry>Short Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <filepath>sqldb.dll</filepath>  </p> </entry>

<entry><p> <filepath>sqldb.lib</filepath>  </p> </entry>

<entry><p>The Symbian platform implementation of SQL. </p> </entry>

</row>

</tbody>

</tgroup>

</table> </section>

<section id="GUID-F0C1300B-FF3E-481A-82E2-C93A063059BE"><title>Architectural relationship</title> <p>The SQL database service

is implemented using the standard Symbian platform client-server model. </p> <p><b>Description</b> </p> <p>The SQL DB library allows you to access and query

databases. </p> <p><b>Accessing

and querying databases</b> </p> <p>By accessing a database is meant creating,

opening and closing it. By querying a database is meant any read or write

operation performed by an SQL query, not just data retrieval. </p> <p><b>Accessing

databases</b> </p> <p>Database access operations include </p> <ul>

<li id="GUID-4176F81A-CC3E-5253-8CC3-BBBD99D69DD2"><p>creating and deleting

databases </p> </li>

<li id="GUID-A667905B-7B29-5B97-886E-2104762E9105"><p>creating security policies

and applying them to databases, </p> </li>

<li id="GUID-DC874CD5-B54D-58EE-B538-BCA7EBA2F238"><p>attaching and detaching

databases to each other, and </p> </li>

<li id="GUID-7B127B9A-608E-53CC-A81B-CC406D8AD8EC"><p>opening and closing

databases. </p> </li>

</ul> <p><b>Querying

databases</b> </p> <p>Database query operations include: </p> <ul>

<li id="GUID-E343FB81-F15E-50CF-BC37-B42A0CFAAB25"><p>preparing an SQL query

for use within Symbian platform, </p> </li>

<li id="GUID-D8815872-91E6-529D-8FD0-21C5EE4263B9"><p>indexing variables inside

the query to correspond to data table columns, </p> </li>

<li id="GUID-2FD10588-2F4C-5069-95CE-681F948A35E0"><p>binding values to variables

inside the query, and </p> </li>

<li id="GUID-AA74A3A6-5905-5A18-B632-AC71D4F720C0"><p>executing the query, </p> </li>

<li id="GUID-519C582D-11DC-51AC-AB29-B66891542451"><p>using the result of

the query, and </p> </li>

<li id="GUID-FEE60608-AABF-5D86-9B2D-98FECBE38E32"><p>closing the query. </p> </li>

</ul> </section>

<section id="GUID-6E56C72A-29E5-451D-85C8-07CB6062631B"><title>Key SQL DB classes</title> <p>The key classes that make up

the SQL DB component are as follows: </p> <ol id="GUID-E1BC7A5F-7F6A-596C-AE24-F618B323B38B">

<li id="GUID-352B4A83-96FC-5ABB-BBF3-9A16DFFA2818"><p> <xref href="GUID-4688F6B7-E1B0-37CF-BAA2-C6BD103D4FDF.dita"><apiname>RSqlDatabase</apiname></xref>  </p> <p>This

class represents a database and provides the functionality to: </p> <ul>

<li id="GUID-206EF4BF-091B-5D41-BBF7-45C5E6341762"><p>creates a secure shared,

non-secure shared or private database </p> </li>

<li id="GUID-05F39286-2C6D-5389-8196-8168105CACFD"><p>opens and closes named

(and previously created) databases </p> </li>

<li id="GUID-B3BDE645-F6E5-52B2-AB6D-7D29C48AE7E8"><p>attaches/detaches existing

databases </p> </li>

<li id="GUID-BEDF12B3-EFD0-50D5-803B-43570BD5CDBE"><p>copies named databases </p> </li>

<li id="GUID-E8FFDA2B-44CA-5052-A268-BF9F00A52F0D"><p>deletes named databases </p> </li>

<li id="GUID-B551CE70-E201-509B-9182-71677BA41854"><p>retrieves the security

policy </p> </li>

<li id="GUID-46BC8711-582F-50D4-B426-E3E153EA690A"><p>sets the isolation level

(currently supported levels - <xref href="GUID-26BE2671-7C38-3EC4-A742-5DBADBC97377.dita"><apiname>EReadUncommited</apiname></xref>, <xref href="GUID-0B361830-BE3B-3199-B62F-7EFB4490D70E.dita"><apiname>ESerializable</apiname></xref>) </p> </li>

<li id="GUID-48139D95-1994-589B-9F69-F37E6D3E013B"><p>Executes SQL statements

(however, this functionality is intended for SQL statements that do not return

data rows – see RSqlStatement for executing queries that return data). </p> </li>

<li id="GUID-34DB38FF-1937-5AC5-9D21-58AAE9816967"><p>retrieves database file

size and free space </p> </li>

<li id="GUID-643F5EE3-6765-57BE-8A73-A99EA0D9081B"><p>compacts the database </p> </li>

<li id="GUID-1C010A50-2E2E-50E5-80F6-DA4CA9C99FAD"><p>manages reserved drive

space </p> </li>

</ul> <p>The main responsibilities of this class are: </p> <ol id="GUID-AE265DBB-47F8-582B-8DEB-A4B968474780">

<li id="GUID-BDF4F7EE-3381-54E2-9760-638903BD0D3A"><p>create a secure or a

non-secure new database, </p> </li>

<li id="GUID-66E15DB8-6D7D-5C43-9580-21A0F54871CA"><p>open an existing database, </p> </li>

<li id="GUID-6135E1FD-70AF-5FFD-933D-8465BF0FD775"><p>close a database, </p> </li>

<li id="GUID-3ED09A98-48DC-597F-BB84-CCFD6CE4DBB7"><p>copy a database, </p> </li>

<li id="GUID-81E2B7ED-F6D4-5B8D-89CE-7900DE2787B7"><p>delete a database, </p> </li>

<li id="GUID-A3BB27E4-94B9-5E31-91AB-952DE1A23476"><p>attach a secondary database

to a primary database, </p> </li>

<li id="GUID-07ED62FB-5E9F-575D-A871-385455A737D7"><p>detach a secondary database

from a primary database. </p> </li>

</ol> </li>

<li id="GUID-EC9C979B-16C9-553B-9D03-7F389724C6CC"><p> <xref href="GUID-0176BF07-DF94-3259-8F90-DE030E35CE9A.dita"><apiname>RSqlStatement</apiname></xref>  </p> <p>This

class represents an SQL statement and provides the functionality to: </p> <ol id="GUID-39440DE3-644C-5C6F-90AB-A9C59C2CBFF4">

<li id="GUID-A346CC62-85D6-5A55-AA21-DC9860A83761"><p>preparing SQL statements

for execution </p> </li>

<li id="GUID-A536460E-B827-5030-ACD5-685D27BD4E6E"><p>resetting previously

prepared SQL statements </p> </li>

<li id="GUID-1EA39BCD-538B-5D8D-855E-3A9DEDE7CFF9"><p>closing SQL statements </p> </li>

<li id="GUID-A8966577-28CA-5F5F-95F3-2944EFDF3808"><p>binding substitutable

parameters into prepared SQL statements </p> </li>

<li id="GUID-BC969EDD-8F21-5B22-940B-AC81C223F77D"><p>executing prepared SQL

statements (two methods provided: (a) Next() for SELECT statements and (b)

Exec() for everything else) </p> </li>

<li id="GUID-A1015C1C-E59B-5CB6-9098-C96B4658AC76"><p>iteration through the

result set. </p> </li>

<li id="GUID-664F550D-4EBE-5270-AEB7-18229F4D050A"><p>Retrieving the column

count of the retrieved record(s) </p> </li>

<li id="GUID-55C6C2FA-7C00-5091-B775-CAB43114564B"><p>Retrieving the type,

declared type, index, size and value of a particular column of the retrieved

record(s) </p> </li>

</ol> <p>The main responsibilities of this class are: </p> <ul>

<li id="GUID-002C6394-E32A-5EA3-BA89-58B8FCA541FD"><p>prepare a statement, </p> </li>

<li id="GUID-8DD88F58-D8A5-5CCD-9C81-8004C41A7F3A"><p>index parameters of

a statement to columns of a data table, </p> </li>

<li id="GUID-E4D81BB3-9674-5AB4-A4B8-8B500A7D5F1B"><p>bind values to parameters

of the statement, </p> </li>

<li id="GUID-A16AD4D3-D7D6-5351-93E1-4C64AC94C07B"><p>reset the values of

parameters of the statement, </p> </li>

<li id="GUID-2C17E9DF-D64E-577E-A56F-5F59FBF3C98D"><p>execute the statement, </p> </li>

<li id="GUID-C0FE1771-9276-5D66-9E48-66DBEA5264D2"><p>read the result of the

statement, </p> </li>

<li id="GUID-3C603506-470D-5F24-88AF-FA23F77DB899"><p>close the statement. </p> </li>

</ul> </li>

<li id="GUID-EC6E7C22-C3C3-5C1A-9456-24349A64EE2F"><p> <xref href="GUID-56C52D43-C4A9-3B31-B154-CA1E77693F57.dita"><apiname>RSqlSecurityPolicy</apiname></xref>  </p> <p>This

class holds the collection of user permissions that make up a security policy

for a secure database. </p> </li>

</ol> </section>

<section id="GUID-31AAA9C3-D868-4DE3-940A-415C7F8A5915"><title>Using SQL DB</title> <p>The main uses of the SQL DB are: </p> <ul>

<li id="GUID-6FD03738-53E7-550A-8A03-9793D7CA0E36"><p>access a database (create

or opening an existing database), </p> </li>

<li id="GUID-811B026A-65A4-597E-B783-0D62A1F92659"><p>give a database a security

policy, if needed, </p> </li>

<li id="GUID-F777C9E5-CD9B-5705-B119-A6D96FA5B4BE"><p>query a database (select,

insert, modify and delete data), </p> </li>

<li id="GUID-78E18949-3725-5661-BE09-45594453959E"><p>close a database (and

possibly delete it). </p> </li>

</ul> </section>

</conbody><related-links>

<link href="GUID-22844C28-AB5B-5A6F-8863-7269464684B4.dita"><linktext>Symbian SQL

Overview</linktext></link>

<link href="GUID-78773BCA-ADF6-53E6-AC80-5CB2AE1F8BCC.dita"><linktext>SQL Server

Guide</linktext></link>