What is the mechanism for reading, writing and searching for data
This topic describes the mechanism for reading data from the Comms Database and writing data to the Comms Database.
All elements that you can read and write have the class MMetaDatabase as a base class. This base class contains the functions that get and store that element.
Tables, records, links and fields are all elements. The classes that represent tables, records, links and fields have MMetaDatabase in their class hierarchy. You use the functions in MMetaDatabase to load and store tables, records, links and fields.
The MMetaDatabase class gives you:
the functions to get data from the Comms Database: LoadL(), FindL(), RefreshL()
the functions to put data into the Comms Database: StoreL(), ModifyL(), DeleteL()
Getting data directly from the Comms Database
If you know the record Id part of the element Id of a table, record, field or link, you can load the table, record, field or link from the Comms Database. Call SetRecordId() on the CMDBElement base class to set the record Id. Call LoadL() on the MMetaDatabase base class to load the table, record, field or link.
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.
A request to load a single element fails if the tool or application does not have the platform security capabilities.
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.
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.
LoadL() writes over the content of the table, record, field or link object in memory.
LoadL() opens a read-only transaction with the Comms Database if the tool or application has not already started a transaction.
Finding data in the Comms Database
You can search for records in the Comms Database. There are two patterns:
Finding a single record that has specified field values
You create a CMDBRecordBase object in memory. You select the fields for the search and set the field values. Call FindL() on the CMDBRecordBase object. FindL() is member of the MMetaDatabase base class. If the search is successful, the CommsDat API fills the CMDBRecordBase object with the values from the first record in the Comms Database that matches. The values include the element Id. If the search is not successful, the CMDBRecordBase object is not changed.
FindL() opens a read-only transaction with the Comms Database if the tool or application has not already started a transaction.
Note that you do not need to set the record Id part of the element Id of the table, the record, the field or the link object.
Finding all records in a table that match a specified record
You create a CMDBRecordSet 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 FindL() on the CMDBRecordSet 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 CMDBRecordSet object is not changed
FindL() opens a read-only transaction with the Comms Database if the tool or application has not already started a transaction.
Note that you do not need to set the record Id part of the element Id of the table, the record, the field or the link object.
Refreshing data in memory
You can update your copy of the data in memory. You call RefreshL() to update the data. The method is similar to LoadL() but the method does not write over fields that the tool or application has changed. All other fields are refreshed from the Comms Database.
RefreshL() is a member of the MMetaDatabase base class.
RefreshL() is useful if a tool or application maintains a cache of Comms information.
RefreshL() opens a read-only transaction with the Comms Database if the tool or application has not already started a transaction.
Adding new data to the Comms Database
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.
Call StoreL() to create new records, tables and fields. The CommsDat API only stores the fields that the tool or application has changed.
A table, record, field or link object that exists must have a valid element Id before the call to StoreL().
To add a new user defined table to the Comms Database set the record Id part of the element Id of the table to KCDNewTableRequest before the call to StoreL(). Call SetRecordId() on the CMDBElement base class to set the record Id.
To add a new record to a table set the record Id part of the element Id of the table to KCDNewRecordRequest before the call to StoreL(). Call SetRecordId() on the CMDBElement base class to set the record Id. The table must exist before you add the new record.
To add a new column to a user defined table set the record Id part of the element Id of the table to KCDNewColumnRequest before the call to StoreL(). Call SetRecordId() on the CMDBElement base class to set the record Id. The effect of a new column is to add a new field in the user defined records.
The tool or application must have the platform security capabilities to write to the Comms Database.
StoreL() opens a read/write transaction with the Comms Database if the tool or application has not already started a transaction.
Changing data in the Comms Database
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.
Call ModifyL() to change existing data. The function cannot create new records or tables, but can store new fields in a record.
The tool or application must have the platform security capabilities to write to the Comms Database.
ModifyL() opens a read/write transaction with the Comms Database if the tool or application has not already started a transaction.
Deleting data from the Comms Database
Call DeleteL() to delete a table, a record, a field or a link from the Comms Database.
The tool or application must have the platform security capabilities to write to the Comms Database.
DeleteL() opens a read/write transaction with the Comms Database if the tool or application has not already started a transaction.