<?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-1F12E3F5-45B2-55EC-B021-00338277C608"><title>SQL DB overview </title><prolog><metadata><keywords/></metadata></prolog><conbody><p>Used to access and query relational databases using the SQL query language. </p> <section><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 OS 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 OS implementation of SQL. </p> </entry> </row> </tbody> </tgroup> </table> </section> <section><title>Architectural relationship</title> <p>The SQL database service is implemented using the standard Symbian OS 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 OS, </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><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><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> </related-links></concept>