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.