< Home < Developers < Development Support < Documentation

## 50 System Manager

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part II: System Management 50 System Manager System Manager Data Structures SysDBListItemType System Functions SysAppLaunch SysBatteryInfo SysBatteryInfoV20 SysBinarySearch SysBroadcastActionCode SysCopyStringResource SysCreateDataBaseList SysCreatePanelList SysCurAppDatabase SysErrString SysFormPointerArrayToStrings SysGetOSVersionString SysGetROMToken SysGetStackInfo SysGetTrapAddress SysGremlins SysHandleEvent SysInsertionSort SysKeyboardDialog SysKeyboardDialogV10 SysLibFind SysLibInstall SysLibLoad SysLibRemove SysQSort SysRandom SysReset SysSetAutoOffTime SysSetTrapAddress SysStringByIndex SysTaskDelay SysTicksPerSecond SysUIAppSwitch Application-Defined Functions PilotMain |  |  |  | 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 The SysDBListItemType structure describes a single database or panel. The SysCreateDataBaseList and SysCreatePanelList functions each create and return an array of SysDBListItemType structures.
    typedef struct {
      Char         name[dmDBNameLength];
      UInt32       creator;
      UInt32       type;
      UInt16       version;
      LocalID      dbID;
      UInt16       cardNo;
      BitmapPtr    iconP;
    } SysDBListItemType;
## System Functions ## SysAppLaunch #### Purpose Launch a specified application as a subroutine of the caller. #### 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.
#### Result 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 #### 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! #### 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 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.
#### Result 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 #### 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! #### 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 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.
#### Result 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 #### Purpose Search elements in a sorted array for the specified data according to the specified comparison function. #### Prototype Boolean SysBinarySearch (void const *baseP, Int16 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.
#### Result 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. 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. ## SysBroadcastActionCode #### Purpose Send the specified action code (launch code) and parameter block to the latest version of every UI application. #### Prototype Err SysBroadcastActionCode (UInt16 cmd, MemPtr cmdPBP) #### Parameters #####
cmd | Action code to send.
#####
cmdPBP | Action code parameter block to send.
#### Result Returns 0 if no error, or one of the following errors: sysErrParamErr, memErrNotEnoughSpace, or sysErrOutOfOwnerIDs. #### See Also SysAppLaunch, Chapter 3, "Application Startup and Stop." of the Palm OS Programmer's Companion, vol. I ## SysCopyStringResource #### Purpose Copy a resource string to a passed string. #### Prototype void SysCopyStringResource (Char *string, Int16 theID) #### Parameters #####
string | String to copy the resource string to.
#####
theID | Resource string ID.
#### Result Stores a copy of the resource string in string. ## SysCreateDataBaseList #### 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. #### 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 uses tAIN names and sorts the list.
#### Result 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 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 50.1 Listing 50.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 #### Purpose Generate a list of panels found on the memory cards and return the result. Multiple versions of a panel are listed once. #### 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.
#### Result 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 50.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 #### Purpose Return the card number and database ID of the current application's resource database. #### Prototype Err SysCurAppDatabase (UInt16 *cardNoP, LocalID *dbIDP) #### Parameters #####
cardNoP | Pointer to the card number; 0 or 1.
#####
dbIDP | Pointer to the database ID.
#### Result Returns 0 if no error, or SysErrParamErr if an error occurs. #### See Also SysAppLaunch, SysUIAppSwitch ## SysErrString #### 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. #### Prototype Char *SysErrString (Err err, Char *strP, UInt16 maxLen) #### Parameters #####
err | Error number
#####
strP | Pointer to space to form the string
#####
maxLen | Size of strP buffer.
#### Result Stores the error number string. #### Compatibility Implemented only if 2.0 New Feature Set is present. ## SysFormPointerArrayToStrings #### Purpose Form an array of pointers to strings in a block. Useful for setting the items of a list. #### Prototype MemHandle SysFormPointerArrayToStrings (Char *c, Int16 stringCount) #### Parameters #####
c | Pointer to packed block of strings, each terminated by NULL.
#####
stringCount | Count of strings in block.
#### Result 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. ## SysGetOSVersionString #### Purpose Return the version number of the PalmTM operating system. #### Prototype Char *SysGetOSVersionString() #### Parameters #####
None.
#### Result 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 #### Purpose Return from ROM a value specified by token. #### 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:
#####
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.
#### Result 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 #### Purpose Return the start and end of the current thread's stack. #### 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.
#### Result 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 #### Purpose Return the address of a function given its system trap. #### Prototype void *SysGetTrapAddress (UInt16 trapNum) #### Parameters #####
-> trapNum | One of the routine selectors defined in SysTraps.h (sysTrap...) or CoreTraps.h on Palm OS version 3.5 and higher.
#### Result 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 76, "PalmOSGlue Library." ## SysGremlins #### 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. #### 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.
#### Result 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 #### Purpose Handle defaults for system events such as hard and soft key presses. #### Prototype Boolean SysHandleEvent (EventPtr eventP) #### Parameters #####
eventP | Pointer to an event.
#### Result 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 #### Purpose Sort elements in an array according to the passed comparison function. #### Prototype void SysInsertionSort (void *baseP, Int16 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.
#### Result 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, 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);
#### See Also SysQSort ## SysKeyboardDialog #### Purpose Pop up the system keyboard if there is a field object with the focus. The field object's text chunk is edited directly. #### Prototype void SysKeyboardDialog (KeyboardType kbd) #### Parameters #####
kbd | The keyboard type. See Keyboard.h.
#### Result Returns nothing. Changes the field's text chunk. #### Compatibility Implemented only if 2.0 New Feature Set is present. #### See Also SysKeyboardDialogV10, FrmSetFocus ## SysKeyboardDialogV10 #### Purpose Pop up the system keyboard if there is a field object with the focus. The field object's text chunk is edited directly. #### Prototype void SysKeyboardDialogV10 () #### Parameters #####
None.
#### Result Returns nothing. The field's text chunk is changed. #### Compatibility Corresponds to the 1.0 implementation of SysKeyboardDialog. #### See Also SysKeyboardDialog, FrmSetFocus ## SysLibFind #### Purpose Return a reference number for a library that is already loaded, given its name. #### 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)
#### Result 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 #### Purpose Installs a library into the Library table and calls the library's install entry point. #### 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.
#### Result 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 #### Purpose Load a library given its database creator and type. #### 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)
#### Result 0 if no error; otherwise: sysErrLibNotFound, sysErrNoFreeRAM, sysErrNoFreeLibSlots, or other error returned from the library's install entry point. #### Comments Presently, the "load" functionality is not supported when you use the Palm OS Simulator. 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 #### Purpose Unload a library previously loaded with SysLibLoad. #### Prototype Err SysLibRemove (UInt16 refNum) #### Parameters #####
-> refNum | The library reference number.
#### Result 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 #### Purpose Sort elements in an array according to the supplied comparison function. #### Prototype void SysQSort (void *baseP, Int16 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.
#### Result 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, 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);
#### See Also SysInsertionSort ## SysRandom #### Purpose Return a random number anywhere from 0 to sysRandomMax. #### Prototype Int16 SysRandom (Int32 newSeed) #### Parameters #####
newSeed | New seed value, or 0 to use existing seed.
#### Result Returns a random number. ## SysReset #### Purpose Perform a soft reset and reinitialize the globals and the dynamic memory heap. #### Prototype void SysReset (void) #### Parameters #####
None.
#### Result 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 #### Purpose Set the time out value in seconds for auto-power-off. Zero means never power off. #### Prototype UInt16 SysSetAutoOffTime (UInt16 seconds) #### Parameters #####
seconds | Time out in seconds, or 0 for no time out.
#### Result Returns previous value of time out in seconds. ## SysSetTrapAddress #### Purpose Set the address of the function corresponding to a system trap. #### Prototype Err SysSetTrapAddress (UInt16 trapNum, 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.
#### Result 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. ## SysStringByIndex #### 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. #### 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.
#### Result 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 #### Purpose Put the processor into doze mode for the specified number of ticks. #### Prototype Err SysTaskDelay (Int32 delay) #### Parameters #####
delay | Number of ticks to wait (see SysTicksPerSecond)
#### Result Returns 0 if no error. #### See Also EvtGetEvent ## SysTicksPerSecond #### 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. #### Prototype UInt16 SysTicksPerSecond (void) #### Parameters #####
None
#### Result Returns the number of ticks per second. #### Compatibility Implemented only if 2.0 New Feature Set is present. ## SysUIAppSwitch #### Purpose Try to make the current UI application quit and then launch the UI application specified by card number and database ID. #### 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.
#### Result 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 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. 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. 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 3, "Application Startup and Stop." in the Palm OS Programmer's Companion, vol. I. ## Application-Defined Functions ## PilotMain #### Purpose The entry point for all Palm OS applications, this function's sole purpose is to receive and respond to launch codes. #### 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.
#### Result 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 3, "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. |