The first step in this application is to understand how Databases
are created and accessed on the Palm. The API documentation provided
as of DR4.1 is quite sparse. Before you do anything, you need to
determine what you are going to call your database and how to identify it.
The key values are as follows:
Creating a database
The first part of this sample is to make an application(MakeEzDB.java) which will
write data out to a Database. In this case, would like to write the
flashID of the Palm to the database, followed by 0 to 3 strings, based
on my selection of a trio of CheckBoxes. The screen capture to the
right shows what the initial screen of this application looks like.
On initialization, there are three CheckBoxes and two buttons, with a
status string on top. The user selects which of the three fabulous
words they wish to include in the database and then presses the "Make
DB" button, which then writes the flashID and the selected words to
the database.
Some key elements of this program are as follows:
First, CheckBox appears to be fatally flawed. It turns out that
there is no way to get the text, or state of the CheckBox once it has
been constructed. Since both of these values are package protected in
the class, I had to do the following:
public class MyCheckBox extends CheckBox {
boolean checked = false;
String label="";
public MyCheckBox(int x, int y, String label) {
super(x, y, label);
this.label = label;
}
public void handlePenDown(int x, int y) {
super.handlePenDown(x, y);
checked = !checked;
}
public boolean getState() {
return checked;
}
public String getText() {
return label;
}
}
This allows me to query the state and content of the CheckBoxes later
in the program. It's not pretty, but it was the only
solution available
The creatorId and typeId values are set as follows:
static int dbType = 0x457A4442; // 'EzDB'
static int dbCreator = 0x414B414E; // 'AKAN'
This is because the values are integers, but you actually are using
four characters as labels.
When the "Make DB" button is pushed, you first try to open the
Database with the method.
db = new Database(dbType, dbCreator, Database.WRITEONLY);
This attempts to open the database (indexed by its type and creator,
not its name) in write only mode. A Database object is returned
whether the database exists or not. You then need to call
db.isOpen() to see if you actually did open the Database
successfully. For this example, if the Database does open, we need to
clear out the existing records as a first step. This is easily done
with the following code:
int numRecords = db.getNumberOfRecords();
for (int i=(numRecords -1); i > -1; i--) {
db.deleteRecord(i);
}
If the database did not open, it indicates that it is not present. If
not, then we need to create it. A Database is created with the following:
Database.create(0, "EzDB", dbCreator, dbType, false);
db = new Database(dbType, dbCreator, Database.WRITEONLY);
Note that this firsts creates the database, then opens it with the new
Database() call.
Once the Database is open, we just add records. A record is a
variable sized elements which are initialized witht the byte[]
argument to addRecord(). In this case, we need to convert the String
to first a null terminated string and then convert it to bytes.
The recordWithNull value is just a placeholder for the
new string with the '\0' character at the end.
recordWithNull = checkFoo.getText() + '\0';
db.addRecord(recordWithNull.getBytes());
When you run the makeEzDB, the sequence of Screens should be as
follows:
Initial screen
Application first comes up, and Foo and Bar have been selected
Database has been written to...
Reading a database
Reading the database created above is the job of ReadEzDB.java. This application initially has
a screen with text and two buttons. The text instructs the user to
push the Read DB button. When this is done, the database created in
the above example is read, and the information from the Database is
then displayed on the screen.
Note that the method call new String(recNoNull, 0, 0,
recNoNull.length) had to be changed in the new CLDC version. it is
now new String(recNoNull, 0, recNoNull.length).
The first secret is to make sure and use the same typeID and
creatorID as the original database.
static int dbType = 0x457A4442; // 'EzDB'
static int dbCreator = 0x414B414E; // 'AKAN'
The only other significant piece of code is the following:
if (readButton.pressed(x,y)) {
// first clear our output
output="";
db = new Database(dbType, dbCreator, Database.READONLY);
if (db.isOpen()) {
int recordCount = db.getNumberOfRecords();
title="Reading DB...found " + recordCount + " items";
for (int i=0; i < recordCount; i++) {
record = db.getRecord(i);
recNoNull = new byte[record.length - 1];
for (int j=0; j < record.length - 1; j++) {
recNoNull[j] = record[j];
}
string = new String(recNoNull, 0, 0,
recNoNull.length);
length=recNoNull.length;
output = output + string + '\n';
}
db.close();
}
textBox.setText(output);
paint();
}
In this example, we use the output variable to accumulate
the information in the Database. As with the first example, you open
the database with the:
db = new Database(dbType, dbCreator, Database.READONLY);
After that, you just get the number of records with the
getNumberOfRecords() and loop through each record. The
only trick is that the Strings that are pulled out of the Database
first as byte arrays, and must be converted to a String. That String
still has the '\0' character on the end, so there is a chunk of code
to make a new String with that last character missing. As each String
is pulled out, it is appended to the output variable,
which is finally placed in a TextBox for viewing.
When you run the makeEzDB, the sequence of Screens should be as
follows:
Initial screen
Application first comes up
ReadDB has been pressed, Database has been read from...
The graphic to the left shows what the EzDB looks like on the Palm
when created.
In this case it holds 3 records. Note that applications are also listed,
but have a