Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

54    System Manager

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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 ^TOP^

SysDBListItemType Struct ^TOP^

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 ^TOP^

SysAppLaunch Function ^TOP^

Purpose

Launch a specified application as a subroutine of the caller.

Declared In

SystemMgr.h

Prototype

Err SysAppLaunch (
   UInt16cardNo,
   LocalIDdbID,
   UInt16launchFlags,
   UInt16cmd,
   MemPtrcmdPBP,
   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 ^TOP^

Purpose

Retrieve settings for the batteries. Set set to false to retrieve battery settings. (Applications should not change any of the settings).


WARNING! Use this function only to retrieve settings!

Declared In

SystemMgr.h

Prototype

UInt16 SysBatteryInfo (
   Booleanset,
   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 to true.
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, or NULL.
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()

SysBatteryInfoV20 Function ^TOP^

Purpose

Retrieve settings for the batteries. Set to false to retrieve battery settings. (Applications should not change any of the settings).


WARNING! Use this function only to retrieve settings!

Declared In

SystemMgr.h

Prototype

UInt16 SysBatteryInfoV20 (
   Booleanset,
   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 to true.
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, or NULL.

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

SysBatteryInfo()

SysBinarySearch Function ^TOP^

Purpose

Search elements in a sorted array for the specified data according to the specified comparison function.

Declared In

SysUtils.h

Prototype

Boolean SysBinarySearch (
   voidconst*baseP,
   UInt16numOfElements,
   Int16width,
   SearchFuncPtrsearchF,
   voidconst*searchData,
   Int32other,
   Int32*position,
   BooleanfindFirst
)

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 (voidconst*searchData,
voidconst*arrayData, Int32other);

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.

The function returns:

  • > 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 ^TOP^

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 (
   UInt16cmd,
   MemPtrcmdPBP
)

Parameters

cmd
Action code to send.
cmdPBP
Action code parameter block to send.

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 ^TOP^

Purpose

Copy a resource string to a passed string.

Declared In

SysUtils.h

Prototype

void SysCopyStringResource (
   Char*string,
   Int16theID
)

Parameters

string
String to copy the resource string to.
theID
Resource string ID.

Returns

Stores a copy of the resource string in string.

SysCreateDataBaseList Function ^TOP^

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 (
   UInt32type,
   UInt32creator,
   UInt16*dbCount,
   MemHandle*dbIDs,
   BooleanlookupName
)

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 uses tAIN 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; 
MemHandledbListIDsH; 
UInt16dbCount = 0; 
Booleanstatus; 
UInt16counter; 
SysDBListItemTypetheItem; 
 
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 ^TOP^

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 ^TOP^

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

cardNoP
Pointer to the card number; 0 or 1.
dbIDP
Pointer to the database ID.

Returns

Returns 0 if no error, or SysErrParamErr if an error occurs.

See Also

SysAppLaunch(), SysUIAppSwitch()

SysErrString Function ^TOP^

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 (
   Errerr,
   Char*strP,
   UInt16maxLen
)

Parameters

err
Error number
strP
Pointer to space to form the string
maxLen
Size of strP buffer.

Returns

Stores the error number string.

Compatibility

Implemented only if 2.0 New Feature Set is present.

SysFormPointerArrayToStrings Function ^TOP^

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,
   Int16stringCount
)

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

LstSetListChoices()

sysFtrNumProcessorIs68K Macro ^TOP^

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 ^TOP^

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 ^TOP^

Purpose

Return the version number of the Palm operating system.

Declared In

SystemMgr.h

Prototype

Char *SysGetOSVersionString()

Parameters

None.

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 ^TOP^

Purpose

Return from ROM a value specified by token.

Declared In

SystemMgr.h

Prototype

Err SysGetROMToken (
   UInt16cardNo,
   UInt32token,
   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:
sysROMTokenSnum
The serial number of the ROM, expressed as a text string with no null terminator.
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 ^TOP^

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 ^TOP^

Purpose

Return the address of a function given its system trap.

Declared In

SystemMgr.h

Prototype

void *SysGetTrapAddress (
   UInt16trapNum
)

Parameters

trapNum
One of the routine selectors defined in SysTraps.h (sysTrap...) or CoreTraps.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 ^TOP^

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 (
   GremlinFunctionTypeselector,
   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 ^TOP^

Purpose

Handle defaults for system events such as hard and soft key presses.

Declared In

SystemMgr.h

Prototype

Boolean SysHandleEvent (
   EventPtreventP
)

Parameters

eventP
Pointer to an event.

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 ^TOP^

Purpose

Sort elements in an array according to the passed comparison function.

Declared In

SysUtils.h

Prototype

void SysInsertionSort (
   void*baseP,
   UInt16numOfElements,
   Int16width,
   CmpFuncPtrcomparF,
   Int32other
)

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

Returns nothing.

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, Int32other)

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

SysQSort()

SysKeyboardDialog Function ^TOP^

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 (
   KeyboardTypekbd
)

Parameters

kbd
The keyboard type. See Keyboard.h.

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 ^TOP^

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

None.

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 ^TOP^

Purpose

Return a reference number for a library that is already loaded, given its name.

Declared In

SystemMgr.h

Prototype

Err SysLibFind (
   constChar*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 ^TOP^

Purpose

Installs a library into the Library table and calls the library's install entry point.

Declared In

SystemMgr.h

Prototype

Err SysLibInstall (
   SysLibEntryProcPtrlibraryP,
   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 ^TOP^

Purpose

Load a library given its database creator and type.

Declared In

SystemMgr.h

Prototype

Err SysLibLoad (
   UInt32libType,
   UInt32libCreator,
   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 ^TOP^

Purpose

Unload a library previously loaded with SysLibLoad().

Declared In

SystemMgr.h

Prototype

Err SysLibRemove (
   UInt16refNum
)

Parameters

refNum
The library reference number.

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 ^TOP^

Purpose

Sort elements in an array according to the supplied comparison function.

Declared In

SysUtils.h

Prototype

void SysQSort (
   void*baseP,
   UInt16numOfElements,
   Int16width,
   CmpFuncPtrcomparF,
   Int32other
)

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

Returns nothing.

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, Int32other)

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

SysInsertionSort()

SysRandom Function ^TOP^

Purpose

Return a random number anywhere from 0 to sysRandomMax.

Declared In

SysUtils.h

Prototype

Int16 SysRandom (
   Int32newSeed
)

Parameters

newSeed
New seed value, or 0 to use existing seed.

Returns

Returns a random number.

SysReset Function ^TOP^

Purpose

Perform a soft reset and reinitialize the globals and the dynamic memory heap.

Declared In

SystemMgr.h

Prototype

void SysReset (
   void
)

Parameters

None.

Returns

No return value.

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 ^TOP^

Purpose

Set the time out value in seconds for auto-power-off. Zero means never power off.

Declared In

SystemMgr.h

Prototype

UInt16 SysSetAutoOffTime (
   UInt16seconds
)

Parameters

seconds
Time out in seconds, or 0 for no time out.

Returns

Returns previous value of time out in seconds.

SysSetTrapAddress Function ^TOP^

Purpose

Set the address of the function corresponding to a system trap.

Declared In

SystemMgr.h

Prototype

Err SysSetTrapAddress (
   UInt16trapNum,
   void*procP
)

Parameters

trapNum
One of the routine selectors defined in SysTraps.h (sysTrap...) or CoreTraps.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 ^TOP^

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 (
   UInt16resID,
   UInt16index,
   Char*strP,
   UInt16maxLen
)

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 ^TOP^

Purpose

Put the processor into doze mode for the specified number of ticks.

Declared In

SystemMgr.h

Prototype

Err SysTaskDelay (
   Int32delay
)

Parameters

delay
Number of ticks to wait (see SysTicksPerSecond())

Returns

Returns 0 if no error.

See Also

EvtGetEvent()

SysTicksPerSecond Function ^TOP^

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

None

Returns

Returns the number of ticks per second.

Compatibility

Implemented only if 2.0 New Feature Set is present.

SysUIAppSwitch Function ^TOP^

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 (
   UInt16cardNo,
   LocalIDdbID,
   UInt16cmd,
   MemPtrcmdPBP
)

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

Returns 0 if no error.

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 ^TOP^

PilotMain Function ^TOP^

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(
   UInt16cmd,
   void*cmdPBP,
   UInt16launchFlags
)

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.