ColdSync::PDB - Manage a Palm database via the DLP protocol using Palm::PDB helpers. use ColdSync::SPC; use ColdSync::PDB; use Palm::Mail; my $db = ColdSync::PDB->Current("r"); my $catno = $db->catno('Inbox'); while (my $record = $db->nextRecInCategory($catno)) { print "Email from $record->{'from'}\n"; } The Palm::PDB module provides hooks allowing helper modules to handle the application specific details of Palm database files. ColdSync::PDB extends the Palm::PDB helper support to remote databases accessed during a sync. Due to limitations in the DLP protocol (actually, it appears more likely to be a PalmOS implementation limit), only a single database can be open at any one time. As well, due to the remote communications issues, some of the Palm::PDB approaches to database access aren't terribly efficient. Specifically, fetching the entire record list in one call is a bad idea for most sync conduits.

Current
my $db = ColdSync::PDB->Current($mode); Contructs a new ColdSync::PDB object from the database currently being synced on the Palm. $mode indicates how to open the database. It's a combination of characters indicating the desired access: r open for reading w open for writing x exclusive access s show secret records

Load
my $db = ColdSync::PDB->Load($dbname, $mode); Creates a handle to the newly opened database $dbname. This constructor is, compared to ColdSync::PDB::Current(), extremely slow since it has to search the database list in order to find things like creator and type information. $mode indicates how to open the database. It's a combination of characters indicating the desired access: r open for reading w open for writing x exclusive access s show secret records

isReadable
read_database() if $db->isReadable(); Returns true if the database is open for reading.

isWritable
$db->deleteRecord($record) if $db->isWritable(); Returns true if the database is open for writing.

catno
my $catno = $db->catno($catname); Map the category name $catname to an index into the databases category list or return undef if it can't be found. This isn't a DLP or Palm::PDB method, but it's something that a lot of conduits have to do.

num_records
my $num_records = $db->num_records(); Returns the number of records currently in the database. Note that this number changes whenever a database write of any kind of done. Since this can occur at any time over the life of a conduit, care should be taken before trusting cached "num_records" results.

record
for (my $i = 0; $i < $num_records; $i ++) { process_record( $db->record( $i ) ); } Returns the record at the specified $index. If the record doesn't exist, undef is returned.

records
my @records = $db->records(); foreach (@records) { process_record($_); } Returns all the records in the database. More specifically, it downloads and returns all the records. And it doesn't cache. Depending on the size of the database and the speed of the link, this can be a very expensive operation. Only use it if you're sure you want all the records in the database. It's usually sufficient to try fetching modified records, records in a specific category, or (if synching with a local source) accessing records by a known ID.

nextRecInCategory
my $catno = $db->catno('Inbox'); while(my $record = $db->nextRecInCategory($catno)) { process_record($record); } Fetch the next record in the category index $catno. Returns undef when no more records are available. The "resetIndex" method will reset the index back to the beginning. Mixing different calling modes (modified/unmodified,category/any) may give some undefined results. If you're planning on changing records while iterating, check out the Sync Manager API documentation (http://www.palmos.com/dev/support/docs/conduits/win/CComp_SyncMgr.html#970971).

nextModifiedRec
my $record = $db->nextModifiedRec($catno); Fetch the next modified record in the category index $catno. If $catno is undef, it will fetch the next modified record in any category. Returns undef when no more records are available. The "resetIndex" method will reset the index back to the beginning. Mixing different calling modes (modified/unmodified,category/any) may give some undefined results. If you're planning on changing records while iterating, check out the Sync Manager API documentation (http://www.palmos.com/dev/support/docs/conduits/win/CComp_SyncMgr.html#970971).

resetIndex
$db->resetIndex(); Resets the modified/category index.

deleteRecord
$db->deleteRecord($record); Deletes the specified $record.

deleteAllRecords
$db->deleteAllRecords(); Deletes all records in the database.

writeRecord
$db->writeRecord($record); Writes the given record to the database. If the record already exists (i.e. has a non-zero id) it will simply be modified. If it doesn't exist, it will be appended. The "id" field of the $record will be modified to the new record id.

newRecord
my $record = $db->newRecord(); $db->writeRecord($record); Creates a new record of the appropriate helper type, filling in all the appropriate defaults. Note that this is simply an empty local template. The record does not exist in the remote database and will not exist until a "writeRecord" method is called for it.

findRecordByID
$record = $db->findRecordByID($id); Find a record in the database with record ID $id. If the record doesn't exist, undef is returned. I'm fairly sure that the write attribute setting doesn't really work properly. Resource databases aren't handled. Certain things like mucking with the appinfo block is not supported. The "Load" method uses "dlp_FindDBByName" which limits us to Palm OS 3.0 and up. coldsync(8) Palm::PDB ColdSync::SPC Palm OS C/C++ Sync Suite Companion: http://www.palmos.com/dev/support/docs/conduits/win/C++SyncCompanionTOC.html Christophe Beauregard, <christophe.beauregard@sympatico.ca>