This chapter provides reference material for the System Manager. The System Manager API is declared in the header files SystemMgr.h
and SysUtils.h
.
For more information on the System Manager, see the chapters "Application Startup and Stop" and "Palm System Support" in the Palm OS Programmer's Companion, vol. I.
System Manager Data Structures
SysDBListItemType Struct
Purpose
The SysDBListItemType
structure describes a single database or panel. The SysCreateDataBaseList()
and SysCreatePanelList()
functions each create and return an array of SysDBListItemType
structures.
Prototype
typedef struct { Char name[dmDBNameLength]; UInt32 creator; UInt32 type; UInt16 version; LocalID dbID; UInt16 cardNo; BitmapPtr iconP; } SysDBListItemType;
System Functions
SysAppLaunch Function
Purpose
Launch a specified application as a subroutine of the caller.
Declared In
SystemMgr.h
Prototype
Err SysAppLaunch ( UInt16 cardNo, LocalID dbID, UInt16 launchFlags, UInt16 cmd, MemPtr cmdPBP, UInt32 *resultP )
Parameters
-
→
cardNo
,dbID
- The card number and ID of the resource database of the application to launch.
-
→
launchFlags
- Set to 0.
-
→
cmd
- Launch code.
-
→
cmdPBP
- Launch code parameter block.
-
←
resultP
- The value returned from the application's
PilotMain()
routine.
Returns
Returns 0 if no error, or one of sysErrParamErr
, memErrNotEnoughSpace
, or sysErrOutOfOwnerIDs
.
Comments
Applications can use SysAppLaunch
to send a specific launch code to another application and have control return to the calling application when finished. This function in effect makes the specified application a subroutine of the caller. If you want to actually close your application and call another application, use SysUIAppSwitch()
instead of this function. SysUIAppSwitch
sends the current application an appStopEvent
and then starts the specified application.
Do not use this function to open the system-supplied Application Launcher application. If another application has replaced the default launcher with one of its own, this function will open the custom launcher instead of the system-supplied one. To open the system-supplied launcher reliably, enqueue a keyDownEvent
that contains a launchChr
, as shown in the section "Application Launcher" of the user interface chapter in the Palm OS Programmer's Companion, vol. I.
NOTE: For important information regarding the correct use of this function, see the "Application Startup and Stop" chapter in the Palm OS Programmer's Companion, vol. I.
See Also
SysBroadcastActionCode()
, SysUIAppSwitch()
, SysCurAppDatabase()
SysBatteryInfo Function
Purpose
Retrieve settings for the batteries. Set set
to false
to retrieve battery settings. (Applications should not change any of the settings).
Declared In
SystemMgr.h
Prototype
UInt16 SysBatteryInfo ( Boolean set, UInt16 *warnThresholdP, UInt16 *criticalThresholdP, Int16 *maxTicksP, SysBatteryKind *kindP, Boolean *pluggedIn, UInt8 *percentP )
Parameters
-
set
- If
false
, parameters with non-NULL
pointers are retrieved. Never set this parameter totrue
. -
warnThresholdP
- Pointer to battery voltage warning threshold in volts*100, or
NULL
. -
criticalThresholdP
- Pointer to the battery voltage critical threshold in volts*100, or
NULL
. -
maxTicksP
- Pointer to the battery timeout, or
NULL
. -
kindP
- Pointer to the battery kind, or
NULL
. -
pluggedIn
- Pointer to
pluggedIn
return value, orNULL
. -
percentP
- Percentage of power remaining in the battery.
Returns
Returns the current battery voltage in volts*100.
Comments
Call this function to make sure an upcoming activity won't be interrupted by a low battery warning.
warnThresholdP
and maxTicksP
are the battery-warning voltage threshold and time out. If the battery voltage falls below the threshold, or the timeout expires, a lowBatteryChr
key event is put on the queue. Normally, applications call SysHandleEvent()
which calls SysBatteryDialog
in response to this event.
criticalThresholdP
is the battery voltage threshold. If battery voltage falls below this level, the system turns itself off without warning and doesn't turn on until battery voltage is above it again.
Compatibility
This function was revised for Palm OS® 3.0. In Palm OS 3.0, the percentP
parameter was added. This enhancement is implemented only if 3.0 New Feature Set is present.
See Also
SysBatteryInfoV20 Function
Purpose
Retrieve settings for the batteries. Set to false
to retrieve battery settings. (Applications should not change any of the settings).
Declared In
SystemMgr.h
Prototype
UInt16 SysBatteryInfoV20 ( Boolean set, UInt16 *warnThresholdP, UInt16 *criticalThresholdP, Int16 *maxTicksP, SysBatteryKind *kindP, Boolean *pluggedIn )
Parameters
-
set
- If
false
, parameters with non-NULL
pointers are retrieved. Never set this parameter totrue
. -
warnThresholdP
- Pointer to battery voltage warning threshold in volts*100, or
NULL
. -
criticalThresholdP
- Pointer to the battery voltage critical threshold in volts*100, or
NULL
. -
maxTicksP
- Pointer to the battery timeout, or
NULL
. -
kindP
- Pointer to the battery kind, or
NULL
. -
pluggedIn
- Pointer to
pluggedIn
return value, orNULL
.
Returns
Returns the current battery voltage in volts*100.
Comments
Call this function to make sure an upcoming activity won't be interrupted by a low battery warning.
warnThresholdP
and maxTicksP
are the battery-warning voltage threshold and time out. If the battery voltage falls below the threshold, or the timeout expires, a lowBatteryChr
key event is put on the queue. Normally, applications call SysHandleEvent()
which calls SysBatteryDialog
in response to this event.
criticalThresholdP
is the battery voltage threshold. If battery voltage falls below this level, the system turns itself off without warning and doesn't turn on until battery voltage is above it again.
Compatibility
This function corresponds to the Palm OS 2.0 version of SysBatteryInfo
. Implemented only if 3.0 New Feature Set is present.
See Also
SysBinarySearch Function
Purpose
Search elements in a sorted array for the specified data according to the specified comparison function.
Declared In
SysUtils.h
Prototype
Boolean SysBinarySearch ( void const *baseP, UInt16 numOfElements, Int16 width, SearchFuncPtr searchF, void const *searchData, Int32 other, Int32 *position, Boolean findFirst )
Parameters
-
baseP
- Base pointer to an array of elements
-
numOfElements
- Number of elements to search. Must be greater than 0.
-
width
- Width of each array element.
-
searchF
- Search function.
-
searchData
- Data to search for. This data is passed to the
searchF
function. -
other
- Data to be passed as the third parameter (the
other
parameter) to the comparison function. -
position
- Pointer to the position result.
-
findFirst
- If set to
true
, the first matching element is returned. Use this parameter if the array contains duplicate entries to ensure that the first such entry will be the one returned.
Returns
Returns true
if an exact match was found. In this case, position
points to the element number where the data was found.
Returns false
if an exact match was not found. If false
is returned, position
points to the element number where the data should be inserted if it was to be added to the array in sorted order.
Comments
The array must be sorted in ascending order prior to the search. Use SysInsertionSort()
or SysQSort()
to sort the array.
The search starts at element 0 and ends at element (numOfElements
- 1).
The search function's (searchF
) prototype is:
Int16 _searchF (void const *searchData, void const *arrayData, Int32 other);
The first parameter is the data for which to search, the second parameter is a pointer to an element in the array, and the third parameter is any other necessary data.
- > 0 if the search data is greater than the element
- < 0 if the search data is less than the element
- 0 if the search data is the same as the element
Compatibility
Implemented only if 2.0 New Feature Set is present. Prior to Palm OS Garnet version 5.3SC, the numOfElements
parameter was declared to be an Int16
, limiting the number of elements to be searched to 32,767.
SysBroadcastActionCode Function
Purpose
Send the specified action code (launch code) and parameter block to the latest version of every UI application.
Declared In
SystemMgr.h
Prototype
Err SysBroadcastActionCode ( UInt16 cmd, MemPtr cmdPBP )
Parameters
Returns
Returns 0 if no error, or one of the following errors: sysErrParamErr
, memErrNotEnoughSpace
, or sysErrOutOfOwnerIDs
.
See Also
SysAppLaunch()
, Chapter 2, "Application Startup and Stop." of the Palm OS Programmer's Companion, vol. I
SysCopyStringResource Function
Purpose
Copy a resource string to a passed string.
Declared In
SysUtils.h
Prototype
void SysCopyStringResource ( Char *string, Int16 theID )
Parameters
Returns
Stores a copy of the resource string in string
.
SysCreateDataBaseList Function
Purpose
Generate a list of databases found on the memory cards matching a specific type and return the result. If lookupName
is true
then a name in a tAIN
resource is used instead of the database's name and the list is sorted. Only the last version of a database is returned. Databases with multiple versions are listed only once.
Declared In
SystemMgr.h
Prototype
Boolean SysCreateDataBaseList ( UInt32 type, UInt32 creator, UInt16 *dbCount, MemHandle *dbIDs, Boolean lookupName )
Parameters
-
type
- The type of database to find. Use
0
to find all databases. -
creator
- The creator ID of the database to find. Use
0
to find any creator ID. -
dbCount
- A pointer to an integer value that is updated by this function to the number of matching databases.
-
dbIDs
- A pointer to a handle that gets allocated to contain the database list. Upon return, this references an array of
SysDBListItemType
structures. See the Comments section below for more information. -
lookupName
- If
true
,SysCreateDatabaseList
usestAIN
names and sorts the list.
Returns
Returns false
if no databases were found, and true
if any databases were found. The value of dbCount
is updated to reflect the number of databases that were found. If at least one database is found, dbIDs
is updated to reference a array of SysDBListItemType
structures; this array contains dbCount
items.
Comments
This function creates a list of unique databases, where unique is defined as having a different type and creator ID. Two or more databases with the same type and creator ID are counted as one. Thus, you cannot use SysCreateDataBaseList
to build a list of databases that share a common type and creator. There are two exceptions to this rule, however. If type
is 0 or if creator
is not 0, the code that removes "non-unique" databases isn't run. It also isn't run if the type is sysFileTpqa
, since web-clipping databases all have the same type and creator ID.
If this function returns true
and the value of dbCount
is greater then 0, than you can iterate through the list of database items, as shown in Listing 54.1
Listing 54.1 Using the SysCreateDatabaseList function
SysDBListItemType *dbListIDsP; MemHandle dbListIDsH; UInt16 dbCount = 0; Boolean status; UInt16 counter; SysDBListItemType theItem; status = SysCreateDatabaseList(sysFileTpqa, 0, &dbCount, &dbListIDsH, false); if (status == true && dbCount > 0) { dbListIDsP = MemHandleLock (dbListIDsH); for (counter = 0; counter < dbCount; counter++) if StrCompare(dbListIDsP[counter].name, "MINE") == 0 // we found my database ... ... MemPtrFree (dbListIDsP); }
NOTE: It is your responsibility to free the memory allocated by this function for the list of databases.
Compatibility
Implemented only if 2.0 New Feature Set is present.
SysCreatePanelList Function
Purpose
Generate a list of panels found on the memory cards and return the result. Multiple versions of a panel are listed once.
Declared In
SystemMgr.h
Prototype
Boolean SysCreatePanelList ( UInt16 *panelCount, MemHandle *panelIDs )
Parameters
-
panelCount
- Pointer to set to the number of panels.
-
panelIDs
- A pointer to a handle that gets allocated to contain the panel list. Upon return, this references an array of
SysDBListItemType
structures.
Returns
Returns false
if no panels were found, and true
if any panels were found. The value of panelCount
is updated to reflect the number of panels that were found. If at least one panel is found, panelIDs
is updated to reference a array of SysDBListItemType
structures; this array contains panelCount
items.
Comments
If this function returns true
and the value of panelCount
is greater than 0, than you can iterate through the list of panel items, as shown in Listing 54.1. It is your responsibility to free the memory allocated for the panel list.
Compatibility
Implemented only if 2.0 New Feature Set is present.
SysCurAppDatabase Function
Purpose
Return the card number and database ID of the current application's resource database.
Declared In
SystemMgr.h
Prototype
Err SysCurAppDatabase ( UInt16 *cardNoP, LocalID *dbIDP )
Parameters
Returns
Returns 0 if no error, or SysErrParamErr
if an error occurs.
See Also
SysAppLaunch()
, SysUIAppSwitch()
SysErrString Function
Purpose
Returns text to describe an error number. This routine looks up the textual description of a system error number in the appropriate List resource and creates a string that can be used to display that error.
The actual string will be of the form: "<error message> (XXXX)" where XXXX is the hexadecimal error number.
This routine looks for a resource of type 'tstl' and resource ID of (err>>8). It then grabs the string at index (err & 0x00FF) out of that resource.
The first string in the resource is called index #1 by Constructor, NOT #0. For example, an error code of 0x0101 will fetch the first string in the resource.
Declared In
SysUtils.h
Prototype
Char *SysErrString ( Err err, Char *strP, UInt16 maxLen )
Parameters
Returns
Stores the error number string.
Compatibility
Implemented only if 2.0 New Feature Set is present.
SysFormPointerArrayToStrings Function
Purpose
Form an array of pointers to strings in a block. Useful for setting the items of a list.
Declared In
SysUtils.h
Prototype
MemHandle SysFormPointerArrayToStrings ( Char *c, Int16 stringCount )
Parameters
-
c
- Pointer to packed block of strings, each terminated by a null character.
-
stringCount
- Count of strings in block.
Returns
Unlocked handle to allocated array of pointers to the strings in the passed block. The returned array points to the strings in the passed packed block. Note that you'll need to free the returned handle when you no longer need it.
See Also
sysFtrNumProcessorIs68K Macro
Purpose
Determines whether or not the underlying processor is part of the 68K family.
Declared In
SystemMgr.h
Prototype
#define sysFtrNumProcessorIs68K( x )
Parameters
-
→
x
- Processor type obtained from a call to
FtrGet()
.
Returns
Returns true
if the underlying processor is a 68K, false
otherwise.
Comments
This macro is typically used in conjunction with PceNativeCall()
.
Example
UInt32 processorType; FtrGet(sysFileCSystem, sysFtrNumProcessorID, &processorType); if (sysFtrNumProcessorIs68K(processorType)){ // processor is 68K } else { // processor is not 68K }
sysFtrNumProcessorIsARM Macro
Purpose
Determines whether or not the underlying processor is part of the ARM family.
Declared In
SystemMgr.h
Prototype
#define sysFtrNumProcessorIsARM( x )
Parameters
-
→
x
- Processor type obtained from a call to
FtrGet()
.
Returns
Returns true
if the underlying processor is an ARM core, false
otherwise.
Comments
This macro is typically used in conjunction with PceNativeCall()
.
Example
UInt32 processorType; FtrGet(sysFileCSystem, sysFtrNumProcessorID, &processorType); if (sysFtrNumProcessorIsARM(processorType)){ // processor is ARM } else { // processor is not ARM }
SysGetOSVersionString Function
Purpose
Return the version number of the Palm™ operating system.
Declared In
SystemMgr.h
Prototype
Char *SysGetOSVersionString()
Parameters
Returns
Returns a string such as "v. 3.0."
Comments
You must free the returned string using the MemPtrFree()
function.
Compatibility
Implemented only if 3.0 New Feature Set is present.
SysGetROMToken Function
Purpose
Return from ROM a value specified by token.
Declared In
SystemMgr.h
Prototype
Err SysGetROMToken ( UInt16 cardNo, UInt32 token, UInt8 **dataP, UInt16 *sizeP )
Parameters
-
→
cardNo
- The card on which the ROM to be queried resides. Currently, no Palm hardware provides multiple cards, so this value must be 0.
-
→
token
- The value to retrieve, as specified by one of the following tokens:
-
←
dataP
- Pointer to a text buffer that holds the requested value when the function returns.
-
←
sizeP
- The number of bytes in the
dataP
buffer.
Returns
Returns the requested value if no error, or an error code if an error occurs. If this function returns an error, or if the returned pointer to the buffer is NULL
, or if the first byte of the text buffer is 0xFF
, then no serial number is available.
Comments
The serial number is shown to the user in the Application Launcher, along with a checksum digit you can use to validate input when your users read the ID from their device and type it in or tell it to someone else.
Compatibility
Implemented only if 3.0 New Feature Set is present. Serial numbers are available only on flash ROM-based units.
See Also
"Retrieving the ROM Serial Number" section in the Palm OS Programmer's Companion, vol. I shows how to retrieve the ROM serial number and calculate its associated checksum.
SysGetStackInfo Function
Purpose
Return the start and end of the current thread's stack.
Declared In
SystemMgr.h
Prototype
Boolean SysGetStackInfo ( MemPtr *startPP, MemPtr *endPP )
Parameters
-
startPP
- Upon return, points to the start of the stack.
-
endPP
- Upon return, points to the end of the stack.
Returns
Returns true
if the stack has not overflowed, that is, the value of the stack overflow address has not been changed. Returns false
if the stack overflow value has been overwritten, meaning that a stack overflow has occurred.
Compatibility
Implemented only if 3.0 New Feature Set is present.
SysGetTrapAddress Function
Purpose
Return the address of a function given its system trap.
Declared In
SystemMgr.h
Prototype
void *SysGetTrapAddress ( UInt16 trapNum )
Parameters
-
→
trapNum
- One of the routine selectors defined in
SysTraps.h
(sysTrap...
) orCoreTraps.h
on Palm OS version 3.5 and higher.
Returns
Returns the address of the corresponding function. Returns the address of the sysTrapSysUnimplemented
routine if an invalid routine selector is passed; compare the results of this function to SysGetTrapAddress(sysTrapSysUnimplemented)
if you need to check for an invalid routine selector.
Comments
Use this function for performance reasons. You can then use the address it returns to call the function without having to go through the trap dispatch table. This function is mostly useful for optimizing the performance of functions called in a tight loop.
The Palm OS trap dispatch mechanism allows the trap table entries to be modified at any time, either as the result of a system update or a hack. For this reason, it's important to call this function immediately before entering the tight loop. If the trap address changes in between when you call SysGetTrapAddress
and you use the address, the wrong function will be called.
Compatibility
On Palm OS 3.0 and earlier, this function contains a bug that causes it to return a garbage value if an invalid routine selector is passed. To prevent this bug from affecting your application, use SysGlueGetTrapAddress
in the PalmOSGlue library instead of calling this function directly. For more information, see Chapter 80, "PalmOSGlue Library."
SysGremlins Function
Purpose
Query the Gremlins facility. You pass a selector for a function and parameters for that function. Gremlins performs the function call and returns the result.
Declared In
SysUtils.h
Prototype
UInt32 SysGremlins ( GremlinFunctionType selector, GremlinParamsType *params )
Parameters
-
selector
- The selector for a function to pass to Gremlins.
-
params
- Pointer to a parameter block used to pass parameters to the function specified by
selector
.
Returns
Returns the result of the function performed in Gremlins.
Comments
Currently, only one selector is defined, GremlinIsOn
, which takes no parameters. GremlinIsOn
returns 0 if Gremlins is not running, non-zero if it is running.
Currently, non-zero values are returned only from the version of Gremlins in the Palm OS emulator. The Gremlins running in the Simulator on a Macintosh and over the serial line via the Palm Debugger return zero for GremlinIsOn
.
Use this function if you need to alter the application's behavior when Gremlins is running. For example, the debug 3.0 ROM refuses to bring up the digitizer panel when Gremlins is running under the emulator.
Compatibility
Implemented only if 3.0 New Feature Set is present.
In Palm OS 3.2 and later, SysGremlins
is replaced by the functions defined in the file HostControl.h
. Specifically, the one selector supported by SysGremlins
is replaced with the function HostGremlinIsRunning
. For backward compatibility, SysGremlins
is mapped to HostGremlinIsRunning
.
SysHandleEvent Function
Purpose
Handle defaults for system events such as hard and soft key presses.
Declared In
SystemMgr.h
Prototype
Boolean SysHandleEvent ( EventPtr eventP )
Parameters
Returns
Returns true
if the system handled the event.
Comments
Applications should call this routine immediately after calling EvtGetEvent()
unless they want to override the default system behavior. However, overriding the default system behavior is almost never appropriate for an application.
See Also
EvtProcessSoftKeyStroke()
, KeyRates()
SysInsertionSort Function
Purpose
Sort elements in an array according to the passed comparison function.
Declared In
SysUtils.h
Prototype
void SysInsertionSort ( void *baseP, UInt16 numOfElements, Int16 width, CmpFuncPtr comparF, Int32 other )
Parameters
-
baseP
- Base pointer to an array of elements.
-
numOfElements
- Number of elements to sort (must be at least 2).
-
width
- Width of an element.
-
comparF
- Comparison function. See Comments, below.
-
other
- Other data passed to the comparison function.
Returns
Comments
Only elements which are out of order move. Moved elements are moved to the end of the range of equal elements. If a large amount of elements are being sorted, try to use the quick sort (see SysQSort()
).
This is the insertion sort algorithm: Starting with the second element, each element is compared to the preceding element. Each element not greater than the last is inserted into sorted position within those already sorted. A binary search for the insertion point is performed. A moved element is inserted after any other equal elements.
In order to use SysInsertionSort
you must write a comparison function with the following prototype:
Int16 comparF (void *p1, void *p2, Int32 other)
Your comparison function must return zero if p1 equals p2, a positive integer value if p1 is greater than p2, and a negative integer value if p1 is less than p2. Note that the value of the parameter named other
is passed through from the SysInsertionSort
call and can be used to control the behavior of the comparF
function if appropriate for your application.
Compatibility
The Palm OS 2.0 comparison function (comparF
) has this prototype:
Int comparF (VoidPtr, VoidPtr, Long other);
The Palm OS 1.0 comparison function (comparF
) has this prototype:
Int comparF (BytePtr A, BytePtr B, Long other);
Prior to Palm OS Garnet version 5.3SC, the numOfElements
parameter was declared to be an Int16
, limiting the number of elements to be sorted to 32,767.
See Also
SysKeyboardDialog Function
Purpose
Pop up the system keyboard if there is a field object with the focus. The field object's text chunk is edited directly.
Declared In
Keyboard.h
Prototype
void SysKeyboardDialog ( KeyboardType kbd )
Parameters
Returns
Returns nothing. Changes the field's text chunk.
Compatibility
Implemented only if 2.0 New Feature Set is present.
See Also
SysKeyboardDialogV10()
, FrmSetFocus()
SysKeyboardDialogV10 Function
Purpose
Pop up the system keyboard if there is a field object with the focus. The field object's text chunk is edited directly.
Declared In
Keyboard.h
Prototype
void SysKeyboardDialogV10 ()
Parameters
Returns
Returns nothing. The field's text chunk is changed.
Compatibility
Corresponds to the 1.0 implementation of SysKeyboardDialog
.
See Also
SysKeyboardDialog()
, FrmSetFocus()
SysLibFind Function
Purpose
Return a reference number for a library that is already loaded, given its name.
Declared In
SystemMgr.h
Prototype
Err SysLibFind ( const Char *nameP, UInt16 *refNumP )
Parameters
-
nameP
- Pointer to the name of a loaded library.
-
refNumP
- Pointer to a variable for returning the library reference number (on failure, this variable is undefined)
Returns
0 if no error; otherwise: sysErrLibNotFound
(if the library is not yet loaded), or another error returned from the library's install entry point.
Comments
Most built-in libraries (NetLib, serial, IR) are preloaded automatically when the system is reset. Third-party libraries must be loaded before this call can succeed (use SysLibLoad()
). You can check if a library is already loaded by calling SysLibFind
and checking for a 0 error return value (it will return a non-zero value if the library is not loaded).
SysLibInstall Function
Purpose
Installs a library into the Library table and calls the library's install entry point.
Declared In
SystemMgr.h
Prototype
Err SysLibInstall ( SysLibEntryProcPtr libraryP, UInt16 *refNumP )
Parameters
-
→ libraryP
- Pointer to the library being installed.
-
← refNumP
- Pointer to the variable in which the installed library reference number is stored upon return.
Returns
Returns 0 if no error, memErrNotEnoughSpace
if an error occurs while allocating memory in the library table, or, if an error is returned by the call to the library's install entry point, that error is returned and the reference number is set to sysInvalidRefNum
.
Comments
This routine is largely used by the Palm OS, but can also be called by applications that need to install their own libraries.
Compatibility
Implemented only if 2.0 New Feature Set is present.
SysLibLoad Function
Purpose
Load a library given its database creator and type.
Declared In
SystemMgr.h
Prototype
Err SysLibLoad ( UInt32 libType, UInt32 libCreator, UInt16 *refNumP )
Parameters
-
libType
- Type of library database.
-
libCreator
- Creator of library database.
-
refNumP
- Pointer to variable for returning the library reference number (on failure,
sysInvalidRefNum
is returned in this variable)
Returns
0 if no error; otherwise: sysErrLibNotFound
, sysErrNoFreeRAM
, sysErrNoFreeLibSlots
, or other error returned from the library's install entry point.
Comments
When an application no longer needs a library that it successfully loaded via SysLibLoad
, it is responsible for unloading the library by calling SysLibRemove()
and passing it the library reference number returned by SysLibLoad
. More information is available in the white paper on shared libraries, which you can find on the Palm developer support web site.
Compatibility
Implemented only if 2.0 New Feature Set is present.
SysLibRemove Function
Purpose
Unload a library previously loaded with SysLibLoad()
.
Declared In
SystemMgr.h
Prototype
Err SysLibRemove ( UInt16 refNum )
Parameters
Returns
0 if no error; otherwise sysErrParamErr
if the refNum
is not a valid library reference number.
Comments
SysLibRemove
releases the dynamic memory allocated to the shared library's dispatch table, resources, and global variables.
SysQSort Function
Purpose
Sort elements in an array according to the supplied comparison function.
Declared In
SysUtils.h
Prototype
void SysQSort ( void *baseP, UInt16 numOfElements, Int16 width, CmpFuncPtr comparF, Int32 other )
Parameters
-
baseP
- Base pointer to an array of elements.
-
numOfElements
- Number of elements to sort (must be at least 2).
-
width
- Width of an element.
-
comparF
- Comparison function. See Comments, below.
-
other
- Other data passed to the comparison function.
Returns
Comments
Equal records can be in any position relative to each other because a quick sort tends to scramble the ordering of records. As a result, calling SysQSort
multiple times can result in a different order if the records are not completely unique. If you don't want this behavior, use the insertion sort instead (see SysInsertionSort()
).
To pick the pivot point, the quick sort algorithm picks the middle of three records picked from around the middle of all records. That way, the algorithm can take advantage of partially sorted data.
These optimizations are built in:
- The routine contains its own stack to limit uncontrolled recursion. When the stack is full, an insertion sort is used because it doesn't require more stack space.
- An insertion sort is also used when the number of records is low. This avoids the overhead of a quick sort which is noticeable for small numbers of records.
- If the records seem mostly sorted, an insertion sort is performed to move only those few records that need to be moved.
In order to use SysQSort
you must write a comparison function with the following prototype:
Int16 comparF (void *p1, void *p2, Int32 other)
Your comparison function must return zero if p1 equals p2, a positive integer value if p1 is greater than p2, and a negative integer value if p1 is less than p2. Note that the value of the parameter named other
is passed through from the SysQSort
call and can be used to control the behavior of the comparF
function if appropriate for your application.
Compatibility
The Palm OS 2.0 comparison function (comparF
) has this prototype:
Int comparF (VoidPtr, VoidPtr, Long other);
The Palm OS 1.0 comparison function (comparF
) has this prototype:
Int comparF (BytePtr A, BytePtr B, Long other);
Prior to Palm OS Garnet version 5.3SC the numOfElements
parameter was declared to be an Int16
, limiting the number of elements to be sorted to 32,767.
See Also
SysRandom Function
Purpose
Return a random number anywhere from 0 to sysRandomMax
.
Declared In
SysUtils.h
Prototype
Int16 SysRandom ( Int32 newSeed )
Parameters
Returns
SysReset Function
Purpose
Perform a soft reset and reinitialize the globals and the dynamic memory heap.
Declared In
SystemMgr.h
Prototype
void SysReset ( void )
Parameters
Returns
Comments
This routine resets the system, reinitializes the globals area and all system managers, and reinitializes the dynamic heap. All database information is preserved. This routine is called when the user presses the hidden reset switch on the device.
When running an application using the simulator, this routine looks for two data files that represent the memory of card 0 and card 1. If these are found, the Palm OS memory image is created using them. If they are not found, they are created.
When running an application on the device, this routine simply looks for the memory cards at fixed locations.
SysSetAutoOffTime Function
Purpose
Set the time out value in seconds for auto-power-off. Zero means never power off.
Declared In
SystemMgr.h
Prototype
UInt16 SysSetAutoOffTime ( UInt16 seconds )
Parameters
Returns
Returns previous value of time out in seconds.
SysSetTrapAddress Function
Purpose
Set the address of the function corresponding to a system trap.
Declared In
SystemMgr.h
Prototype
Err SysSetTrapAddress ( UInt16 trapNum, void *procP )
Parameters
-
→
trapNum
- One of the routine selectors defined in
SysTraps.h
(sysTrap...
) orCoreTraps.h
on Palm OS version 3.5 and higher. -
→
procP
- Pointer to a function that the trap identified by
trapNum
is to point to.
Returns
Returns 0 if no error, or SysErrParamErr
if trapNum
is greater than the number of traps in the trap table.
Comments
This function is useful for patching a system trap, in combination with SysGetTrapAddress()
. To patch a system trap in your application, first call SysGetTrapAddress
to get the trap address and then save this value somewhere. Next use SysSetTrapAddress
to set the trap address to point to your function. Before your application exits, remove the patch by calling SysSetTrapAddress
and passing in the original trap address you saved.
WARNING! If your application patches a system trap using this function, you must remove the patch before your application exits. Do not use this mechanism to permanently patch system traps as it may cause unpredictable results for the system and other applications.
Compatibility
If either 5.0 New Feature Set or Palm OS Cobalt Feature Set is present this function is unimplemented.
SysStringByIndex Function
Purpose
Copy a string out of a string list resource by index. String list resources are of type 'tSTL'
and contain a list of strings and a prefix string.
ResEdit always displays the items in the list as starting at 1, not 0. Consider this when creating your string list.
Declared In
SysUtils.h
Prototype
Char *SysStringByIndex ( UInt16 resID, UInt16 index, Char *strP, UInt16 maxLen )
Parameters
-
resID
- Resource ID of the string list.
-
index
- String to get out of the list.
-
strP
- Pointer to space to form the string.
-
maxLen
- Size of
strP
buffer.
Returns
Returns a pointer to the copied string. The string returned from this call will be the prefix string appended with the designated index string. Indices are 0-based; index 0 is the first string in the resource.
Compatibility
Implemented only if 2.0 New Feature Set is present.
SysTaskDelay Function
Purpose
Put the processor into doze mode for the specified number of ticks.
Declared In
SystemMgr.h
Prototype
Err SysTaskDelay ( Int32 delay )
Parameters
-
delay
- Number of ticks to wait (see
SysTicksPerSecond()
)
Returns
See Also
SysTicksPerSecond Function
Purpose
Return the number of ticks per second. This routine allows applications to be tolerant of changes to the ticks per second rate in the system.
Declared In
SystemMgr.h
Prototype
UInt16 SysTicksPerSecond ( void )
Parameters
Returns
Returns the number of ticks per second.
Compatibility
Implemented only if 2.0 New Feature Set is present.
SysUIAppSwitch Function
Purpose
Try to make the current UI application quit and then launch the UI application specified by card number and database ID.
Declared In
SystemMgr.h
Prototype
Err SysUIAppSwitch ( UInt16 cardNo, LocalID dbID, UInt16 cmd, MemPtr cmdPBP )
Parameters
-
→
cardNo
- Card number for the new application; currently only card 0 is valid.
-
→
dbID
- ID of the new application's resource database.
-
→
cmd
- Action code (launch code).
-
→
cmdPBP
- Action code (launch code) parameter block.
Returns
May display a fatal error message if the cardNo
parameter is invalid. On debug ROMs, displays a fatal error message if there is no currently running application.
Comments
Do not use this function to open the system-supplied Application Launcher application. If a third-party launch is installed, you'll likely want to launch that one instead. To do this, enqueue a keyDownEvent
that contains a launchChr
, as shown in the section "Application Launcher" of the user interface chapter in the Palm OS Programmer's Companion, vol. I. This will run whatever is run whenever you tap on the Applications icon.
If you are passing a parameter block (the cmdPBP
parameter), you must set the owner of the parameter block chunk to the operating system. To do this, and for more information, see MemPtrSetOwner()
. If the parameter block structure contains references by pointer or handle to any other chunks, you also must set the owner of those chunks by using MemHandleSetOwner()
or MemPtrSetOwner()
as appropriate. If you set the owner of this parameter block properly, the system maintains the parameter block and frees it when the second application quits. If you don't set the owner of the parameter block, the system frees the parameter block as soon as the calling application quits, causing unpredictable results.
See Also
SysAppLaunch()
, Chapter 2, "Application Startup and Stop," in the Palm OS Programmer's Companion, vol. I.
Application-Defined Functions
PilotMain Function
Purpose
The entry point for all Palm OS applications, this function's sole purpose is to receive and respond to launch codes.
Declared In
SystemMgr.h
Prototype
UInt32 PilotMain( UInt16 cmd, void *cmdPBP, UInt16 launchFlags )
Parameters
-
→
cmd
- The launch code to which your application is to respond. See Chapter 1, "Application Launch Codes," for a list of predefined launch codes. You may create additional launch codes; see "Creating Your Own Launch Codes" of the Palm OS Programmer's Companion, vol. I.
-
→
cmdPBP
- A pointer to a structure containing any launch-command-specific parameters, or
NULL
if the launch code has none. See the description of each launch code for a description of the parameter structure that accompanies it, if any. -
→
launchFlags
- Flags that indicate whether your application's global variables are available, whether your application is now the active application, whether it already was the active application, and so on. See "Launch Flags" for a list of launch flags.
Returns
Return errNone
if your application processed the launch code successfully, or an appropriate error code if there was a problem. When another application invokes your application using SysAppLaunch()
, this value is returned to the caller.
Comments
See Chapter 2, "Application Startup and Stop," of the Palm OS Programmer's Companion, vol. I for a discussion on how applications receive and handle launch codes, with examples.