<?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<CCDConnectionPrefsRecord>* 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->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& aLeft, const CMDBRecordBase& aRight)

    {

    return (aLeft.RecordId()) < (aRight.RecordId()) ? -1 : 1;

    }

...

// Total number of records in the table

TInt totalcount = ptrConnPrefRecordSet->iRecords.Count();

...

// Sort the records. 

// 1. Define a TLinearOrder<T> class for a Connection Preferences record and instantiate 

//    the class.

// 2. Invoke the sort operation.

TLinearOrder<CMDBRecordBase> orderbyId(SortRecordsById); 

ptrConnPrefRecordSet->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>