<?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 task
  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<task id="GUID-CE011029-0F2B-50D4-B793-A24C7ECFC21E" xml:lang="en"><title>Loading
a Symbian Platform Defined Table: Tutorial</title><shortdesc>This tutorial shows you how to load a Symbian platform defined
table from the Comms Database. The topic also gives an example that shows
you how to process the records in a table. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>
<prereq id="GUID-68076901-260F-5588-B05A-5B51412DEE43"><p>Before you start,
you must understand: </p> <ul>
<li id="GUID-AA2573E6-E199-5E5B-B458-DC189FE982F0"><p>the general concept
of the Comms Database </p> </li>
<li id="GUID-43160B1C-200E-5326-9CE8-474A49A81C4E"><p>the specific concept
of fields, records, links and tables </p> </li>
<li id="GUID-2CED5E8A-83C3-5CCE-B91D-9E773AFEBB2D"><p>how to write and build
application code to run on Symbian platform</p> </li>
</ul> </prereq>
<context id="GUID-770B3F59-5FA6-58C6-A484-118DB7288D3B"><p>This tutorial shows
you how to load the <i>Connection Preferences</i> table. The principles that
apply here also apply to the other Symbian platform defined tables. </p> <p>This
tutorial shows you the main steps. </p> <p>This tutorial also shows how you
can process the records in the table. The example code shows you how to sort
the records in the table. </p> </context>
<steps id="GUID-03C423B7-1C20-592A-9E8D-0D7D996E2A05">
<step id="GUID-0DE3770C-9E39-5A43-88F3-5957F5627317"><cmd>Make sure that you
have created a session. </cmd>
</step>
<step id="GUID-3F0C9272-6A9E-52DF-9711-F44036BC87CE"><cmd>Create the table
object in the tool or application process. </cmd>

<info>You create a <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBRecordSet</apiname></xref> <codeph>&lt;T&gt;</codeph> object
and specify <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CCDConnectionPrefsRecord</apiname></xref> as
the template parameter. </info>

<info>Symbian platform defines the <codeph>CCDConnectionPrefsRecord</codeph> class
to represent a Connection Preferences record. The class is a schema for the
record. The class defines the fields and links that make a Connection Preferences
record. </info>
<info>Symbian platform defines <xref href="GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84.dita#GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84/GUID-32E556BC-55C3-5FBD-9A60-9708139C20D6">unique
numeric Id</xref> s for Symbian platform defined tables. The symbol <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>KCDTIdConnectionPrefsRecord</apiname></xref> defines the value
of this Id for the Connection Preferences table. The Id allows the CommsDat
API to retrieve the table from the Comms Database efficiently. </info>
<info>To work with other Symbian platform defined tables, use
the correct class name and the correct unique numeric Id values. The <xref href="GUID-58089281-9DD0-502D-8DFD-831E7BAA931E.dita">Reference</xref> section
contains a list of all Symbian  defined tables. </info>
<stepxmp><codeblock id="GUID-B141FB9E-11BA-53FB-912C-4A86294161EB" xml:space="preserve">...

// This code fragment assumes that a session with the Comms Database has been created.
// iDb is a pointer to a CMDBSession object
...

// Use the standard "new (ELeave)" construction to create the object to 
// represent the table. 
//
// Note:
// 1. the template parameter CCDConnectionPrefsRecord defines 
//    the "Connection Preferences" record type.
// 2. the unique numeric Id KCDTIdConnectionPrefsRecord is passed as a parameter
//    to the constructor.
CMDBRecordSet&lt;CCDConnectionPrefsRecord&gt;* ptrConnPrefRecordSet = 
   new (ELeave) CMDBRecordSet(KCDTIdConnectionPrefsRecord);
...
             </codeblock> </stepxmp>
</step>
<step id="GUID-A622B842-A502-573A-BCD0-E521AA5C7011"><cmd>Load the table from
the Comms Database. </cmd>

<info>Use the <codeph>LoadL()</codeph> function to load the table from the
Comms Database. The function is called on the class that defines the table.
The function is implemented in the base class <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>MMetaDatabase</apiname></xref>.
You pass a reference to the session object into the <codeph>LoadL()</codeph> function. </info>
<stepxmp><codeblock id="GUID-3B4F5F6D-4ACE-560D-BBF7-1DCC037AAADE" xml:space="preserve">...
ptrConnPrefRecordSet-&gt;LoadL(*iDb);
// If the flow of the code reaches here, the table has been loaded.        
...</codeblock> </stepxmp>
</step>
<step id="GUID-7A9CA79C-79FD-570A-9D48-82565878E422"><cmd>Process the records. </cmd>

<info>This step is optional. It is an example that shows how you can process
the records in a table. The example also shows you how to retrieve the number
of records in the table. </info>
<stepxmp>The following code sorts the records into record Id order. The record
Id is the part of the <xref href="GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84.dita#GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84/GUID-32E556BC-55C3-5FBD-9A60-9708139C20D6">unique
numeric Id</xref> that identifies an instance of a record. </stepxmp>
<stepxmp>A table uses an <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>RPointerArray</apiname></xref> <codeph>&lt;T&gt;</codeph> to
contain the records. <codeph>RPointerArray</codeph> allows applications to
customise the behaviour of the sort operation. </stepxmp>
<info>The code uses the <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>TLinearOrder</apiname></xref> <codeph>&lt;T&gt;</codeph> class. </info>
<stepxmp><codeblock id="GUID-FE35BC1E-1D10-5741-9684-4C6383A226AC" xml:space="preserve">...
// Customised sort function
TInt SortRecordsById(const CMDBRecordBase&amp; aLeft, const CMDBRecordBase&amp; aRight)
    {
    return (aLeft.RecordId()) &lt; (aRight.RecordId()) ? -1 : 1;
    }
...

// Total number of records in the table
TInt totalcount = ptrConnPrefRecordSet-&gt;iRecords.Count();
...

// Sort the records. 
// 1. Define a TLinearOrder&lt;T&gt; class for a Connection Preferences record and instantiate 
//    the class.
// 2. Invoke the sort operation.
TLinearOrder&lt;CMDBRecordBase&gt; orderbyId(SortRecordsById); 
ptrConnPrefRecordSet-&gt;iRecords.Sort(orderbyId); 
...</codeblock> </stepxmp>
</step>
</steps>
</taskbody><related-links>
<link href="GUID-1AFDDD6F-CB99-587D-A0B5-D3F5B27F7135.dita"><linktext>Comms Database
                concepts</linktext></link>
</related-links></task>