<?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-E71DEB5F-A13A-5675-B2DE-9BCFDB38A3EC"><title>What is the mechanism for reading, writing and searching for data</title><shortdesc>This topic describes the mechanism for reading data from the Comms Database and writing data to the Comms Database. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><p>All elements that you can read and write have the class <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>MMetaDatabase</apiname></xref> as a base class. This base class contains the functions that get and store that element. </p> <p>Tables, records, links and fields are all elements. The classes that represent tables, records, links and fields have <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>MMetaDatabase</apiname></xref> in their class hierarchy. You use the functions in <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>MMetaDatabase</apiname></xref> to load and store tables, records, links and fields. </p> <fig id="GUID-3EED9581-A88B-5E79-B672-42486CFB6BE3"><image href="GUID-69831D75-D16D-54CF-A083-0EDB358F3390_d0e80082_href.png" placement="inline"/></fig> <p>The <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>MMetaDatabase</apiname></xref> class gives you: </p> <ul><li id="GUID-3D33E6EE-F6FA-5B75-A165-4A8731BD2FCB"><p>the functions to get data from the Comms Database: <codeph>LoadL()</codeph>, <codeph>FindL()</codeph>, <codeph>RefreshL()</codeph>  </p> </li> <li id="GUID-413D285C-2447-5157-B573-51056F79C50D"><p>the functions to put data into the Comms Database: <codeph>StoreL()</codeph>, <codeph>ModifyL()</codeph>, <codeph>DeleteL()</codeph>  </p> </li> </ul> <section><title>Getting data directly from the Comms Database</title> <p>If you know the record Id part of the <xref href="GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84.dita#GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84/GUID-4DDD4947-D379-5B68-8DC0-B67B074FA852">element Id</xref> of a table, record, field or link, you can load the table, record, field or link from the Comms Database. Call <codeph>SetRecordId()</codeph> on the <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBElement</apiname></xref> base class to set the record Id. Call <codeph>LoadL()</codeph> on the <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>MMetaDatabase</apiname></xref> base class to load the table, record, field or link. </p> <p>The CommsDat API gets the data that the tool or application is allowed to see from the Comms database. The data that the tool or application can see depends on platform security capabilities and the access attributes for the session. </p> <p>A request to load a single element fails if the tool or application does not have the platform security capabilities. </p> <p>A request to load a table does not fail if some records in the table are not available. The tool or application can see only those records that are available. </p> <p>A request to load a record does not fail if some fields in the record are not available. The tool or application can see only those fields that are available. </p> <p> <codeph>LoadL()</codeph> writes over the content of the table, record, field or link object in memory. </p> <p> <codeph>LoadL()</codeph> opens a read-only transaction with the Comms Database if the tool or application has not already started a transaction. </p> </section> <section><title>Finding data in the Comms Database</title> <p>You can search for records in the Comms Database. There are two patterns: </p> <p><b>Finding a single record that has specified field values </b> </p> <p>You create a <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBRecordBase</apiname></xref> object in memory. You select the fields for the search and set the field values. Call <codeph>FindL()</codeph> on the <codeph>CMDBRecordBase</codeph> object. <codeph>FindL()</codeph> is member of the <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>MMetaDatabase</apiname></xref> base class. If the search is successful, the CommsDat API fills the <codeph>CMDBRecordBase</codeph> object with the values from the first record in the Comms Database that matches. The values include the <xref href="GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84.dita#GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84/GUID-4DDD4947-D379-5B68-8DC0-B67B074FA852">element Id</xref>. If the search is not successful, the <codeph>CMDBRecordBase</codeph> object is not changed. </p> <p> <codeph>FindL()</codeph> opens a read-only transaction with the Comms Database if the tool or application has not already started a transaction. </p> <p>Note that you do not need to set the record Id part of the <xref href="GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84.dita#GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84/GUID-4DDD4947-D379-5B68-8DC0-B67B074FA852">element Id</xref> of the table, the record, the field or the link object. </p> <p><b>Finding all records in a table that match a specified record </b> </p> <p>You create a <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBRecordSet</apiname></xref> object and append a single record to the array of records. You select the fields for the search and set the field values. This record is the 'search record'. Call <codeph>FindL()</codeph> on the <codeph>CMDBRecordSet</codeph> object. If the search is successful, the function returns a number of complete records. The first record found writes over the 'search record'. If the search is not successful, the <codeph>CMDBRecordSet</codeph> object is not changed </p> <p> <codeph>FindL()</codeph> opens a read-only transaction with the Comms Database if the tool or application has not already started a transaction. </p> <p>Note that you do not need to set the record Id part of the <xref href="GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84.dita#GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84/GUID-4DDD4947-D379-5B68-8DC0-B67B074FA852">element Id</xref> of the table, the record, the field or the link object. </p> </section> <section><title>Refreshing data in memory</title> <p>You can update your copy of the data in memory. You call <codeph>RefreshL()</codeph> to update the data. The method is similar to <codeph>LoadL()</codeph> but the method does not write over fields that the tool or application has changed. All other fields are refreshed from the Comms Database. </p> <p> <codeph>RefreshL()</codeph> is a member of the <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>MMetaDatabase</apiname></xref> base class. </p> <p> <codeph>RefreshL()</codeph> is useful if a tool or application maintains a cache of Comms information. </p> <p> <codeph>RefreshL()</codeph> opens a read-only transaction with the Comms Database if the tool or application has not already started a transaction. </p> </section> <section><title>Adding new data to the Comms Database</title> <p>If need to add or change the data in the Comms Database you must add or change the data in the table, the record, the link or the field object in memory. </p> <p>Call <codeph>StoreL()</codeph> to create new records, tables and fields. The CommsDat API only stores the fields that the tool or application has changed. </p> <p>A table, record, field or link object that exists must have a valid <xref href="GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84.dita#GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84/GUID-4DDD4947-D379-5B68-8DC0-B67B074FA852">element Id</xref> before the call to <codeph>StoreL()</codeph>. </p> <p>To add a new user defined table to the Comms Database set the record Id part of the <xref href="GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84.dita#GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84/GUID-4DDD4947-D379-5B68-8DC0-B67B074FA852">element Id</xref> of the table to <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>KCDNewTableRequest</apiname></xref> before the call to <codeph>StoreL()</codeph>. Call <codeph>SetRecordId()</codeph> on the <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBElement</apiname></xref> base class to set the record Id. </p> <p>To add a new record to a table set the record Id part of the <xref href="GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84.dita#GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84/GUID-4DDD4947-D379-5B68-8DC0-B67B074FA852">element Id</xref> of the table to <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>KCDNewRecordRequest</apiname></xref> before the call to <codeph>StoreL()</codeph>. Call <codeph>SetRecordId()</codeph> on the <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBElement</apiname></xref> base class to set the record Id. The table must exist before you add the new record. </p> <p>To add a new column to a user defined table set the record Id part of the <xref href="GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84.dita#GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84/GUID-4DDD4947-D379-5B68-8DC0-B67B074FA852">element Id</xref> of the table to <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>KCDNewColumnRequest</apiname></xref> before the call to <codeph>StoreL()</codeph>. Call <codeph>SetRecordId()</codeph> on the <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBElement</apiname></xref> base class to set the record Id. The effect of a new column is to add a new field in the user defined records. </p> <p>The tool or application must have the platform security capabilities to write to the Comms Database. </p> <p> <codeph>StoreL()</codeph> opens a read/write transaction with the Comms Database if the tool or application has not already started a transaction. </p> </section> <section><title>Changing data in the Comms Database</title> <p>If you need to change data in the Comms Database you must change the data in the table, the record, the link or the field object in memory. The table, the record, the link and the field must already exist in the database. </p> <p>Call <codeph>ModifyL()</codeph> to change existing data. The function cannot create new records or tables, but can store new fields in a record. </p> <p>The tool or application must have the platform security capabilities to write to the Comms Database. </p> <p> <codeph>ModifyL()</codeph> opens a read/write transaction with the Comms Database if the tool or application has not already started a transaction. </p> </section> <section><title>Deleting data from the Comms Database</title> <p>Call <codeph>DeleteL()</codeph> to delete a table, a record, a field or a link from the Comms Database. </p> <p>The tool or application must have the platform security capabilities to write to the Comms Database. </p> <p> <codeph>DeleteL()</codeph> opens a read/write transaction with the Comms Database if the tool or application has not already started a transaction. </p> </section> </conbody></concept>