Dynaworks - 'PalmOS databases'

DynaWorks Tutorial

How to write applications with the DynaWorks framework

Working with the Palm build-in databases

The DynaWorks framework offers a read-only access to the built-in PalmOS™ databases. The reason, that DynaWorks does not support writing to these databases, is that at least the KVM/KJava implementation of databases is not able to control all of the internaöl state of a record. This means that DynaWorks can't access attributes like 'new', 'deleted' and so forth, making a write access to the databases unsafe and problematic. If I find ways around this problem or if the underlaying J2ME implementations have a better support for PalmOS™ databases (like J9 has today), I will try to incorporate a write-access in a future version of the DynaWorks framework.

To work with Palm databases you make use of two classes: one class for the database you want to access and one class for the record of that database. The following table shows the class name combinations for the different databases:

All classes derived from PalmRecord have specific methods to address the fields in the record. There are no common methods for that purpose; so look at the record class definitions for the databases you want to work with. You find more inffrmation about the databases in the following sections:

Caveat: Things that don't work ...
Address database
Datebook database
eMail database
Memo database
ToDo database
Expense database

Database	Database class	Record class
'abstract'	PalmDB	PalmRec
Address	AddressDB	AddressRec
Datebook	DatebookDB	DatebookRec
eMail	MailDB	MailRec
Memo	MemoDB	MemoRec
ToDo	TodoDB	TodoRec
Expense	ExpenseDB	ExpenseRec

Things that don't work correctly ...

Deleted records

Due to the implementation of the class com.sun.kjava.Database there is no way to determine 'deleted' records in build-in databases. If you query the number of records in a database, you receive the overall number of records including deleted records.

If you traverse the database from the start, you see the "normal" records first. If you hit the first deleted record, DynaDb returns an error. You can't access data in deleted records, so all example programs return a message "record not available".

Unique index

Currently there is no way to determine a unique index for a record in build-in databases. Even the position of a record in a database may change if the user interacts with the database using build-in applications. This means you have no way to address database records between sessions. This makes it impossible to write applications that link build-in informations together. I hope that this will change in future releases of the KVM.

Application info

The application specific information in build-in databases is not accessible from DynaDb. This is also due to a "crippled" implementation of the class com.sun.kjava.Database and I hope that this will change in future releases of the KVM too!

Back to top of page ...

Address database

(Source code example)

To access the records of the build-in address database you first have to create instances of the class AddressDB and AddressRec. You can then read in the record:

// open the database and allocate address record. AddressDB db = new AddressDB (); int recNum = -1; if (db != null) { db.open (); // get number of records in this db. recCount = db.numberOfRecords(); // allocate a new record of address entries. rec = new AddressRec (); } else { // can't open database. recCount = -1; rec = null; } : if (db.getRecord (recNum, rec)) { // read ok. now access the fields of the record. }

To access the fields of an address record the class AddressRec offers the following methods:

String getString(int field)

All fields in an AddressRec are of type String. So there is only one method called getString() neccessary to retreive data from an address record.

The argument passed into the methods denotes the field we want to read. The following table lists all values that correspond with address fields; if you pass a value that does correspond to a valid address field, an empty string is returned:

Mode Description

FLD_SURNAME 0x00001

FLD_NAME 0x00002

FLD_COMPANY 0x00004

FLD_TELCO1 0x00008 To find out the 'meaning' of one of these fields you have to call the method
int tcmode = rec.getTelcoMode (field);
with a field identifier between FLD_TELCO1 and FLD_TELCO5 as an argument. You receive a mode identifier between TC_OFFICE and TC_CELLPHONE that describes the 'meaning' of the field.

FLD_TELCO2 0x00010

FLD_TELCO3 0x00020

FLD_TELCO4 0x00040

FLD_TELCO5 0x00080

FLD_ADDR 0x00100

FLD_POSTAL 0x00200

FLD_CITY 0x00400

FLD_STATE 0x00800

FLD_COUNTRY 0x01000

FLD_TITLE 0x02000

FLD_DEF1 0x04000

FLD_DEF2 0x08000

FLD_DEF3 0x10000

FLD_DEF4 0x20000

FLD_NOTE 0x40000 This field contains an attached note

FLD_FAVORITE 0x80000 This corresponds not to a 'real' field but returns the content of that field that is addressed by the selected favourite telecommunication mode.

int getTelcoMode(int fld)

This method returns the telecommunication mode for the fields FLD_TELCO1 to FLD_TELCO5. If you pass in any other field value you will get a mode of -1 designating an error.

public int getFavorite()

This method return the favourite telecommunication mode of the address record (this is the entry that shows up in the address book list view). The mode is an integer value that marks the associated address field as the telco favourite.

Mode Description

TC_OFFICE 0 office telephone number

TC_PRIVATE 1 private telephone number

TC_FAX 2 office fax number

TC_OTHER 3 other telephone number

TC_EMAIL 4 email address

TC_COMPANY 5 company name

TC_PAGER 6 pager access number

TC_CELLPHONE 7 cellphone number

Back to top of page ...

Datebook database

(Source code example)

To access the records of the build-in datebook database you first have to create instances of the class DatebookDB and DatebookRec. You can then read in the record:

: // open the database and allocate datebook record. DatebookDB db = new DatebookDB (); int recNum = -1; if (db != null) { db.open (); // get number of records in this db. recCount = db.numberOfRecords(); // allocate a new record of datebook entries. rec = new DatebookRec (); } else { // can't open database. recCount = -1; rec = null; } : if (db.getRecord (recNum, rec)) { // read ok. now access the fields of the record. }

To access the fields of a datebook record the class DatebkRec offers the following methods:

(These methods use the utility classes Date and Time, that can be found in the brf.pilot.util package of the DynaWorks framework)

brf.j2me.dynaworks.util.Time getStartTime()

Get the start time for the appointment. Use the Time class methods to extract hour and minutes.

brf.j2me.dynaworks.util.Time getEndTime()

Get the end time for the appointment. Use the Time class methods to extract hour and minutes.

brf.j2me.dynaworks.util.Date getDate()

Get the date of the appointment. Use the Date class methods to extract day, month and year.

String getDescription()

Get the descriptive text for the appointment.

String getNote()

Get any attached note for this appointment.

boolean isChanged()

Has the appointment entry changed?

boolean isAlarm()

Is this an alarm entry?

boolean isRepeat()

Is this an repeating appointment?

boolean hasExceptions()

Are there any exceptions in the repeat of this appointment?

brf.j2me.dynaworks.util.Date[] getExceptions()

Get a list of exception dates when a scheduled repetition does not take place. This list is ordered chronologically.

int getAlarmUnit()

Get the alarm advance unit. This can be any of the following values:

Alarm unit value

UNIT_MINUTES 0

UNIT_HOURS 1

UNIT_DAYS 2

int getAlarmAdvance()

Get the number of alarm units to trigger the alarm before the appointment starts.

int getRepeatType()

Get the repeat type. This can be any of the following values:

Reapeat type value

REPEAT_NONE 0

REPEAT_DAILY 1

REPEAT_WEEKLY 2

REPEAT_MONTHLY_BY_DAY 3

REPEAT_MONTHLY_BY_DATE 4

REPEAT_YEARLY 5

brf.pilot.util.Date getRepeatEnd()

Get the end date for the repeat. Use the Date class methods to extract day, month and year. If you receive a null object, there is no end date for the repeat.

int getRepeatFrequency()

Get the frequency of the repetition.

int getRepeatAt()

In case you have a repeated event of type REPEAT_WEEKLY or REPEAT_MONTHLY_BY_DAY, you get the 'day of the week' the appointment is scheduled for.

Use the following scheme to determine the day for the scheduled event:

Reapeat type Value Description

REPEAT_WEEKLY 0 .. 6 value represents the 'day of the week' for the event

REPEAT_MONTHLY_BY_DAY 0 .. 27 Compute the 'day of the week' as (value%7) and the week number as (value/7+1)

int getRepeatDayBase()

Get the 'day of the week' the week starts. This also serves as the offset of any value received from the getRepeatAt() method. The following values might occur:

Value Description Value Description

0 Monday 4 Friday

1 Tuesday 5 Saturday

2 Wednesday 6 Sunday

3 Thursday

Back to top of page ...

eMail database

(Source code example)

To access the records of the build-in eMail database you first have to create instances of the class MailDB and MailRec. You can then read in the record:

: // open the database and allocate email record. MailDB db = new MailDB (); int recNum = -1; if (db != null) { db.open (); // get number of records in this db. recCount = db.numberOfRecords(); // allocate a new record of email messages. rec = new MailRec (); } else { // can't open database. recCount = -1; rec = null; } : if (db.getRecord (recNum, rec)) { // read ok. now access the fields of the record. }

To access the fields of an email record the class MailRec offers the following methods:

brf.pilot.util.Date getSendDate()

Get the date the email is sent.

int getPriority()

Get the priority of this email. The follwoing priority values can show up:

Value Description

PRIO_HIGH 0 High priority

PRIO_NORMAL 1 Normal priority

PRIO_LOW 2 low priority

String getString(int field)

Most fields in a MailRec are of type String. So this method can be used to retreive these field values from the record.

The argument passed into the methods denotes the field we want to read. The following table lists all values that correspond with email fields; if you pass a value that does correspond to a valid field, an empty string is returned:

Mode Description

FLD_SUBJECT 0 The subject of the email

FLD_SENDER 1 email address of the sender

FLD_RECEIPIENT 2 email address of the receipient

FLD_CARBONCOPY 3 carbon copy receipients

FLD_BLINDCARBON 4 blind carbon copy receipients

FLD_BODY 7 The body of the email. This string can contain multiple lines delimited by '\n' characters.

boolean isConfirmDelivery()

Confirm delivery of this email?

boolean isConfirmRead()

Confirm read of this email?

boolean isSignature()

Is this email signed digitally?

boolean isRead()

Is this email already read?

Back to top of page ...

Memo database

(Source code example)

To access the records of the build-in memo database you first have to create instances of the class MemoDB and MemoRec. You can then read in the record:

: // open the database and allocate memo record. MemoDB db = new MemoDB (); int recNum = -1; if (db != null) { db.open (); // get number of records in this db. recCount = db.numberOfRecords(); // allocate a new record of memo entries. rec = new MemoRec (); } else { // can't open database. recCount = -1; rec = null; } : if (db.getRecord (recNum, rec)) { // read ok. now access the fields of the record. }

To access the fields of a memo record the class MemoRec offers the following method:

String getMemo()

Returns the memo contained in the record in compact form. The string can contain multiple lines that are delimited by '\n' characters.

Back to top of page ...

ToDo database

(Source code example)

To access the records of the build-in ToDoList database you first have to create instances of the class TodoDB and TodoRec. You can then read in the record:

: // open the database and allocate todo record. ToDoDB db = new TodoDB (); int recNum = -1; if (db != null) { db.open (); // get number of records in this db. recCount = db.numberOfRecords(); // allocate a new record of todo list entries. rec = new TodoRec (); } else { // can't open database. recCount = -1; rec = null; } : if (db.getRecord (recNum, rec)) { // read ok. now access the fields of the record. }

To access the fields of a todo list record the class TodoRec offers the following methods:

brf.pilot.util.Date getDueDate()

Get the due date for the task. Use the Date class methods to extract day, month and year. If you receive a null object, there is no due date.

String getDescription()

Get the description of the task.

String getNote()

Get an attached note (if any)

int getPriority()

Get the priority of the task (1..5)

boolean isDone()

Is the job done?

Back to top of page ...

Expense database

(Source code example)

To access the records of the build-in expense database you first have to create instances of the class ExpenseDB and ExpenseRec. You can then read in the record:

: // open the database and allocate expense record. ExpenseDB db = new ExpenseDB (); int recNum = -1; if (db != null) { db.open (); // get number of records in this db. recCount = db.numberOfRecords(); // allocate a new expense record. rec = new ExpenseRec (); } else { // can't open database. recCount = -1; rec = null; } : if (db.getRecord (recNum, rec)) { // read ok. now access the fields of the record. }

To access the fields of an expense record the class ExpenseRec offers the following methods:

brf.pilot.util.Date getDate()

Get the date of the expense.

int getCategory()

Get the category of expense. This can be one of the following values:

Category Description Category Description

CAT_AIR 0x00 CAT_BEVERAGES 0x0D

CAT_BREAKFAST 0x01 CAT_GUESTHOUSE 0x0E

CAT_BUS 0x02 CAT_LUNCH 0x0F

CAT_COMPANYMEAL 0x03 CAT_MILAGE 0x10

CAT_CARRENTAL 0x04 CAT_OTHER 0x11

CAT_DINNER 0x05 CAT_PARKING 0x12

CAT_ENTERTAINMENT 0x06 CAT_PORTO 0x13

CAT_FAX 0x07 CAT_SNACK 0x14

CAT_GASOLINE 0x08 CAT_TRAIN 0x15

CAT_GIFTS 0x09 CAT_OFFICE 0x16

CAT_HOTEL 0x0A CAT_TAXI 0x17

CAT_SPECIAL 0x0B CAT_TELEPHONE 0x18

CAT_CLEANING 0x0C CAT_TIP 0x19

CAT_FEES 0x1A

int getCurrencyCode()

Get the currency code for this expense. The currency code can have the following values:

Currency code Value Currency code Value

CTRY_AUSTRALIA 0 CTRY_ITALY 12

CTRY_AUSTRIA 1 CTRY_JAPAN 13

CTRY_BELGIUM 2 CTRY_LUXEMBURG 14

CTRY_BRASIL 3 CTRY_MEXICO 15

CTRY_CANADA 4 CTRY_NETHERLANDS 16

CTRY_DENMARK 5 CTRY_NEWZEALAND 17

CTRY_FINLAND 6 CTRY_NORWAY 18

CTRY_FRANCE 7 CTRY_SPAIN 19

CTRY_GERMANY 8 CTRY_SWEDEN 20

CTRY_HONGKONG 9 CTRY_SWITZERLAND 21

CTRY_ISLAND 10 CTRY_UK 22

CTRY_IRLAND 11 CTRY_USA 23

String getCurrencyTag()

Get the currency name for this expense. The currency name will be one of the follwoing values:

Currency code Currency Currency code Currency

CTRY_AUSTRALIA AU$ CTRY_ITALY L.

CTRY_AUSTRIA S CTRY_JAPAN Yen

CTRY_BELGIUM BF CTRY_LUXEMBURG Flux

CTRY_BRASIL R$ CTRY_MEXICO MXP

CTRY_CANADA $CN CTRY_NETHERLANDS NLG

CTRY_DENMARK DKK CTRY_NEWZEALAND $NZ

CTRY_FINLAND Mk CTRY_NORWAY NOK

CTRY_FRANCE FRF CTRY_SPAIN Pts

CTRY_GERMANY DEM CTRY_SWEDEN SEK

CTRY_HONGKONG HK$ CTRY_SWITZERLAND CHF

CTRY_ISLAND ISK CTRY_UK GBP

CTRY_IRLAND IRP CTRY_USA $US

String getString(int field)

Some fields in a ExpenseRec are of type String. So this method can be used to retreive these field values from the record.

The argument passed into the methods denotes the field you want to read. The following table lists all values that correspond with expense fields; if you pass a value that does correspond to a valid field, an empty string is returned:

Mode Description

FLD_AMOUNT 0 The amount of the expense.

FLD_SELLER 1 The recipient of the expense.

FLD_CITY 2 The city were the expense is paid.

FLD_PEOPLE 3 The list of participients.

FLD_NOTE 4 An attached note.

int getPayment()

Get the method of payment for this expense. The payment can be one of the following:

Mode Value

PAY_AMEX 0

PAY_CASH 1

PAY_CHEQUE 2

PAY_CREDITCARD 3

PAY_MASTERCARD 4

PAY_ADVANCE 5

PAY_VISA 6

PAY_NONE 7

	Java™-based development framework for PalmOS™ devices (PDAs) Copyright© 2000 by Bernd R. Fix. All Rights Reserved.