System Manager
 

 < 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, dbIDThe card number and ID of the resource database of the application to launch.
-> launchFlagsSet to 0.
-> cmdLaunch code.
-> cmdPBPLaunch code parameter block.
<- resultPThe 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

setIf false, parameters with non-NULL pointers are retrieved. Never set this parameter to true.
warnThresholdPPointer to battery voltage warning threshold in volts*100, or NULL.
criticalThresholdPPointer to the battery voltage critical threshold in volts*100, or NULL.
maxTicksPPointer to the battery timeout, or NULL.
kindPPointer to the battery kind, or NULL.
pluggedInPointer to pluggedIn return value, or NULL.
percentPPercentage 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

setIf false, parameters with non-NULL pointers are retrieved. Never set this parameter to true.
warnThresholdPPointer to battery voltage warning threshold in volts*100, or NULL.
criticalThresholdPPointer to the battery voltage critical threshold in volts*100, or NULL.
maxTicksPPointer to the battery timeout, or NULL.
kindPPointer to the battery kind, or NULL.
pluggedInPointer 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

basePBase pointer to an array of elements
numOfElementsNumber of elements to search. Must be greater than 0.
widthWidth of each array element.
searchFSearch function.
searchDataData to search for. This data is passed to the searchF function.
otherData to be passed as the third parameter (the other parameter) to the comparison function.
positionPointer to the position result.
findFirstIf 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

cmdAction code to send.
cmdPBPAction 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

stringString to copy the resource string to.
theIDResource 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

typeThe type of database to find. Use 0 to find all databases.
creatorThe creator ID of the database to find. Use 0 to find any creator ID.
dbCountA pointer to an integer value that is updated by this function to the number of matching databases.
dbIDsA 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.
lookupNameIf 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

panelCountPointer to set to the number of panels.
panelIDsA 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

cardNoPPointer to the card number; 0 or 1.
dbIDPPointer 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
maxLenSize 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

cPointer to packed block of strings, each terminated by NULL.
stringCountCount 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

-> cardNoThe card on which the ROM to be queried resides. Currently, no Palm hardware provides multiple cards, so this value must be 0.
-> tokenThe value to retrieve, as specified by one of the following tokens:
sysROMTokenSnumThe serial number of the ROM, expressed as a text string with no null terminator.
<- dataPPointer to a text buffer that holds the requested value when the function returns.
<- sizePThe 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

startPPUpon return, points to the start of the stack.
endPPUpon 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

-> trapNumOne 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

selectorThe selector for a function to pass to Gremlins.
paramsPointer 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

eventPPointer 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

basePBase pointer to an array of elements.
numOfElementsNumber of elements to sort (must be at least 2).
widthWidth of an element.
comparFComparison function. See Comments, below.
otherOther 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

kbdThe 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

namePPointer to the name of a loaded library.
refNumPPointer 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

-> libraryPPointer to the library being installed.
<- refNumPPointer 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

libTypeType of library database.
libCreatorCreator of library database.
refNumPPointer 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

-> refNumThe 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

basePBase pointer to an array of elements.
numOfElementsNumber of elements to sort (must be at least 2).
widthWidth of an element.
comparFComparison function. See Comments, below.
otherOther 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

newSeedNew 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

secondsTime 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

-> trapNumOne of the routine selectors defined in SysTraps.h (sysTrap...) or CoreTraps.h on Palm OS version 3.5 and higher.
-> procPPointer 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

resIDResource ID of the string list.
indexString to get out of the list.
strP Pointer to space to form the string.
maxLenSize 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

delayNumber 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

-> cardNoCard number for the new application; currently only card 0 is valid.
-> dbIDID of the new application's resource database.
-> cmdAction code (launch code).
-> cmdPBPAction 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

-> cmdThe 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.
-> cmdPBPA 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.
-> launchFlagsFlags 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.