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, dbDateBackupContents > 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.