dbUtils.opx — Additional DBMS functionality

Contents

• Overview
• Compatibility
• DbRefresh: — Refreshes the current restricted view

Overview

This OPX is supplied with the EPOC Release 5 OPL SDK, and does not exist in EPOC Release 5 ROMs. To use this OPX, you must include the header file dbUtils.oxh which contains the following declaration:

    CONST KUidOpxdbUtils&=&10004C87
    CONST KOpxdbUtilsVersion%=$0100
    DECLARE OPX dbUtils,KUidOpxdbUtils&,KOpxdbUtilsVersion%
          DbRefresh: : 1
    END DECLARE

Compatibility

This OPX is introduced in ER5, and is not available to users of earlier devices.

DbRefresh: — Refreshes the current restricted view

Usage: DbRefresh:

Refreshes the current restricted DBMS view. It is only required in ER5 (and beyond) when using the WHERE keyword to restrict a view to a subset of the current table. The view does not dynamically update, so it must be refreshed manually in order to pick up any changes to the table contents.

DBMS has been optimised for ER5, but one problem of implementing the speed improvement is that a restricted view (that is, a view using the WHERE keyword to restrict the records to a subset of the current table) is no longer dynamically updated. A restricted view must be refreshed to pick up any changes to the table contents.

This means once a restricted view is created, any changes to the records in the view should be followed by a call to DbRefresh:, otherwise the view will be out-of-date, and any further database commands may give inaccurate information.

For example, a view is created on a table and restricted to show only a subset of the table. A new record that is expected to appear in the view is added. For ER5 devices, using COUNT to find the number of rows in the table returns one less than expected, as the new record has not been recognised. DbRefresh: is called, and the COUNT now accurately reflects the number of records expected.

Note that on EPOC releases ER1 to ER4, an index would have been required to create the restricted view. For ER5, the index is no longer required for these views, and any such index is ignored.

Finally, although DbRefresh: is not required when running on ER1-ER4, calling it on these devices has no ill effects.

For example:

    SELECT ... WHERE b=c ORDER BY a ...
    PRINT COUNT    REM Prints 0
    AddNewRecord:  REM Adds a record to the table.
    PRINT COUNT    REM Still 0
    DbRefresh:
    PRINT COUNT    REM Prints 1.