Contents > Library Reference > Database

Database

Objects for creating and manipulating databases and memos.

Objects and Structures

DBRecord Encapsulates a database record.
DBRecordStream Exposes a DBRecord as a Stream.
Database Encapsulates a Palm OS database.
DatabaseMgr Allows for enumerating databases.
Memo Provides access to reading and writing memos.

Contents > Library Reference > Database > DBRecord object

DBRecord

A DBRecord object respresents a single database record. To use a DBRecord, you must associate it with a record using Database.getrec() or Database.newrec(). Once a DBRecord is associated with a record, it must be closed before it is reused. All DBRecords associated with records in a given database must be closed before the database is closed. Two DBRecords cannot be used to open the same record at the same time.

Object Properties

int offset Gets or sets the current read/write location in the record. If offset is set to a value greater than the size of the record, offset becomes the record size.
int size Gets the current size of the record.
int category Gets or sets the category of the record. Valid values are 0-15.
int id Gets the id of the record.
int uniqueid Gets the uniqueid of the record.
int handle The MemHandle associated with this record to allow access to native add-ins.

Object Methods

int read(void* pdata, string type, int count) Reads count blocks of data from the record into the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type. Advances the current offset.
int write(void* pdata, string type, int count) Writes count blocks of data to the record from the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type. Advances the current offset.
void erase() Erases the contents of the record, but does not remove it from the database.
void close() Closes the record. The object cannot be used again until it is re-initialized using Database.newrec() or Database.getrec().

Contents > Library Reference > Database > DBRecordStream object

DBRecordStream

The DBRecordStream is derived from Stream, providing read/write access to a DBRecord. To use this object, create and open a DBRecord object, assign it to the rec property, then call the read and write methods on Stream.

Object Properties

DBRecord rec Sets the DBRecord object that this stream should read/write to.

Object Methods

bool read(void* pdata, string type, int count) Reads count blocks of data from the stream into the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type.
bool write(void* pdata, string type, int count) Writes count blocks of data to the stream from the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type.
bool readInt(int* pi) Read an int from the stream into the memory pointed to by pi.
bool writeInt(int i) Write an int to the stream.
bool readWord(int* pw) Read an 2-byte word from the stream into the memory pointed to by pw.
bool writeWord(int w) Write a 2-byte word to the stream.
bool readFloat(float* pf) Read a float from the stream into the memory pointed to by pf.
bool writeFloat(float f) Write a float to the stream.
bool readString(string* ps) Read a string from the stream into the memory pointed to by ps.
bool writeString(string s) Write a string to the stream.
bool readChar(char* pc) Read a char from the stream into the memory pointed to by pc.
bool writeChar(char c) Write a char to the stream.

Contents > Library Reference > Database > Database object

Database

A Database represents a Palm OS database. A database can only be opened by one Database object at a time.

Object Properties

int nrecs Gets the number of records or resources in the database
bool backup Gets or sets the backup bit. If set, the database will be backed up the next time the device is HotSynced.
bool locked Gets or sets the locked bit. If set, the database cannot be beamed from one device to another.
int version Gets or sets the database version number. The version stored in the database is 16-bits unsigned, so it must be less than 65536.
int size Gets the total size of the database.
string type Gets the 4-character type of the database.
string creator Gets the 4-character creator id of the database.
string name Gets or sets the name of the database.
bool res True if this is a resource database, false otherwise.
bool inrom True if this database is in ROM.
int dbref The DmOpenRef for this database to allow access to native add-ins.
int dbid The LocalID for this database to allow interop with external applications.
int card The card on which this database resides (always 0 except on a few rare devices - has nothing to do with VFS).

Object Methods

bool open(string name, bool readonly) Opens the database named name. This method searches all the available cards, starting with the builtin RAM. Returns true on success.
bool opentc(string type, string creatorid, bool readonly) Opens the first database of type type and creator id creatorid.
bool create(string name, string type, string creatorid, bool res) Creates a database named name with type type and creator id creatorid on card 0 (builtin RAM). If res is true a resource database is created, otherwise a record database is created. If a database with this name already exists, the method will fail. Returns true on success.
void close() Close the database. All open records MUST be closed first.
void deldb() Close and delete the database. All open records MUST be closed first.
Date getdate(int which) Retrieve the creation, modification, or backup date of the database.
string getcatname(int num) Get the category name associated with the index num. This method may only be called if the the database has an app info block.
void setcatname(int num, string name) Set the category associated with the index num to name. This method may only be called if the the database has an app info block. You can create an empty app info block using createappinfo().
void moverec(int from, int to) Remove the record at index from and insert it at index to.
void removerec(int id) Remove the record at index id. This method may NOT be called when any records in the database are open.
void removeres(string type, int id) Remove the resource of the given type with the given id.
void delrec(int id) Delete the record at index id, but leave the record entry in the database header. If a conduit exists, the next synchronization should remove the corresponding record on the desktop and remove this record entry from the device.
void archiverec(int id) Archive the record at index id. This leaves the record in the database, but marks it as deleted. If a conduit exists, the next synchronization should archive the corresponding record on the desktop and remove this record from the device.
bool getrec(int id, DBRecord rec, bool readonly) Gets the record at index id, and attaches the DBRecord rec to it. Pass true for readonly if you only intend to read from the record. Returns true if successful.
bool newrec(int* id, DBRecord rec) Inserts a new record at index id, and attaches the DBRecord rec to it. If id is greater than the number of records in the database or -1, the new record is appended to the end of the database - use the id property to determine its index.
int findrec(int uniqueid) Finds the record which has the specified uniqueid, returning the record index if found, or -1 if not found. Calling this method on some OSes will cause a fatal error if the record is not found.
bool getresinfo(int index, string* pType, int* pId) Gets the resource type and id of the resource with the given index. Returns true if successful.
bool getres(string type, int id, DBRecord rec) Gets the resource with the given type and the given id, and attaches the DBRecord rec to it. Returns true if successful.
bool newres(string type, int id, DBRecord rec) Inserts a new resource with the given type and the given id, and attaches the DBRecord rec to it. Returns true if successful.
bool hasappinfo() Checks if the database has an app info block. Only a record database can have an app info block.
int getappinfo() Retrieves the app info block of the database and creates a record to hold its data. Before closing the database, you must remove this temporary record, or call setappinfo to convert it to an app info block. This method will fail if the database was opened in read-only mode.
bool setappinfo(int id) Converts the record at index id into an app info block and attaches it to the database. Removes the specified record.
bool createappinfo() Creates an empty app info block.

Contents > Library Reference > Database > DatabaseMgr object

DatabaseMgr

The DatabaseMgr object provides a function for enumerating all available databases on the device.

Object Methods

string dbenum(bool first, string type, string creatorid) Enumerates the databases with the given creatorid and type. Call this function once with first = true to get the first database, and (if it doesn't return an empty string) continue calling with first = false until the empty string is returned.

Contents > Library Reference > Database > Memo object

Memo

A Memo object provides the ability to read and write memos. A Memo object provides methods for working with an individual memo, as well as the memo database as a whole. To attach a Memo object to a given memo, use the create, open, or find methods. Two objects cannot open the same memo at a time.

Object Properties

string text Gets or sets the entire text of the memo.
int nrecs Gets the number of records in the memo database.
int index Gets the index of the record in the memo database.

Object Methods

bool find(string name) Searches for a memo beginning with name as the first line, and opens it if found. Returns true on success.
bool create() Create a new, empty memo record. Returns true on success.
bool open(int index) Opens the memo record at location index. This may fail if index is greater than the number of records, or if the specified record is marked for deletion.
void puts(string text) Appends text to the end of the current memo.
string line() Reads the next line of text from the memo. This method does NOT return the \n character at the end of the line. Returns the empty string if the contents have all been read, or if the current line is blank.
bool end() Returns true if the end of the memo has been reached while reading the the record using the line() method.
void rewind() Resets the location from which the line() method reads to be the start of the memo.
void close() Closes the current memo. This must be called before opening or creating another memo.
void del() Close the memo and delete it from the memo database. A record header will remain in the database until the next sync so that the desktop database can be cleaned up.
void archive() Close the memo and mark it for archival. The record will remain in the database until the next sync so that the desktop can archive the contents.
void remove() Close the memo and completely removes it from the memo database. This method may not be called when any other Memo object is open.
void erase() Erases the contents of the current memo.

Contents > Library Reference > Database > DBRecord object > read

DBRecord.read

int read(void* pdata, string type, int count)

Parameters:

pdata data pointer
type format string
count format count

Return value: the number of values read

Reads count blocks of data from the record into the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type. Advances the current offset.


Contents > Library Reference > Database > DBRecord object > write

DBRecord.write

int write(void* pdata, string type, int count)

Parameters:

pdata data pointer
type format string
count format count

Return value: the number of values written

Writes count blocks of data to the record from the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type. Advances the current offset.


Contents > Library Reference > Database > DBRecord object > erase

DBRecord.erase

void erase()

Erases the contents of the record, but does not remove it from the database.


Contents > Library Reference > Database > DBRecord object > close

DBRecord.close

void close()

Closes the record. The object cannot be used again until it is re-initialized using Database.newrec() or Database.getrec().


Contents > Library Reference > Database > DBRecordStream object > read

DBRecordStream.read

bool read(void* pdata, string type, int count)

Parameters:

pdata data pointer
type format string
count format count

Return value: true if all the data was read

Reads count blocks of data from the stream into the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type.


Contents > Library Reference > Database > DBRecordStream object > write

DBRecordStream.write

bool write(void* pdata, string type, int count)

Parameters:

pdata data pointer
type format string
count format count

Return value: true if all the data was written

Writes count blocks of data to the stream from the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type.


Contents > Library Reference > Database > DBRecordStream object > readInt

DBRecordStream.readInt

bool readInt(int* pi)

Parameters:

pi int pointer

Return value: true if successful

Read an int from the stream into the memory pointed to by pi.


Contents > Library Reference > Database > DBRecordStream object > writeInt

DBRecordStream.writeInt

bool writeInt(int i)

Parameters:

i int to write

Return value: true if successful

Write an int to the stream.


Contents > Library Reference > Database > DBRecordStream object > readWord

DBRecordStream.readWord

bool readWord(int* pw)

Parameters:

pw int pointer

Return value: true if successful

Read an 2-byte word from the stream into the memory pointed to by pw.


Contents > Library Reference > Database > DBRecordStream object > writeWord

DBRecordStream.writeWord

bool writeWord(int w)

Parameters:

w word to write

Return value: true if successful

Write a 2-byte word to the stream.


Contents > Library Reference > Database > DBRecordStream object > readFloat

DBRecordStream.readFloat

bool readFloat(float* pf)

Parameters:

pf float pointer

Return value: true if successful

Read a float from the stream into the memory pointed to by pf.


Contents > Library Reference > Database > DBRecordStream object > writeFloat

DBRecordStream.writeFloat

bool writeFloat(float f)

Parameters:

f float to write

Return value: true if successful

Write a float to the stream.


Contents > Library Reference > Database > DBRecordStream object > readString

DBRecordStream.readString

bool readString(string* ps)

Parameters:

ps string pointer

Return value: true if successful

Read a string from the stream into the memory pointed to by ps.


Contents > Library Reference > Database > DBRecordStream object > writeString

DBRecordStream.writeString

bool writeString(string s)

Parameters:

s string to write

Return value: true if successful

Write a string to the stream.


Contents > Library Reference > Database > DBRecordStream object > readChar

DBRecordStream.readChar

bool readChar(char* pc)

Parameters:

pc char pointer

Return value: true if successful

Read a char from the stream into the memory pointed to by pc.


Contents > Library Reference > Database > DBRecordStream object > writeChar

DBRecordStream.writeChar

bool writeChar(char c)

Parameters:

c char to write

Return value: true if successful

Write a char to the stream.


Contents > Library Reference > Database > Database object > open

Database.open

bool open(string name, bool readonly)

Parameters:

name database name
readonly open for read only

Return value: true if successful, false otherwise

Opens the database named name. This method searches all the available cards, starting with the builtin RAM. Returns true on success.


Contents > Library Reference > Database > Database object > opentc

Database.opentc

bool opentc(string type, string creatorid, bool readonly)

Parameters:

type type
creatorid creator id
readonly open for read only

Return value: true if successful, false otherwise

Opens the first database of type type and creator id creatorid.


Contents > Library Reference > Database > Database object > create

Database.create

bool create(string name, string type, string creatorid, bool res)

Parameters:

name name, less than 32 characters
type type
creatorid creator id
res true if this is a resource database, false otherwise

Return value: true if successful, false otherwise

Creates a database named name with type type and creator id creatorid on card 0 (builtin RAM). If res is true a resource database is created, otherwise a record database is created. If a database with this name already exists, the method will fail. Returns true on success.


Contents > Library Reference > Database > Database object > close

Database.close

void close()

Close the database. All open records MUST be closed first.


Contents > Library Reference > Database > Database object > deldb

Database.deldb

void deldb()

Close and delete the database. All open records MUST be closed first.


Contents > Library Reference > Database > Database object > getdate

Database.getdate

Date getdate(int which)

Parameters:

which which date to retrieve

Return value: requested date

Retrieve the creation, modification, or backup date of the database.

Note: Valid date ids are: dbDateCreated, dbDateModified, dbDateBackup
Contents > Library Reference > Database > Database object > getcatname

Database.getcatname

string getcatname(int num)

Parameters:

num category number. Valid range is 0-15

Return value: category name, less than 32 characters

Get the category name associated with the index num. This method may only be called if the the database has an app info block.


Contents > Library Reference > Database > Database object > setcatname

Database.setcatname

void setcatname(int num, string name)

Parameters:

num category number. Valid range is 0-15
name category name, less than 32 characters

Set the category associated with the index num to name. This method may only be called if the the database has an app info block. You can create an empty app info block using createappinfo().


Contents > Library Reference > Database > Database object > moverec

Database.moverec

void moverec(int from, int to)

Parameters:

from source index
to destination index

Remove the record at index from and insert it at index to.

Note: This method may cause the ids of other records to change. This method may NOT be called when any records in the database are open.
Contents > Library Reference > Database > Database object > removerec

Database.removerec

void removerec(int id)

Parameters:

id record index

Remove the record at index id. This method may NOT be called when any records in the database are open.

Note: This method may cause the ids of other records to change.
Contents > Library Reference > Database > Database object > removeres

Database.removeres

void removeres(string type, int id)

Parameters:

type resource type
id resource id

Remove the resource of the given type with the given id.


Contents > Library Reference > Database > Database object > delrec

Database.delrec

void delrec(int id)

Parameters:

id record index

Delete the record at index id, but leave the record entry in the database header. If a conduit exists, the next synchronization should remove the corresponding record on the desktop and remove this record entry from the device.

Note: Do not use this method unless your application has a conduit.
Contents > Library Reference > Database > Database object > archiverec

Database.archiverec

void archiverec(int id)

Parameters:

id record index

Archive the record at index id. This leaves the record in the database, but marks it as deleted. If a conduit exists, the next synchronization should archive the corresponding record on the desktop and remove this record from the device.

Note: Do not use this method unless your application has a conduit.
Contents > Library Reference > Database > Database object > getrec

Database.getrec

bool getrec(int id, DBRecord rec, bool readonly)

Parameters:

id record index
rec pointer to a DBRecord
readonly true for read only

Return value: true on success

Gets the record at index id, and attaches the DBRecord rec to it. Pass true for readonly if you only intend to read from the record. Returns true if successful.


Contents > Library Reference > Database > Database object > newrec

Database.newrec

bool newrec(int* id, DBRecord rec)

Parameters:

id record index
rec pointer to a DBRecord

Return value: true on success

Inserts a new record at index id, and attaches the DBRecord rec to it. If id is greater than the number of records in the database or -1, the new record is appended to the end of the database - use the id property to determine its index.

Note: If the new record is not being appended to the end of the database, the ids of other records in the database may change.
Contents > Library Reference > Database > Database object > findrec

Database.findrec

int findrec(int uniqueid)

Parameters:

uniqueid record unique id

Return value: record id, or -1 if not found

Finds the record which has the specified uniqueid, returning the record index if found, or -1 if not found. Calling this method on some OSes will cause a fatal error if the record is not found.


Contents > Library Reference > Database > Database object > getresinfo

Database.getresinfo

bool getresinfo(int index, string* pType, int* pId)

Parameters:

index resource index
pType pointer to resource type
pId pointer to resource id

Return value: true on success

Gets the resource type and id of the resource with the given index. Returns true if successful.


Contents > Library Reference > Database > Database object > getres

Database.getres

bool getres(string type, int id, DBRecord rec)

Parameters:

type resource type
id resource id
rec pointer to a DBRecord

Return value: true on success

Gets the resource with the given type and the given id, and attaches the DBRecord rec to it. Returns true if successful.


Contents > Library Reference > Database > Database object > newres

Database.newres

bool newres(string type, int id, DBRecord rec)

Parameters:

type resource type
id resource id
rec pointer to a DBRecord

Return value: true on success

Inserts a new resource with the given type and the given id, and attaches the DBRecord rec to it. Returns true if successful.


Contents > Library Reference > Database > Database object > hasappinfo

Database.hasappinfo

bool hasappinfo()

Return value: true if the database has an app info block

Checks if the database has an app info block. Only a record database can have an app info block.


Contents > Library Reference > Database > Database object > getappinfo

Database.getappinfo

int getappinfo()

Return value: record id, or -1 if there is no app info block

Retrieves the app info block of the database and creates a record to hold its data. Before closing the database, you must remove this temporary record, or call setappinfo to convert it to an app info block. This method will fail if the database was opened in read-only mode.


Contents > Library Reference > Database > Database object > setappinfo

Database.setappinfo

bool setappinfo(int id)

Parameters:

id record index to convert

Return value: true if successful

Converts the record at index id into an app info block and attaches it to the database. Removes the specified record.


Contents > Library Reference > Database > Database object > createappinfo

Database.createappinfo

bool createappinfo()

Return value: true on success

Creates an empty app info block.


Contents > Library Reference > Database > DatabaseMgr object > dbenum

DatabaseMgr.dbenum

string dbenum(bool first, string type, string creatorid)

Parameters:

first true to get the first item
type 4-character type string or empty string for wildcard
creatorid 4-character creator id string or empty string for wildcard

Return value: database name, or empty string if no more

Enumerates the databases with the given creatorid and type. Call this function once with first = true to get the first database, and (if it doesn't return an empty string) continue calling with first = false until the empty string is returned.


Contents > Library Reference > Database > Memo object > find

Memo.find

bool find(string name)

Parameters:

name first line of the desired memo

Return value: true if successful

Searches for a memo beginning with name as the first line, and opens it if found. Returns true on success.


Contents > Library Reference > Database > Memo object > create

Memo.create

bool create()

Return value: true if successful

Create a new, empty memo record. Returns true on success.


Contents > Library Reference > Database > Memo object > open

Memo.open

bool open(int index)

Parameters:

index memo record index

Return value: true on success

Opens the memo record at location index. This may fail if index is greater than the number of records, or if the specified record is marked for deletion.


Contents > Library Reference > Database > Memo object > puts

Memo.puts

void puts(string text)

Parameters:

text text to append

Appends text to the end of the current memo.


Contents > Library Reference > Database > Memo object > line

Memo.line

string line()

Return value: next line of text

Reads the next line of text from the memo. This method does NOT return the \n character at the end of the line. Returns the empty string if the contents have all been read, or if the current line is blank.


Contents > Library Reference > Database > Memo object > end

Memo.end

bool end()

Return value: true on end

Returns true if the end of the memo has been reached while reading the the record using the line() method.


Contents > Library Reference > Database > Memo object > rewind

Memo.rewind

void rewind()

Resets the location from which the line() method reads to be the start of the memo.


Contents > Library Reference > Database > Memo object > close

Memo.close

void close()

Closes the current memo. This must be called before opening or creating another memo.


Contents > Library Reference > Database > Memo object > del

Memo.del

void del()

Close the memo and delete it from the memo database. A record header will remain in the database until the next sync so that the desktop database can be cleaned up.


Contents > Library Reference > Database > Memo object > archive

Memo.archive

void archive()

Close the memo and mark it for archival. The record will remain in the database until the next sync so that the desktop can archive the contents.


Contents > Library Reference > Database > Memo object > remove

Memo.remove

void remove()

Close the memo and completely removes it from the memo database. This method may not be called when any other Memo object is open.


Contents > Library Reference > Database > Memo object > erase

Memo.erase

void erase()

Erases the contents of the current memo.