Database I/O Functions

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:

FunctionDescription
fcloseclose the record
feofcheck end-of-record status
fgetlread a line
fgetsread a line
fprintfwrite formatted data
freadread data
fscanfread formatted data
fseekchange the current I/O position
ftellget the current I/O position
fwritewrite data
redirectredirect output

dbdeldb

Delete a database.

Syntax

dbdeldb(dbName)

Description

dbdelrec(dbName) deletes a database identified by its name dbName. All its records are discarded.

See also

dbnewdb, dbdir, dbdelrec

dbdelrec

Delete a database record.

Syntax

dbdelrec(dbName, index)
dbdelrec(dbName, index, delBackup)

Description

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.

See also

dbdeldb, dbdir, dbnumrec

dbdir

List of databases.

Syntax

dbdir
dbdir('type')
dbdir('type/creator')
dblist = dbdir(...)

Description

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.

Examples

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');

See also

dbnumrec

dbinfo

Get info about a database.

Syntax

s = dbinfo(dbName)
dbinfo(dbName, s)

Description

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.

Example

dbinfo('TestDB', struct('ReadOnly', true));

See also

dbset

dbnewdb

Create a new database.

Syntax

dbnewdb(dbName)
dbnewdb(dbName, 'type/creator')

Description

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.

Example

Creation of a new database with type TEXT and creator test:

dbnewdb('TestDB', 'TEXT/test');

See also

dbset, dbnewrec, dbdeldb

dbnewrec

Create a new database record.

Syntax

fd = dbnewrec(dbName)
(fd, index) = dbnewrec(dbName)

Description

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.

Example

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);

See also

fclose, dbopenrec

dbnumrec

Number of records in a database.

Syntax

n = dbnumrec(dbName)

Description

dbnumrec(dbName) gives the number of records in the database identified by its name dbName.

See also

dbdir

dbopenrec

Open an existing database record.

Syntax

fd = dbopenrec(dbName, index)
fd = dbopenrec(dbName, index, mode)

Description

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:

ModeDescription
'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.

Example

Reading of the first line of the first note for the Memo Pad application.

fd = dbopenrec('MemoDB', 0);
line = fgets(fd);
fclose(fd);

See also

fclose, dbnewrec

dbset

Set options for dbnewdb.

Syntax

options = dbset
options = dbset(name1, value1, ...)
options = dbset(options0, name1, value1, ...)

Description

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:

NameDefaultMeaning
Backuptrueshould be backed up
Bundlefalsebundled with its application
CopyPreventionfalsecannot be copied
Hiddenfalsehidden in the launcher
OKToInstallNewerfalseif open, the backup may install a newer db
ReadOnlyfalsecannot be modified
Recyclablefalsedeleted when closed or upon reset

See also

dbnewdb, dbinfo


Copyright 1998-2007, Calerga.
All rights reserved.