Contents > Library Reference > System

System

Functions for retrieving and manipulating system status, dynamic memory, dates, and the clipboard.

Objects and Structures

Date Encapsulates date and time operations.
Preferences Stores and retrieves application preferences.
Serial Serial I/O and raw IR support.
SerialStream Exposes a Serial object as a Stream.
Stream Base object for a Stream.
ISerializable Interface for an object that can be serialized.

Functions

void events(bool blocking) Processes all pending events, calling user provided event handlers, returning when the queue is empty. If blocking is true and no events are in the queue, the function will not return until an event is processed. If an appStopEvent is received, the app's onstop handler is called but this function never returns. This function should be called during long calculations to allow the user interface to respond (for example, allowing the user to cancel).
void fatal(string str) Displays a runtime error message containing the specified text and information about the current function. When the error message is dismissed, the app exits. This function does not return.
string callstack() Creates a string containing a list of functions in the current callstack, one per line.
void debuglog(string str) Writes the text as a line to the debug log. See Debug support for details. This is not a real function, as no code is generated unless the project is compiled with the debug property set.
void assert(bool expr) When expr is false, displays an error message containing the text of the expression and a call stack. See Debug support for details. This is not a real function, as no code is generated unless the project is compiled with the debug property set.
int ticks() Returns the number of clock ticks since the device was last reset.
int tickspersec() Returns the number of clock ticks that occur each second.
void resetaot() Reset the device's auto off timer. If the device goes without input for a short time, it will turn itself off. To prevent this, periodically call this function.
void sleep(int ms) Causes the app to sleep for ms milliseconds. While sleeping, the CPU will be put into low power mode, but the user will not be able to interact with the device (including turning it off).
void launch(string creatorid) Launch the app with the given 4 character creator id. This function will post a message to quit the current app if the specified app is found. However, it will return and allow the current app to process its queued events.
void launchGoto(string creatorid, string database, int recId, int searchStrLen, int matchPos, int matchField, int matchCustom) Launch the app with the given 4 character creator id using the system defined sysAppLaunchCmdGoTo launch code. The other parameters refer to fields in the system defined GoToParamsType structure. Different applications use the GoToParamsType differently, and not all field may be required/used by all applications. This function will post a message to quit the current app if the specified app is found. However, it will return and allow the current app to process its queued events.
void launchCustomString(string creatorid, int code, string param) Launch the app with the given 4 character creator id passing a custom launch code and a pointer to the specified string param. Only use this function if the app you are launching supports a char* launch parameter. This function will post a message to quit the current app if the specified app is found. However, it will return and allow the current app to process its queued events.
string username() Returns the HotSync username associated with the device.
string serialnum() Returns the string representation of the device's serial number, or the empty string if it does not have one.
int osver() Returns the integer version of the OS, using the standard Palm OS version specification - 32-bit number with the high 8 bits being the major version, the the next 8 bits being the minor version, and the remaining bits representing the fix number, build number, and build type.
string osvers() Returns the string representation of the OS version.
int orbver() Returns the OrbC runtime version the current app is using - 16-bit number with the high 8 bits being the major version, and the low 8 bits being the minor version.
string getclip() Returns the contents of the clipboard if it currently contains text, otherwise it returns the empty string.
void setclip(string text) Copys text to the clipboard.
void memcpy(void* pDest, void* pSrc, int len) Copies len values from pSrc to pDst. The data types at the destination must be the same as the source, or the application's behavior will be unpredictable.
void* malloct(string type, int count) Allocates count blocks of memory, initializing the memory elements to the types specified by the type string type.
void free(void* ptr) Releases the memory allocated by calling malloct.
int freemem() Returns the amount of free dynamic memory. Because the OrbC runtime has some overhead, this value cannot be used to make any direct calculations about how much memory can be allocated.
int battery(bool volts) Returns the requested battery status - voltage or percent remaining.

Contents > Library Reference > System > Date object

Date

A Date object encapsulates date and time operations. The Palm OS stores time as a count of the seconds since January 1st, 1904, so the OrbC Date object does the same.

Object Properties

int secs Gets or sets the seconds since January 1st, 1904.
int year Gets or sets the year
int month Gets or sets the month. January = 1, December = 12.
int day Gets or sets the day. First day of the month is 1.
int hour Gets or sets the hour. Valid range is 0-23.
int min Gets or sets the minute. Valid range is 0-59.
int sec Gets or sets the second. Valid range is 0-59.
int weekday Gets the day of week, with 0 being Sunday.
int ymd Gets or sets the date as an integer in yyyymmdd format, such as 20000527 for May 27th, 2000.

Object Methods

void now() Sets the date object to the current date and time.
bool selectdate(int selby, string title) Displays the system date selector dialog, using the mode specified by selby, using title as the dialog title. If the user selects a date, true is returned; if the user cancels, false is returned.
bool selecttime(string title) Displays the system time selector dialog, using title as the dialog title. If the user selects a time, true is returned; if the user cancels, false is returned. Available only on OS v3.1 and higher.
void addsecs(int s) Adds s seconds to the date object.
void adddays(int days) Adds d days to the date object.
void subsecs(int s) Subtracts s seconds from the date object.
void subdays(int days) Subtracts d days from the date object.
int diffsecs(Date d) Returns the difference of this date and d. If d is before this date, the result will be positive.
int diffdays(Date d) Returns the difference of this date and d. If d is before this date, the result will be positive.
string time() Returns the string representation of the time in the format specified by the system preferences.
string date() Returns the short string representation of the date in the format specified by the system preferences.
string ldate() Returns the long string representation of the date in the format specified by the system preferences.

Contents > Library Reference > System > Preferences object

Preferences

The Preferences object is used to store and retrieve application preferences. There are two types of preferences - saved and unsaved. Saved preferences are backed up to the desktop during a HotSync operation.

Object Methods

bool get(string creatorid, bool saved, void* pdata, string type, int count) Load the preference associated with creatorid into the memory pointed to by pdata. The memory must be in a format compatible with that specified by the type string type. The format is repeated count. If the preference does not exist, or is shorter than requested, this method returns false.
bool set(string creatorid, bool saved, void* pdata, string type, int count) Save the data pointed to by pdata into the saved or unsaved preference associated with creatorid using the format specified by type. The format is repeated count. This method returns true if successful.
void del(string creatorid, bool saved) Delete the preference, saved or unsaved, associated with the app creatorid.

Contents > Library Reference > System > Serial object

Serial

The Serial object implements serial I/O, raw IR, IrComm, and RfComm, (depending on which port is opened). The Serial object is implemented using the New Serial Manager which is only available on OS 3.3 and higher.

The Serial object is implemented in the OrbSerial native add-in. To use it, you must #include "OrbSerial.oc". The source code is available in the samples directory.

Object Properties

int error Gets the current set of line error bits. Call clearerr() to clear. Possible bits are serErrorParity, serErrorHWOverrun, serErrorFraming, serErrorBreak, serErrorHShake, serErrorSWOverrun, serErrorCarrierLost.
int status Gets the current set of status bits. Possible bits are serStatusCTS, serStatusRTS, serStatusDSR, serStatusBreak.

Object Methods

bool open(int port, int baud) Open the specified port at the specified baud rate, using default settings (1 stop bit, 8 bits per char, parity off, RTS receive flow control).
void close() Closes the open port.
void settings(int charbits, int stopbits, int parity, char flowctl, int ctstimeout) Apply the given settings to the open port.
bool setbuffer(int size) Allocates a new receive buffer of the specified size. The default buffer is 512 bytes, so most applications will not need to enlarge it.
void clearerr() Clears all pending line errors. This method must be called if a line error occurs before further sending and receiving can be done.
bool send(void* pdata, string type, int count) Sends count blocks of data over the port 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 recv(void* pdata, string type, int count, int timeout) Attempts to receive count blocks of data from the port into the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type. timeout is the number of ticks to wait for the data.
bool sendb(char byte) Sends the given byte over the port.
bool recvb(char* pbyte) Recieves one byte from the port, waiting up to one second to receive it. If successful, the received byte is stored in the char pointed to by pbyte.
int sendcheck() Retrieves the number of bytes remaining to be sent.
int recvcheck() Retrieves the number of bytes in the recieve buffer.
bool sendwait() Waits for all pending data to be sent.
bool recvwait(int bytes, int timeout) Waits for the specified number of bytes to be received into the receive buffer, waiting up to timeout ticks. Returns when the data is received or the timeout is reached.
void sendflush() Flushes all pending send data.
void recvflush(int timeout) Flushes all data from the recieve buffer, and waits until timeout ticks have passed with no new data received.

Contents > Library Reference > System > SerialStream object

SerialStream

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

Object Properties

Serial serial Sets the Serial 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 > System > Stream object

Stream

The Stream object provides a common set of methods for reading and writing data. The Stream object is a base object for specialized implementations, so you should never create an instance of this object. Instead, create an instance of the desired derived object.

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 > System > ISerializable object

ISerializable

The ISerializable interface can be implemented by any object which can be written to and read from a Stream.

Object Methods

bool serialize(Stream* stream) This method should write all of the important data of the implementing object to the stream.
bool deserialize(Stream* stream) This method should read all of the important data of the implementing object to the stream.

Contents > Library Reference > System > Date object > now

Date.now

void now()

Sets the date object to the current date and time.


Contents > Library Reference > System > Date object > selectdate

Date.selectdate

bool selectdate(int selby, string title)

Parameters:

selby select by mode
title dialog title

Return value: user selected something

Displays the system date selector dialog, using the mode specified by selby, using title as the dialog title. If the user selects a date, true is returned; if the user cancels, false is returned.

Note: Available selection modes are dateDayByDay, dateDayByWeek, dateDayByMonth.
Contents > Library Reference > System > Date object > selecttime

Date.selecttime

bool selecttime(string title)

Parameters:

title dialog title

Return value: user selected something

Displays the system time selector dialog, using title as the dialog title. If the user selects a time, true is returned; if the user cancels, false is returned. Available only on OS v3.1 and higher.


Contents > Library Reference > System > Date object > addsecs

Date.addsecs

void addsecs(int s)

Parameters:

s seconds

Adds s seconds to the date object.


Contents > Library Reference > System > Date object > adddays

Date.adddays

void adddays(int days)

Parameters:

days days

Adds d days to the date object.


Contents > Library Reference > System > Date object > subsecs

Date.subsecs

void subsecs(int s)

Parameters:

s seconds

Subtracts s seconds from the date object.


Contents > Library Reference > System > Date object > subdays

Date.subdays

void subdays(int days)

Parameters:

days days

Subtracts d days from the date object.


Contents > Library Reference > System > Date object > diffsecs

Date.diffsecs

int diffsecs(Date d)

Parameters:

d end date

Return value: difference in seconds

Returns the difference of this date and d. If d is before this date, the result will be positive.


Contents > Library Reference > System > Date object > diffdays

Date.diffdays

int diffdays(Date d)

Parameters:

d end date

Return value: difference in days

Returns the difference of this date and d. If d is before this date, the result will be positive.


Contents > Library Reference > System > Date object > time

Date.time

string time()

Return value: string represention of the time

Returns the string representation of the time in the format specified by the system preferences.


Contents > Library Reference > System > Date object > date

Date.date

string date()

Return value: string representation of the date

Returns the short string representation of the date in the format specified by the system preferences.


Contents > Library Reference > System > Date object > ldate

Date.ldate

string ldate()

Return value: string representation of the date

Returns the long string representation of the date in the format specified by the system preferences.


Contents > Library Reference > System > Preferences object > get

Preferences.get

bool get(string creatorid, bool saved, void* pdata, string type, int count)

Parameters:

creatorid creator id
saved true for saved preferences, false for unsaved
pdata data pointer
type format string
count format count

Return value: true if successful, false otherwise

Load the preference associated with creatorid into the memory pointed to by pdata. The memory must be in a format compatible with that specified by the type string type. The format is repeated count. If the preference does not exist, or is shorter than requested, this method returns false.

Example:

Load the array 'people' from the saved preferences of "MyAp".

struct Person {
  string name;
  int age;
};

Person people[2];

bool LoadPrefs() {
  Preferences prefs;
  return prefs.get("MyAp", true, people, typeof(Person), 2);
}


Contents > Library Reference > System > Preferences object > set

Preferences.set

bool set(string creatorid, bool saved, void* pdata, string type, int count)

Parameters:

creatorid creator id
saved true for saved preferences, false for unsaved
pdata data pointer
type format string
count format count

Return value: true if successful, false otherwise

Save the data pointed to by pdata into the saved or unsaved preference associated with creatorid using the format specified by type. The format is repeated count. This method returns true if successful.

Example:

Save the array 'people' into the saved preferences of "MyAp".

struct Person {
  string name;
  int age;
};

Person people[2];

bool SavePrefs() {
  Preferences prefs;
  people[0].name = "Jeremy";
  people[0].age = 26;
  people[1].name = "Hudson";
  people[1].age = 7; // in dog years
  return prefs.set("MyAp", true, people, typeof(Person), 2);
}


Contents > Library Reference > System > Preferences object > del

Preferences.del

void del(string creatorid, bool saved)

Parameters:

creatorid creator id
saved true for saved preferences, false for unsaved

Delete the preference, saved or unsaved, associated with the app creatorid.


Contents > Library Reference > System > Serial object > open

Serial.open

bool open(int port, int baud)

Parameters:

port port number
baud baud rate

Return value: true if the port was opened successfully.

Open the specified port at the specified baud rate, using default settings (1 stop bit, 8 bits per char, parity off, RTS receive flow control).

Note: Possible port values are serCradlePort, serIRPort (raw IR - does not work on devices with OMAP processor), serIrComm (works on most current devices), and serRfComm (bluetooth).
Contents > Library Reference > System > Serial object > close

Serial.close

void close()

Closes the open port.


Contents > Library Reference > System > Serial object > settings

Serial.settings

void settings(int charbits, int stopbits, int parity, char flowctl, int ctstimeout)

Parameters:

charbits bits per char
stopbits stop bits
parity parity setting (0=off, 1=on, 2=even)
flowctl flow control ('r'=RTS, 'c'=CTS, 'h'=RTS+CTR, 'x'=XonXoff, 'n'=none)
ctstimeout inter-byte timeout

Apply the given settings to the open port.


Contents > Library Reference > System > Serial object > setbuffer

Serial.setbuffer

bool setbuffer(int size)

Parameters:

size size of buffer to allocate

Return value: true if the buffer was allocated successfully.

Allocates a new receive buffer of the specified size. The default buffer is 512 bytes, so most applications will not need to enlarge it.


Contents > Library Reference > System > Serial object > clearerr

Serial.clearerr

void clearerr()

Clears all pending line errors. This method must be called if a line error occurs before further sending and receiving can be done.


Contents > Library Reference > System > Serial object > send

Serial.send

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

Parameters:

pdata data pointer
type format string
count format count

Return value: true if all data was sent without error

Sends count blocks of data over the port 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 > System > Serial object > recv

Serial.recv

bool recv(void* pdata, string type, int count, int timeout)

Parameters:

pdata data pointer
type format string
count format count
timeout timeout in ticks

Return value: true if all data was received without error

Attempts to receive count blocks of data from the port into the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type. timeout is the number of ticks to wait for the data.

Note: If the return value is false, but the no line error occured (error property is 0), then the request timed out.
Contents > Library Reference > System > Serial object > sendb

Serial.sendb

bool sendb(char byte)

Parameters:

byte byte to send

Return value: true if the data was sent without error

Sends the given byte over the port.


Contents > Library Reference > System > Serial object > recvb

Serial.recvb

bool recvb(char* pbyte)

Parameters:

pbyte pointer to byte receive

Return value: true if the data was received without error

Recieves one byte from the port, waiting up to one second to receive it. If successful, the received byte is stored in the char pointed to by pbyte.


Contents > Library Reference > System > Serial object > sendcheck

Serial.sendcheck

int sendcheck()

Return value: Bytes remaining to be sent

Retrieves the number of bytes remaining to be sent.


Contents > Library Reference > System > Serial object > recvcheck

Serial.recvcheck

int recvcheck()

Return value: Bytes in the receive buffer

Retrieves the number of bytes in the recieve buffer.


Contents > Library Reference > System > Serial object > sendwait

Serial.sendwait

bool sendwait()

Return value: true if no error occured

Waits for all pending data to be sent.


Contents > Library Reference > System > Serial object > recvwait

Serial.recvwait

bool recvwait(int bytes, int timeout)

Parameters:

bytes number of bytes to wait for
timeout timeout in ticks

Return value: true if no error or timeout occured

Waits for the specified number of bytes to be received into the receive buffer, waiting up to timeout ticks. Returns when the data is received or the timeout is reached.


Contents > Library Reference > System > Serial object > sendflush

Serial.sendflush

void sendflush()

Flushes all pending send data.


Contents > Library Reference > System > Serial object > recvflush

Serial.recvflush

void recvflush(int timeout)

Parameters:

timeout inter-byte timeout

Flushes all data from the recieve buffer, and waits until timeout ticks have passed with no new data received.


Contents > Library Reference > System > SerialStream object > read

SerialStream.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 > System > SerialStream object > write

SerialStream.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 > System > SerialStream object > readInt

SerialStream.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 > System > SerialStream object > writeInt

SerialStream.writeInt

bool writeInt(int i)

Parameters:

i int to write

Return value: true if successful

Write an int to the stream.


Contents > Library Reference > System > SerialStream object > readWord

SerialStream.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 > System > SerialStream object > writeWord

SerialStream.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 > System > SerialStream object > readFloat

SerialStream.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 > System > SerialStream object > writeFloat

SerialStream.writeFloat

bool writeFloat(float f)

Parameters:

f float to write

Return value: true if successful

Write a float to the stream.


Contents > Library Reference > System > SerialStream object > readString

SerialStream.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 > System > SerialStream object > writeString

SerialStream.writeString

bool writeString(string s)

Parameters:

s string to write

Return value: true if successful

Write a string to the stream.


Contents > Library Reference > System > SerialStream object > readChar

SerialStream.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 > System > SerialStream object > writeChar

SerialStream.writeChar

bool writeChar(char c)

Parameters:

c char to write

Return value: true if successful

Write a char to the stream.


Contents > Library Reference > System > Stream object > read

Stream.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 > System > Stream object > write

Stream.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 > System > Stream object > readInt

Stream.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 > System > Stream object > writeInt

Stream.writeInt

bool writeInt(int i)

Parameters:

i int to write

Return value: true if successful

Write an int to the stream.


Contents > Library Reference > System > Stream object > readWord

Stream.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 > System > Stream object > writeWord

Stream.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 > System > Stream object > readFloat

Stream.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 > System > Stream object > writeFloat

Stream.writeFloat

bool writeFloat(float f)

Parameters:

f float to write

Return value: true if successful

Write a float to the stream.


Contents > Library Reference > System > Stream object > readString

Stream.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 > System > Stream object > writeString

Stream.writeString

bool writeString(string s)

Parameters:

s string to write

Return value: true if successful

Write a string to the stream.


Contents > Library Reference > System > Stream object > readChar

Stream.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 > System > Stream object > writeChar

Stream.writeChar

bool writeChar(char c)

Parameters:

c char to write

Return value: true if successful

Write a char to the stream.


Contents > Library Reference > System > ISerializable object > serialize

ISerializable.serialize

bool serialize(Stream* stream)

Parameters:

stream stream pointer

Return value: true if all the data was written

This method should write all of the important data of the implementing object to the stream.


Contents > Library Reference > System > ISerializable object > deserialize

ISerializable.deserialize

bool deserialize(Stream* stream)

Parameters:

stream stream pointer

Return value: true if all the data was read

This method should read all of the important data of the implementing object to the stream.


Contents > Library Reference > System > events

events

void events(bool blocking)

Parameters:

blocking true to wait for an event to occur

Processes all pending events, calling user provided event handlers, returning when the queue is empty. If blocking is true and no events are in the queue, the function will not return until an event is processed. If an appStopEvent is received, the app's onstop handler is called but this function never returns. This function should be called during long calculations to allow the user interface to respond (for example, allowing the user to cancel).

Example:

Displays a dialog synchronously. Calling executeDialog() will open myDialog, process all its events, and return when the dialog has been closed.

bool myDialogClosed;
handler myDialog.onclose() {
  myDialogClosed = true;
}
void executeDialog() {
  myDialogClosed = false;
  myDialog.domodal();
  while (!myDialogClosed) {
    events(true);
  }
}


Contents > Library Reference > System > fatal

fatal

void fatal(string str)

Parameters:

str text to display

Displays a runtime error message containing the specified text and information about the current function. When the error message is dismissed, the app exits. This function does not return.


Contents > Library Reference > System > callstack

callstack

string callstack()

Return value: a formatted callstack

Creates a string containing a list of functions in the current callstack, one per line.


Contents > Library Reference > System > debuglog

debuglog

void debuglog(string str)

Parameters:

str text to log

Writes the text as a line to the debug log. See Debug support for details. This is not a real function, as no code is generated unless the project is compiled with the debug property set.


Contents > Library Reference > System > assert

assert

void assert(bool expr)

Parameters:

expr expression to check

When expr is false, displays an error message containing the text of the expression and a call stack. See Debug support for details. This is not a real function, as no code is generated unless the project is compiled with the debug property set.


Contents > Library Reference > System > ticks

ticks

int ticks()

Return value: tick count

Returns the number of clock ticks since the device was last reset.


Contents > Library Reference > System > tickspersec

tickspersec

int tickspersec()

Return value: ticks per second

Returns the number of clock ticks that occur each second.


Contents > Library Reference > System > resetaot

resetaot

void resetaot()

Reset the device's auto off timer. If the device goes without input for a short time, it will turn itself off. To prevent this, periodically call this function.


Contents > Library Reference > System > sleep

sleep

void sleep(int ms)

Parameters:

ms milliseconds to sleep

Causes the app to sleep for ms milliseconds. While sleeping, the CPU will be put into low power mode, but the user will not be able to interact with the device (including turning it off).


Contents > Library Reference > System > launch

launch

void launch(string creatorid)

Parameters:

creatorid creator id of app to launch

Launch the app with the given 4 character creator id. This function will post a message to quit the current app if the specified app is found. However, it will return and allow the current app to process its queued events.


Contents > Library Reference > System > launchGoto

launchGoto

void launchGoto(string creatorid, string database, int recId, int searchStrLen, int matchPos, int matchField, int matchCustom)

Parameters:

creatorid creator id of app to launch
database name of database to open (used to set GoToParamsType.dbID)
recId record to open (sets GoToParamsType.recordNum)
searchStrLen sets GoToParamsType.searchStrLen
matchPos sets GoToParamsType.matchPos
matchField sets GoToParamsType.matchFieldNum
matchCustom sets GoToParamsType.matchCustom

Launch the app with the given 4 character creator id using the system defined sysAppLaunchCmdGoTo launch code. The other parameters refer to fields in the system defined GoToParamsType structure. Different applications use the GoToParamsType differently, and not all field may be required/used by all applications. This function will post a message to quit the current app if the specified app is found. However, it will return and allow the current app to process its queued events.


Contents > Library Reference > System > launchCustomString

launchCustomString

void launchCustomString(string creatorid, int code, string param)

Parameters:

creatorid creator id of app to launch
code launch code to send
param string to pass with the launch code

Launch the app with the given 4 character creator id passing a custom launch code and a pointer to the specified string param. Only use this function if the app you are launching supports a char* launch parameter. This function will post a message to quit the current app if the specified app is found. However, it will return and allow the current app to process its queued events.

Note: In order to launch an OrbC application with a string parameter (as retrieved by UIApp.launchArgs, specify launchCodeOrbCAppWithArgs as the launch code.
Contents > Library Reference > System > username

username

string username()

Return value: HotSync username

Returns the HotSync username associated with the device.


Contents > Library Reference > System > serialnum

serialnum

string serialnum()

Return value: serial number

Returns the string representation of the device's serial number, or the empty string if it does not have one.


Contents > Library Reference > System > osver

osver

int osver()

Return value: OS version

Returns the integer version of the OS, using the standard Palm OS version specification - 32-bit number with the high 8 bits being the major version, the the next 8 bits being the minor version, and the remaining bits representing the fix number, build number, and build type.


Contents > Library Reference > System > osvers

osvers

string osvers()

Return value: OS version string

Returns the string representation of the OS version.


Contents > Library Reference > System > orbver

orbver

int orbver()

Return value: OrbC version

Returns the OrbC runtime version the current app is using - 16-bit number with the high 8 bits being the major version, and the low 8 bits being the minor version.


Contents > Library Reference > System > getclip

getclip

string getclip()

Return value: clipboard contents

Returns the contents of the clipboard if it currently contains text, otherwise it returns the empty string.


Contents > Library Reference > System > setclip

setclip

void setclip(string text)

Parameters:

text new clipboard text

Copys text to the clipboard.


Contents > Library Reference > System > memcpy

memcpy

void memcpy(void* pDest, void* pSrc, int len)

Parameters:

pDest destination pointer
pSrc source pointer
len number of values

Copies len values from pSrc to pDst. The data types at the destination must be the same as the source, or the application's behavior will be unpredictable.

Note: Each data type (int, float, string, char) has a length of 1 from the perspective of this function.
Contents > Library Reference > System > malloct

malloct

void* malloct(string type, int count)

Parameters:

type type string
count type count

Return value: pointer to allocated data

Allocates count blocks of memory, initializing the memory elements to the types specified by the type string type.


Contents > Library Reference > System > free

free

void free(void* ptr)

Parameters:

ptr pointer to memory block

Releases the memory allocated by calling malloct.


Contents > Library Reference > System > freemem

freemem

int freemem()

Return value: free memory available

Returns the amount of free dynamic memory. Because the OrbC runtime has some overhead, this value cannot be used to make any direct calculations about how much memory can be allocated.


Contents > Library Reference > System > battery

battery

int battery(bool volts)

Parameters:

volts true to retrieve voltage * 100, false to retrieve the percent remaining

Return value: percent remaining or voltage * 100

Returns the requested battery status - voltage or percent remaining.