7 Nokia Corporation - initial contribution. |
7 Nokia Corporation - initial contribution. |
8 Contributors: |
8 Contributors: |
9 --> |
9 --> |
10 <!DOCTYPE concept |
10 <!DOCTYPE concept |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
12 <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> |
12 <concept id="GUID-1F12E3F5-45B2-55EC-B021-00338277C608" xml:lang="en"><title>SQL |
|
13 DB overview </title><shortdesc>Used to access and query relational databases using the SQL query |
|
14 language.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <section id="GUID-CC2C3F55-C82D-41CA-9035-DA3DEA45C2C8"><title>Purpose</title> <p>The SQL DB library allows developers to |
|
16 access and query relational databases using the SQL query language. It also |
|
17 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 |
|
18 Symbian platform licensees and third party application developers. </p> <p><b>SQL DB library details</b> </p> <p>The DLL that provides the functionality |
|
19 and the library to which your code must link is identified below. </p> <table id="GUID-590E4683-542E-54D2-95FC-7FF83C728B95"> |
|
20 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/> |
|
21 <thead> |
|
22 <row> |
|
23 <entry>DLL</entry> |
|
24 <entry>LIB</entry> |
|
25 <entry>Short Description</entry> |
|
26 </row> |
|
27 </thead> |
|
28 <tbody> |
|
29 <row> |
|
30 <entry><p> <filepath>sqldb.dll</filepath> </p> </entry> |
|
31 <entry><p> <filepath>sqldb.lib</filepath> </p> </entry> |
|
32 <entry><p>The Symbian platform implementation of SQL. </p> </entry> |
|
33 </row> |
|
34 </tbody> |
|
35 </tgroup> |
|
36 </table> </section> |
|
37 <section id="GUID-F0C1300B-FF3E-481A-82E2-C93A063059BE"><title>Architectural relationship</title> <p>The SQL database service |
|
38 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 |
|
39 databases. </p> <p><b>Accessing |
|
40 and querying databases</b> </p> <p>By accessing a database is meant creating, |
|
41 opening and closing it. By querying a database is meant any read or write |
|
42 operation performed by an SQL query, not just data retrieval. </p> <p><b>Accessing |
|
43 databases</b> </p> <p>Database access operations include </p> <ul> |
|
44 <li id="GUID-4176F81A-CC3E-5253-8CC3-BBBD99D69DD2"><p>creating and deleting |
|
45 databases </p> </li> |
|
46 <li id="GUID-A667905B-7B29-5B97-886E-2104762E9105"><p>creating security policies |
|
47 and applying them to databases, </p> </li> |
|
48 <li id="GUID-DC874CD5-B54D-58EE-B538-BCA7EBA2F238"><p>attaching and detaching |
|
49 databases to each other, and </p> </li> |
|
50 <li id="GUID-7B127B9A-608E-53CC-A81B-CC406D8AD8EC"><p>opening and closing |
|
51 databases. </p> </li> |
|
52 </ul> <p><b>Querying |
|
53 databases</b> </p> <p>Database query operations include: </p> <ul> |
|
54 <li id="GUID-E343FB81-F15E-50CF-BC37-B42A0CFAAB25"><p>preparing an SQL query |
|
55 for use within Symbian platform, </p> </li> |
|
56 <li id="GUID-D8815872-91E6-529D-8FD0-21C5EE4263B9"><p>indexing variables inside |
|
57 the query to correspond to data table columns, </p> </li> |
|
58 <li id="GUID-2FD10588-2F4C-5069-95CE-681F948A35E0"><p>binding values to variables |
|
59 inside the query, and </p> </li> |
|
60 <li id="GUID-AA74A3A6-5905-5A18-B632-AC71D4F720C0"><p>executing the query, </p> </li> |
|
61 <li id="GUID-519C582D-11DC-51AC-AB29-B66891542451"><p>using the result of |
|
62 the query, and </p> </li> |
|
63 <li id="GUID-FEE60608-AABF-5D86-9B2D-98FECBE38E32"><p>closing the query. </p> </li> |
|
64 </ul> </section> |
|
65 <section id="GUID-6E56C72A-29E5-451D-85C8-07CB6062631B"><title>Key SQL DB classes</title> <p>The key classes that make up |
|
66 the SQL DB component are as follows: </p> <ol id="GUID-E1BC7A5F-7F6A-596C-AE24-F618B323B38B"> |
|
67 <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 |
|
68 class represents a database and provides the functionality to: </p> <ul> |
|
69 <li id="GUID-206EF4BF-091B-5D41-BBF7-45C5E6341762"><p>creates a secure shared, |
|
70 non-secure shared or private database </p> </li> |
|
71 <li id="GUID-05F39286-2C6D-5389-8196-8168105CACFD"><p>opens and closes named |
|
72 (and previously created) databases </p> </li> |
|
73 <li id="GUID-B3BDE645-F6E5-52B2-AB6D-7D29C48AE7E8"><p>attaches/detaches existing |
|
74 databases </p> </li> |
|
75 <li id="GUID-BEDF12B3-EFD0-50D5-803B-43570BD5CDBE"><p>copies named databases </p> </li> |
|
76 <li id="GUID-E8FFDA2B-44CA-5052-A268-BF9F00A52F0D"><p>deletes named databases </p> </li> |
|
77 <li id="GUID-B551CE70-E201-509B-9182-71677BA41854"><p>retrieves the security |
|
78 policy </p> </li> |
|
79 <li id="GUID-46BC8711-582F-50D4-B426-E3E153EA690A"><p>sets the isolation level |
|
80 (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> |
|
81 <li id="GUID-48139D95-1994-589B-9F69-F37E6D3E013B"><p>Executes SQL statements |
|
82 (however, this functionality is intended for SQL statements that do not return |
|
83 data rows – see RSqlStatement for executing queries that return data). </p> </li> |
|
84 <li id="GUID-34DB38FF-1937-5AC5-9D21-58AAE9816967"><p>retrieves database file |
|
85 size and free space </p> </li> |
|
86 <li id="GUID-643F5EE3-6765-57BE-8A73-A99EA0D9081B"><p>compacts the database </p> </li> |
|
87 <li id="GUID-1C010A50-2E2E-50E5-80F6-DA4CA9C99FAD"><p>manages reserved drive |
|
88 space </p> </li> |
|
89 </ul> <p>The main responsibilities of this class are: </p> <ol id="GUID-AE265DBB-47F8-582B-8DEB-A4B968474780"> |
|
90 <li id="GUID-BDF4F7EE-3381-54E2-9760-638903BD0D3A"><p>create a secure or a |
|
91 non-secure new database, </p> </li> |
|
92 <li id="GUID-66E15DB8-6D7D-5C43-9580-21A0F54871CA"><p>open an existing database, </p> </li> |
|
93 <li id="GUID-6135E1FD-70AF-5FFD-933D-8465BF0FD775"><p>close a database, </p> </li> |
|
94 <li id="GUID-3ED09A98-48DC-597F-BB84-CCFD6CE4DBB7"><p>copy a database, </p> </li> |
|
95 <li id="GUID-81E2B7ED-F6D4-5B8D-89CE-7900DE2787B7"><p>delete a database, </p> </li> |
|
96 <li id="GUID-A3BB27E4-94B9-5E31-91AB-952DE1A23476"><p>attach a secondary database |
|
97 to a primary database, </p> </li> |
|
98 <li id="GUID-07ED62FB-5E9F-575D-A871-385455A737D7"><p>detach a secondary database |
|
99 from a primary database. </p> </li> |
|
100 </ol> </li> |
|
101 <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 |
|
102 class represents an SQL statement and provides the functionality to: </p> <ol id="GUID-39440DE3-644C-5C6F-90AB-A9C59C2CBFF4"> |
|
103 <li id="GUID-A346CC62-85D6-5A55-AA21-DC9860A83761"><p>preparing SQL statements |
|
104 for execution </p> </li> |
|
105 <li id="GUID-A536460E-B827-5030-ACD5-685D27BD4E6E"><p>resetting previously |
|
106 prepared SQL statements </p> </li> |
|
107 <li id="GUID-1EA39BCD-538B-5D8D-855E-3A9DEDE7CFF9"><p>closing SQL statements </p> </li> |
|
108 <li id="GUID-A8966577-28CA-5F5F-95F3-2944EFDF3808"><p>binding substitutable |
|
109 parameters into prepared SQL statements </p> </li> |
|
110 <li id="GUID-BC969EDD-8F21-5B22-940B-AC81C223F77D"><p>executing prepared SQL |
|
111 statements (two methods provided: (a) Next() for SELECT statements and (b) |
|
112 Exec() for everything else) </p> </li> |
|
113 <li id="GUID-A1015C1C-E59B-5CB6-9098-C96B4658AC76"><p>iteration through the |
|
114 result set. </p> </li> |
|
115 <li id="GUID-664F550D-4EBE-5270-AEB7-18229F4D050A"><p>Retrieving the column |
|
116 count of the retrieved record(s) </p> </li> |
|
117 <li id="GUID-55C6C2FA-7C00-5091-B775-CAB43114564B"><p>Retrieving the type, |
|
118 declared type, index, size and value of a particular column of the retrieved |
|
119 record(s) </p> </li> |
|
120 </ol> <p>The main responsibilities of this class are: </p> <ul> |
|
121 <li id="GUID-002C6394-E32A-5EA3-BA89-58B8FCA541FD"><p>prepare a statement, </p> </li> |
|
122 <li id="GUID-8DD88F58-D8A5-5CCD-9C81-8004C41A7F3A"><p>index parameters of |
|
123 a statement to columns of a data table, </p> </li> |
|
124 <li id="GUID-E4D81BB3-9674-5AB4-A4B8-8B500A7D5F1B"><p>bind values to parameters |
|
125 of the statement, </p> </li> |
|
126 <li id="GUID-A16AD4D3-D7D6-5351-93E1-4C64AC94C07B"><p>reset the values of |
|
127 parameters of the statement, </p> </li> |
|
128 <li id="GUID-2C17E9DF-D64E-577E-A56F-5F59FBF3C98D"><p>execute the statement, </p> </li> |
|
129 <li id="GUID-C0FE1771-9276-5D66-9E48-66DBEA5264D2"><p>read the result of the |
|
130 statement, </p> </li> |
|
131 <li id="GUID-3C603506-470D-5F24-88AF-FA23F77DB899"><p>close the statement. </p> </li> |
|
132 </ul> </li> |
|
133 <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 |
|
134 class holds the collection of user permissions that make up a security policy |
|
135 for a secure database. </p> </li> |
|
136 </ol> </section> |
|
137 <section id="GUID-31AAA9C3-D868-4DE3-940A-415C7F8A5915"><title>Using SQL DB</title> <p>The main uses of the SQL DB are: </p> <ul> |
|
138 <li id="GUID-6FD03738-53E7-550A-8A03-9793D7CA0E36"><p>access a database (create |
|
139 or opening an existing database), </p> </li> |
|
140 <li id="GUID-811B026A-65A4-597E-B783-0D62A1F92659"><p>give a database a security |
|
141 policy, if needed, </p> </li> |
|
142 <li id="GUID-F777C9E5-CD9B-5705-B119-A6D96FA5B4BE"><p>query a database (select, |
|
143 insert, modify and delete data), </p> </li> |
|
144 <li id="GUID-78E18949-3725-5661-BE09-45594453959E"><p>close a database (and |
|
145 possibly delete it). </p> </li> |
|
146 </ul> </section> |
|
147 </conbody><related-links> |
|
148 <link href="GUID-22844C28-AB5B-5A6F-8863-7269464684B4.dita"><linktext>Symbian SQL |
|
149 Overview</linktext></link> |
|
150 <link href="GUID-78773BCA-ADF6-53E6-AC80-5CB2AE1F8BCC.dita"><linktext>SQL Server |
|
151 Guide</linktext></link> |
|
152 </related-links></concept> |