How to access tables in the database

Note: This section is provided as a reference for the legacy CommDb component, which has been superceded by the CommsDat component. It is strongly recommended that users migrate to CommsDat. Migration information is available in the CommsDat API and Migration Guide.

A client must first access the communications database through DBMS. This is done using the services of a CCommsDatabase object, which inherits from CCommsDatabaseBase.

A client constructs a CCommsDatabase object using the static NewL() function of the CCommsDatabase class. In common with all servers, the first client to attempt to connect to the server causes that server to start. The database is opened with shared access.

Note that if the communications database does not exist when NewL() is called, it is created, with empty tables, before trying to connect to the DBMS.

Access to an individual table is gained by opening a view on that table. A view is simply a subset of the records (or rows) within a table, selected according to defined criteria. Tables, records, rows, columns, and so on, are DBMS concepts.

CommDb uses a CCommsDbTableView object to encapsulate a view on a specific table. A view is constructed using one of the CCommsDatabaseBase member functions:

• OpenTableLC()

• OpenViewMatchingUintLC()

• OpenViewMatchingBoolLC()

• OpenViewMatchingTextLC()

• OpenViewLC()

Each function offers a different way of building a view: for example, OpenTableLC() builds a view where all the records in the table are selected, while OpenViewMatchingUintLC() builds a view where the records are selected based on matching the unsigned integer values in a named column.

All of these functions construct a CCommsDbTableView object which is subsequently used to navigate through the recordset and access individual records.

Notes

• Views on the Connection preferences table cannot be obtained through CCommsDbTableView. For details, on what to do instead, see Connection preferences.

• Specialist functions for opening particular views on the IAP table (CCommsDatabase::OpenIAPTableViewMatchingBearerSetLC()) and on the Proxies table (CCommsDatabase::OpenViewOnProxyRecordLC()) are also available.

Within a given view, there is always the idea of a cursor which points to a current record. The CCommsDbTableView class offers three functions which allow a client to navigate between records:

• GotoFirstRecord() sets the cursor to point to the first record in the view.

• GotoNextRecord() sets the cursor to point to the next record in the view.

• GotoPreviousRecord() sets the cursor to point to the previous record in the view.

The CCommsDbTableView class offers functions which allow a client to read from or write to named columns within the current record. There are specific functions for reading and writing columns of: unsigned integer type, boolean type, short length narrow (ASCII) text, short length wide (Unicode) text and long text (ASCII or Unicode):

• ReadUintL() and WriteUintL()

• ReadBoolL() and WriteBoolL()

• ReadTextL() and WriteTextL()

• ReadLongTextLC() and WriteLongTextL()

See also

Column type characteristics.

All changes must start with a call to the CCommsDbTableView member functions InsertRecord() or UpdateRecord(), depending on whether a new record is to be inserted or the current record changed, and must complete with a call to either PutRecordChanges() or CancelRecordChanges().

PutRecordChanges() confirms the changes to the record while CancelRecordChanges() causes the changes to be abandoned.

No read type operations can be made while a change to a record is in progress. Any attempt to call a read type function in between, for example, a call to UpdateRecord() and a call to PutRecordChanges(), raises a panic.

Records are deleted by a call to the CCommsDbTableView member function DeleteRecord().

This function is not normally followed by any write operations; in addition, neither of the functions PutRecordChanges() nor CancelRecordChanges() is called after a record is deleted.