developer's mag
main page
article
part 1
part 2
part 3
part 4
part 5
part 6
part 7
part 8
4 - The New Database
(January 2002 - the Database Manager was recently discovered to not be thread-safe, meaning that under certain conditions data could be corrupted. Until fixed (possibly in OS 2.1), the workaround is to disable timers before accessing any database functions using GUI_DisableTimer(), and enable with GUI_EnableTimer() afterwards.)Invariably, your program will both need to open a database and create it if missing. Although there may be exceptions (for example, connecting to a third party database), for the most part you'll have to do both.
First, you will need to create the COpenDB and the CFMDatabase database access objects:
COpenDB m_db; CFMDatabase m_fMgr;Together, they provide allow both file and record level access. Opening a database is then a case of using COpenDB::Open():
DBErr Open(AppID app,ebo_name_t *name,U32 mapinAddr,size_t mapinSize);Where 'app' is your program application number (which can be zero), 'name' is the ebm file descriptor, 'mapinAddr' is the memory start of your database, and 'mapinSize' is the maximum length. Success is a return value of DB_OK, which is zero; however, I recommend always checking against DB_OK rather than zero, in case someday the value is changed.
On failure, we likely have no database, and so the next step (generally) is to create a new database via COpenDB::Create():
DBErr Create(AppID app,ebo_name_t *name,U32 mapinAddr, size_t mapinSize,
CDBHeaderHdl *dbh = (CDBHeaderHdl *) 0);
The only difference from Open() is the CDBHeaderHdl
object, which is optional. Again, the error
codes are in the form DB_, and found at /franklin/SDK/sneak32/include/DatabaseErrors.h;
for us, the most obvious and recoverable
error in creating is not enough heap memory
(the /franklin/working/gui/test/test.cpp
uses HEAP_OUT_OF_MEMORY, but the value DB_OUT_OF_MEMORY
is the same value, and is more appropriate
for database code). This being the case,
we ask the operating system for more memory
with the function GUI_NeedFileSpace(), and
try again. On the second failure, we give
up and report the error.
Previous Section
Next Section