C: / Documents and Settings / steve / My Documents / cvsroot / morepalmos / morepalmos / Public

MoreDataMgr.h File Reference

Functions for data manager. More...

#include "MorePrefix.h"
#include <DataMgr.h>

Include dependency graph for MoreDataMgr.h:

This graph shows which files directly or indirectly include this file:


Functions
MemHandle	MDmQueryRecordByID (DmOpenRef dbP, UInt32 recID, Err errCode, UInt32 recIdx)
	Searches a database for a record based on record id. Queries the found record.
MemHandle	MDmGetRecordByID (DmOpenRef dbP, UInt32 recID, Err errCode, UInt32 recIdx)
	Searches a database for a record based on record id. Gets the found record.
Err	MDmReleaseRecordByID (DmOpenRef dbP, UInt32 recID, Boolean dirty, UInt32 *recIdx)
	Searches a database for a record based on record id. Releases the found record.

Detailed Description

Functions for data manager.

MoreDataMgr.h contains functions for working with the Palm OS data manager in ways not directly supported by the Palm OS SDK. For example, MDmQueryRecordByID( ) performs a query on a record in the database based on record id instead of index.

Definition in file MoreDataMgr.h.

Function Documentation

MemHandle MDmGetRecordByID	(	DmOpenRef	dbP,
		UInt32	recID,
		Err *	errCode,
		UInt32 *	recIdx
	)

Searches a database for a record based on record id. Gets the found record.

Get a record from a database based on record id. If there is no record with that id or an error occurs, NULL is returned.

The difference between a query and a get is that a get marks a record as busy. You can not get a busy record. Thus, you should call DmReleaseRecord as soon as possible.

You can use MDmReleaseRecordByID or DmReleaseRecord; if convenient, it's more efficient to use DmReleaseRecord.

In addition to the function result, this MDmGetRecordByID has two optional returns:

errCode - the error that occurred

recIdx - the index of the record

Required pre-conditions:

dbP is open and valid.

Definition at line 48 of file MoreDataMgr.c.

00050 {
00051         MemHandle recH = NULL;
00052         UInt16 idsIdx;
00053         Err err = DmFindRecordByID( dbP, recID, &idsIdx );
00054         _reject( err, failedDmFind );
00055         if ( recIdx )
00056                 *recIdx = idsIdx;
00057         recH = DmGetRecord( dbP, idsIdx );
00058         _require( recH, failedDmQuery );
00059         err = errNone;
00060         goto succeed;
00061 failedDmQuery:
00062         err = DmGetLastErr( );
00063         // fall through 
00064 failedDmFind:
00065 succeed:
00066         if ( errCode )
00067                 *errCode = err;
00068         return recH;
00069 }

MemHandle MDmQueryRecordByID	(	DmOpenRef	dbP,
		UInt32	recID,
		Err *	errCode,
		UInt32 *	recIdx
	)

Searches a database for a record based on record id. Queries the found record.

Query a record from a database based on record id. If there is no record with that id or an error occurs, NULL is returned.

In addition to the function result, this MDmQueryRecordByID has two optional returns:

errCode - the error that occurred

recIdx - the index of the record

Required pre-conditions:

dbP is open and valid.

Definition at line 23 of file MoreDataMgr.c.

00025 {
00026         MemHandle recH = NULL;
00027         UInt16 idsIdx;
00028         Err err = DmFindRecordByID( dbP, recID, &idsIdx );
00029         _reject( err, failedDmFind );
00030         if ( recIdx )
00031                 *recIdx = idsIdx;
00032         recH = DmQueryRecord( dbP, idsIdx );
00033         _require( recH, failedDmQuery );
00034         err = errNone;
00035         goto succeed;
00036 failedDmQuery:
00037         err = DmGetLastErr( );
00038         // fall through 
00039 failedDmFind:
00040 succeed:
00041         if ( errCode )
00042                 *errCode = err;
00043         return recH;
00044 }

Err MDmReleaseRecordByID	(	DmOpenRef	dbP,
		UInt32	recID,
		Boolean	dirty,
		UInt32 *	recIdx
	)

Searches a database for a record based on record id. Releases the found record.

Releases a record from a database based on record id. If there is no record with that id or an error occurs, an error is returned.

Internally, MDmReleaseRecord( ) calls DmFindRecordByID( ) to find the record and DmReleaseRecord to release it. It is more efficient to store the recIdx returned from MDmGetRecordByID( ) and call DmReleaseRecord( ) directly.

Definition at line 73 of file MoreDataMgr.c.

00075 {
00076         UInt16 idsIdx;
00077         Err err = DmFindRecordByID( dbP, recID, &idsIdx );
00078         if ( recIdx )
00079                 *recIdx = idsIdx;
00080         _reject( err, failedDmFind );
00081         return DmReleaseRecord( dbP, idsIdx, dirty );
00082 failedDmFind:
00083         return err;
00084 }