On Palm OS, databases are the most common way to store data. They replace files on computers. Databases are identified by a name, and have a four-character creator which links them to an application, and a four-character type. They contain multiple records, identified by an index; the first record has index 0.
Functions specific to databases are described in this section. Input, output, and control are done with the following generic functions:
Function | Description |
---|---|
fclose | close the record |
feof | check end-of-record status |
fgetl | read a line |
fgets | read a line |
fprintf | write formatted data |
fread | read data |
fscanf | read formatted data |
fseek | change the current I/O position |
ftell | get the current I/O position |
fwrite | write data |
redirect | redirect output |
Delete a database.
dbdeldb(dbName)
dbdelrec(dbName) deletes a database identified by its name dbName. All its records are discarded.
Delete a database record.
dbdelrec(dbName, index) dbdelrec(dbName, index, delBackup)
dbdelrec(dbName,index) deletes a record from the database identified by its name dbName. The record itself is identified by its index; the first record has index 0.
With a third argument delBackup, dbdelrec marks the record as deleted, so that the record will also be deleted from the backup the next time the Palm device is synchronized.
List of databases.
dbdir dbdir('type') dbdir('type/creator') dblist = dbdir(...)
dbdir displays the list of databases with their types and creators. Types and creators are strings of four characters; the type characterizes the kind of data, and the creator identifies the application which owns the database. Without argument, databases with type 'appl', 'libr', 'neti', 'ovly', or 'panl' are not displayed.
To filter the databases which are displayed, a string argument may be provided. It contains the type, and optionally a slash character and the creator. The type or the creator can be replaced with the star character, which stands for any value.
With an output argument, dbdir returns a list of structures with fields name, type, and creator.
dbdir('DATA') AddressDB DATA/addr DatebookDB DATA/date MailDB DATA/mail MemoDB DATA/memo ConnectionDB DATA/modm NetworkDB DATA/netw ToDoDB DATA/todo db = dbdir('*/LyME'); dumpvar('db1', db{1}); db1 = struct('name','LyMELibDB', ... 'type','Lml ', ... 'creator','LyME');
Get info about a database.
s = dbinfo(dbName) dbinfo(dbName, s)
dbinfo(dbName) gets the attributes of the database identified by its name dbName and returns them in a structure. Atrributes are the same as options of dbset.
dbinfo(dbName,s) changes the attributes database dbName with the fields of structure s.
dbinfo('TestDB', struct('ReadOnly', true));
Create a new database.
dbnewdb(dbName) dbnewdb(dbName, 'type/creator')
dbnewdb(dbName) creates a new database identified by its name dbName. The four-character type of the database is DATA and its four-character creator is LyME. The new database has no records; dbnewrec can be used to populate it.
The second output argument, if present, specifies the database type and creator. It is a string of two four-characters codes separated by a slash.
Creation of a new database with type TEXT and creator test:
dbnewdb('TestDB', 'TEXT/test');
Create a new database record.
fd = dbnewrec(dbName) (fd, index) = dbnewrec(dbName)
dbnewrec(dbName) adds a new record to the database identified by its name dbName. It returns a file descriptor which should be saved and used with functions such as fprintf and fwrite. Once the record is written, fclose should be called to terminate the record creation.
The second output argument, if present, is set to the index of the record. The first record has index 0.
Creation of a new note for the Memo Pad application. Note that the record ends with a null byte.
fd = dbnewrec('MemoDB'); fprintf(fd, 'Sine between 0 and 90 deg\n'); for a = 0:15:90 fprintf(fd, 'sin(%d) = %g\n', a, sin(a)); end fwrite(fd, 0); fclose(fd);
Number of records in a database.
n = dbnumrec(dbName)
dbnumrec(dbName) gives the number of records in the database identified by its name dbName.
Open an existing database record.
fd = dbopenrec(dbName, index) fd = dbopenrec(dbName, index, mode)
dbopenrec(dbName,index) opens a record from the database identified by its name dbName in read-only mode. The record itself is identified by its index; the first record has index 0. dbopenrec returns a file descriptor which should be saved and used with functions such as fgets, fscanf and fread. Once the record has been read, fclose should be called.
A third input argument can be used to specify the access mode:
Mode | Description |
---|---|
'r' | read |
'w' | write after discarding the previous contents |
'a' | append to the end of the previous contents |
The functions which can be used in write or append mode include fprintf, fwrite and dumpvar.
Reading of the first line of the first note for the Memo Pad application.
fd = dbopenrec('MemoDB', 0); line = fgets(fd); fclose(fd);
Set options for dbnewdb.
options = dbset options = dbset(name1, value1, ...) options = dbset(options0, name1, value1, ...)
dbset(name1,value1,...) creates the option argument used by dbnewdb. Options are specified with name/value pairs, where the name is a string which must match exactly the names in the table below. Case is significant. Options which are not specified have a default value. The result is a structure whose fields correspond to each option. Without any input argument, dbset creates a structure with all the default options. Note that dbnewdb also interprets the lack of an option argument, or the empty array [], as a request to use the default values.
When its first input argument is a structure, dbset adds or changes fields which correspond to the name/value pairs which follow.
Here is the list of permissible options:
Name | Default | Meaning |
---|---|---|
Backup | true | should be backed up |
Bundle | false | bundled with its application |
CopyPrevention | false | cannot be copied |
Hidden | false | hidden in the launcher |
OKToInstallNewer | false | if open, the backup may install a newer db |
ReadOnly | false | cannot be modified |
Recyclable | false | deleted when closed or upon reset |