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.