ExtraGroups:
    =>API-Serial communication:SerComm
    =>API-Date and Time Functions:DateTim
    =>API-Password functions:Pwfuncs
    =>API-String functions:StrFuncs
    =>API-Float point functions:FlpFuncs
    =>API-Text functions:TxtFuncs
    =>API-Sound functions:SoundFuncs
    =>API-Memory manager functions:MemFuncs
    =>API-File streaming functions:FileFuncs
    =>API-Error manager functions:ErrFuncs
    =>API-System Dialogs:DlgFuncs
DlgFuncs:
   =>void SysAppLauncherDialog()
   =>UInt16 SysFatalAlert(const Char *msg)
   =>void SysGraffitiReferenceDialog(ReferenceType referenceType)
ErrFuncs:
   =>void ErrAlert(err)
   =>void ErrDisplay(msg)
   =>void ErrDisplayFileLineMsg(const Char * const filename, UInt16 lineno, const Char * const msg)
   =>void ErrFatalDisplayIf(condition, msg)
   =>void ErrNonFatalDisplayIf(condition, msg)
   =>void ErrThrow(Int32 err)
FileFuncs:
   =>Err FileClearerr(FileHand stream) 
   =>Err FileClose(FileHand stream)
   =>Err FileControl(FileOpEnum op, FileHand stream, void* valueP, Int32* valueLenP)
   =>Err FileDelete(UInt16 cardNo, Char* nameP)
   =>Int32 FileDmRead(FileHand stream, void* startOfDmChunkP, Int32 destOffset, Int32 objSize, Int32 numObj, Err* errP) 
   =>Err FileEOF(FileHand stream) 
   =>Err FileError(FileHand stream) 
   =>Err FileFlush(FileHand stream) 
   =>Err FileGetLastError(FileHand stream) 
   =>FileHand FileOpen(UInt16 cardNo, Char* nameP, UInt32 type, UInt32 creator, UInt32 openMode, Err* errP)
   =>Int32 FileRead(FileHand stream, void* bufP, Int32 objSize, Int32 numObj, Err* errP) 
   =>Err FileRewind(FileHand stream) 
   =>Err FileSeek(FileHand stream, Int32 offset, FileOriginEnum origin) 
   =>Int32 FileTell(FileHand stream, Int32* fileSizeP, Err* errP) 
   =>Err FileTruncate(FileHand stream, Int32 newSize) 
   =>Int32 FileWrite(FileHand stream, void* dataP, Int32 objSize, Int32 numObj, Err* errP) 
SoundFuncs:
   =>Boolean SndCreateMidiList(UInt32 creator, Boolean multipleDBs, UInt16* wCountP, MemHandle *entHP)
   =>Err SndDoCmd(void* channelP, SndCommandPtr cmdP, Boolean noWait)
   =>void SndGetDefaultVolume(UInt16* alarmAmpP, UInt16* sysAmpP, UInt16* masterAmpP)
   =>Err SndPlaySmf(void* chanP, SndSmfCmdEnum cmd, UInt8* smfP, SndSmfOptionsType* selP, SndSmfChanRangeType* chanRangeP, SndSmfCallbacksType* callbacksP, Boolean bNoWait)
   =>Err SndPlaySmfResource(UInt32 resType, Int16 resID, SystemPreferencesChoice volumeSelector)
   =>void SndPlaySystemSound(SndSysBeepType beepID)
   =>void SndComplFuncType(void* chanP, UInt32 dwUserData)
   =>Boolean SndBlockingFuncType(void* chanP, UInt32 dwUserData, Int32 sysTicksAvailable)
MemFuncs:
   =>Err MemCardInfo(UInt16 cardNo, Char* cardNameP, Char* manufNameP, UInt16* versionP, UInt32* crDateP, UInt32* romSizeP, UInt32* ramSizeP, UInt32* freeBytesP)
   =>Int16 MemCmp(const void* s1, const void* s2, Int32 numBytes)
   =>UInt16 MemDebugMode(void)
   =>UInt16 MemHandleCardNo(MemHandle h)
   =>Boolean MemHandleDataStorage(MemHandle h) 
   =>Err MemHandleFree(MemHandle h)
   =>UInt16 MemHandleHeapID(MemHandle h)
   =>MemPtr MemHandleLock(MemHandle h)
   =>MemHandle MemHandleNew(UInt32 size)
   =>Err MemHandleResize(MemHandle h, UInt32 newSize)
   =>Err MemHandleSetOwner(MemHandle h, UInt16 owner)
   =>UInt32 MemHandleSize(MemHandle h)
   =>LocalID MemHandleToLocalID(MemHandle h)
   =>Err MemHandleUnlock(MemHandle h)
   =>Err MemHeapCheck(UInt16 heapID)
   =>Err MemHeapCompact(UInt16 heapID)
   =>Boolean MemHeapDynamic(UInt16 heapID) 
   =>UInt16 MemHeapFlags(UInt16 heapID)
   =>Err MemHeapFreeBytes(UInt16 heapID, UInt32* freeP, UInt32* maxP)
   =>UInt16 MemHeapID(UInt16 cardNo, UInt16 heapIndex)
   =>Err MemHeapScramble(UInt16 heapID)
   =>UInt32 MemHeapSize(UInt16 heapID)
   =>LocalIDKind MemLocalIDKind(LocalID local)
   =>MemPtr MemLocalIDToGlobal(LocalID local, UInt16 cardNo)
   =>MemPtr MemLocalIDToLockedPtr(LocalID local, UInt16 cardNo)
   =>MemPtr MemLocalIDToPtr(LocalID local, UInt16 cardNo)
   =>Err MemMove(void* dstP, const void* sP, Int32 numBytes)
   =>UInt16 MemNumCards(void)
   =>UInt16 MemNumHeaps(UInt16 cardNo)
   =>UInt16 MemNumRAMHeaps(UInt16 cardNo)
   =>UInt16 MemPtrCardNo(MemPtr p)
   =>Boolean MemPtrDataStorage(MemPtr p)
   =>Err MemPtrFree(MemPtr p)
   =>UInt16 MemPtrHeapID(MemPtr p)
   =>MemPtr MemPtrNew(UInt32 size)
   =>MemHandle MemPtrRecoverHandle(MemPtr p)
   =>Err MemPtrResize(MemPtr p, UInt32 newSize)
   =>Err MemPtrSetOwner(MemPtr p, UInt16 owner)
   =>UInt32 MemPtrSize(MemPtr p)
   =>LocalID MemPtrToLocalID(MemPtr p)
   =>Err MemPtrUnlock(MemPtr p)
   =>Err MemSet(void* dstP, Int32 numBytes, UInt8 value)
   =>Err MemSetDebugMode(UInt16 flags)
   =>Err MemStoreInfo(UInt16 cardNo, UInt16 storeNumber, UInt16* versionP, UInt16* flagsP, Char* nameP, UInt32* crDateP, UInt32* bckUpDateP, UInt32* heapListOffsetP, UInt32* initCodeOffset1P, UInt32* initCodeOffset2P, LocalID* databaseDirIDP)
TxtFuncs:
   =>UInt8 TxtByteAttr(UInt8 inByte)
   =>Int16 TxtCaselessCompare(const Char* s1, UInt16 s1Len, UInt16* s1MatchLen, const Char* s2, UInt16 s2Len, UInt16* s2MatchLen)
   =>UInt16 TxtCharAttr(WChar inChar)
   =>WChar TxtCharBounds(const Char* inText, UInt32 inOffset, UInt32* outStart, UInt32* outEnd)
   =>CharEncodingType TxtCharEncoding(WChar inChar)
   =>Boolean TxtCharIsAlNum(ch)
   =>Boolean TxtCharIsAlpha(ch)
   =>Boolean TxtCharIsCntrl(ch)
   =>Boolean TxtCharIsDelim(ch)
   =>Boolean TxtCharIsDigit(ch)
   =>Boolean TxtCharIsGraph(ch)
   =>Boolean TxtCharIsHardKey(m, ch)
   =>Boolean TxtCharIsHex(ch)
   =>Boolean TxtCharIsLower(ch)
   =>Boolean TxtCharIsPrint(ch)
   =>Boolean TxtCharIsPunct(ch)
   =>Boolean TxtCharIsSpace(ch)
   =>Boolean TxtCharIsUpper(ch)
   =>Boolean TxtCharIsValid(WChar inChar)
   =>UInt16 TxtCharSize(WChar inChar)
   =>Int16 TxtCharWidth(WChar inChar)
   =>UInt16 TxtCharXAttr(WChar inChar)
   =>Int16 TxtCompare(const Char* s1, UInt16 s1Len, UInt16* s1MatchLen, const Char* s2, UInt16 s2Len, UInt16* s2MatchLen)
   =>const_Char* TxtEncodingName(CharEncodingType inEncoding)
   =>Boolean TxtFindString(const Char* inSourceStr, const Char* inTargetStr, UInt32* outPos, UInt16* outLength)
   =>WChar TxtGetChar(const Char* inText, UInt32 inOffset)
   =>UInt16 TxtGetNextChar(const Char* inText, UInt32 inOffset, WChar* outChar)
   =>UInt16 TxtGetPreviousChar(const Char* inText, UInt32 inOffset, WChar* outChar)
   =>UInt32 TxtGetTruncationOffset(const Char* inText, UInt32 inOffset)
   =>CharEncodingType TxtMaxEncoding(CharEncodingType a, CharEncodingType b)
   =>UInt16 TxtNextCharSize(inText, inOffset)
   =>Char* TxtParamString(const Char* inTemplate, const Char* param0, const Char* param1, const Char* param2, const Char* param3)
   =>void TxtPreviousCharSize(inText, inOffset)
   =>UInt16 TxtReplaceStr(Char* ioStr, UInt16 inMaxLen, const Char* inParamStr, UInt16 inParamNum)
   =>UInt16 TxtSetNextChar(Char* ioText, UInt32 inOffset, WChar inChar)
   =>CharEncodingType TxtStrEncoding(const Char* inStr)
   =>Err TxtTransliterate(const Char* inSrcText, UInt16 inSrcLength, Char* outDstText, UInt16* ioDstLength, TranslitOpType inOp)
   =>Boolean TxtWordBounds(const Char* inText, UInt32 inLength, UInt32 inOffset, UInt32* outStart, UInt32* outEnd)
FlpFuncs:
    =>FloatType FplAdd(FloatType a, FloatType b) 
    =>FloatType FplAToF(char* s) 
    =>Err FplBase10Info(FloatType a, ULong* mantissaP, Int* exponentP, Int* signP) 
    =>FloatType FplDiv(FloatType dividend, FloatType divisor) 
    =>Long FplFloatToLong(FloatType f) 
    =>ULong FplFloatToULong(FloatType f) 
    =>void FplFree() 
    =>Err FplFToA(FloatType a, char* s) 
    =>Err FplInit() 
    =>FloatType FplLongToFloat(Long x) 
    =>FloatType FplMul(FloatType a, FloatType b) 
    =>FloatType FplSub(FloatType a, FloatType b) 
StrFuncs:
    =>Int32 StrAToI(const Char* str) 
    =>Int16 StrCaselessCompare(const Char* s1, const Char* s2) 
    =>Char* StrCat(Char* dst, const Char* src) 
    =>Char* StrChr(const Char* str, WChar chr) 
    =>Int16 StrCompare(const Char* s1, const Char* s2) 
    =>Char* StrCopy(Char* dst, const Char* src) 
    =>Char* StrDelocalizeNumber(Char* s, Char thousandSeparator, Char decimalSeparator) 
    =>Char* StrIToA(Char* s, Int32 i) 
    =>Char* StrIToH(Char* s, UInt32 i) 
    =>UInt16 StrLen(const Char* src) 
    =>Char* StrLocalizeNumber(Char* s, Char thousandSeparator, Char decimalSeparator) 
    =>Int16 StrNCaselessCompare(const Char* s1, const Char* s2, Int32 n) 
    =>Char* StrNCat(Char* dst, const Char* src, Int16 n) 
    =>Int16 StrNCompare(const Char* s1, const Char* s2, UInt32 n) 
    =>Char* StrNCopy(Char* dst, const Char* src, Int16 n) 
    =>Int16 StrPrintF(Char* s, 
    =>Char* StrStr(const Char* str, const Char* token) 
    =>Char* StrToLower(Char* dst, const Char* src) 
    =>Int16 StrVPrintF(Char* s, const Char* formatStr, _Palm_va_list argParam) 
SerComm:
    =>Err SerClearErr(UInt16 refNum)
    =>Err SerClose(UInt16 refNum)
    =>Err SerControl(UInt16 refNum, UInt16 op, void *valueP, UInt16 *valueLenP)
    =>Err SerGetSettings(UInt16 refNum, SerSettingsPtr settingsP)
    =>UInt16 SerGetStatus(UInt16 refNum, Boolean *ctsOnP, Boolean *dsrOnP)
    =>Err SerOpen(UInt16 refNum, UInt16 port, UInt32 baud)
    =>UInt32 SerReceive(UInt16 refNum, void *bufP, UInt32 count, Int32 timeout, Err* errP)
    =>Err SerReceive10(UInt16 refNum, void *bufP, UInt32 bytes, Int32 timeout)
    =>Err SerReceiveCheck(UInt16 refNum, UInt32 *numBytesP)
    =>void SerReceiveFlush(UInt16 refNum, Int32 timeout)
    =>Err SerReceiveWait(UInt16 refNum, UInt32 bytes, Int32 timeout)
    =>UInt32 SerSend(UInt16 refNum, void *bufP, UInt32 count, Err *errP)
    =>Err SerSend10(UInt16 refNum, void *bufP, UInt32 size)
    =>Err SerSendFlush(UInt16 refNum)
    =>Err SerSendWait(UInt16 refNum, Int32 timeout)
    =>Err SerSetReceiveBuffer(UInt16 refNum, void *bufP, UInt16 bufSize)
    =>Err SerSetSettings(UInt16 refNum, SerSettingsPtr settingsP)
DateTim:
    =>void DateAdjust(DatePtr dateP, Int32 adjustment)
    =>void DateDaysToDate(UInt32 days, DatePtr date)
    =>void DateSecondsToDate(UInt32 seconds, DatePtr date)
    =>UInt16 DateTemplateToAscii(const Char *templateP, UInt8 months, UInt8 days, UInt16 years, Char *stringP, Int16 stringLen)
    =>void DateToAscii(UInt8 months, UInt8 days, UInt16 years, DateFormatType dateFormat, Char* pString)
    =>UInt32 DateToDays(DateType date)
    =>void DateToDOWDMFormat(UInt8 month, UInt8 day, UInt16 year, DateFormatType dateFormat, Char * pString)
    =>Int16 DayOfMonth(Int16 month, Int16 day, Int16 year)
    =>Int16 DayOfWeek(Int16 month, Int16 day, Int16 year)
    =>Int16 DaysInMonth(Int16 month, Int16 year)
    =>void TimAdjust(DateTimePtr dateTimeP, Int32 adjustment)
    =>UInt32 TimDateTimeToSeconds(DateTimePtr dateTimeP)
    =>UInt32 TimGetSeconds(void)
    =>UInt32 TimGetTicks(void)
    =>void TimSecondsToDateTime(UInt32 seconds, DateTimePtr dateTimeP)
    =>void TimSetSeconds(UInt32 seconds)
    =>void TimeToAscii(UInt8 hours, UInt8 minutes, TimeFormatType timeFormat, Char* pString)
    =>Boolean DayHandleEvent(const DaySelectorPtr pSelector, const EventType *pEvent) 
    =>Boolean SelectDay(const SelectDayType selectDayBy, Int16 *month, Int16 *day, Int16 *year, const Char *title) 
    =>Boolean SelectDay(Int16 *month, Int16 *day, Int16 *year, const Char title) 
    =>Boolean SelectOneTime(Int16 *hour, Int16 *minute, const Char *titleP) 
    =>Boolean SelectTime(TimeType * startTimeP, TimeType * endTimeP, Boolean untimed, const Char * titleP, Int16 startOfDay, Int16 endOfDay, Int16 startOfDisplay) 
    =>Boolean SelectTimeV33(TimeType *startTimeP, TimeType *EndTimeP, Boolean untimed, Char *title, Int16 startOfDay) 
Pwfuncs:
    =>Boolean PwdExists()
    =>void PwdRemove(void)
    =>void PwdSet(Char* oldPassword, Char* newPassword)
    =>Boolean PwdVerify(Char* string)
DayHandleEvent()
    =><h4> Purpose  </h4>
    =>Handle event in the specified control. This routine handles two types of events,  penDownEvent  and  ctlEnterEvent . 
    =><h4> Prototype  </h4>
    =><code> Boolean DayHandleEvent (const&nbsp;DaySelectorPtr&nbsp;pSelector, const&nbsp;EventType&nbsp;*pEvent) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; pSelector </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to control object. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; pEvent </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to an  <code> EventType </code>  structure. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =><code> true </code>  if the event was handled or  <code> false </code>  if it was not.  Posts a  daySelectEvent  with information on whether to use the date. 
    =><h4> Comments  </h4>
    =>A date is used if the user selects a day in the visible month.  When this routine receives a  penDownEvent , it checks if the pen position is within the bounds of the control object. If it is, a dayEnterEvent is added to the event queue and the routine exits.  When this routine receives a  <code> dayEnterEvent </code> , it checks that the control id in the event record matches the id of the control specified. If they match, this routine will track the pen until it comes up in the bounds in which case daySelectEvent is sent.  If the pen exits the bounds a  <code> dayExitEvent </code>  is sent.  <br> <br> <br> <h3>
SelectDay()
    =><h4> Purpose  </h4>
    =>Display a form showing a date; allow user to select a different date. 
    =><h4> Prototype  </h4>
    =><code> Boolean SelectDay (const&nbsp;SelectDayType&nbsp;selectDayBy, Int16&nbsp;*month, Int16&nbsp;*day, Int16&nbsp;*year, const&nbsp;Char&nbsp;*title) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> selectDayBy </code> The method by which the user should choose the day. Possible values are  <code> selectDayByDay </code> , </code> <br> </td>
    =><td valign="top" align="left" width=""> The method by which the user should choose the day. Possible values are  <code> selectDayByDay </code> , <code> selectDayByWeek </code> , and  <code> selectDayByMonth </code> . See  SelectDayType <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> &lt;-&gt; month, day, year </code> <br> </code> </td>
    =><td valign="top" align="left" width=""> Month, day, and year selected. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; title </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> String title for the dialog. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =><code> true </code>  if the OK button was pressed. If  <code> true </code> ,  <code> month </code> ,  <code> day </code> , and  <code> year </code>  contain the new date. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  2.0 New Feature Set  is present. 
    =><h4> See Also  </h4>
    =>SelectDayV10 <br> <br> <br> <h3>
SelectDayV10()
    =><h4> Purpose  </h4>
    =>Display a form showing a date, allow user to select a different date. 
    =><h4> Prototype  </h4>
    =><code> Boolean SelectDay (Int16&nbsp;*month, Int16&nbsp;*day, Int16&nbsp;*year, const&nbsp;Char&nbsp;title) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> &lt;-&gt; month, day, year </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Month, day, and year selected. The initial values passed in these parameters must be valid.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; title </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> String title for the dialog. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns  <code> true </code>  if the OK button was pressed. In that case, the parameters passed are changed. 
    =><h4> Compatibility  </h4>
    =>This function corresponds to the 1.0 version of  <code> SelectDay </code> . 
    =><h4> See Also  </h4>
    =>SelectDay <br> <br> <br> <h3>
SelectOneTime()
    =><h4> Purpose  </h4>
    =>Display a form showing the time and allow the user to select a different time. 
    =><h4> Prototype  </h4>
    =><code> Boolean SelectOneTime (Int16 *hour, Int16&nbsp;*minute, const&nbsp;Char&nbsp;*titleP) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> &lt;-&gt; hour </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The hour selected in the form.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> &lt;-&gt; minute </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The minute selected in the form.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; titleP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A pointer to a string to display as the title. Doesn't change as the function executes. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns  <code> true </code>  if the user selects OK and  <code> false </code>  otherwise. If  <code> true </code>  is returned, the values in  <code> hour </code>  and  <code> minute  </code> have probably been changed. 
    =><h4> Comments  </h4>
    =>Use this function instead of  <code> SelectTime </code>  if you want to display a dialog that specifies a single point in time, not a range of time from start to end. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  3.1 New Feature Set  is present. 
    =><h4> See Also  </h4>
    =>SelectTimeV33 <br> <br> <br> <h3>
SelectTime()
    =><h4> Purpose  </h4>
    =>Display a form showing a start and end time. Allow the user to select a different time. 
    =><h4> Prototype  </h4>
    =><code> Boolean SelectTime (TimeType * startTimeP, TimeType&nbsp;*&nbsp;endTimeP, Boolean untimed, const Char * titleP, Int16 startOfDay, Int16 endOfDay, Int16&nbsp;startOfDisplay) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> &lt;-&gt; startTimeP, endTimeP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointers to values of type  <code> TimeType </code> . Pass values to display in these two parameters. If the user makes a selection and taps the OK button, the selected values are returned here. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; untimed </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pass in  <code> true </code>  to indicate that no time is selected. If the user sets the time to no time then  <code> startTimeP </code>  and  <code> EndTimeP </code>  are both set to the constant  <code> noTime (-1) </code> . <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; titleP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A pointer to a string to display as the title. Doesn't change as the function executes. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; startOfDay </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The hour that the hour list displays at its top. To see earlier hours, the user can scroll the list up. The value must be between 0 to 12, inclusive. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; endOfDay </code> <br> </code> </td>
    =><td valign="top" align="left" width=""> The hour used when the "All Day" button is selected. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; </code> <code> startOfDisplay </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> First hour initially visible. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns  <code> true </code>  if the user selects OK and  <code> false </code>  otherwise. If  <code> true </code>  is returned, the values in  <code> hour </code>  and  <code> minute  </code> have probably been changed. 
    =><h4> Comments  </h4>
    =>This version of  <code> SelectTime </code>  adds the  <code> endOfDay </code>  and  <code> startOfDisplay </code>  functionality. 
    =><h4> Compatibility  </h4>
    =>Implemented if  3.5 New Feature Set  is present. 
    =><h4> See Also  </h4>
    =>SelectDay ,  SelectOneTime <br> <br> <br> <h3>
SelectTimeV33()
    =><h4> Purpose  </h4>
    =>Display a form showing the time and allow the user to select a different time.  This function is obsolete and should not be used. 
    =><h4> Prototype  </h4>
    =><code> Boolean SelectTimeV33 (TimeType&nbsp;*startTimeP, TimeType&nbsp;*EndTimeP, Boolean&nbsp;untimed, Char&nbsp;*title, Int16&nbsp;startOfDay) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> &lt;-&gt; startTimeP, EndTimeP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointers to values of type  <code> TimeType </code> . Pass values to display in these two parameters. If the user makes a selection and taps the OK button, the selected values are returned here. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; untimed </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pass in  <code> true </code>  to indicate that no time is selected. If the user sets the time to no time then  <code> startTimeP </code>  and  <code> EndTimeP </code>  are both set to the constant  <code> noTime (-1) </code> . <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; title </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A pointer to a string to display as the title. Doesn't change as the function executes. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; startOfDay </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The hour that the hour list displays at its top. To see earlier hours, the user can scroll the list up. The value must be between 0 to 12, inclusive. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns  <code> true </code>  if the user selects OK and  <code> false </code>  otherwise. If  <code> true </code>  is returned, the values in  <code> hour </code>  and  <code> minute  </code> have probably been changed. 
    =><h4> Comments  </h4>
    =><blockquote> <hr> <strong> NOTE: &nbsp; </strong> Obsolete functions are provided ONLY for backward compatibility; for example, so a 1.0 application will work on 3.x OS releases. New code should not call these routines! <hr> <br> </blockquote>
    =><h4> See Also  </h4>
    =>SelectDay ,  SelectOneTime <strong> </strong> <br> <h3>
FplAdd()
    =><h4> Purpose  </h4>
    =>Add two floating-point numbers (returns a + b). 
    =><h4> Prototype  </h4>
    =><code> FloatType FplAdd (FloatType&nbsp;a, FloatType&nbsp;b) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> a, b </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The floating-point numbers. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the normalized floating-point result of the addition. 
    =><h4> Comment </h4>
    =>Under Palm OS <sup> &reg; </sup>  2.0 and later, most applications will want to use the arithmetic symbols instead. See the  "Floating-Point"  section in the  <em> Palm OS Programmer's Companion </em> .  <br> <br> <br> <h3>
FplAToF()
    =><h4> Purpose  </h4>
    =>Convert a zero-terminated ASCII string to a floating-point number. The string must be in the format: [-]x[.]yyyyyyyy[e[-]zz] 
    =><h4> Prototype  </h4>
    =><code> FloatType FplAToF (char*&nbsp;s) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> s </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the ASCII string. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the floating-point number. 
    =><h4> Comment </h4>
    =>The mantissa of the number is limited to 32 bits. 
    =><h4> See Also </h4>
    =>FplFToA <br> <br> <br> <h3>
FplBase10Info()
    =><h4> Purpose  </h4>
    =>Extract detailed information on the base 10 form of a floating-point number: the base 10 mantissa, exponent, and sign. 
    =><h4> Prototype  </h4>
    =><code> Err FplBase10Info (FloatType&nbsp;a, ULong*&nbsp;mantissaP, Int*&nbsp;exponentP, Int*&nbsp;signP) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> a </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The floating-point number. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> mantissaP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The base 10 mantissa (return value). <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> exponentP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The base 10 exponent (return value). <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> signP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The sign, 1 or -1 (return value). <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns an error code, or 0 if no error. 
    =><h4> Comments  </h4>
    =>The mantissa is normalized so it contains at least  <code> kMaxSignificantDigits </code>  significant digits when printed as an integer value.  <code> FlpBase10Info </code>  reports that zero is "negative"; that is, it returns a one for xSign. If this is a problem, a simple workaround is:  <br> <code> if (xMantissa == 0) { </code> <br> <code> xSign = 0; </code> <br> <br> <br> <br> <h3>
FplDiv()
    =><h4> Purpose  </h4>
    =>Divide two floating-point numbers (result = dividend/divisor). 
    =><h4> Prototype  </h4>
    =><code> FloatType FplDiv (FloatType&nbsp;dividend, FloatType&nbsp;divisor) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> dividend </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Floating-point dividend. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> divisor </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Floating-point divisor. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the normalized floating-point result of the division.  Under Palm OS 2.0 and later, most applications will want to use the arithmetic symbols instead. See the  "Floating-Point"  section in the  <em> Palm OS Programmer's Companion </em> .  <br> <br> <br> <h3>
FplFloatToLong()
    =><h4> Purpose  </h4>
    =>Convert a floating-point number to a long integer. 
    =><h4> Prototype  </h4>
    =><code> Long FplFloatToLong (FloatType&nbsp;f) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> f </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Floating-point number to be converted. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the long integer. 
    =><h4> See Also  </h4>
    =>FplLongToFloat ,  FplFloatToULong <br> <br> <br> <h3>
FplFloatToULong()
    =><h4> Purpose  </h4>
    =>Convert a floating-point number to an unsigned long integer. 
    =><h4> Prototype  </h4>
    =><code> ULong FplFloatToULong (FloatType&nbsp;f) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> f </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Floating-point number to be converted. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns an unsigned long integer. 
    =><h4> See Also  </h4>
    =>FplLongToFloat ,  FplFloatToLong <br> <br> <br> <h3>
FplFree()
    =><h4> Purpose  </h4>
    =>Release all memory allocated by the floating-point initialization. 
    =><h4> Prototype  </h4>
    =><code> void FplFree() </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> </code> <br> </td>
    =><td valign="top" align="left" width=""> <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns nothing. 
    =><h4> Comments  </h4>
    =>Applications must call this routine after they've called other functions that are part of the float manager. 
    =><h4> See Also  </h4>
    =>FplInit <br> <br> <br> <h3>
FplFToA()
    =><h4> Purpose  </h4>
    =>Convert a floating-point number to a zero-terminated ASCII string in exponential format: <code>  [-]x.yyyyyyyye[-]zz </code>
    =><h4> Prototype  </h4>
    =><code> Err FplFToA (FloatType&nbsp;a, char*&nbsp;s) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> a </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Floating-point number. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> s </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to buffer to contain the ASCII string. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns an error code, or 0 if no error. 
    =><h4> See Also  </h4>
    =>FplAToF <br> <br> <br> <h3>
FplInit()
    =><h4> Purpose  </h4>
    =>Initialize the floating-point conversion routines.  Allocate space in the system heap for floating-point globals.  Initialize the  <code> tenPowers </code>  array in the globals area to the powers of 10 from -99 to +99 in floating-point format. 
    =><h4> Prototype  </h4>
    =><code> Err FplInit() </code>
    =><h4> Parameters  </h4>
    =>None. 
    =><h4> Result  </h4>
    =>Returns an error code, or 0 if no error. 
    =><h4> Comments  </h4>
    =>Applications must call this routine before calling any other  <code> Fpl </code>  function. 
    =><h4> See Also  </h4>
    =>FplFree <br> <br> <br> <h3>
FplLongToFloat()
    =><h4> Purpose  </h4>
    =>Convert a long integer to a floating-point number. 
    =><h4> Prototype  </h4>
    =><code> FloatType FplLongToFloat (Long&nbsp;x) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> x </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A long integer. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the floating-point number.  <br> <br> <br> <h3>
FplMul()
    =><h4> Purpose  </h4>
    =>Multiply two floating-point numbers. 
    =><h4> Prototype  </h4>
    =><code> FloatType FplMul (FloatType&nbsp;a, FloatType&nbsp;b)  </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> a, b </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The floating-point numbers. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the normalized floating-point result of the multiplication. 
    =><h4> Comment </h4>
    =>Under Palm OS 2.0 and later, most applications will want to use the arithmetic symbols instead. See the  "Floating-Point"  section in the  <em> Palm OS Programmer's Companion </em> .  <br> <br> <br> <h3>
FplSub()
    =><h4> Purpose  </h4>
    =>Subtract two floating-point numbers (returns a - b). 
    =><h4> Prototype  </h4>
    =><code> FloatType FplSub (FloatType&nbsp;a, FloatType&nbsp;b) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> a, b </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The floating-point numbers. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the normalized floating-point result of the subtraction. 
    =><h4> Comment </h4>
    =>Under Palm OS 2.0 and later, most applications will want to use the arithmetic symbols instead. See the  "Floating-Point"  section in the  <em> Palm OS Programmer's Companion </em> .  <br> <br> <h3>
PwdExists()
    =><h4> Purpose  </h4>
    =>Return  <code> true </code>  if the system password is set. 
    =><h4> Prototype  </h4>
    =><code> Boolean PwdExists() </code>
    =><h4> Parameters  </h4>
    =>None 
    =><h4> Result  </h4>
    =>Returns  <code> true </code>  if the system password is set.  <br> <br> <br> <h3>
PwdRemove()
    =><h4> Purpose  </h4>
    =>Remove the encrypted password string and recover data hidden in databases. 
    =><h4> Prototype  </h4>
    =><code> void PwdRemove(void) </code>
    =><h4> Parameters  </h4>
    =>None 
    =><h4> Result  </h4>
    =>Returns nothing.  <br> <br> <br> <h3>
PwdSet()
    =><h4> Purpose  </h4>
    =>Use a passed string as the new password. The password is stored in an encrypted form. 
    =><h4> Prototype  </h4>
    =><code> void PwdSet (Char*&nbsp;oldPassword, Char*&nbsp;newPassword) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> oldPassword </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The old password must be successfully verified or the new password isn't accepted <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> newPassword </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> <code> Char* </code>  to a string to use as the password.  <code> NULL </code>  means no password. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns nothing.  <br> <br> <br> <h3>
PwdVerify()
    =><h4> Purpose  </h4>
    =>Verify that the string passed matches the system password. 
    =><h4> Prototype  </h4>
    =><code> Boolean PwdVerify (Char*&nbsp;string) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> string </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> String to compare to the system password.  <code> NULL </code>  means no current password. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns  <code> true </code>  if the string matches the system password.  <strong> </strong> <br> <h3>
DateAdjust()
    =><h4> Purpose  </h4>
    =>Return a new date +/- the days adjustment. 
    =><h4> Prototype  </h4>
    =><code> void DateAdjust (DatePtr&nbsp;dateP, Int32&nbsp;adjustment) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> dateP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A  "DateType"  structure with the date to be adjusted (see  <code> DateTime.h </code> ). <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> adjustment </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The adjustment in number of days. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Changes  <code> dateP </code>  to contain the new date. 
    =><h4> Comments  </h4>
    =>This function is useful for advancing a day or week and not worrying about month and year wrapping.  If the time is advanced out of bounds, it is cut at the bounds surpassed.  <br> <br> <br> <h3>
DateDaysToDate()
    =><h4> Purpose  </h4>
    =>Return the date, given days. 
    =><h4> Prototype  </h4>
    =><code> void DateDaysToDate (UInt32&nbsp;days, DatePtr&nbsp;date) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> days </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Days since 1/1/1904. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> date </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to  "DateType"  structure (returned). <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns nothing, stores the date in  <code> date. </code>
    =><h4> See Also  </h4>
    =>TimAdjust ,  DateToDays <br> <br> <br> <h3>
DateSecondsToDate()
    =><h4> Purpose  </h4>
    =>Return the date given seconds. 
    =><h4> Prototype  </h4>
    =><code> void DateSecondsToDate (UInt32&nbsp;seconds, DatePtr&nbsp;date) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> seconds </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Seconds since 1/1/1904. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> date </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to  "DateType"  structure (returned).  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns nothing; stores the date in  <code> date. </code> <br> <br> <br> <h3>
DateTemplateToAscii()
    =><h4> Purpose  </h4>
    =>Convert the date passed to a string, using the formatting specified by the  <code> templateP </code>  string. 
    =><h4> Prototype  </h4>
    =><code> UInt16 DateTemplateToAscii(const Char *templateP, UInt8 months, UInt8 days, UInt16 years, Char *stringP, Int16 stringLen) </code>
    =><h4> Parameters  </h4>
    =><code> templateP </code>  pointer to template string used to format date. Max length is  <code> maxDateTemplateLen </code>  bytes, excluding the terminating null.  <code> months </code>  months (1-12)  <code> days </code>  days (1-31)  <code> years </code>  years. For example, 1995.  <code> stringP </code>  pointer to string which gets the result. Up to  <code> stringLen </code>  bytes (excluding the terminating null byte.) Can be NULL, in which case the required string length is still returned by the function. If not NULL, then the formatted string is written to it,  <code> stringLen </code>  size of string buffer, excluding the terminating NULL byte. 
    =><h4> Result  </h4>
    =>The length of the formatted string (without the terminating null byte) is always returned, even if the  <code> stringP </code>  parameter is null.  This then lets you allocate a buffer at run time, without having to previously fix it to some max size. 
    =><h4> Comments  </h4>
    =>The  <code> stringP </code>  parameter can be NULL, in which case the required string length is still returned.  <blockquote> <hr> <strong> NOTE: &nbsp; </strong> This routine is only available in PalmOS 3.5 or later ROMs. <hr> <br> </blockquote> This routine uses the template text contained in  <code> templateP </code> , and creates a properly formatted date string in  <code> stringP </code>  for the values passed in  <code> months </code> ,  <code> days </code> , and  <code> years </code> .  Template strings:  A template string contains a mixture of regular text and formatting substrings. Each formatting substring has the format  "^&lt;number&gt;&lt;modifier&gt;". The possible values for number are: <p> <div>
    =><table border="3"> <caption> <br> </caption> <tbody> <tr>
    =><td> dateTemplateDayNum = '0',  </td>
    =><td> // Day number (1..31)  </td> </tr> <tr>
    =><td> dateTemplateDOWName,  </td>
    =><td> // Day name (e.g. Tue)  </td> </tr> <tr>
    =><td> dateTemplateMonthName,  </td>
    =><td> // Month name (e.g. Aug)  </td> </tr> <tr>
    =><td> dateTemplateMonthNum,  </td>
    =><td> // Month number (1..12)  </td> </tr> <tr>
    =><td> dateTemplateYearNum  </td>
    =><td> // Year (e.g. 1995)  </td> </tr> </tbody> </table>
    =><table> <tbody> <tr>
    =><td> <br> </td> </tr> </tbody> </table> </div> The possible values for modifier are: <p> <div>
    =><table border="3"> <caption> <br> </caption> <tbody> <tr>
    =><td> #define dateTemplateShortModifier  </td>
    =><td> 's'  </td> </tr> <tr>
    =><td> #define dateTemplateRegularModifier  </td>
    =><td> 'r'  </td> </tr> <tr>
    =><td> #define dateTemplateLongModifier  </td>
    =><td> 'l'  </td> </tr> <tr>
    =><td> #define dateTemplateLeadZeroModifier  </td>
    =><td> 'z'  </td> </tr> </tbody> </table>
    =><table> <tbody> <tr>
    =><td> <br> </td> </tr> </tbody> </table> </div> The meaning of each modifier depends on what type of formatting string it's part of. An example of each is as follows: <p> <div>
    =><table border="3"> <caption> <br> </caption> <tbody> <tr>
    =><td> Format  </td>
    =><td> Short  </td>
    =><td> Regular  </td>
    =><td> Long  </td>
    =><td> Zero  </td> </tr> <tr>
    =><td> DayNum  </td>
    =><td> 5  </td>
    =><td> 5  </td>
    =><td> 5  </td>
    =><td> 05  </td> </tr> <tr>
    =><td> DOWName  </td>
    =><td> T  </td>
    =><td> Tue  </td>
    =><td> Tuesday  </td>
    =><td> n/a  </td> </tr> <tr>
    =><td> MonthName  </td>
    =><td> A  </td>
    =><td> Aug  </td>
    =><td> August  </td>
    =><td> n/a  </td> </tr> <tr>
    =><td> MonthNum  </td>
    =><td> 8  </td>
    =><td> 8  </td>
    =><td> 8  </td>
    =><td> 08  </td> </tr> <tr>
    =><td> YearNum  </td>
    =><td> 00  </td>
    =><td> 2000  </td>
    =><td> 2000  </td>
    =><td> n/a  </td> </tr> </tbody> </table>
    =><table> <tbody> <tr>
    =><td> <br> </td> </tr> </tbody> </table> </div> So, for example, the formatting string to get "02 February 2000" would be:  " <code> ^0z ^2l ^4r </code> "  </p> </p> </p>
    =><h4> See Also  </h4>
    =><code> DateToAscii </code> ,  <code> DateToDOWDMFormat </code> <br> <br> <br> <h3>
DateToAscii()
    =><h4> Purpose  </h4>
    =>Convert the date passed to a string using the format specified by the  <code> dateFormat </code>  parameter. 
    =><h4> Prototype  </h4>
    =><code> void DateToAscii (UInt8&nbsp;months, UInt8&nbsp;days, UInt16&nbsp;years, DateFormatType&nbsp;dateFormat, Char*&nbsp;pString) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> months </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Months (1-12). <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> days </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Days (1-31). <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> years </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Years (for example 1995). <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> dateFormat </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Any  "DateFormatType"  format. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> pString </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to string which gets the result. Must be of length  <code> dateStringLength </code>  for standard formats or  <code> longDateStrLength </code>  for medium or long formats. (See  "Time Manager Constants"  for allowed lengths. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns nothing. Stores the result in  <code> pString. </code>
    =><h4> Comments  </h4>
    =><blockquote> <hr> <strong> NOTE: &nbsp; </strong> If you are using a debug ROM, the string buffer is filled with  <code> dateStringLength </code>  or  <code> longStrLength </code>  debugging bytes, depending on the dateFormat parameter. <hr> <br> </blockquote> Common situations where buffers overflow on debug ROMs include stack-based or global variables, form titles, form labels, and control labels. Overflowing a form object is sometimes very hard to catch, because often what happens is that the following form object's data (such as its position) is overwritten, and so suddenly the form object disappears. 
    =><h4> See Also  </h4>
    =>TimeToAscii ,  DateToDOWDMFormat ,  DateTemplateToAscii <br> <br> <br> <h3>
DateToDays()
    =><h4> Purpose  </h4>
    =>Return the date in days since 1/1/1904. 
    =><h4> Prototype  </h4>
    =><code> UInt32 DateToDays (DateType&nbsp;date) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> date </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> "DateType"  structure. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the days since 1/1/1904. 
    =><h4> See Also  </h4>
    =>TimAdjust ,  DateDaysToDate <br> <br> <br> <h3>
DateToDOWDMFormat()
    =><h4> Purpose  </h4>
    =>Convert a date to a formatted string using the format specified by the dateFormat parameter. The string passed must include the name of the day of the week. 
    =><h4> Prototype  </h4>
    =><code> void DateToDOWDMFormat (UInt8&nbsp;month, UInt8&nbsp;day, UInt16&nbsp;year, DateFormatType&nbsp;dateFormat, Char&nbsp;*&nbsp;pString) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> month </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Month (1-12). <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> day </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Days (1-31). <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> year </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Years (for example 1995). <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> dateFormat </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Any  "DateFormatType"  format. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> pString </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to string which gets the result. Must be of length  <code> dateStringLength </code>  for standard formats or  <code> longDateStrLength </code>  for medium or long date formats. (See  "Time Manager Constants"  for string buffer lengths.) <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns nothing; stores formatted string in  <code> pString </code> . 
    =><h4> Comments  </h4>
    =>For the routines that return the day-of-week name in addition to the date, the size of the buffers has been expanded, so developers need to check the maximum lengths defined in  <code> DateTime.h </code> .  Common situations where buffers overflow on debug ROMs include stack-based or global variables, form titles, form labels, and control labels. Overflowing a form object is sometimes very hard to catch, because often what happens is that the following form object's data (such as its position) is overwritten, and so suddenly the form object disappears. 
    =><h4> See Also  </h4>
    =>DateToAscii ,  DateTemplateToAscii <br> <br> <br> <h3>
DayOfMonth()
    =><h4> Purpose  </h4>
    =>Return the day of a month on which the specified date occurs. 
    =><h4> Prototype  </h4>
    =><code> Int16 DayOfMonth (Int16&nbsp;month, Int16&nbsp;day, Int16&nbsp;year) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> month </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Month (1-12). <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> day </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Day (1-31). <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> year </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Year (for example 1995). <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the day of the month; see  <code> DateTime.h </code> . 
    =><h4> Comments  </h4>
    =>For example, "first Monday" is returned for 2/7/00.  <br> <br> <br> <h3>
DayOfWeek()
    =><h4> Purpose  </h4>
    =>Return the day of the week. 
    =><h4> Prototype  </h4>
    =><code> Int16 DayOfWeek (Int16&nbsp;month, Int16&nbsp;day, Int16&nbsp;year) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> month </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Month (1-12). <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> day </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Day (1-31). <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> year </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Year (for example 1995). <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the day of the week (Sunday = 0, Monday = 1, etc.).  <br> <br> <br> <h3>
DaysInMonth()
    =><h4> Purpose  </h4>
    =>Return the number of days in the month. 
    =><h4> Prototype  </h4>
    =><code> Int16 DaysInMonth (Int16&nbsp;month, Int16&nbsp;year) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> month </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Month (1-12). <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> year </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Year (for example, 1995). <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the number of days in the month for that year.  <br> <br> <br> <h3>
TimAdjust()
    =><h4> Purpose  </h4>
    =>Return a new date, +/- the time adjustment. 
    =><h4> Prototype  </h4>
    =><code> void TimAdjust (DateTimePtr&nbsp;dateTimeP, Int32&nbsp;adjustment) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> dateTimeP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A  "DateType"  structure (see  <code> DateTime.h </code> ). <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> adjustment </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The adjustment in seconds.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns nothing. Changes  <code> dateTimeP </code>  to the new date and time. 
    =><h4> Comments  </h4>
    =>This function is useful for advancing a day or week and not worrying about month and year wrapping.  If the time is advanced out of bounds it is cut at the bounds surpassed. 
    =><h4> See Also  </h4>
    =>DateAdjust <br> <br> <br> <h3>
TimDateTimeToSeconds()
    =><h4> Purpose  </h4>
    =>Return the number of seconds since 1/1/1904 to the passed date and time. 
    =><h4> Prototype  </h4>
    =><code> UInt32 TimDateTimeToSeconds (DateTimePtr&nbsp;dateTimeP) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> dateTimeP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to a  "DateTimeType"  structure (see  <code> DateTime.h </code> ). <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>The time in seconds since 1/1/1904. 
    =><h4> See Also  </h4>
    =>TimSecondsToDateTime <br> <br> <br> <h3>
TimGetSeconds()
    =><h4> Purpose  </h4>
    =>Return the current date and time of the device in seconds since 1/1/1904 12AM. 
    =><h4> Prototype  </h4>
    =><code> UInt32 TimGetSeconds (void) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> </code> <br> </td>
    =><td valign="top" align="left" width=""> <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the number of seconds. 
    =><h4> See Also  </h4>
    =>TimSetSeconds <br> <br> <br> <h3>
TimGetTicks()
    =><h4> Purpose  </h4>
    =>Return the tick count since the last reset. The tick count does not advance while the device is in sleep mode. 
    =><h4> Prototype  </h4>
    =><code> UInt32 TimGetTicks (void) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> </code> <br> </td>
    =><td valign="top" align="left" width=""> <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the tick count. 
    =><h4> Comments  </h4>
    =>Use to determine the number of ticks per second.  <br> <br> <br> <h3>
TimSecondsToDateTime()
    =><h4> Purpose  </h4>
    =>Return the date and time, given seconds. 
    =><h4> Prototype  </h4>
    =><code> void TimSecondsToDateTime (UInt32&nbsp;seconds, DateTimePtr&nbsp;dateTimeP) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> seconds </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Seconds to advance from 1/1/1904. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> dateTimeP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A  "DateTimeType"  structure that's filled by the function. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns nothing. Stores the date and time given seconds since 1/1/1904 in  <code> dateTimeP. </code>
    =><h4> See Also  </h4>
    =>TimDateTimeToSeconds <br> <br> <br> <h3>
TimSetSeconds()
    =><h4> Purpose  </h4>
    =>Set the clock of the device to the date and time passed as the number of seconds since 1/1/1904 12AM. 
    =><h4> Prototype  </h4>
    =><code> void TimSetSeconds (UInt32&nbsp;seconds) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> seconds </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The seconds since 1/1/1904. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns nothing. 
    =><h4> Comments  </h4>
    =>On systems where the  Notification Feature Set  is present, this function broadcasts the  <code> sysNotifyTimeChangeEvent </code>  to all interested parties. See the  "Notification Manager"  chapter for more information. 
    =><h4> See Also  </h4>
    =>TimGetSeconds <br> <br> <br> <h3>
TimeToAscii()
    =><h4> Purpose  </h4>
    =>Convert the time passed to a formatted string. 
    =><h4> Prototype  </h4>
    =><code> void TimeToAscii (UInt8&nbsp;hours, UInt8&nbsp;minutes, TimeFormatType&nbsp;timeFormat, Char*&nbsp;pString) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> hours </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Hours (0-23). <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> minutes </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Minutes (0-59). <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> timeFormat </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> <code> FALSE </code>  to use AM and PM. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> pString </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to string which gets the result. Must be of length  <code> timeStringLength </code> . See  "Time Manager Constants"  for information on string buffer lengths. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns nothing. Stores the formatted string in  <code> pString </code> . 
    =><h4> Comments  </h4>
    =><blockquote> <hr> <strong> NOTE: &nbsp; </strong> If you are using a debug ROM in PalmOS 3.5, the string buffer is filled with timeStringLength debugging bytes. <hr> <br> </blockquote> For the routines that return the day-of-week name in addition to the date, the size of the buffers has been expanded, so developers need to check the maximum lengths defined in  <code> DateTime.h </code> . See  "Time Manager Constants" . 
    =><h4> See Also  </h4>
    =>DateToAscii <strong> </strong> <br> <h3>
SerClearErr()
    =><h4> Purpose  </h4>
    =>Reset the serial port's line error status. 
    =><h4> Prototype  </h4>
    =><code> Err SerClearErr (UInt16&nbsp;refNum) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> refNum </code> <br> </code> </td>
    =><td valign="top" align="left" width=""> The serial library reference number. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> 0 </code> <br> </td>
    =><td valign="top" align="left" width=""> No error. <br> </td> </tr> </tbody> </table>
    =><h4> Comments  </h4>
    =>Call  <code> SerClearErr </code>  only after a serial manager function ( <code> SerReceive </code> ,  <code> SerReceiveCheck </code> ,  <code> SerSend </code> , etc.) returns with the error code  <code> serErrLineErr </code> .  The reason for this is that  <code> SerClearErr </code>  resets the serial port. So, if  <code> SerClearErr </code>  is called unconditionally while a byte is coming into the serial port, that byte is guaranteed to become corrupted.  The right strategy is to always check the error code returned by a serial manager function. If it `s  <code> serErrLineErr </code> , call  <code> SerClearErr </code>  immediately. However, don't make unsolicited calls to  <code> SerClearErr </code> .  When you get  <code> serErrLineErr </code> , consider flushing the receive queue for a fraction of a second by calling  <code> SerReceiveFlush </code> .  <code> SerReceiveFlush </code>  calls  <code> SerClearErr </code>  for you.  <br> <br> <br> <h3>
SerClose()
    =><h4> Purpose  </h4>
    =>Release the serial port previously acquired by SerOpen. 
    =><h4> Prototype  </h4>
    =><code> Err SerClose (UInt16&nbsp;refNum) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> refNum </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Serial library reference number. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> 0 </code> <br> </td>
    =><td valign="top" align="left" width=""> No error. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> serErrNotOpen </code> <br> </td>
    =><td valign="top" align="left" width=""> Port wasn't open. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> serErrStillOpen </code> <br> </td>
    =><td valign="top" align="left" width=""> Port still held open by another process. <br> </td> </tr> </tbody> </table>
    =><h4> Comments  </h4>
    =>Releases the serial port and shuts down serial port hardware if the open count has reached 0. Open serial ports consume more energy from the device's batteries; it's therefore essential to keep a port open only as long as necessary. 
    =><h4> Caveat </h4>
    =>Don't call SerClose unless the return value from  SerOpen  was 0 (zero) or serErrAlreadyOpen. 
    =><h4> See Also  </h4>
    =>SerOpen <br> <br> <br> <h3>
SerControl()
    =><h4> Purpose  </h4>
    =>Perform a control function. 
    =><h4> Prototype  </h4>
    =><code> Err SerControl (UInt16&nbsp;refNum, UInt16&nbsp;op, void&nbsp;*valueP, UInt16&nbsp;*valueLenP) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> refNum </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Reference number of library. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> op </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Control operation to perform ( <code> SerCtlEnum </code> ). <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;-&gt;  <code> valueP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to value for operation. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;-&gt;  <code> valueLenP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to size of value. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> 0 </code> <br> </td>
    =><td valign="top" align="left" width=""> No error. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> serErrBadParam </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Invalid parameter (unknown).  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> serErrNotOpen </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Library not open. <br> </td> </tr> </tbody> </table>
    =><h4> Comments  </h4>
    =>This function provides extensible control features for the serial manager. You can  <ul type="square"> <br> <li> Turn on/off the RS232 break signal and check its status. <br> <br> <li> Perform a local loopback test. <br> <br> <li> Get the maximum supported baud rate. <br> <br> <li> Get the hardware handshake threshold baud rate. <br> </li> </li> </li> </li> </ul> There is one emulator-only control,  <code> serCtlEmuSetBlockingHook </code> . See  Using the Serial Manager  for more information. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  2.0 New Feature Set  is present.  <br> <br> <br> <h3>
SerGetSettings()
    =><h4> Purpose  </h4>
    =>Fill in the  SerSettingsType  structure with current serial port attributes. 
    =><h4> Prototype  </h4>
    =><code> Err SerGetSettings (UInt16&nbsp;refNum, SerSettingsPtr&nbsp;settingsP) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> refNum </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Serial library reference number. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;-&gt;  <code> settingsP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to  SerSettingsType  structure to be filled in. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> 0 </code> <br> </td>
    =><td valign="top" align="left" width=""> No error. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> serErrNotOpen </code> <br> </td>
    =><td valign="top" align="left" width=""> The port wasn't open. <br> </td> </tr> </tbody> </table>
    =><h4> Comments  </h4>
    =>The information returned by this call includes the current baud rate, CTS timeout, handshaking options, and data format options.  See the  SerSettingsType  structure for more details. 
    =><h4> See Also  </h4>
    =>SerSend <br> <br> <br> <h3>
SerGetStatus()
    =><h4> Purpose  </h4>
    =>Return the pending line error status for errors that have been detected since the last time  SerClearErr  was called. 
    =><h4> Prototype  </h4>
    =><code> UInt16 SerGetStatus (UInt16&nbsp;refNum, Boolean&nbsp;*ctsOnP, Boolean&nbsp;*dsrOnP) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> refNum </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Serial library reference number. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> ctsOnP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to location for storing a Boolean value. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> dsrOnP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to location for storing a Boolean value. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns any combination of the following constants, bitwise ORed together: 
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> serLineErrorParity </code> <br> </code> </td>
    =><td valign="top" align="left" width=""> Parity error. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> serLineErrorHWOverrun </code> <br> </td>
    =><td valign="top" align="left" width=""> Hardware overrun. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> serLineErrorFraming </code> <br> </td>
    =><td valign="top" align="left" width=""> Framing error. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> serLineErrorBreak </code> <br> </td>
    =><td valign="top" align="left" width=""> Break signal detected. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> serLineErrorHShake </code> <br> </td>
    =><td valign="top" align="left" width=""> Line handshake error. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> serLineErrorSWOverrun </code> <br> </td>
    =><td valign="top" align="left" width=""> Software overrun. <br> </td> </tr> </tbody> </table>
    =><h4> Comments  </h4>
    =>When another serial manager function returns an error code of serErrLineErr, SerGetStatus can be used to find out the specific nature of the line error(s).  The values returned via  <code> ctsOnP </code>  and  <code> dsrOnP </code>  are not meaningful in the present version of the software 
    =><h4> See Also  </h4>
    =>SerClearErr <br> <br> <br> <h3>
SerOpen()
    =><h4> Purpose  </h4>
    =>Acquire and open a serial port with given baud rate and default settings. 
    =><h4> Prototype  </h4>
    =><code> Err SerOpen (UInt16&nbsp;refNum, UInt16&nbsp;port, UInt32&nbsp;baud) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> refNum </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Serial library reference number. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> port </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Port number. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> baud </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Baud rate. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> 0 </code> <br> </td>
    =><td valign="top" align="left" width=""> No error. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> serErrAlreadyOpen </code> <br> </td>
    =><td valign="top" align="left" width=""> Port was open. Enables port sharing by "friendly" clients (not recommended). <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> serErrBadParam </code> <br> </td>
    =><td valign="top" align="left" width=""> Invalid parameter. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> memErrNotEnoughSpace </code> <br> </td>
    =><td valign="top" align="left" width=""> Insufficient memory. <br> </td> </tr> </tbody> </table>
    =><h4> Comments  </h4>
    =>Acquires the serial port, powers it up, and prepares it for operation. To obtain the serial library reference number, call  SysLibFind  with "Serial Library" as the library name. This reference number must be passed as a parameter to all serial manager functions. The device currently contains only one serial port with port number 0 (zero).  The baud rate is an integral baud value (for example - 300, 1200, 2400, 9600, 19200, 38400, 57600, etc.). The Palm OS <sup> &reg; </sup>  device has been tested at the standard baud rates in the range of 300 - 57600 baud. Baud rates through 1 Mbit are theoretically possible. Use CTS handshaking at baud rates above 19200 (see  SerSetSettings ).  An error code of 0 (zero) or serErrAlreadyOpen indicates that the port was successfully opened. If the port is already open when SerOpen is called, the port's open count is incremented and an error code of serErrAlreadyOpen is returned. This ability to open the serial port multiple times allows cooperating tasks to share the serial port. Other tasks must refrain from using the port if serErrAlreadyOpen is returned and close it by calling  SerClose .  <br> <br> <br> <h3>
SerReceive()
    =><h4> Purpose  </h4>
    =>Receives  <code> size </code>  bytes worth of data or returns with error if a line error or timeout is encountered. 
    =><h4> Prototype  </h4>
    =><code> UInt32 SerReceive (UInt16&nbsp;refNum, void&nbsp;*bufP, UInt32&nbsp;count, Int32&nbsp;timeout, Err* errP) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> refNum </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Serial library reference number. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;-&gt;  <code> bufP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Buffer for receiving data. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> count </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Number of bytes to receive. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> timeout </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Interbyte timeout in ticks, 0 for none, -1 forever. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;-&gt;  <code> errP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> For returning error code. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Number of bytes received: 
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> *errP = 0 </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> No error. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> serErrLineErr </code> <br> </code> </td>
    =><td valign="top" align="left" width=""> RS232 line error. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> serErrTimeOut </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Interbyte timeout. <br> </td> </tr> </tbody> </table>
    =><h4> Compatibility  </h4>
    =>Implemented only if  2.0 New Feature Set  is present.  <blockquote> <hr> <strong> NOTE: &nbsp; </strong> The old versions of  <code> SerSend </code>  and  <code> SerReceive </code>  are still available as  <code> SerSend10 </code>  and  <code> SerReceive10 </code>  (not V10). <hr> <br> </blockquote>
    =><h4> See Also  </h4>
    =>SerReceive10 <br> <br> <br> <h3>
SerReceive10()
    =><h4> Purpose  </h4>
    =>Receive a stream of bytes. 
    =><h4> Prototype  </h4>
    =><code> Err SerReceive10 (UInt16&nbsp;refNum, void&nbsp;*bufP, UInt32&nbsp;bytes, Int32&nbsp;timeout) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> refNum </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The serial library reference number. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> bufP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the buffer for receiving data. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> bytes </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Number of bytes desired. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> timeout </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Interbyte time out in system ticks (-1 = forever). <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> 0 </code> <br> </td>
    =><td valign="top" align="left" width=""> No error. Requested number of bytes was received. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> serErrTimeOut </code> <br> </td>
    =><td valign="top" align="left" width=""> Interbyte time out exceeded while waiting for the next byte to arrive. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> serErrLineErr </code> <br> </td>
    =><td valign="top" align="left" width=""> Line error occurred (see  SerClearErr  and  SerGetStatus ). <br> </td> </tr> </tbody> </table>
    =><h4> Comments  </h4>
    =>SerReceive blocks until all the requested data has been received or an error occurs. Because this call returns immediately without any data if line errors are pending, it is important to acknowledge the detection of line errors by calling  SerClearErr . If you just need to retrieve all or some of the bytes which are already in the receive queue, call  SerReceiveCheck  first to get the count of bytes presently in the receive queue. 
    =><h4> Compatibility  </h4>
    =>This function corresponds to the 1.0 version of  <code> SerReceive </code> .  <br> <br> <br> <h3>
SerReceiveCheck()
    =><h4> Purpose  </h4>
    =>Return the count of bytes presently in the receive queue. 
    =><h4> Prototype  </h4>
    =><code> Err SerReceiveCheck (UInt16&nbsp;refNum, UInt32&nbsp;*numBytesP) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> refNum </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Serial library reference number. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;-&gt;  <code> numBytesP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to location for returning the byte count. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> 0 </code> <br> </td>
    =><td valign="top" align="left" width=""> No error. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> serErrLineErr </code> <br> </td>
    =><td valign="top" align="left" width=""> Line error pending (see  SerClearErr  and  SerGetStatus ). <br> </td> </tr> </tbody> </table>
    =><h4> Comments  </h4>
    =>Because this call does not return the byte count if line errors are pending, it is important to acknowledge the detection of line errors by calling  SerClearErr . 
    =><h4> See Also  </h4>
    =>SerReceiveWait <br> <br> <br> <h3>
SerReceiveFlush()
    =><h4> Purpose  </h4>
    =>Discard all data presently in the receive queue and flush bytes coming into the serial port. Clear the saved error status. 
    =><h4> Prototype  </h4>
    =><code> void SerReceiveFlush (UInt16&nbsp;refNum, Int32&nbsp;timeout) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> refNum </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Serial library reference number. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> timeout </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Interbyte time out in system ticks (-1 = forever). <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns nothing. 
    =><h4> Comments  </h4>
    =><code> SerReceiveFlush </code>  blocks until a timeout occurs while waiting for the next byte to arrive.  <br> <br> <br> <h3>
SerReceiveWait()
    =><h4> Purpose  </h4>
    =>Wait for at least  <code> bytes </code>  bytes of data to accumulate in the receive queue. 
    =><h4> Prototype  </h4>
    =><code> Err SerReceiveWait (UInt16&nbsp;refNum, UInt32&nbsp;bytes, Int32&nbsp;timeout) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> refNum </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Serial library reference number. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> bytes </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Number of bytes desired. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> timeout </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Interbyte timeout in system ticks (-1 = forever). <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> 0 </code> <br> </td>
    =><td valign="top" align="left" width=""> No error. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> serErrTimeOut </code> <br> </td>
    =><td valign="top" align="left" width=""> Interbyte timeout exceeded while waiting for next byte to arrive. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> serErrLineErr </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Line error occurred (see  SerClearErr  and  SerGetStatus ). <br> </td> </tr> </tbody> </table>
    =><h4> Comments  </h4>
    =>This is the preferred method of waiting for serial input, since it blocks the current task and allows switching the processor into a more energy-efficient state.  SerReceiveWait blocks until the desired number of bytes accumulate in the receive queue or an error occurs. The desired number of bytes must be less than the current receive queue size. The default queue size is 512 bytes. Because this call returns immediately if line errors are pending, it is important to acknowledge the detection of line errors by calling  SerClearErr . 
    =><h4> See Also  </h4>
    =>SerReceiveCheck ,  SerSetReceiveBuffer <br> <br> <br> <h3>
SerSend()
    =><h4> Purpose  </h4>
    =>Send one or more bytes of data over the serial port. 
    =><h4> Prototype  </h4>
    =><code> UInt32 SerSend (UInt16&nbsp;refNum, void&nbsp;*bufP, UInt32&nbsp;count, Err&nbsp;*errP </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> refNum </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Serial library reference number. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> bufP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to data to send. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> count </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Number of bytes to send. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;-&gt;  <code> errP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> For returning error code. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the number of bytes transferred.  Stores in  <code> errP </code> : 
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> 0 </code> <br> </td>
    =><td valign="top" align="left" width=""> No error. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> serErrTimeOut </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Handshake timeout. <br> </td> </tr> </tbody> </table> The old calls worked, but they did not return enough info when they failed. The new calls (available in Palm OS v2.0 and greater) add more parameters to solve this problem and make serial communications programming simpler.  Don't call the new functions when running on Palm OS 1.0. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  2.0 New Feature Set  is present.  <blockquote> <hr> <strong> NOTE: &nbsp; </strong> The old versions of  <code> SerSend </code>  and  <code> SerReceive </code>  are still available as  <code> SerSend10 </code>  and  <code> SerReceive10 </code>  (not V10). <hr> <br> </blockquote>
    =><h4> See Also  </h4>
    =>SerSend10 ,  SerSendWait <br> <br> <br> <h3>
SerSend10()
    =><h4> Purpose  </h4>
    =>Send a stream of bytes to the serial port. 
    =><h4> Prototype  </h4>
    =><code> Err SerSend10 (UInt16&nbsp;refNum, void&nbsp;*bufP, UInt32&nbsp;size) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> refNum </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Serial library reference number. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> bufP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the data to send. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> size </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Size (in number of bytes) of the data to send. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> 0 </code> <br> </td>
    =><td valign="top" align="left" width=""> No error. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> serErrTimeOut </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Handshake timeout (such as waiting for CTS to become asserted). <br> </td> </tr> </tbody> </table>
    =><h4> Comments  </h4>
    =>In the present implementation,  <code> S </code> erSend10 blocks until all data is transferred to the UART or a timeout error (if CTS handshaking is enabled) occurs. Future implementations may queue up the request and return immediately, performing transmission in the background. If your software needs to detect when all data has been transmitted, see  SerSendWait .  This routine observes the current CTS time out setting if CTS handshaking is enabled (see  SerGetSettings  and  SerSend ). 
    =><h4> Compatibility  </h4>
    =>This function corresponds to the 1.0 version of  <code> SerSend </code> . 
    =><h4> See Also  </h4>
    =>SerSend ,  SerSendWait <br> <br> <br> <h3>
SerSendFlush()
    =><h4> Purpose  </h4>
    =>Discard all data presently in the transmit queue. 
    =><h4> Prototype  </h4>
    =><code> Err SerSendFlush (UInt16&nbsp;refNum) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> refNum </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Serial library reference number. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> 0 </code> <br> </td>
    =><td valign="top" align="left" width=""> No error. <br> </td> </tr> </tbody> </table>
    =><h4> See Also  </h4>
    =>SerSend ,  SerSendWait <br> <br> <br> <h3>
SerSendWait()
    =><h4> Purpose  </h4>
    =>Wait until the serial transmit buffer empties. 
    =><h4> Prototype  </h4>
    =><code> Err SerSendWait (UInt16&nbsp;refNum, Int32&nbsp;timeout) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> refNum </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Serial library reference number. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> timeout </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Reserved for future enhancements. Set to (-1) for compatibility. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> 0 </code> <br> </td>
    =><td valign="top" align="left" width=""> No error. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> serErrTimeOut </code> <br> </td>
    =><td valign="top" align="left" width=""> Handshake timeout (such as waiting for CTS to become asserted). <br> </td> </tr> </tbody> </table>
    =><h4> Comments  </h4>
    =>SerSendWait blocks until all data is transferred or a timeout error (if CTS handshaking is enabled) occurs. This routine observes the current CTS timeout setting if CTS handshaking is enabled (see  SerGetSettings  and  SerSend ). 
    =><h4> See Also  </h4>
    =>SerSend <br> <br> <br> <h3>
SerSetReceiveBuffer()
    =><h4> Purpose  </h4>
    =>Replace the default receive queue. To restore the original buffer, pass  <code> bufSize </code>  = 0. 
    =><h4> Prototype  </h4>
    =><code> Err SerSetReceiveBuffer (UInt16&nbsp;refNum, void&nbsp;*bufP, UInt16&nbsp;bufSize) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> refNum </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Serial library reference number. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> bufP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to buffer to be used as the new receive queue. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> bufSize </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Size of buffer, or 0 to restore the default receive queue. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns 0 if successful. 
    =><h4> Comments  </h4>
    =>The specified buffer needs to contain 32 extra bytes for serial manager overhead (its size should be your application's requirement plus 32 bytes). The default receive queue must be restored before the serial port is closed. To restore the default receive queue, call  SerSetReceiveBuffer  passing 0 (zero) for the buffer size. The serial manager does not free the custom receive queue.  <br> <br> <br> <h3>
SerSetSettings()
    =><h4> Purpose  </h4>
    =>Set the serial port settings; that is, change its attributes. 
    =><h4> Prototype  </h4>
    =><code> Err SerSetSettings (UInt16&nbsp;refNum, SerSettingsPtr&nbsp;settingsP) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> refNum </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Serial library reference number. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;-&gt;  <code> settingsP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the filled in  SerSettingsType  structure. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> 0 </code> <br> </td>
    =><td valign="top" align="left" width=""> No error. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> serErrNotOpen </code> <br> </td>
    =><td valign="top" align="left" width=""> The port wasn't open. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> serErrBadParam </code> <br> </td>
    =><td valign="top" align="left" width=""> Invalid parameter. <br> </td> </tr> </tbody> </table>
    =><h4> Comments  </h4>
    =>The attributes set by this call include the current baud rate, CTS timeout, handshaking options, and data format options. See the definition of the  SerSettingsType  structure for more details.  To do 7E1 transmission,  <code> OR </code>  together:  <code> serSettingsFlagBitsPerChar7 | serSettingsFlagParityOnM | serSettingsFlagParityEvenM | serSettingsFlagStopBits1 </code> If you're trying to communicate at speeds greater than 19.2 Kbps, you need to use hardware handshaking:  <code> serSettingsFlagRTSAutoM </code>  |  <code> serSettingsFlagCTSAutoM </code> . 
    =><h4> See Also  </h4>
    =>SerGetSettings <strong> </strong> <br> <h3>
StrAToI()
    =><h4> Purpose  </h4>
    =>Convert a string to an integer. 
    =><h4> Prototype  </h4>
    =><code> Int32 StrAToI (const&nbsp;Char*&nbsp;str) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> str </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> String to convert. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the integer. 
    =><h4> Comments  </h4>
    =>Use this function instead of the standard  <code> atoi </code>  routine.  <br> <br> <br> <h3>
StrCaselessCompare()
    =><h4> Purpose  </h4>
    =>Compare two strings with case and accent insensitivity. 
    =><h4> Prototype  </h4>
    =><code> Int16 StrCaselessCompare (const&nbsp;Char*&nbsp;s1, const&nbsp;Char*&nbsp;s2) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> s1 </code> ,  <code> s2 </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Two string pointers. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns 0 if the strings match.  Returns a positive number if  <code> s1 </code>  &gt;  <code> s2 </code> .  Returns a negative number if  <code> s1 </code>  &lt;  <code> s2 </code> . 
    =><h4> Comments  </h4>
    =>Use this function instead of the standard  <code> stricmp </code>  routine. Use it to find strings, or use it with  StrCompare  to sort strings. (See the comments in  <code> StrCompare </code>  for a example code.)  To support systems that use multi-byte character encodings, consider using  TxtCaselessCompare  instead of this function. Both functions can match single-byte characters with their multi-byte equivalents, but  <code> TxtCaselessCompare </code>  can also return the length of the matching text. 
    =><h4> See Also  </h4>
    =>StrNCaselessCompare ,  TxtCaselessCompare ,  StrCompare ,  StrNCompare ,  TxtCompare <br> <br> <br> <h3>
StrCat()
    =><h4> Purpose  </h4>
    =>Concatenate one string to another. 
    =><h4> Prototype  </h4>
    =><code> Char* StrCat (Char*&nbsp;dst, const&nbsp;Char*&nbsp;src) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> dst </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Destination string pointer. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> src </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Source string pointer.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns a pointer to the destination string. 
    =><h4> Comments  </h4>
    =>Use this function instead of the standard  <code> strcat </code>  routine.  <br> <br> <br> <h3>
StrChr()
    =><h4> Purpose  </h4>
    =>Look for a character within a string. 
    =><h4> Prototype  </h4>
    =><code> Char* StrChr (const&nbsp;Char*&nbsp;str, WChar&nbsp;chr) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> str </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> String to search. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> chr </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Character to search for. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns a pointer to the first occurrence of character in  <code> str </code> . Returns  <code> NULL </code>  if the character is not found. 
    =><h4> Comments  </h4>
    =>Use this function instead of the standard  <code> strchr </code>  routine.  This routine does not correctly find a `\0' character on Palm OS <sup> &reg; </sup>  version 1.0.  This function can handle both single-byte characters and multi-byte characters.  <code> StrChr </code>  displays a non-fatal error message if  <code> chr </code>  is greater than  <code> 0xFF </code> . 
    =><h4> See Also  </h4>
    =>StrStr <br> <br> <br> <h3>
StrCompare()
    =><h4> Purpose  </h4>
    =>Compare two strings. 
    =><h4> Prototype  </h4>
    =><code> Int16 StrCompare (const&nbsp;Char*&nbsp;s1, const&nbsp;Char*&nbsp;s2) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> s1, s2 </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Two string pointers. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns 0 if the strings match.  Returns a positive number if  <code> s1 </code>  sorts after  <code> s2 </code>  alphabetically.  Returns a negative number if  <code> s1 </code>  sorts before  <code> s2 </code>  alphabetically. 
    =><h4> Comments  </h4>
    =>Use this function instead of the standard  <code> strcmp </code>  routine.  This function is case sensitive. Use it to sort strings but not to find them.  This function performs a character-by-character comparison of  <code> s1 </code>  and  <code> s2 </code>  and returns as soon as it finds two unequal characters. For example, if you are comparing the string "celery" with the string "Cauliflower,"  <code> StrCompare </code>  returns that "celery" should appear before "Cauliflower" because it sorts the letter "c" before "C."  If you need to perform a true alphabetical sort, use  StrCaselessCompare  before using  <code> StrCompare </code> , as in the following code:  <br> <code> Int16 result = StrCaselessCompare(a, b); </code> <br> <code> if (result == 0) </code> <br> <code> &nbsp;&nbsp;&nbsp; result = StrCompare(a, b); </code> <br> <code> return(result); </code> <br> To support systems that use multi-byte character encodings, consider using  TxtCompare  instead of this function. Both functions can match single-byte characters with their multi-byte equivalents, but  <code> TxtCompare </code>  can also return the length of the matching text. 
    =><h4> See Also  </h4>
    =>StrNCompare ,  TxtCompare ,  StrCaselessCompare ,  StrNCaselessCompare ,  TxtCaselessCompare <br> <br> <br> <h3>
StrCopy()
    =><h4> Purpose  </h4>
    =>Copy one string to another. 
    =><h4> Prototype  </h4>
    =><code> Char* StrCopy (Char*&nbsp;dst, const&nbsp;Char*&nbsp;src) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> dst, src </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Two string pointers. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns a pointer to the destination string. 
    =><h4> Comments  </h4>
    =>Use this function instead of the standard  <code> strcpy </code>  routine.  This function does not work properly with overlapping strings.  <br> <br> <br> <h3>
StrDelocalizeNumber()
    =><h4> Purpose  </h4>
    =>Delocalize a number passed in as a string. Convert the number from any localized notation to US notation (decimal point and thousandth comma). The current thousand and decimal separators have to be passed in. 
    =><h4> Prototype  </h4>
    =><code> Char* StrDelocalizeNumber (Char*&nbsp;s, Char&nbsp;thousandSeparator, Char&nbsp;decimalSeparator) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> s </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the number as an ASCII string. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> thousandSeparator </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Current thousand separator. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> decimalSeparator </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Current decimal separator. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns a pointer to the changed number and modifies the string in  <code> s </code> . 
    =><h4> Compatibility  </h4>
    =>Implemented only if  2.0 New Feature Set  is present. 
    =><h4> See Also  </h4>
    =>StrLocalizeNumber ,  LocGetNumberSeparators <br> <br> <br> <h3>
StrIToA()
    =><h4> Purpose  </h4>
    =>Convert an integer to ASCII. 
    =><h4> Prototype  </h4>
    =><code> Char* StrIToA (Char*&nbsp;s, Int32&nbsp;i) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> s </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> String pointer to store results. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> i </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Integer to convert. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns a pointer to the result string. 
    =><h4> See Also  </h4>
    =>StrAToI ,  StrIToH <br> <br> <br> <h3>
StrIToH()
    =><h4> Purpose  </h4>
    =>Convert an integer to hexadecimal ASCII. 
    =><h4> Prototype  </h4>
    =><code> Char* StrIToH (Char*&nbsp;s, UInt32&nbsp;i) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> s </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> String pointer to store results. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> i </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Integer to convert. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the string pointer  <code> s </code> . 
    =><h4> See Also  </h4>
    =>StrIToA <br> <br> <br> <h3>
StrLen()
    =><h4> Purpose  </h4>
    =>Compute the length of a string. 
    =><h4> Prototype  </h4>
    =><code> UInt16 StrLen (const&nbsp;Char*&nbsp;src) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> src </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> String pointer <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the length of the string in bytes. 
    =><h4> Comments  </h4>
    =>Use this function instead of the standard  <code> strlen </code>  routine.  This function returns the length of the string in bytes. On systems that support multi-byte characters, the number returned does not always equal the number of characters.  <br> <br> <br> <h3>
StrLocalizeNumber()
    =><h4> Purpose  </h4>
    =>Convert a number (passed in as a string) to localized format, using a specified thousands separator and decimal separator. 
    =><h4> Prototype  </h4>
    =><code> Char* StrLocalizeNumber (Char*&nbsp;s, Char&nbsp;thousandSeparator, Char&nbsp;decimalSeparator) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> s </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Number ASCII string to localize. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> thousandSeparator </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Localized thousand separator. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> decimalSeparator </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Localized decimal separator. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns a pointer to the changed number. Converts the number string in  <code> s </code>  by replacing all occurrences of "," with  <code> thousandSeparator </code>  and all occurrences of "." with  <code> decimalSeparator </code> . 
    =><h4> Compatibility  </h4>
    =>Implemented only if  2.0 New Feature Set  is present. 
    =><h4> See Also  </h4>
    =>StrDelocalizeNumber <br> <br> <br> <h3>
StrNCaselessCompare()
    =><h4> Purpose  </h4>
    =>Compares two strings out to  <em> n </em>  characters with case and accent insensitivity. 
    =><h4> Prototype  </h4>
    =><code> Int16 StrNCaselessCompare (const&nbsp;Char*&nbsp;s1, const&nbsp;Char*&nbsp;s2, Int32&nbsp;n) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> s1 </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to first string. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> s2 </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to second string.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> n </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Length in bytes of the text to compare. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns 0 if the strings match.  Returns a positive number if  <code> s1 </code>  &gt;  <code> s2 </code> .  Returns a negative number if  <code> s1 </code>  &lt;  <code> s2 </code> . 
    =><h4> Comments  </h4>
    =>To support systems that use multi-byte character encodings, consider using  TxtCaselessCompare  instead of this function. Both functions can match single-byte characters with their multi-byte equivalents, but  <code> TxtCaselessCompare </code>  can also return the length of the matching text. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  2.0 New Feature Set  is present. 
    =><h4> See Also  </h4>
    =>StrNCompare ,  StrCaselessCompare ,  TxtCaselessCompare ,  StrCompare ,  TxtCompare <br> <br> <br> <h3>
StrNCat()
    =><h4> Purpose  </h4>
    =>Concatenates one string to another clipping the destination string to a maximum of  <em> n </em>  bytes (including the null character at the end). 
    =><h4> Prototype  </h4>
    =><code> Char* StrNCat (Char*&nbsp;dst, const&nbsp;Char*&nbsp;src, Int16&nbsp;n) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> dst </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to destination string.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> src </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to source string. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> n </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Maximum length in bytes for  <code> dst </code> , including the terminating null character. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns a pointer to the destination string. 
    =><h4> Comment </h4>
    =>This function differs from the standard C  <code> strncat </code>  function in these ways:  <ul type="square"> <br> <li> <code> StrNCat </code>  treats the parameter  <code> n </code>  as the maximum length in bytes for  <code> dst </code> . That means it will copy at most  <code> n </code>  -  <code> StrLen(dst) </code>  - 1 bytes from  <code> src </code> . The standard C function always copies  <code> n </code>  bytes from  <code> src </code>  into  <code> dst </code> . (It copies the entire  <code> src </code>  into  <code> dst </code>  if the length of  <code> src </code>  is less than  <code> n </code> ).  <br> <br> <li> If the length of the destination string reaches  <code> n </code>  - 1,  <code> StrNCat </code>  stops copying bytes from  <code> src </code>  and appends the terminating null character to  <code> dst </code> . If the length of the destination string is already greater than or equal to  <code> n </code>  - 1 before the copying begins,  <code> StrNCat </code>  does not copy any data from  <code> src </code> .  <br> <br> <li> In the standard C function, if  <code> src </code>  is less than  <code> n </code> , the entire  <code> src </code>  string is copied into  <code> dst </code>  and then the remaining space is filled with null characters.  <code> StrNCat </code>  does not fill the remaining space with null characters in released ROMs. In debug ROMs,  <code> StrNCat </code>  fills the remaining bytes with the value  <code> 0xFE </code> .  <br> </li> </li> </li> </ul>
    =><h4> Compatibility  </h4>
    =>Implemented only if  2.0 New Feature Set  is present.  <br> <br> <br> <h3>
StrNCompare()
    =><h4> Purpose  </h4>
    =>Compare two strings out to  <em> n </em>  characters. This function is case and accent sensitive. 
    =><h4> Prototype  </h4>
    =><code> Int16 StrNCompare (const&nbsp;Char*&nbsp;s1, const&nbsp;Char*&nbsp;s2, UInt32&nbsp;n) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> s1 </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to first string. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> s2 </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to second string.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> n </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Length in bytes of text to compare.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns 0 if the strings match.  Returns a positive number if  <code> s1 </code>  &gt;  <code> s2 </code> .  Returns a negative number if  <code> s1 </code>  &lt;  <code> s2 </code> . 
    =><h4> Comments  </h4>
    =>To support systems that use multi-byte character encodings, consider using  TxtCompare  instead of this function. Both functions can match single-byte characters with their multi-byte equivalents, but  <code> TxtCompare </code>  can also return the length of the matching text. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  2.0 New Feature Set  is present. 
    =><h4> See Also  </h4>
    =>StrCompare ,  TxtCompare ,  StrNCaselessCompare ,  StrCaselessCompare ,  TxtCaselessCompare <br> <br> <br> <h3>
StrNCopy()
    =><h4> Purpose  </h4>
    =>Copies up to  <em> n </em>  characters from a source string to the destination string. Terminates  <code> dst </code>  string at index  <em> n </em> -1 if the source string length was  <em> n </em> -1 or less. 
    =><h4> Prototype  </h4>
    =><code> Char* StrNCopy (Char*&nbsp;dst, const&nbsp;Char*&nbsp;src, Int16&nbsp;n) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> dst </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Destination string. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> src </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Source string. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> n </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Maximum number of bytes to copy from  <code> src </code>  string. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns nothing. 
    =><h4> Comments  </h4>
    =>On systems with multi-byte character encodings, this function makes sure that it does not copy part of a multi-byte character. If the  <code> n </code> th byte of  <code> src </code>  contains the high-order or middle byte of a multi-byte character,  <code> StrNCopy </code>  backs up in  <code> dst </code>  until the byte after the end of the previous character, and replaces the remaining bytes (up to  <code> n </code> -1) with nulls. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  2.0 New Feature Set  is present.  <br> <br> <br> <h3>
StrPrintF()
    =><h4> Purpose  </h4>
    =>Implements a subset of the ANSI C  <code> sprintf </code>  call, which writes formatted output to a string. 
    =><h4> Prototype  </h4>
    =><code> Int16 StrPrintF (Char*&nbsp;s,  <br> const&nbsp;Char*&nbsp;formatStr, ...) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> s </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to a string where the results are written. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> formatStr </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the format specification string. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> ... </code> <br> </td>
    =><td valign="top" align="left" width=""> Zero or more arguments to be formatted as specified by  <code> formatStr </code> . <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Number of characters written to destination string. Returns a negative number if there is an error. 
    =><h4> Comments  </h4>
    =>This function internally calls  StrVPrintF  to do the formatting. See that function for details on which format specifications are supported. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  2.0 New Feature Set  is present. 
    =><h4> See Also  </h4>
    =>StrVPrintF <br> <br> <br> <h3>
StrStr()
    =><h4> Purpose  </h4>
    =>Look for a substring within a string. 
    =><h4> Prototype  </h4>
    =><code> Char* StrStr (const&nbsp;Char*&nbsp;str, const&nbsp;Char*&nbsp;token) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> str </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> String to search. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> token </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> String to search for. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns a pointer to the first occurrence of  <code> token </code>  in  <code> str </code>  or  <code> NULL </code>  if not found. 
    =><h4> Comments  </h4>
    =>Use this function instead of the standard  <code> strstr </code>  routine.  On systems with multi-byte character encodings, this function makes sure that it does not match only part of a multi-byte character. If the matching strings begins at an inter-character boundary, then this function returns  <code> NULL </code> . 
    =><h4> See Also  </h4>
    =>StrChr <br> <br> <br> <h3>
StrToLower()
    =><h4> Purpose  </h4>
    =>Convert all the characters in a string to lowercase. 
    =><h4> Prototype  </h4>
    =><code> Char* StrToLower (Char*&nbsp;dst, const&nbsp;Char*&nbsp;src) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> dst </code> ,  <code> src </code> <br> </code> </td>
    =><td valign="top" align="left" width=""> Two string pointers. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns a pointer to the destination string. 
    =><h4> Compatibility  </h4>
    =>Prior to Palm OS version 3.5, this function only converted accented characters on Japanese devices. On Palm OS version 3.5 and higher, all characters are appropriately lowercased, including accented characters on Latin devices.  <br> <br> <br> <h3>
StrVPrintF()
    =><h4> Purpose  </h4>
    =>Implements a subset of the ANSI C  <code> vsprintf </code>  call, which writes formatted output to a string. 
    =><h4> Prototype  </h4>
    =><code> Int16 StrVPrintF (Char*&nbsp;s, const&nbsp;Char*&nbsp;formatStr, _Palm_va_list&nbsp;argParam) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> s </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to a string where the results are written. This string is always terminated by a null terminator. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> formatStr </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the format specification string. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> argParam </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to a list of zero or more parameters to be formatted as specified by the  <code> formatStr </code>  string. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Number of characters written to destination string, not including the null terminator. Returns a negative number if there is an error. 
    =><h4> Comments  </h4>
    =>Like the C  <code> vsprintf </code>  function, this function is designed to be called by your own function that takes a variable number of arguments and passes them to this function. For details on how to use it, see  "Using the StrVPrintF Function"  in  <em> Palm OS Programmer's Companion </em> , or refer to  <code> vsprintf </code>  in a standard C reference book.  Currently, only the conversion specifications  <code> %d </code> ,  <code> %i </code> ,  <code> %u </code> ,  <code> %x </code> ,  <code> %s </code> , and  <code> %c </code>  are implemented by  <code> StrVPrintF </code>  (and related functions). Optional modifiers that are supported include:  <code> + </code> ,  <code> - </code> , &lt;space&gt;,  <code> * </code> , &lt;digits&gt;,  <code> h </code>  and  <code> l </code>  (long). Following is a brief description of how these format specifications work (see a C book for more details).  Each conversion specification begins with the % character. Following the % character, there may be one or more of the characters list in  Table 44.1 , in sequence.  <p> </p> <p> <div>
    =><table border="3"> <caption> <b>
    =><h4> Table 44.1 StrVPrintF Format Specification&nbsp; </h4>
    =></b> </caption> <tbody> <tr> <th> <strong> Character </strong> </th> <th colspan="2"> <strong> Description </strong> </th> </tr> <tr>
    =><td> <code> + </code> </td>
    =><td colspan="2"> Specifies that a sign always be placed before a number produced by a signed conversion. A + overrides a space if both are used. Example:  <code> StrPrintF(s,"%+d %+d",4,-5); </code> Output to  <code> s </code> :  <code> +4 -5 </code> </td> </tr> <tr>
    =><td> <code> - </code> </td>
    =><td colspan="2"> Specifies that the printed value is left justified within the field width allowed for it. Example:  <code> StrPrintF(s,"%5d%-5d%d",6,9,8); </code> Output to  <code> s </code> :  <code> 69 8 </code> </td> </tr> <tr>
    =><td> &lt;space&gt;  </td>
    =><td colspan="2"> Specifies that a minus sign always be placed before a negative number and a space before a positive number. Example:  <code> StrPrintF(s,"%&nbsp;d %&nbsp;d",4,-5); </code> Output to  <code> s </code> :  <code> 4 -5 </code> </td> </tr> <tr>
    =><td> <code> * </code> </td>
    =><td colspan="2"> Indicates that the next argument (must be an integer) in the list specifies the field width. In this case, the argument following that one is used for the value of this field. Example:  <code> StrPrintF(s,"%*d%d",4,8,5); </code> Output to  <code> s </code> :  <code> 8 5 </code> </td> </tr> <tr>
    =><td> &lt;number&gt;  </td>
    =><td colspan="2"> Specifies a minimum field width. If the converted value has fewer characters than the field width, it will be padded with spaces on the left (or right, if the left justified flag is also specified) to fill out the field width. Example:  <code> StrPrintF(s,"%d%5d",4,3); </code> Output to  <code> s </code> :  <code> 4 3 </code> </td> </tr> <tr>
    =><td> <code> h </code> </td>
    =><td colspan="2"> Specifies that the following d, i, u, or x conversion corresponds to a  <code> short </code>  or  <code> unsigned short </code>  argument. Example:  <code> StrPrintF(s,"%hd",401); </code> Output to  <code> s </code> :  <code> 401 </code> </td> </tr> <tr>
    =><td> <code> l </code>  or  <code> L </code> </td>
    =><td colspan="2"> Specifies that the following d, i, u, or x conversion corresponds to a  <code> long </code>  or  <code> unsigned long </code> <code> StrPrintF(s,"%ld",999999999); </code> Output to  <code> s </code> :  <code> 999999999 </code> </td> </tr> <tr>
    =><td> &lt;character&gt;  </td>
    =><td colspan="2"> A character that indicates the type of conversion to be performed. The supported conversion characters include:  </td> </tr> <tr>
    =><td> </td>
    =><td> <code> d </code> or  <code> i </code> </td>
    =><td> A signed integer argument is converted to decimal notation. Example:  <code> StrPrintF(s,"%d %d",4,-4); </code> Output to  <code> s </code> :  <code> 4 -4 </code> </td> </tr> <tr>
    =><td> </td>
    =><td> <code> u </code> </td>
    =><td> An unsigned integer argument is converted to decimal notation. Example:  <code> StrPrintF(s,"%u %u",4,-4); </code> Output to  <code> s </code> :  <code> 4 65532 </code> </td> </tr> <tr>
    =><td> </td>
    =><td> <code> x </code> </td>
    =><td> An integer argument is converted to hexadecimal notation. Example:  <code> StrPrintF(s,"%x",125); </code> Output to  <code> s </code> :  <code> 0000007D </code> </td> </tr> <tr>
    =><td> </td>
    =><td> <code> s </code> </td>
    =><td> A string ( <code> char * </code> ) argument is copied to the destination string. Example:  <code> StrPrintF(s,"ABC%s","DEF"); </code> Output to  <code> s </code> :  <code> ABCDEF </code> </td> </tr> <tr>
    =><td> </td>
    =><td> <code> c </code> </td>
    =><td> A single character ( <code> int </code> ) argument is copied to the destination string. Example:  <code> StrPrintF(s,"Telephone%c",'s'); </code> Output to  <code> s </code> :  <code> Telephones </code> </td> </tr> <tr>
    =><td> </td>
    =><td> <code> % </code> </td>
    =><td> A % character is copied to the destination string. Example:  <code> StrPrintF(s,"%%"); </code> Output to  <code> s </code> :  <code> % </code> </td> </tr> </tbody> </table>
    =><table> <tbody> <tr>
    =><td> <br> </td> </tr> </tbody> </table> </div> </p>
    =><h4> Example  </h4>
    =>Here's an example of how to use this call:  <br> <code> #include &lt;stdarg.h&gt; </code> <br> <code> void MyPrintF(Char* s, Char* formatStr, ...)  <br> { </code> <br> <code> &nbsp;&nbsp;&nbsp; va_list args; <br> Char text[0x100]; </code> <br> <code> &nbsp;&nbsp;&nbsp; va_start(args, formatStr); <br> StrVPrintF(text, formatStr, args); <br> va_end(args); </code> <br> <code> &nbsp;&nbsp;&nbsp; MyPutS(text);  <br> } </code> <br>
    =><h4> Compatibility  </h4>
    =>Implemented only if  2.0 New Feature Set  is present. 
    =><h4> See Also  </h4>
    =>StrPrintF ,  Using the StrVPrintF Function <strong> </strong> <br> <h3>
TxtByteAttr()
    =><h4> Purpose  </h4>
    =>Return the possible locations of a given byte within a multi-byte character. 
    =><h4> Prototype  </h4>
    =><code> UInt8 TxtByteAttr (UInt8&nbsp;inByte) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inByte </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A byte representing all or part of a valid character. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns a byte with one or more of the following bits set:  <p> </p> <p> <div>
    =><table border="3"> <caption> <br> </caption> <tbody> <tr> <th> <p> <code> byteAttrFirst </code> </p> </th> <th> <p> First byte of multi-byte character.  </p> </th> </tr> <tr>
    =><td> <p> <code> byteAttrLast </code> </p> </td>
    =><td> <p> Last byte of multi-byte character.  </p> </td> </tr> <tr>
    =><td> <p> <code> byteAttrMiddle </code> </p> </td>
    =><td> <p> Middle byte of multi-byte character.  </p> </td> </tr> <tr>
    =><td> <p> <code> byteAttrSingle </code> </p> </td>
    =><td> <p> Single-byte character.  </p> </td> </tr> </tbody> </table>
    =><table> <tbody> <tr>
    =><td> <br> </td> </tr> </tbody> </table> </div> </p>
    =><h4> Comments  </h4>
    =>If  <code> inByte </code>  is valid in more than one location of a character, multiple return bits are set. For example, 0x40 in the Shift JIS character encoding is valid as a single-byte character and as the low-order byte of a double-byte character. Thus, the return value for  <code> TxtByteAttr(0x40) </code>  on a Shift JIS system has both the  <code> byteAttrSingle </code>  and  <code> byteAttrLast </code>  bits set.  Text manager functions that need to determine the byte positioning of a character use  <code> TxtByteAttr </code>  to do so. You rarely need to use this function yourself. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present.  <br> <br> <br> <h3>
TxtCaselessCompare()
    =><h4> Purpose  </h4>
    =>Perform a case-insensitive comparison of two text buffers. 
    =><h4> Prototype  </h4>
    =><code> Int16 TxtCaselessCompare (const&nbsp;Char*&nbsp;s1, UInt16&nbsp;s1Len, UInt16*&nbsp;s1MatchLen, const&nbsp;Char*&nbsp;s2, UInt16&nbsp;s2Len, UInt16*&nbsp;s2MatchLen) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; s1 </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the first text buffer to compare. Must not be  <code> NULL </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; s1Len </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Length in bytes of the text pointed to by  <code> s1 </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> &lt;- s1MatchLen </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Points to the length in bytes of the text in  <code> s1 </code>  that matched text in  <code> s2 </code> . Pass  <code> NULL </code>  for this parameter if you don't need to know this number.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; s2 </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the second text buffer to compare. Must not be  <code> NULL </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; s2Len </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Length in bytes of the text pointed to by  <code> s2 </code> . <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> &lt;- s2MatchLen </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Points to the length in bytes of the text in  <code> s2 </code>  that matched text in  <code> s1 </code> . Pass  <code> NULL </code>  for this parameter if you don't need to know this number.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns one of the following values:  <p> </p> <p> <div>
    =><table border="3"> <caption> <br> </caption> <tbody> <tr>
    =><td> &lt; 0  </td>
    =><td> If  <code> s1 </code>  occurs before  <code> s2 </code>  in alphabetical order.  </td> </tr> <tr>
    =><td> &gt; 0  </td>
    =><td> If  <code> s1 </code>  occurs after  <code> s2 </code>  in alphabetical order.  </td> </tr> <tr>
    =><td> 0  </td>
    =><td> If the two substrings that were compared are equal.  </td> </tr> </tbody> </table>
    =><table> <tbody> <tr>
    =><td> <br> </td> </tr> </tbody> </table> </div> </p>
    =><h4> Comments  </h4>
    =>In certain character encodings (such as Shift JIS), one character may be accurately represented as either a single-byte character or a multi-byte character.  <code> TxtCaselessCompare </code>  accurately matches a single-byte character with its multi-byte equivalent. For this reason, the values returned in  <code> s1MatchLen </code>  and  <code> s2MatchLen </code>  are not always equal.  You must make sure that the parameters  <code> s1 </code>  and  <code> s2 </code>  point to a the start of a valid character. That is, they must point to the first byte of a multi-byte character or they must point to a single-byte character. If they don't, results are unpredictable. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present. 
    =><h4> See Also  </h4>
    =>StrCaselessCompare ,  TxtCompare ,  StrCompare <br> <br> <br> <h3>
TxtCharAttr()
    =><h4> Purpose  </h4>
    =>Return a character's attributes. 
    =><h4> Prototype  </h4>
    =><code> UInt16 TxtCharAttr (WChar&nbsp;inChar) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inChar </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Any valid character.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns a 16-bit unsigned value with any of the following bits set:  <p> </p> <p> <div>
    =><table border="3"> <caption> <br> </caption> <tbody> <tr> <th> <p> <code> charAttrPrint </code> </p> </th> <th> <p> Printable  </p> </th> </tr> <tr>
    =><td> <p> <code> charAttrSpace </code> </p> </td>
    =><td> <p> Blank space, tab, or newline  </p> </td> </tr> <tr>
    =><td> <p> <code> charAttrAlNum </code> </p> </td>
    =><td> <p> Alphanumeric  </p> </td> </tr> <tr>
    =><td> <p> <code> charAttrAlpha </code> </p> </td>
    =><td> <p> Alphabetic  </p> </td> </tr> <tr>
    =><td> <p> <code> charAttrCntrl </code> </p> </td>
    =><td> <p> Control character  </p> </td> </tr> <tr>
    =><td> <p> <code> charAttrGraph </code> </p> </td>
    =><td> <p> Character that appears on the screen; that is, is not whitespace, a control character, or a virtual character.  </p> </td> </tr> <tr>
    =><td> <p> <code> charAttrDelim </code> </p> </td>
    =><td> <p> Word delimiter (whitespace or punctuation).  </p> </td> </tr> </tbody> </table>
    =><table> <tbody> <tr>
    =><td> <br> </td> </tr> </tbody> </table> </div> </p>
    =><h4> Comments  </h4>
    =>The character passed to this function must be a valid character given the system encoding.  This function is used in the text manager's character attribute macros ( TxtCharIsAlNum ,  TxtCharIsCntrl , and so on). The macros perform operations analogous to the standard C functions  <code> isPunct </code> ,  <code> isPrintable </code> , and so on. Usually, you'd use one of these macros instead of calling  <code> TxtCharAttr </code>  directly.  To obtain attributes specific to a given character encoding, use  TxtCharXAttr . 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present. 
    =><h4> See Also  </h4>
    =>TxtCharIsValid <br> <br> <br> <h3>
TxtCharBounds()
    =><h4> Purpose  </h4>
    =>Return the boundaries of a character containing the byte at a specified offset in a string. 
    =><h4> Prototype  </h4>
    =><code> WChar TxtCharBounds (const&nbsp;Char*&nbsp;inText, UInt32&nbsp;inOffset, UInt32*&nbsp;outStart, UInt32*&nbsp;outEnd) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inText </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the text buffer to search. Must not be  <code> NULL </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inOffset </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A valid offset into the buffer  <code> inText </code> . This location may contain a byte in any position (start, middle, or end) of a multi-byte character. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> &lt;- outStart </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Points to the starting offset of the character containing the byte at  <code> inOffset </code> . <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> &lt;- outEnd </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Points to the ending offset of the character containing the byte at  <code> inOffset </code> . <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the character located between the offsets  <code> outStart </code>  and  <code> outEnd </code> . 
    =><h4> Comments  </h4>
    =>Use this function to determine the boundaries of a character in a string or text buffer.  If the byte at  <code> inOffset </code>  is valid in more than one location of a character, the function must search back toward the beginning of the text buffer until it finds an unambiguous byte to determine the appropriate boundaries. For this reason,  <code> TxtCharBounds </code>  is often slow and should be used only where needed.  You must make sure that the parameter  <code> inText </code>  points to the beginning of the string. That is, if the string begins with a multi-byte character,  <code> inText </code>  must point to the first byte of that character. If it doesn't, results are unpredictable. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present.  <br> <br> <br> <h3>
TxtCharEncoding()
    =><h4> Purpose  </h4>
    =>Return the minimum encoding required to represent a character. 
    =><h4> Prototype  </h4>
    =><code> CharEncodingType TxtCharEncoding (WChar&nbsp;inChar) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inChar </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A valid character.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>A  CharEncodingType  value that indicates the minimum encoding required to represent  <code> inChar </code> . If the character isn't recognizable,  <code> charEncodingUnknown </code>  is returned. 
    =><h4> Comments  </h4>
    =>The minimum encoding is the encoding that takes the lowest number of bytes to represent the character. For example, if the character is a blank or a tab character, the minimum encoding is  <code> charEncodingAscii </code>  because these characters can be represented in single-byte ASCII. If the character is a &uuml;, the minimum encoding is  <code> charEncodingISO8859_1 </code> .  Because Palm OS <sup> &reg; </sup>  only supports a single character encoding at a time, the result of this function is always logically equal to or less than the encoding used on the current system. That is, you'll only receive a return value of  <code> charEncodingISO8859_1 </code>  if you're running on a US or European system and you pass a non-ASCII character.  Use this function for informational purposes only. Your code should not assume that the character encoding returned by this function is the Palm OS system character encoding. (Instead use  <code> FtrGet </code>  as shown in the  TxtCharXAttr  function description.)  Use  TxtMaxEncoding  to determine the order of encodings. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present. 
    =><h4> See Also  </h4>
    =>TxtStrEncoding ,  TxtMaxEncoding <br> <br> <br> <h3>
TxtCharIsAlNum()
    =><h4> Purpose  </h4>
    =>Macro that indicates if the character is alphanumeric. 
    =><h4> Prototype  </h4>
    =><code> TxtCharIsAlNum (ch) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; ch </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A valid character. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns  <code> true </code>  if the character is a letter in an alphabet or a numeric digit,  <code> false </code>  otherwise. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present. 
    =><h4> See Also  </h4>
    =>TxtCharIsDigit ,  TxtCharIsAlpha <br> <br> <br> <h3>
TxtCharIsAlpha()
    =><h4> Purpose  </h4>
    =>Macro that indicates if a character is a letter in an alphabet. 
    =><h4> Prototype  </h4>
    =><code> TxtCharIsAlpha (ch) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; ch </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A valid character. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns  <code> true </code>  if the character is a letter in an alphabet,  <code> false </code>  otherwise. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present. 
    =><h4> See Also  </h4>
    =>TxtCharIsAlNum ,  TxtCharIsLower ,  TxtCharIsUpper <br> <br> <br> <h3>
TxtCharIsCntrl()
    =><h4> Purpose  </h4>
    =>Macro that indicates if a character is a control character. 
    =><h4> Prototype  </h4>
    =><code> TxtCharIsCntrl (ch) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; ch </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A valid character. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns  <code> true </code>  if the character is a non-printable character, such as the bell character or a carriage return;  <code> false </code>  otherwise. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present.  <br> <br> <br> <h3>
TxtCharIsDelim()
    =><h4> Purpose  </h4>
    =>Macro that indicates if a character is a delimiter. 
    =><h4> Prototype  </h4>
    =><code> TxtCharIsDelim (ch) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; ch </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A valid character. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns  <code> true </code>  if the character is a word delimiter (whitespace or punctuation),  <code> false </code>  otherwise. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present.  <br> <br> <br> <h3>
TxtCharIsDigit()
    =><h4> Purpose  </h4>
    =>Macro that indicates if the character is a decimal digit. 
    =><h4> Prototype  </h4>
    =><code> TxtCharIsDigit (ch) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; ch </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A valid character. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns  <code> true </code>  if the character is 0 through 9,  <code> false </code>  otherwise. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present. 
    =><h4> See Also  </h4>
    =>TxtCharIsAlNum ,  TxtCharIsHex <br> <br> <br> <h3>
TxtCharIsGraph()
    =><h4> Purpose  </h4>
    =>Macro that indicates if a character is a graphic character. 
    =><h4> Prototype  </h4>
    =><code> TxtCharIsGraph (ch) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; ch </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A valid character. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns  <code> true </code>  if the character is a graphic character, false otherwise. 
    =><h4> Comments  </h4>
    =>A graphic character is any character visible on the screen, in other words, letters, digits, and punctuation marks. A blank space is not a graphic character because it is not visible. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present. 
    =><h4> See Also  </h4>
    =>TxtCharIsPrint <br> <br> <br> <h3>
TxtCharIsHardKey()
    =><h4> Purpose  </h4>
    =>Macro that returns true if the character is one of the hard keys on the device. 
    =><h4> Prototype  </h4>
    =><code> TxtCharIsHardKey (m, ch) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> m </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The modifier keys from the  keyDownEvent . <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> ch </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The character from the  <code> keyDownEvent </code> . <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =><code> true </code>  if the character is one of the four built-in hard keys on the device,  <code> false </code>  otherwise. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present. 
    =><h4> See Also  </h4>
    =>ChrIsHardKey <br> <br> <br> <h3>
TxtCharIsHex()
    =><h4> Purpose  </h4>
    =>Macro that indicates if a character is a hexadecimal digit. 
    =><h4> Prototype  </h4>
    =><code> TxtCharIsHex (ch) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; ch </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A valid character. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns  <code> true </code>  if the character is a hexadecimal digit from 0 to F,  <code> false </code>  otherwise. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present. 
    =><h4> See Also  </h4>
    =>TxtCharIsDigit <br> <br> <br> <h3>
TxtCharIsLower()
    =><h4> Purpose  </h4>
    =>Macro that indicates if a character is a lowercase letter. 
    =><h4> Prototype  </h4>
    =><code> TxtCharIsLower (ch) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; ch </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A valid character. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns  <code> true </code>  if the character is a lowercase letter,  <code> false </code>  otherwise. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present. 
    =><h4> See Also  </h4>
    =>TxtCharIsAlpha ,  TxtCharIsUpper <br> <br> <br> <h3>
TxtCharIsPrint()
    =><h4> Purpose  </h4>
    =>Macro that indicates if a character is printable. 
    =><h4> Prototype  </h4>
    =><code> TxtCharIsPrint (ch) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; ch </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A valid character. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns  <code> true </code>  if the character is not a control or virtual character,  <code> false </code>  otherwise. 
    =><h4> Comments  </h4>
    =>This function differs from  TxtCharIsGraph  in that it returns  <code> true </code>  if the character is whitespace.  <code> TxtCharIsGraph </code>  returns  <code> false </code>  if the character is whitespace. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present. 
    =><h4> See Also  </h4>
    =>TxtCharIsValid <br> <br> <br> <h3>
TxtCharIsPunct()
    =><h4> Purpose  </h4>
    =>Macro that indicates if a character is a punctuation mark. 
    =><h4> Prototype  </h4>
    =><code> TxtCharIsPunct (ch) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; ch </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A valid character. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns  <code> true </code>  if the character is a punctuation mark,  <code> false </code>  otherwise. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present.  <br> <br> <br> <h3>
TxtCharIsSpace()
    =><h4> Purpose  </h4>
    =>Macro that indicates if a character is a whitespace character. 
    =><h4> Prototype  </h4>
    =><code> TxtCharIsSpace (ch) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; ch </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A valid character. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns  <code> true </code>  if the character is whitespace such as a blank space, tab, or newline;  <code> false </code>  otherwise. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present.  <br> <br> <br> <h3>
TxtCharIsUpper()
    =><h4> Purpose  </h4>
    =>Macro that indicates if a character is an uppercase letter. 
    =><h4> Prototype  </h4>
    =><code> TxtCharIsUpper (ch) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; ch </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A valid character. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns  <code> true </code>  if the character is an uppercase letter,  <code> false </code>  otherwise. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present. 
    =><h4> See Also  </h4>
    =>TxtCharIsAlpha ,  TxtCharIsLower <br> <br> <br> <h3>
TxtCharIsValid()
    =><h4> Purpose  </h4>
    =>Determine whether a character is valid character given the Palm OS character encoding. 
    =><h4> Prototype  </h4>
    =><code> Boolean TxtCharIsValid (WChar&nbsp;inChar) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inChar </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A character.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns  <code> true </code>  if  <code> inChar </code>  is a valid character;  <code> false </code>  if  <code> inChar </code>  is not a valid character. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present. 
    =><h4> See Also  </h4>
    =>TxtCharAttr ,  TxtCharIsPrint <br> <br> <br> <h3>
TxtCharSize()
    =><h4> Purpose  </h4>
    =>Return the number of bytes required to store the character in a string. 
    =><h4> Prototype  </h4>
    =><code> UInt16 TxtCharSize (WChar&nbsp;inChar) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inChar </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A valid character.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>The the number of bytes required to store the character in a string. 
    =><h4> Comments  </h4>
    =>Outside of strings, characters are always two-byte long  <code> WChar </code>  values; however, strings may store characters as a single-byte value. If the character can be represented by a single byte (its high-order byte is 0), it is stored in a string as a single-byte character. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present. 
    =><h4> See Also  </h4>
    =>TxtCharBounds <br> <br> <br> <h3>
TxtCharWidth()
    =><h4> Purpose  </h4>
    =>Return the width required to display the specified character in the current font. If the specified character does not exist within the current font, the missing character symbol is substituted. 
    =><h4> Prototype  </h4>
    =><code> Int16 TxtCharWidth (WChar&nbsp;inChar) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inChar </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A valid character. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the width of the specified character (in pixels). 
    =><h4> Comments  </h4>
    =>Use this function instead of  FntCharWidth  to determine the width of a single-byte or multi-byte character. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present.  <br> <br> <br> <h3>
TxtCharXAttr()
    =><h4> Purpose  </h4>
    =>Return the extended attribute bits for a character. 
    =><h4> Prototype  </h4>
    =><code> UInt16 TxtCharXAttr (WChar inChar) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inChar </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A valid character. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns an unsigned 16-bit value with one or more extended attribute bits set. For specific return values, look in the header files that are specific to certain character encodings ( <code> CharLatin.h </code>  or  <code> CharShiftJIS.h </code> ). 
    =><h4> Comments  </h4>
    =>To interpret the results, you must know the character encoding being used. Use  FtrGet  with  <code> sysFtrNumEncoding </code>  as the feature number to determine the character encoding. This returns one of the  CharEncodingType  values. For example:  <br> <code> WChar ch; <br> UInt16 encoding, attr;  <br> ... <br> attr = TxtCharXAttr(ch); <br> if (FtrGet(sysFtrCreator, sysFtrNumEncoding,  <br> &amp;encoding) != 0) <br> encoding = charEncodingCP1252;; <br> if (encoding == charEncodingUTF8) { <br> } </code> <br>
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present. 
    =><h4> See Also  </h4>
    =>TxtCharAttr <br> <br> <br> <h3>
TxtCompare()
    =><h4> Purpose  </h4>
    =>Performs a case-sensitive comparison of all or part of two text buffers. 
    =><h4> Prototype  </h4>
    =><code> Int16 TxtCompare (const&nbsp;Char*&nbsp;s1, UInt16&nbsp;s1Len, UInt16*&nbsp;s1MatchLen, const&nbsp;Char*&nbsp;s2, UInt16&nbsp;s2Len, UInt16*&nbsp;s2MatchLen) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; s1 </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the first text buffer to compare. Must not be  <code> NULL </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; s1Len </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The length in bytes of the text pointed to by  <code> s1 </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> &lt;- s1MatchLen </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Points to the length in bytes of the text in  <code> s1 </code>  that matched text in  <code> s2 </code> . Pass  <code> NULL </code>  for this parameter if you don't need to know this number.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; s2 </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the second text buffer to compare. Must not be  <code> NULL </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; s2Len </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The length in bytes of the text pointed to by  <code> s2 </code> . <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> &lt;- s2MatchLen </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Points to the length in bytes of the text in  <code> s2 </code>  that matched text in  <code> s1 </code> . Pass  <code> NULL </code>  for this parameter if you don't need to know this number.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns one of the following values:  <p> </p> <p> <div>
    =><table border="3"> <caption> <br> </caption> <tbody> <tr>
    =><td> &lt; 0  </td>
    =><td> If  <code> s1 </code>  occurs before  <code> s2 </code>  in alphabetical order.  </td> </tr> <tr>
    =><td> &gt; 0  </td>
    =><td> If  <code> s1 </code>  occurs after  <code> s2 </code>  in alphabetical order.  </td> </tr> <tr>
    =><td> 0  </td>
    =><td> If the two substrings that were compared are equal.  </td> </tr> </tbody> </table>
    =><table> <tbody> <tr>
    =><td> <br> </td> </tr> </tbody> </table> </div> </p>
    =><h4> Comments  </h4>
    =>In certain character encodings (such as Shift JIS), one character may be accurately represented as either a single-byte character or a multi-byte character.  <code> TxtCompare </code>  accurately matches a single-byte character with its multi-byte equivalent. For this reason, the values returned in  <code> s1MatchLen </code>  and  <code> s2MatchLen </code>  are not always equal.  This function performs a case-sensitive comparison. If you want to perform a case-insensitive comparison, use  TxtCaselessCompare .  You must make sure that the parameters  <code> s1 </code>  and  <code> s2 </code>  point to the start of a a valid character. That is, they must point to the first byte of a multi-byte character or they must point to a single-byte character. If they don't, results are unpredictable. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present. 
    =><h4> See Also  </h4>
    =>StrCompare ,  TxtFindString <br> <br> <br> <h3>
TxtEncodingName()
    =><h4> Purpose  </h4>
    =>Obtain a character encoding's name. 
    =><h4> Prototype  </h4>
    =><code> const&nbsp;Char* TxtEncodingName (CharEncodingType&nbsp;inEncoding) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inEncoding </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> One of the values from  CharEncodingType , indicating a character encoding.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>A constant string containing the name of the encoding.  <p> </p> <p> <div>
    =><table border="3"> <caption> <br> </caption> <tbody> <tr>
    =><td> <p> <code> encodingNameAscii </code> </p> </td>
    =><td> <p> us ascii  </p> </td> </tr> <tr>
    =><td> <p> <code> encodingNameISO8859_1 </code> </p> </td>
    =><td> <p> ISO-8859-1  </p> </td> </tr> <tr>
    =><td> <p> <code> encodingNameCP1252 </code> </p> </td>
    =><td> <p> ISO-8859-1-Windows-3.1-Latin-1  </p> </td> </tr> <tr>
    =><td> <p> <code> encodingNameShiftJIS </code> </p> </td>
    =><td> <p> Shift_JIS  </p> </td> </tr> <tr>
    =><td> <p> <code> encodingNameCP932 </code> </p> </td>
    =><td> <p> Windows-31J  </p> </td> </tr> <tr>
    =><td> <p> <code> encodingNameUTF8 </code> </p> </td>
    =><td> <p> UTF-8  </p> </td> </tr> <tr>
    =><td> <p> <code> "" </code> </p> </td>
    =><td> <p> The encoding is not known  </p> </td> </tr> </tbody> </table>
    =><table> <tbody> <tr>
    =><td> <br> </td> </tr> </tbody> </table> </div> </p>
    =><h4> Comments  </h4>
    =>Use this function to obtain the official name of the character encoding, suitable to pass to an Internet application or any other application that requires the character encoding's name to be passed along with the data. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present. 
    =><h4> See Also  </h4>
    =>CharEncodingType <br> <br> <br> <h3>
TxtFindString()
    =><h4> Purpose  </h4>
    =>Perform a case-insensitive search for a string in another string. 
    =><h4> Prototype  </h4>
    =><code> Boolean TxtFindString (const&nbsp;Char*&nbsp;inSourceStr, const&nbsp;Char*&nbsp;inTargetStr, UInt32*&nbsp;outPos, UInt16*&nbsp;outLength) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inSourceStr </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the string to be searched. Must not be  <code> NULL </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inTargetStr </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Prepared version of the string to be found.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> &lt;- outPos </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the offset of the match in  <code> inSourceStr </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> &lt;- outLength </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the length in bytes of the matching text.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns  <code> true </code>  if the function finds  <code> inTargetStr </code>  within  <code> inSourceStr </code> ;  <code> false </code>  otherwise.  If found, the values pointed to by the  <code> outPos </code>  and  <code> outLength </code>  parameters are set to the starting offset and the length of the matching text. If not found, the values pointed to by  <code> outPos </code>  and  <code> outLength </code>  are set to 0. 
    =><h4> Comments  </h4>
    =>Use this function instead of  FindStrInStr  to support the global system find facility. This function contains an extra parameter,  <code> outLength </code> , to specify the length of the text that matched. Pass this value to  FindSaveMatch  in the  <code> appCustom </code>  parameter. Then when your application receives  <code> sysAppLaunchCmdGoTo </code> , the  <code> matchCustom </code>  field contains the length of the matching text. You use the length of matching text to highlight the match within the selected record.  You must make sure that the parameters  <code> inSourceStr </code>  and  <code> inTargetStr </code>  point to the start of a valid character. That is, they must point to the first byte of a multi-byte character, or they must point to a single-byte character. If they don't, results are unpredictable. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present. 
    =><h4> See Also  </h4>
    =>TxtCaselessCompare <br> <br> <br> <h3>
TxtGetChar()
    =><h4> Purpose  </h4>
    =>Retrieve the character starting at the specified offset within a text buffer. 
    =><h4> Prototype  </h4>
    =><code> WChar TxtGetChar (const&nbsp;Char*&nbsp;inText, UInt32&nbsp;inOffset) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inText </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the text buffer to be searched. Must not be  <code> NULL </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inOffset </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A valid offset into the buffer  <code> inText </code> . This offset must point to an inter-character boundary.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the character at  <code> inOffset </code>  in  <code> inText </code> . 
    =><h4> Comments  </h4>
    =>You must make sure that the parameter  <code> inText </code>  points to the start of a valid character. That is, it must point to the first byte of a multi-byte character or it must point to a single-byte character. If it doesn't, results are unpredictable. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present. 
    =><h4> See Also  </h4>
    =>TxtGetNextChar ,  TxtSetNextChar <br> <br> <br> <h3>
TxtGetNextChar()
    =><h4> Purpose  </h4>
    =>Retrieve the character starting at the specified offset within a text buffer. 
    =><h4> Prototype  </h4>
    =><code> UInt16 TxtGetNextChar (const&nbsp;Char*&nbsp;inText, UInt32&nbsp;inOffset, WChar*&nbsp;outChar) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inText </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the text buffer to be searched. Must not be  <code> NULL </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inOffset </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A valid offset into the buffer  <code> inText </code> . This offset must point to an inter-character boundary.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> &lt;- outChar </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The character at  <code> inOffset </code>  in  <code> inText </code> . Pass  <code> NULL </code>  for this parameter if you don't need the character returned.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the size in bytes of the character at  <code> inOffset </code> . If  <code> outChar </code>  is not  <code> NULL </code>  upon entry, it points to the character at  <code> inOffset </code>  upon return. 
    =><h4> Comments  </h4>
    =>You can use this function to iterate through a text buffer character-by-character in this way:  <br> <code> UInt16 i = 0; <br> while (i &lt; bufferLength) { <br> i += TxtGetNextChar(buffer, i, &amp;ch); <br> //do something with ch. <br> } </code> <br> You must make sure that the parameter  <code> inText </code>  points to the start of a valid character. That is, it must point to the first byte of a multi-byte character or it must point to a single-byte character. If it doesn't, results are unpredictable. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present. 
    =><h4> See Also  </h4>
    =>TxtGetChar ,  TxtGetPreviousChar ,  TxtSetNextChar <br> <br> <br> <h3>
TxtGetPreviousChar()
    =><h4> Purpose  </h4>
    =>Retrieve the character before the specified offset within a text buffer. 
    =><h4> Prototype  </h4>
    =><code> UInt16 TxtGetPreviousChar (const&nbsp;Char*&nbsp;inText, UInt32&nbsp;inOffset, WChar*&nbsp;outChar) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inText </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the text buffer to be searched. Must not be  <code> NULL </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inOffset </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A valid offset into the buffer  <code> inText </code> . This offset must point to an inter-character boundary.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> &lt;- outChar </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The character immediately preceding  <code> inOffset </code>  in  <code> inText </code> . Pass  <code> NULL </code>  for this parameter if you don't need the character returned.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the size in bytes of the character preceding  <code> inOffset </code>  in  <code> inText </code> . If  <code> outChar </code>  is not  <code> NULL </code>  upon entry, then it points to the character preceding  <code> inOffset </code>  upon return. Returns 0 if  <code> inOffset </code>  is at the start of the buffer (that is,  <code> inOffset </code>  is 0). 
    =><h4> Comments  </h4>
    =>You can use this function to iterate through a text buffer character-by-character in this way:  <br> <code> /* Find the start of the character containing the last byte. */ </code> <br> <code> TxtCharBounds (buffer, bufferLength - 1, &amp;start, &amp;end); </code> <br> <code> i = start; </code> <br> <code> while (i &gt; 0) { </code> <br> <code> &nbsp;&nbsp;&nbsp; i -= TxtGetPreviousChar(buffer, i, &amp;ch); </code> <br> <code> &nbsp;&nbsp;&nbsp; //do something with ch. </code> <br> <code> } </code> <br> This function is often slower to use than  TxtGetNextChar  because it must determine the appropriate character boundaries if the byte immediately before the offset is valid in more than one location (start, middle, or end) of a multi-byte character. To do this, it must work backwards toward the beginning of the string until it finds an unambiguous byte.  You must make sure that the parameter  <code> inText </code>  points to the start of a valid character. That is, it must point to the first byte of a multi-byte character or it must point to a single-byte character. If it doesn't, results are unpredictable. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present.  <br> <br> <br> <h3>
TxtGetTruncationOffset()
    =><h4> Purpose  </h4>
    =>Return the appropriate byte position for truncating a text buffer such that it is at most a specified number of bytes long. 
    =><h4> Prototype  </h4>
    =><code> UInt32 TxtGetTruncationOffset (const&nbsp;Char*&nbsp;inText, UInt32&nbsp;inOffset) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inText </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to a text buffer. Must not be  <code> NULL </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inOffset </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A valid offset into the buffer  <code> inText </code> .  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the appropriate byte offset for truncating  <code> inText </code>  at a valid inter-character boundary. The return value may be less than or equal to  <code> inOffset </code> . 
    =><h4> Comments  </h4>
    =>You must make sure that the parameter  <code> inText </code>  points to the start of a valid character. That is, it must point to the first byte of a multi-byte character or it must point to a single-byte character. If it doesn't, results are unpredictable. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present.  <br> <br> <br> <h3>
TxtMaxEncoding()
    =><h4> Purpose  </h4>
    =>Return the higher of two encodings. 
    =><h4> Prototype  </h4>
    =><code> CharEncodingType TxtMaxEncoding (CharEncodingType&nbsp;a, CharEncodingType&nbsp;b) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; a </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A character encoding to compare.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; b </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Another character encoding to compare.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the higher of  <code> a </code>  or  <code> b </code> . One character encoding is higher than another if it is more specific. For example code page 1252 is "higher" than ISO 8859-1 because it represents more characters than ISO 8859-1. 
    =><h4> Comments  </h4>
    =>This function is used by  TxtStrEncoding  to determine the encoding required for a string. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present. 
    =><h4> See Also  </h4>
    =>TxtCharEncoding ,  CharEncodingType <br> <br> <br> <h3>
TxtNextCharSize()
    =><h4> Purpose  </h4>
    =>Macro that returns the size of the character starting at the specified offset within a text buffer. 
    =><h4> Prototype  </h4>
    =><code> TxtNextCharSize (inText, inOffset) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inText </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the text buffer to be searched. Must not be  <code> NULL </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inOffset </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A valid offset into the buffer  <code> inText </code> . This offset must point to an inter-character boundary.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns (as a  <code> UInt16 </code> ) the size in bytes of the character at  <code> inOffset </code> . 
    =><h4> Comments  </h4>
    =>You must make sure that the parameter  <code> inText </code>  points to the start of a valid character. That is, it must point to the first byte of a multi-byte character or it must point to a single-byte character. If it doesn't, results are unpredictable. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present. 
    =><h4> See Also  </h4>
    =>TxtGetNextChar <br> <br> <br> <h3>
TxtParamString()
    =><h4> Purpose  </h4>
    =>Replace substrings within a string with the specified values. 
    =><h4> Prototype  </h4>
    =><code> Char* TxtParamString (const&nbsp;Char*&nbsp;inTemplate, const&nbsp;Char*&nbsp;param0, const&nbsp;Char*&nbsp;param1, const&nbsp;Char*&nbsp;param2, const&nbsp;Char*&nbsp;param3) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> inTemplate </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The string containing the substrings to replace.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> param0 </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> String to replace ^0 with or  <code> NULL </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> param1 </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> String to replace ^1 with or  <code> NULL </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> param2 </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> String to replace ^2 with or  <code> NULL </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> param3 </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> String to replace ^3 with or  <code> NULL </code> .  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns a locked handle to a newly allocated string in the dynamic heap that contains the appropriate substitutions. 
    =><h4> Comments  </h4>
    =>This function searches  <code> inTemplate </code>  for occurrences of the sequences ^0, ^1, ^2, and ^3. When it finds these, it replaces them with the corresponding string passed to this function. Multiple instances of each sequence will be replaced.  You must make sure that the parameter inTemplate points to the start of a valid character. That is, it must point to the first byte of a multi-byte character or it must point to a single-byte character. If it doesn't, results are unpredictable.  <code> TxtParamString </code>  allocates space for the returned string in the dynamic heap. Your code is responsible for freeing this memory when it is no longer needed. 
    =><h4> Compatibility  </h4>
    =>Implemented if  3.5 New Feature Set  is present. 
    =><h4> See Also  </h4>
    =>TxtReplaceStr ,  FrmCustomAlert <br> <br> <br> <h3>
TxtPreviousCharSize()
    =><h4> Purpose  </h4>
    =>Macro that returns the size of the character before the specified offset within a text buffer. 
    =><h4> Prototype  </h4>
    =><code> TxtPreviousCharSize (inText, inOffset) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inText </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the text buffer. Must not be  <code> NULL </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inOffset </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A valid offset into the buffer  <code> inText </code> . This offset must point to an inter-character boundary.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns (as a  <code> UInt16 </code> ) the size in bytes of the character preceding  <code> inOffset </code>  in  <code> inText </code> . Returns 0 if  <code> inOffset </code>  is at the start of the buffer (that is,  <code> inOffset </code>  is 0). 
    =><h4> Comments  </h4>
    =>You must make sure that the parameter  <code> inText </code>  points to the start of a valid character. That is, it must point to the first byte of a multi-byte character or it must point to a single-byte character. If it doesn't, results are unpredictable. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present. 
    =><h4> See Also  </h4>
    =>TxtGetPreviousChar <br> <br> <br> <h3>
TxtReplaceStr()
    =><h4> Purpose  </h4>
    =>Replace a substring of a given format with another string. 
    =><h4> Prototype  </h4>
    =><code> UInt16 TxtReplaceStr (Char*&nbsp;ioStr, UInt16&nbsp;inMaxLen, const&nbsp;Char*&nbsp;inParamStr, UInt16&nbsp;inParamNum) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> &lt;-&gt; ioStr </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The string in which to perform the replacing. Must not be  <code> NULL </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inMaxLen </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The maximum length in bytes that  <code> ioStr </code>  can become.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inParamStr </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The string that  <code> ^ </code> <em> inParamNum </em>  should be replaced with. If  <code> NULL </code> , no changes are made.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inParamNum </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A single-digit number (0 to 9).  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the number of occurrences found and replaced.  Returns a fatal error message if  <code> inParamNum </code>  is greater than 9. 
    =><h4> Comments  </h4>
    =>This function searches  <code> ioStr </code>  for occurrences of the string  <code> ^ </code> <em> inParamNum </em> , where  <em> inParamNum </em>  is any digit from 0 to 9. When it finds the string, it replaces it with  <code> inParamStr </code> . Multiple instances will be replaced as long as the resulting string doesn't contain more than  <code> inMaxLen </code>  bytes, not counting the terminating null.  You can set the  <code> inParamStr </code>  parameter to  <code> NULL </code>  to determine the required length of  <code> ioStr </code>  before actually doing the replacing.  <code> TxtReplaceStr </code>  returns the number of occurrences it finds of  <code> ^ </code> <em> inParamNum </em> . Multiply this value by the length of the  <code> inParamStr </code>  you intend to use to determine the appropriate length of  <code> ioStr </code> .  You must make sure that the parameter  <code> ioStr </code>  points to the start of a valid character. That is, it must point to the first byte of a multi-byte character or it must point to a single-byte character. If it doesn't, results are unpredictable. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present.  <br> <br> <br> <h3>
TxtSetNextChar()
    =><h4> Purpose  </h4>
    =>Set a character within a text buffer. 
    =><h4> Prototype  </h4>
    =><code> UInt16 TxtSetNextChar (Char*&nbsp;ioText, UInt32&nbsp;inOffset, WChar&nbsp;inChar) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> &lt;-&gt; ioText </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to a text buffer. Must not be  <code> NULL </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inOffset </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A valid offset into the buffer  <code> inText </code> . This offset must point to an inter-character boundary.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inChar </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The character to replace the character at  <code> inOffset </code>  with. Must not be a virtual character. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the size of  <code> inChar </code> . 
    =><h4> Comments  </h4>
    =>This function replaces the character in  <code> ioText </code>  at the location  <code> inOffset </code>  with the character  <code> inChar </code> . Note that there must be enough space at  <code> inOffset </code>  to write the character.  You can use  TxtCharSize  to determine the size of  <code> inChar </code> .  You must make sure that the parameter  <code> ioText </code>  points to the start of a valid character. That is, it must point to the first byte of a multi-byte character or it must point to a single-byte character. If it doesn't, results are unpredictable. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present. 
    =><h4> See Also  </h4>
    =>TxtGetNextChar <br> <br> <br> <h3>
TxtStrEncoding()
    =><h4> Purpose  </h4>
    =>Return the encoding required to represent a string. 
    =><h4> Prototype  </h4>
    =><code> CharEncodingType TxtStrEncoding (const&nbsp;Char*&nbsp;inStr) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inStr </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A string. Must not be  <code> NULL </code> .  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>A  CharEncodingType  value that indicates the encoding required to represent  <code> inChar </code> . If any character in the string isn't recognizable, then  <code> charEncodingUnknown </code>  is returned. 
    =><h4> Comments  </h4>
    =>The encoding for the string is the maximum encoding of any character in that string. For example, if a two-character string contains a blank space and a &uuml;, the appropriate encoding is  <code> charEncodingISO8859_1 </code> . The blank space's minimum encoding is ASCII. The minimum encoding for the &uuml; is ISO 8859-1. The maximum of these two encodings is ISO 8859-1.  Because Palm OS only supports a single character encoding at a time, the results of this function is always logically equal to or less than the encoding used on the current system. That is, you'll only receive a return value of  <code> charEncodingISO8859_1 </code>  if you're running on a USA or European system.  Use this function for informational purposes only. Your code should not assume that the character encoding returned by this function is the Palm OS system's character encoding. (Instead use  <code> FtrGet </code>  as shown in the  TxtCharXAttr  function description.) 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present. 
    =><h4> See Also  </h4>
    =>TxtCharEncoding ,  TxtMaxEncoding <br> <br> <br> <h3>
TxtTransliterate()
    =><h4> Purpose  </h4>
    =>Converts the specified number of bytes in a text buffer using the specified operation. 
    =><h4> Prototype  </h4>
    =><code> Err TxtTransliterate (const&nbsp;Char*&nbsp;inSrcText, UInt16&nbsp;inSrcLength, Char*&nbsp;outDstText, UInt16*&nbsp;ioDstLength, TranslitOpType&nbsp;inOp) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inSrcText </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to a text buffer. Must not be  <code> NULL </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inSrcLength </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The length in bytes of  <code> inSrcText </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> &lt;- outDstText </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The output buffer containing the converted characters.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> &lt;-&gt;ioDstLength </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Upon entry, the maximum length of  <code> outDstText </code> . Upon return, the actual length of  <code> outDstText </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inOp </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A 16-bit unsigned value that specifies which transliteration operation is to be performed. The values possible for this field are specific to the character encoding used on a particular device. These operations are universally available:  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="35%"> &nbsp;  </td>
    =><td valign="top" align="left" width="25%"> <code> <code> translitOpUpperCase </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Converts the character to uppercase letters.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="35%"> &nbsp;  </td>
    =><td valign="top" align="left" width="25%"> <code> <code> translitOpLowerCase </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Converts the characters to lowercase letters.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="35%"> &nbsp;  </td>
    =><td valign="top" align="left" width="25%"> <code> <code> translitOpPreprocess </code> <br> </code> </td>
    =><td valign="top" align="left" width=""> Don't actually perform the operation. Instead, return in  <code> ioDstLength </code>  the amount of space required for the output text.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns one of the following values:  <p> </p> <p> <div>
    =><table border="3"> <caption> <br> </caption> <tbody> <tr>
    =><td> 0  </td>
    =><td> Success  </td> </tr> <tr>
    =><td> <code> txtErrUnknownTranslitOp </code> </td>
    =><td> <code> inOp </code> 's value is not recognized  </td> </tr> <tr>
    =><td> <code> txtErrTranslitOverrun </code> </td>
    =><td> If  <code> inSrcText </code>  and  <code> outDstText </code>  point to the same memory location and the operation has caused the function to overwrite unprocessed data in the input buffer.  </td> </tr> <tr>
    =><td> <code> txtErrTranslitOverflow </code> </td>
    =><td> If  <code> outDstText </code>  is not large enough to contain the converted string.  </td> </tr> </tbody> </table>
    =><table> <tbody> <tr>
    =><td> <br> </td> </tr> </tbody> </table> </div> </p>
    =><h4> Comments  </h4>
    =><code> inSrcText </code>  and  <code> outDstText </code>  may point to the same location if you want to perform the operation in place. However, you should be careful that the space required for  <code> outDstText </code>  is not larger than  <code> inSrcText </code>  so that you don't generate a  <code> txtErrTranslitOverrun </code>  error.  For example, suppose on a Shift JIS encoded system, you want to convert a series of single-byte Japanese Katakana symbols to double-byte Katakana symbols. You cannot perform this operation in place because it replaces a single-byte character with a multi-byte character. When the first converted character is written to the buffer, it overwrites the second input character. Thus, a text overrun has occurred.  You can ensure that you have enough space for the output by ORing your chosen operation with  <code> translitOpPreprocess </code> . For example, to convert a string to uppercase letters, do the following:  <br> <code> outSize = buf2Len; <br> error = TxtTransliterate(buf1, buf1len, &amp;buf2, &amp;outSize, translitOpUpperCase|translitOpPreprocess); </code> <br> <code> if (outSize &gt; buf2len)  <br> /* allocate more memory for buf2 */ </code> <br> <code> error = TxtTransliterate(buf1, buf1Len, &amp;buf2, &amp;outSize, translitOpUpperCase); </code> <br> You must make sure that the parameter  <code> inSrcText </code>  points to the start of a valid character. That is, it must point to the first byte of a multi-byte character or it must point to a single-byte character. If it doesn't, results are unpredictable. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present.  <br> <br> <br> <h3>
TxtWordBounds()
    =><h4> Purpose  </h4>
    =>Find the boundaries of a word of text that contains the character starting at the specified offset. 
    =><h4> Prototype  </h4>
    =><code> Boolean TxtWordBounds (const&nbsp;Char*&nbsp;inText, UInt32&nbsp;inLength, UInt32&nbsp;inOffset, UInt32*&nbsp;outStart, UInt32*&nbsp;outEnd) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inText </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to a text buffer. Must not be  <code> NULL </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inLength </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The length in bytes of the text pointed to by  <code> inText </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> -&gt; inOffset </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A valid offset into the text buffer  <code> inText </code> . This offset must point to the beginning of a character.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> &lt;- outStart </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The starting offset of the text word.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> &lt;- outEnd </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The ending offset of the text word.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns  <code> true </code>  if a word is found. Returns  <code> false </code>  if the word doesn't exist or is punctuation or whitespace. 
    =><h4> Comments  </h4>
    =>Assuming the ASCII encoding, if the text buffer contains the string "Hi! How are you?" and you pass 5 as the offset,  <code> TxtWordBounds </code>  returns the start and end of the word containing the character at offset 5, which is the character "o". Thus,  <code> outStart </code>  and  <code> outEnd </code>  would point to the start and end of the word "How".  You must make sure that the parameter  <code> inText </code>  points to the start of a valid character. That is, it must point to the first byte of a multi-byte character or it must point to a single-byte character. If it doesn't, results are unpredictable. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  International Feature Set  is present. 
    =><h4> See Also  </h4>
    =>TxtCharBounds ,  TxtCharIsDelim <br> <h3>
SndCreateMidiList()
    =><h4> Purpose  </h4>
    =>Generate a list of MIDI records having a specified creator. 
    =><h4> Prototype  </h4>
    =><code> Boolean SndCreateMidiList (UInt32&nbsp;creator, Boolean&nbsp;multipleDBs, UInt16*&nbsp;wCountP, MemHandle&nbsp;*entHP) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt; <code> creator </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Creator of database in which to find MIDI records. Pass  <code> 0 </code>  for wildcard. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt; <code> multipleDBs </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pass  <code> true </code>  to search multiple databases for MIDI records. Pass  <code> false </code>  to search only in the first database found that meets search criteria. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;-&gt; <code> wCountP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> When the function returns, contains the number of MIDI records found.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;-&gt; <code> entHP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> When the function returns, this handle holds a a memory chunk containing an array of  SndMidiListItemType  if MIDI records were found. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns  <code> false </code>  if no MIDI records were found,  <code> true </code>  if MIDI records were found. When this function returns  <code> true </code> , it updates the  <code> wCountP </code>  parameter to hold the number of MIDI records found and updates the  <code> entHP </code>  parameter to hold a handle to an array of  <code> SndMidiListItemType </code>  structures. Each record of this type holds the name, record ID, database ID, and card number of a MIDI record. 
    =><h4> Comments  </h4>
    =>This function is useful for displaying lists of sounds residing on the Palm device as MIDI records. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  3.0 New Feature Set  is present. 
    =><h4> See Also  </h4>
    =>DmFindRecordByID ,  DmOpenDatabase ,  DmQueryRecord ,  DmOpenDatabaseByTypeCreator ,"Rock Music" sample code  <br> <br> <br> <h3>
SndDoCmd()
    =><h4> Purpose  </h4>
    =>Send a sound manager command to a specified sound channel. 
    =><h4> Prototype  </h4>
    =><code> Err SndDoCmd (void*&nbsp;channelP, SndCommandPtr&nbsp;cmdP, Boolean&nbsp;noWait) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> channelP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to sound channel. Present implementation doesn't support multiple channels. Must be  <code> NULL </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Passing  <code> NULL </code>  for the channel pointer causes the command to be sent to the shared sound channel; currently, this is the only option. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> cmdP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to a  SndCommandType  holding a parameter block that specifies the note to play, its duration, and amplitude.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> noWait </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Because asynchronous mode is not yet supported for all commands, you must pass  <code> 0 </code>  for this value.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> </code> <br> </td>
    =><td valign="top" align="left" width=""> In the future, pass  <code> 0 </code>  to await completion (synchronous) and pass a nonzero value to specify immediate return (asynchronous). <br> </td> </tr> </tbody> </table>
    =><h4> Result </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> 0 </code> <br> </td>
    =><td valign="top" align="left" width=""> No error. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> sndErrBadParam </code> <br> </code> </td>
    =><td valign="top" align="left" width=""> Invalid parameter. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> sndErrBadChannel </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Invalid channel pointer. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> sndErrQFull </code> <br> </code> </td>
    =><td valign="top" align="left" width=""> Sound queue is full. <br> </td> </tr> </tbody> </table>
    =><h4> Comments </h4>
    =>This function is useful for simple sound playback applications, such as playing a single note to provide user feedback. In addition to providing the same behavior it did in versions 1.0 and 2.0 of Palm OS, (specify the frequency, duration, and amplitude of a single note to be played) new command selectors provided in Palm OS 3.0 and higher allow you to use MIDI values to specify pitch, duration, and amplitude of the note to play, and to stop the note currently being played. 
    =><h4> Compatibility  </h4>
    =>Commands (see  SndCmdIDType ) other than  <code> sndCmdFreqDurationAmp </code>  are implemented only if  3.0 New Feature Set  is present. 
    =><h4> See Also  </h4>
    =>SndPlaySmf <br> <br> <br> <h3>
SndGetDefaultVolume()
    =><h4> Purpose  </h4>
    =>Return default sound volume levels cached by sound manager. 
    =><h4> Prototype  </h4>
    =><code> void SndGetDefaultVolume (UInt16*&nbsp;alarmAmpP, UInt16*&nbsp;sysAmpP, UInt16*&nbsp;masterAmpP) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;-&gt; a <code> larmAmpP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to storage for alarm amplitude. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;-&gt;  <code> sysAmpP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to storage for system sound amplitude. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;-&gt;  <code> masterAmpP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to storage for master amplitude. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns nothing. 
    =><h4> Comments  </h4>
    =>Any pointer arguments may be passed as  <code> NULL </code> . In that case, the corresponding setting is not returned.  <br> <br> <br> <h3>
SndPlaySmf()
    =><h4> Purpose  </h4>
    =>Performs the operation specified by the  <code> cmd </code>  parameter: play the specified standard MIDI file (SMF) or return the number of milliseconds required to play the entire SMF. 
    =><h4> Prototype  </h4>
    =><code> Err SndPlaySmf (void*&nbsp;chanP, SndSmfCmdEnum&nbsp;cmd, UInt8*&nbsp;smfP, SndSmfOptionsType*&nbsp;selP, SndSmfChanRangeType*&nbsp;chanRangeP, SndSmfCallbacksType*&nbsp;callbacksP, Boolean&nbsp;bNoWait) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> chanP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The sound channel used to play the sound. This value must always be  <code> NULL </code>  because current versions of Palm OS provide only one sound channel that all applications share. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> cmd </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The operation to perform, as specified by one of the following selectors:  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="35%"> &nbsp;  </td>
    =><td valign="top" align="left" width="25%"> <code> <code> sndSmfCmdPlay </code> <br> </code> </td>
    =><td valign="top" align="left" width=""> Play the selection synchronously. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="35%"> &nbsp;  </td>
    =><td valign="top" align="left" width="25%"> <code> <code> sndSmfCmdDuration </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Return the duration of the entire SMF, expressed in milliseconds. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> smfP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the SMF data in memory. This pointer can reference a valid  SndCallbackInfoType  followed by MIDI data, or it can point directly to the beginning of the SMF data.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> selP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> <code> NULL </code>  or a pointer to a  SndSmfOptionsType  specifying options for playback volume, position in the SMF from which to begin playback, and whether playback can be interrupted by user interaction with the display. See the  SndSmfOptionsType  for the default behavior specified by a  <code> NULL </code>  value. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> chanRangeP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> <code> NULL </code>  or a pointer to a  SndSmfChanRangeType  specifying a continuous range of MIDI channels 0 -15 to use for playback. If this value is  <code> NULL </code> , all tracks are played. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> callbacksP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> <code> NULL </code>  or a pointer to a  SndSmfCallbacksType  that holds your callback functions. Functions of type  SndBlockingFuncType  execute periodically while a note is playing, and functions of type  SndComplFuncType  execute after playback of the SMF completes. For more information, see the  "Application-Defined Functions"  section.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> bNoWait </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> This value is ignored. This function always finishes playing the SMF selection before returning; however, you can execute a callback function while the SMF is playing. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns  <code> 0 </code>  if no error. When an error occurs, this function returns one of the following values; for more information see the  <code> SoundMgr.h </code>  file included with the Palm OS 3.X SDK:  <p> </p> <p> <div>
    =><table border="3"> <caption> <br> </caption> <tbody> <tr>
    =><td> <code> sndErrBadParam </code> </td>
    =><td> Bogus value passed to this function.  </td> </tr> <tr>
    =><td> <code> sndErrBadChannel </code> </td>
    =><td> Invalid sound channel.  </td> </tr> <tr>
    =><td> <code> sndErrMemory </code> </td>
    =><td> Insufficient memory.  </td> </tr> <tr>
    =><td> <code> sndErrOpen </code> </td>
    =><td> Tried to open channel that's already open.  </td> </tr> <tr>
    =><td> <code> sndErrQFull </code> </td>
    =><td> Can't accept more notes.  </td> </tr> <tr>
    =><td> <code> sndErrQEmpty </code> </td>
    =><td> Internal use; never returned to applications.  </td> </tr> <tr>
    =><td> <code> sndErrFormat </code> </td>
    =><td> Unsupported data format.  </td> </tr> <tr>
    =><td> <code> sndErrBadStream </code> </td>
    =><td> Invalid data stream.  </td> </tr> <tr>
    =><td> <code> sndErrInterrupted </code> </td>
    =><td> Play was interrupted.  </td> </tr> </tbody> </table>
    =><table> <tbody> <tr>
    =><td> <br> </td> </tr> </tbody> </table> </div> </p>
    =><h4> Comments  </h4>
    =>Although this call is synchronous, a callback function can be called while a note is playing. If the callback does not return before the number of system ticks required to play the current sound have elapsed, the next note in the SMF will not start on time. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  3.0 New Feature Set  is present. 
    =><h4> See Also  </h4>
    =>SndPlaySmfResource ,  SndDoCmd , SndCreateMidiList <br> <br> <br> <h3>
SndPlaySmfResource()
    =><h4> Purpose  </h4>
    =>Plays a MIDI sound read out of an open resource database. 
    =><h4> Prototype  </h4>
    =><code> Err SndPlaySmfResource (UInt32&nbsp;resType, Int16&nbsp;resID, SystemPreferencesChoice&nbsp;volumeSelector) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> resType </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Card number of the database containing the SMF resource.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> resID </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Resource ID of the SMF resource.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> volumeSelector </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Volume setting to use. The volume is read out of the system preferences. Possible values for this parameter are: <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> prefSysSoundVolumeprefGameSoundVolume </code> <br> </code> </td>
    =><td valign="top" align="left" width=""> prefSysSoundVolumeprefGameSoundVolumeprefAlarmSoundVolume <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns 0 upon success, otherwise one of the following:  <p> </p> <p> <div>
    =><table border="3"> <caption> <br> </caption> <tbody> <tr>
    =><td> <code> sndErrBadParam </code> </td>
    =><td> The  <code> volumeSelector </code>  parameter has an invalid value or the SMF resource has invalid data.  </td> </tr> <tr>
    =><td> <code> dmErrCantFind </code> </td>
    =><td> The specified resource does not exist on the specified card.  </td> </tr> </tbody> </table>
    =><table> <tbody> <tr>
    =><td> <br> </td> </tr> </tbody> </table> </div> or any error code returned by  SndPlaySmf .  </p>
    =><h4> Comments  </h4>
    =>This is a convenience function to be used in place of  SndPlaySmf . It plays an SMF sound stored in a resource database. This function plays the entire sound on all MIDI channels at the volume specified and allows the sound to be interrupted by a key down event or a digitizer event. No callbacks are specified. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  3.2 New Feature Set  is present.  <br> <br> <br> <h3>
SndPlaySystemSound()
    =><h4> Purpose  </h4>
    =>Play a standard system sound. 
    =><h4> Prototype  </h4>
    =><code> void SndPlaySystemSound (SndSysBeepType&nbsp;beepID) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> beepID </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> System sound to play.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns nothing. 
    =><h4> Comments  </h4>
    =>The  <code> SndSysBeepType </code>  enum is defined in  <code> SoundMgr.h </code>  as follows:  <br> <code> typedef enum SndSysBeepType { </code> <br> <code> &nbsp;&nbsp;&nbsp; sndInfo = 1, </code> <br> <code> &nbsp;&nbsp;&nbsp; sndWarning, </code> <br> <code> &nbsp;&nbsp;&nbsp; sndError, </code> <br> <code> &nbsp;&nbsp;&nbsp; sndStartUp, </code> <br> <code> &nbsp;&nbsp;&nbsp; sndAlarm, </code> <br> <code> &nbsp;&nbsp;&nbsp; sndConfirmation, </code> <br> <code> &nbsp;&nbsp;&nbsp; sndClick </code> <br> <code> &nbsp;&nbsp;&nbsp; } SndSysBeepType; </code> <br> Note that in versions of Palm OS prior to 3.0, all of these sounds were synchronous and blocking. In Palm OS 3.0 and higher,  <code> sndAlarm </code>  still blocks, but the rest of these system sounds are implemented asynchronously.  <h2> Application-Defined Functions </h2> This section describes callback functions to be executed by the  SndPlaySmf  function.  <br> <br> <br> <h3>
SndComplFuncType()
    =><h4> Purpose  </h4>
    =>Executed after playback of the SMF completes. 
    =><h4> Prototype  </h4>
    =><code> void SndComplFuncType (void*&nbsp;chanP, UInt32&nbsp;dwUserData) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> chanP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The sound channel used to play the sound. This value must always be  <code> NULL </code>  because current versions of Palm OS provide only one sound channel that all applications share. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> dwUserData </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Application-defined data that this function needs to access, or  <code> NULL </code> . <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns nothing. 
    =><h4> See Also  </h4>
    =>SndSmfCallbacksType <br> <br> <br> <h3>
SndBlockingFuncType()
    =><h4> Purpose  </h4>
    =>A non-blocking callback function that is executed periodically during playback of the SMF. 
    =><h4> Prototype  </h4>
    =><code> Boolean SndBlockingFuncType (void*&nbsp;chanP, UInt32&nbsp;dwUserData, Int32&nbsp;sysTicksAvailable) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> chanP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The sound channel used to play the sound. This value must always be  <code> NULL </code>  because current versions of Palm OS provide only one sound channel that all applications share. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> dwUserData </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Application-defined data that this function needs to access. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> sysTicksAvailable </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The maximum amount of time available for completion of this function, or  <code> NULL </code> .  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns  <code> true </code>  to continue playback, or  <code> false </code>  to cancel playback. 
    =><h4> Comments  </h4>
    =>Suggested uses for this function include updating the user interface or checking for user input. 
    =><h4> See Also  </h4>
    =>SndSmfCallbacksType ,  SndPlaySmf <strong> </strong> <br> <h3>
MemCardInfo()
    =><h4> Purpose  </h4>
    =>Return information about a memory card. 
    =><h4> Prototype  </h4>
    =><code> Err MemCardInfo (UInt16&nbsp;cardNo, Char*&nbsp;cardNameP, Char*&nbsp;manufNameP, UInt16*&nbsp;versionP, UInt32*&nbsp;crDateP, UInt32*&nbsp;romSizeP, UInt32*&nbsp;ramSizeP, UInt32*&nbsp;freeBytesP) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> cardNo </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Card number. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> cardNameP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to character array (32 bytes), or 0.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> manufNameP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to character array (32 bytes), or 0.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> versionP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to version variable, or 0. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> crDateP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to creation date variable, or 0. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> romSizeP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to ROM size variable, or 0. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> ramSizeP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to RAM size variable, or 0. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> freeBytesP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to free byte-count variable, or 0. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns 0 if no error. 
    =><h4> Comments  </h4>
    =>Pass 0 for those variables that you don't want returned.  <br> <br> <br> <h3>
MemCmp()
    =><h4> Purpose  </h4>
    =>Compare two blocks of memory.  <blockquote> <hr> <strong> NOTE: &nbsp; </strong> Blocks are compared as unsigned bytes.  <hr> <br> </blockquote>
    =><h4> Prototype  </h4>
    =><code> Int16 MemCmp (const&nbsp;void*&nbsp;s1, const&nbsp;void*&nbsp;s2, Int32&nbsp;numBytes) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> s1, s2 </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointers to block of memory. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> numBytes </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Number of bytes to compare.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Zero if they match, non-zero if not:  + if  <code> s1 </code>  &gt;  <code> s2 </code> - if  <code> s1 </code>  &lt;  <code> s2 </code>
    =><h4> Compatibility  </h4>
    =>Implemented only if  2.0 New Feature Set  is present.  <code> MemCmp </code>  can be used to test the equality of blocks in memory on all versions that support  <code> MemCmp </code> ; however, testing the sort ordering of blocks in memory works reliably only on Palm OS <sup> &reg; </sup>  versions 3.5 and higher. On versions earlier than 3.2,  <code> MemCmp </code>  always returns a positive value if the blocks are unequal. On versions 3.2 and 3.3,  <code> MemCmp </code>  reliably returns positive to indicate  <code> s1 </code>  &gt;  <code> s2 </code>  and negative to indicate  <code> s1 </code>  &lt;  <code> s2 </code> <strong> only </strong>  if the characters that differ are less than 128 apart. If the difference is greater than that,  <code> MemCmp </code>  may return positive when it should return negative and vice versa.  <br> <br> <br> <h3>
MemDebugMode()
    =><h4> Purpose  </h4>
    =>Return the current debugging mode of the memory manager. 
    =><h4> Prototype  </h4>
    =><code> UInt16 MemDebugMode(void) </code>
    =><h4> Parameters  </h4>
    =>No parameters. 
    =><h4> Result  </h4>
    =>Returns debug flags as described for  MemSetDebugMode .  <br> <br> <br> <h3>
MemHandleCardNo()
    =><h4> Purpose  </h4>
    =>Return the card number a chunk resides in. 
    =><h4> Prototype  </h4>
    =><code> UInt16 MemHandleCardNo (MemHandle&nbsp;h) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> h </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Chunk handle. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the card number. 
    =><h4> Comments  </h4>
    =>Call this routine to retrieve the card number (0 or 1) a movable chunk resides on. 
    =><h4> See Also  </h4>
    =>MemPtrCardNo <br> <br> <br> <h3>
MemHandleDataStorage()
    =><h4> Purpose  </h4>
    =>Return  <code> true </code>  if the given handle is part of a data storage heap. If not, it's a handle in the dynamic heap. 
    =><h4> Prototype  </h4>
    =><code> Boolean MemHandleDataStorage (MemHandle&nbsp;h)  </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> h </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Chunk handle. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns  <code> true </code>  if the handle is part of a data storage heap. 
    =><h4> Comments  </h4>
    =>Called by Fields package routines to determine if they need to worry about data storage write-protection when editing a text field. 
    =><h4> See Also  </h4>
    =>MemPtrDataStorage <br> <br> <br> <h3>
MemHandleFree()
    =><h4> Purpose  </h4>
    =>Dispose of a movable chunk. 
    =><h4> Prototype  </h4>
    =><code> Err MemHandleFree (MemHandle&nbsp;h) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> h </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Chunk handle. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns 0 if no error, or memErrInvalidParam if an error occurs. 
    =><h4> Comments  </h4>
    =>Call this routine to dispose of a movable chunk. 
    =><h4> See Also  </h4>
    =>MemHandleNew <br> <br> <br> <h3>
MemHandleHeapID()
    =><h4> Purpose  </h4>
    =>Return the heap ID of a chunk. 
    =><h4> Prototype  </h4>
    =><code> UInt16 MemHandleHeapID (MemHandle&nbsp;h) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> h </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Chunk handle. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the heap ID of a chunk. 
    =><h4> Comments  </h4>
    =>Call this routine to get the heap ID of the heap a chunk resides in. 
    =><h4> See Also  </h4>
    =>MemPtrHeapID <br> <br> <br> <h3>
MemHandleLock()
    =><h4> Purpose  </h4>
    =>Lock a chunk and obtain a pointer to the chunk's data. 
    =><h4> Prototype  </h4>
    =><code> MemPtr MemHandleLock (MemHandle&nbsp;h) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> h </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Chunk handle. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns a pointer to the chunk. 
    =><h4> Comments  </h4>
    =>Call this routine to lock a chunk and obtain a pointer to the chunk.  <code> MemHandleLock </code>  and  <code> MemHandleUnlock </code>  should be used in pairs. 
    =><h4> See Also  </h4>
    =>MemHandleNew ,  MemHandleUnlock <br> <br> <br> <h3>
MemHandleNew()
    =><h4> Purpose  </h4>
    =>Allocate a new movable chunk in the dynamic heap and returns a handle to it. 
    =><h4> Prototype  </h4>
    =><code> MemHandle MemHandleNew (UInt32&nbsp;size) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> size </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The desired size of the chunk. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns a handle to the new chunk, or 0 if unsuccessful. 
    =><h4> Comments  </h4>
    =>Use this call to allocate dynamic memory. Before you can write data to the memory chunk that  <code> MemHandleNew </code>  allocates, you must call  MemHandleLock  to lock the chunk and get a pointer to it. 
    =><h4> See Also  </h4>
    =>MemPtrFree ,  MemPtrNew ,  MemHandleFree ,  MemHandleLock <br> <br> <br> <h3>
MemHandleResize()
    =><h4> Purpose  </h4>
    =>Resize a chunk. 
    =><h4> Prototype  </h4>
    =><code> Err MemHandleResize (MemHandle&nbsp;h, UInt32&nbsp;newSize) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> h </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Chunk handle. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> newSize </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The new desired size. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> 0 </code> <br> </td>
    =><td valign="top" align="left" width=""> No error. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> memErrInvalidParam </code> <br> </td>
    =><td valign="top" align="left" width=""> Invalid parameter passed. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> memErrNotEnoughSpace </code> <br> </td>
    =><td valign="top" align="left" width=""> Not enough free space in heap to grow chunk. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> memErrChunkLocked </code> <br> </td>
    =><td valign="top" align="left" width=""> Can't grow chunk because it's locked.  <br> </td> </tr> </tbody> </table>
    =><h4> Comments  </h4>
    =>Call this routine to resize a chunk. This routine is always successful when shrinking the size of a chunk, even if the chunk is locked. When growing a chunk, it first attempts to grab free space immediately following the chunk so that the chunk does not have to move. If the chunk has to move to another free area of the heap to grow, it must be movable and have a lock count of 0.  On devices running version 2.0 or earlier of Palm OS, the  <code> MemHandleResize </code>  function tries to resize the chunk only within the same heap, whereas  DmResizeRecord  will look for space in other data heaps if it can't find enough space in the original heap. 
    =><h4> See Also  </h4>
    =>MemHandleNew ,  MemHandleSize <br> <br> <br> <h3>
MemHandleSetOwner()
    =><h4> Purpose  </h4>
    =>Set the owner ID of a chunk. 
    =><h4> Prototype  </h4>
    =><code> Err MemHandleSetOwner (MemHandle&nbsp;h, UInt16&nbsp;owner) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> h </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Chunk handle. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> owner </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> New owner ID of the chunk. Specify 0 to set the owner to the operating system. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns 0 if no error, or memErrInvalidParam if an error occurs. 
    =><h4> Comments  </h4>
    =>When you allocate a parameter block to pass to  SysUIAppSwitch  or  SysAppLaunch , you must call  MemPtrSetOwner  to grant ownership of the parameter block chunk to the OS (your application is originally set as the owner). If the parameter block structure references any chunks by handle, you also must call  <code> MemHandleSetOwner </code>  to grant ownership of those blocks to the OS. If you don't change the ownership of these chunks, they will get freed before the application you're launching has a chance to use them.  <br> <br> <br> <h3>
MemHandleSize()
    =><h4> Purpose  </h4>
    =>Return the requested size of a chunk. 
    =><h4> Prototype  </h4>
    =><code> UInt32 MemHandleSize (MemHandle&nbsp;h) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> h </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Chunk handle. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the requested size of the chunk. 
    =><h4> Comments  </h4>
    =>Call this routine to get the size originally requested for a chunk. 
    =><h4> See Also  </h4>
    =>MemHandleResize <br> <br> <br> <h3>
MemHandleToLocalID()
    =><h4> Purpose  </h4>
    =>Convert a handle into a local chunk ID which is card relative. 
    =><h4> Prototype  </h4>
    =><code> LocalID MemHandleToLocalID (MemHandle&nbsp;h) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> h </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Chunk handle. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns local ID, or NULL (0) if unsuccessful. 
    =><h4> Comments  </h4>
    =>Call this routine to convert a chunk handle to a local ID. 
    =><h4> See Also  </h4>
    =>MemLocalIDToGlobal ,  MemLocalIDToLockedPtr <br> <br> <br> <h3>
MemHandleUnlock()
    =><h4> Purpose  </h4>
    =>Unlock a chunk given a chunk handle. 
    =><h4> Prototype  </h4>
    =><code> Err MemHandleUnlock (MemHandle&nbsp;h) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> h </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The chunk handle. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> 0 </code> <br> </td>
    =><td valign="top" align="left" width=""> No error. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> memErrInvalidParam </code> <br> </td>
    =><td valign="top" align="left" width=""> Invalid parameter passed. <br> </td> </tr> </tbody> </table>
    =><h4> Comments  </h4>
    =>Call this routine to decrement the lock count for a chunk.  <code> MemHandleLock </code>  and  <code> MemHandleUnlock </code>  should be used in pairs. 
    =><h4> See Also  </h4>
    =>MemHandleLock <br> <br> <br> <h3>
MemHeapCheck()
    =><h4> Purpose  </h4>
    =>Check validity of a given heap. 
    =><h4> Prototype  </h4>
    =><code> Err MemHeapCheck (UInt16&nbsp;heapID) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> heapID </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> ID of heap to check. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns 0 if no error. 
    =><h4> See Also  </h4>
    =>MemDebugMode ,  MemSetDebugMode <br> <br> <br> <h3>
MemHeapCompact()
    =><h4> Purpose  </h4>
    =>Compact a heap. 
    =><h4> Prototype  </h4>
    =><code> Err MemHeapCompact (UInt16&nbsp;heapID) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> heapID </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> ID of the heap to compact. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Always returns 0. 
    =><h4> Comments  </h4>
    =>Most applications never need to call this function explicitly. The system software calls this function at various times; for example, during memory allocation (if sufficient free space is not available) and during system reboot.  Call this routine to compact a heap and merge all free space. This routine attempts to move all movable chunks to the start of the heap and merge all free space in the center of the heap.  <br> <br> <br> <h3>
MemHeapDynamic()
    =><h4> Purpose  </h4>
    =>Return  <code> true </code>  if the given heap is a dynamic heap. 
    =><h4> Prototype  </h4>
    =><code> Boolean MemHeapDynamic (UInt16&nbsp;heapID)  </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> heapID </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> ID of the heap to be tested. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns  <code> true </code>  if dynamic,  <code> false </code>  if not. 
    =><h4> Comments  </h4>
    =>Dynamic heaps are used for volatile storage, application stacks, globals, and dynamically allocated memory.  <blockquote> <hr> <strong> NOTE: &nbsp; </strong> In Palm OS 3.5, the dynamic heap is sized based on the amount of memory available, and is generally larger than before. <hr> <br> </blockquote>
    =><h4> See Also  </h4>
    =>MemNumHeaps ,  MemHeapID <br> <br> <br> <h3>
MemHeapFlags()
    =><h4> Purpose  </h4>
    =>Return the heap flags for a heap. 
    =><h4> Prototype  </h4>
    =><code> UInt16 MemHeapFlags (UInt16&nbsp;heapID) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> heapID </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> ID of heap. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the heap flags. 
    =><h4> Comments  </h4>
    =>Call this routine to retrieve the heap flags for a heap. The flags can be examined to determine if the heap is ROM based or not. ROM-based heaps have the memHeapFlagReadOnly bit set. 
    =><h4> See Also  </h4>
    =>MemNumHeaps ,  MemHeapID <br> <br> <br> <h3>
MemHeapFreeBytes()
    =><h4> Purpose  </h4>
    =>Return the total number of free bytes in a heap and the size of the largest free chunk in the heap. 
    =><h4> Prototype  </h4>
    =><code> Err MemHeapFreeBytes (UInt16&nbsp;heapID, UInt32*&nbsp;freeP, UInt32*&nbsp;maxP) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> heapID </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> ID of heap. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;-&gt;  <code> freeP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to a variable of type  <code> UInt32 </code>  for free bytes. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;-&gt;  <code> maxP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to a variable of type  <code> UInt32 </code>  for max free chunk size. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Always returns 0. 
    =><h4> Comments  </h4>
    =>This routine doesn't compact the heap but may be used to determine in advance whether an allocation request will succeed. Before allocating memory, call this function and test the return value of  <code> maxP </code>  to determine whether enough free space to fulfill your allocation request exists. If not, you may make more space available by calling the  MemHeapCompact  function. An alternative approach is to just call the  MemHeapCompact  function as necessary when an error is returned by the  MemPtrNew  or  MemHandleNew  functions. 
    =><h4> See Also  </h4>
    =>MemHeapSize ,  MemHeapID ,  MemHeapCompact <br> <br> <br> <h3>
MemHeapID()
    =><h4> Purpose  </h4>
    =>Return the heap ID for a heap, given its index and the card number. 
    =><h4> Prototype  </h4>
    =><code> UInt16 MemHeapID (UInt16&nbsp;cardNo, UInt16&nbsp;heapIndex) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> cardNo </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The card number, either 0 or 1. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> heapIndex </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The heap index, anywhere from 0 to  MemNumHeaps  - 1. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the heap ID. 
    =><h4> Comments  </h4>
    =>Call this routine to retrieve the heap ID of a heap, given the heap index and the card number. A heap ID must be used to obtain information on a heap such as its size, free bytes, etc., and is also passed to any routines which manipulate heaps. 
    =><h4> See Also  </h4>
    =>MemNumHeaps <br> <br> <br> <h3>
MemHeapScramble()
    =><h4> Purpose  </h4>
    =>Scramble the specified heap. 
    =><h4> Prototype  </h4>
    =><code> Err MemHeapScramble (UInt16&nbsp;heapID) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> heapID </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> ID of heap to scramble. <br> </td> </tr> </tbody> </table>
    =><h4> Comments  </h4>
    =>The system attempts to move each movable chunk.  Useful for debugging. 
    =><h4> Result  </h4>
    =>Always returns 0. 
    =><h4> See Also  </h4>
    =>MemDebugMode ,  MemSetDebugMode <br> <br> <br> <h3>
MemHeapSize()
    =><h4> Purpose  </h4>
    =>Return the total size of a heap including the heap header. 
    =><h4> Prototype  </h4>
    =><code> UInt32 MemHeapSize (UInt16&nbsp;heapID) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> heapID </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> ID of heap. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the total size of the heap. 
    =><h4> See Also  </h4>
    =>MemHeapFreeBytes ,  MemHeapID <br> <br> <br> <h3>
MemLocalIDKind()
    =><h4> Purpose  </h4>
    =>Return whether or not a local ID references a handle or a pointer. 
    =><h4> Prototype  </h4>
    =><code> LocalIDKind MemLocalIDKind (LocalID&nbsp;local) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> local </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Local ID to query <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns LocalIDKind, or a memIDHandle or memIDPtr (see MemoryMgr.h). 
    =><h4> Comments  </h4>
    =>This routine determines if the given local ID is to a nonmovable (memIDPtr) or movable (memIDHandle) chunk.  <br> <br> <br> <h3>
MemLocalIDToGlobal()
    =><h4> Purpose  </h4>
    =>Convert a local ID, which is card relative, into a global pointer in the designated card. 
    =><h4> Prototype  </h4>
    =><code> MemPtr MemLocalIDToGlobal (LocalID&nbsp;local, UInt16&nbsp;cardNo) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> local </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The local ID to convert. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> cardNo </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Memory card the chunk resides in. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns pointer or handle to chunk. 
    =><h4> See Also  </h4>
    =>MemLocalIDKind ,  MemLocalIDToLockedPtr <br> <br> <br> <h3>
MemLocalIDToLockedPtr()
    =><h4> Purpose  </h4>
    =>Return a pointer to a chunk given its local ID and card number.  If the local ID references a movable chunk handle, this routine automatically locks the chunk before returning. 
    =><h4> Prototype  </h4>
    =><code> MemPtr MemLocalIDToLockedPtr (LocalID&nbsp;local, UInt16&nbsp;cardNo) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> local </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Local chunk ID.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> cardNo </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Card number. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns pointer to chunk, or 0 if an error occurs. 
    =><h4> See Also  </h4>
    =>MemLocalIDToGlobal ,  MemLocalIDToPtr ,  MemLocalIDKind ,  MemPtrToLocalID ,  MemHandleToLocalID <br> <br> <br> <h3>
MemLocalIDToPtr()
    =><h4> Purpose  </h4>
    =>Return pointer to chunk, given the local ID and card number. 
    =><h4> Prototype  </h4>
    =><code> MemPtr MemLocalIDToPtr (LocalID&nbsp;local, UInt16&nbsp;cardNo) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> local </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Local ID to query. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> cardNo </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Card number the chunk resides in. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns a pointer to the chunk, or 0 if error. 
    =><h4> Comments  </h4>
    =>If the local ID references a movable chunk and that chunk is  <strong> not </strong>  locked, this function returns 0 to indicate an error. 
    =><h4> See Also  </h4>
    =>MemLocalIDToGlobal ,  MemLocalIDToLockedPtr <br> <br> <br> <h3>
MemMove()
    =><h4> Purpose  </h4>
    =>Move a range of memory to another rangein the dynamic heap. 
    =><h4> Prototype  </h4>
    =><code> Err MemMove (void*&nbsp;dstP, const&nbsp;void*&nbsp;sP, Int32&nbsp;numBytes) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> dstP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to destination. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> sP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to source. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> numBytes </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Number of bytes to move. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Always returns 0. 
    =><h4> Comments  </h4>
    =>Handles overlapping ranges.  For operations where the destination is in a data heap, see  DmSet ,  DmWrite , and related functions.  <br> <br> <br> <h3>
MemNumCards()
    =><h4> Purpose  </h4>
    =>Return the number of memory card slots in the system. Not all slots need to be populated. 
    =><h4> Prototype  </h4>
    =><code> UInt16 MemNumCards (void) </code>
    =><h4> Parameters  </h4>
    =>None. 
    =><h4> Result  </h4>
    =>Returns number of slots in the system.  <br> <br> <br> <h3>
MemNumHeaps()
    =><h4> Purpose  </h4>
    =>Return the number of heaps available on a particular card. 
    =><h4> Prototype  </h4>
    =><code> UInt16 MemNumHeaps (UInt16&nbsp;cardNo) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> cardNo </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The card number; either 0 or 1. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Number of heaps available, including ROM- and RAM-based heaps. 
    =><h4> Comments  </h4>
    =>Call this routine to retrieve the total number of heaps on a memory card. The information can be obtained by calling  MemHeapSize ,  MemHeapFreeBytes , and  MemHeapFlags  on each heap using its heap ID. The heap ID is obtained by calling  MemHeapID  with the card number and the heap index, which can be any value from 0 to  <code> MemNumHeaps </code> .  <br> <br> <br> <h3>
MemNumRAMHeaps()
    =><h4> Purpose  </h4>
    =>Return the number of RAM heaps in the given card. 
    =><h4> Prototype  </h4>
    =><code> UInt16 MemNumRAMHeaps (UInt16&nbsp;cardNo) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> cardNo </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The card number. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the number of RAM heaps. 
    =><h4> See Also  </h4>
    =>MemNumCards <br> <br> <br> <h3>
MemPtrCardNo()
    =><h4> Purpose  </h4>
    =>Return the card number (0 or 1) a nonmovable chunk resides on. 
    =><h4> Prototype  </h4>
    =><code> UInt16 MemPtrCardNo (MemPtr&nbsp;p) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> p </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the chunk. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the card number. 
    =><h4> See Also  </h4>
    =>MemHandleCardNo <br> <br> <br> <h3>
MemPtrDataStorage()
    =><h4> Purpose  </h4>
    =>Return  <code> true </code>  if the given pointer is part of a data storage heap; if not, it is a pointer in the dynamic heap. 
    =><h4> Prototype  </h4>
    =><code> Boolean MemPtrDataStorage (MemPtr&nbsp;p) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> p </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to a chunk. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns  <code> true </code>  if the chunk is part of a data storage heap. 
    =><h4> Comments  </h4>
    =>Called by Fields package to determine if it needs to worry about data storage write-protection when editing a text field. 
    =><h4> See Also  </h4>
    =>MemHeapDynamic <br> <br> <br> <h3>
MemPtrFree()
    =><h4> Purpose  </h4>
    =>Macro to dispose of a chunk. 
    =><h4> Prototype  </h4>
    =><code> Err MemPtrFree (MemPtr&nbsp;p) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> p </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to a chunk. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> 0 </code> <br> </td>
    =><td valign="top" align="left" width=""> If no error or  <code> memErrInvalidParam </code>  (invalid parameter). <br> </td> </tr> </tbody> </table>
    =><h4> Comments  </h4>
    =>Call this routine to dispose of a nonmovable chunk.  <br> <br> <br> <h3>
MemPtrHeapID()
    =><h4> Purpose  </h4>
    =>Return the heap ID of a chunk. 
    =><h4> Prototype  </h4>
    =><code> UInt16 MemPtrHeapID (MemPtr&nbsp;p) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> p </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the chunk. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the heap ID of a chunk. 
    =><h4> Comments  </h4>
    =>Call this routine to get the heap ID of the heap a chunk resides in.  <br> <br> <br> <h3>
MemPtrNew()
    =><h4> Purpose  </h4>
    =>Allocate a new nonmovable chunk in the dynamic heap. 
    =><h4> Prototype  </h4>
    =><code> MemPtr MemPtrNew (UInt32&nbsp;size) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> size </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The desired size of the chunk. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns pointer to the new chunk, or 0 if unsuccessful. 
    =><h4> Comments  </h4>
    =>This routine allocates a nonmovable chunk in the dynamic heap and returns a pointer to the chunk. Applications can use it when allocating dynamic memory.  In Palm OS 3.5, the dynamic heap is sized based on the amount of memory available, and is generally larger than before.  <blockquote> <hr> <strong> NOTE: &nbsp; </strong> You cannot allocate a zero-size reference block. <hr> <br> </blockquote> <br> <br> <br> <h3>
MemPtrRecoverHandle()
    =><h4> Purpose  </h4>
    =>Recover the handle of a movable chunk, given a pointer to its data. 
    =><h4> Prototype  </h4>
    =><code> MemHandle MemPtrRecoverHandle (MemPtr&nbsp;p) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> p </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the chunk. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the handle of the chunk, or 0 if unsuccessful. 
    =><h4> Comments  </h4>
    =>Don't call this function for pointers in ROM or nonmovable data chunks.  <br> <br> <br> <h3>
MemPtrResize()
    =><h4> Purpose  </h4>
    =>Resize a chunk. 
    =><h4> Prototype  </h4>
    =><code> Err MemPtrResize (MemPtr&nbsp;p, UInt32&nbsp;newSize) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> p </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the chunk. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> newSize </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The new desired size. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns 0 if no error, or memErrNotEnoughSpace memErrInvalidParam, or memErrChunkLocked if an error occurs. 
    =><h4> Comments  </h4>
    =>Call this routine to resize a locked chunk. This routine is always successful when shrinking the size of a chunk. When growing a chunk, it attempts to use free space immediately following the chunk. 
    =><h4> See Also  </h4>
    =>MemPtrSize ,  MemHandleResize <br> <br> <br> <h3>
MemPtrSetOwner()
    =><h4> Purpose  </h4>
    =>Set the owner ID of a chunk. 
    =><h4> Prototype  </h4>
    =><code> Err MemPtrSetOwner (MemPtr&nbsp;p, UInt16&nbsp;owner) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> p </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the chunk. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> owner </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> New owner ID of the chunk. Specify 0 to set the owner to the operating system. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns 0 if no error, or memErrInvalidParam if an error occurs. 
    =><h4> Comments  </h4>
    =>When you allocate a parameter block to pass to  SysUIAppSwitch  or  SysAppLaunch , you must call  <code> MemPtrSetOwner </code>  or  MemHandleSetOwner  to grant ownership of the parameter block chunk, and any other chunks referenced in it, to the OS (your application is originally set as the owner). If you don't change the ownership of the parameter block, it will get freed before the application you're launching has a chance to use it.  <br> <br> <br> <h3>
MemPtrSize()
    =><h4> Purpose  </h4>
    =>Return the size of a chunk. 
    =><h4> Prototype  </h4>
    =><code> UInt32 MemPtrSize (MemPtr&nbsp;p) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> p </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the chunk. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>The requested size of the chunk. 
    =><h4> Comments  </h4>
    =>Call this routine to get the original requested size of a chunk.  <br> <br> <br> <h3>
MemPtrToLocalID()
    =><h4> Purpose  </h4>
    =>Convert a pointer into a card-relative local chunk ID. 
    =><h4> Prototype  </h4>
    =><code> LocalID MemPtrToLocalID (MemPtr&nbsp;p) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> p </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to a chunk. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns the local ID of the chunk. 
    =><h4> Comments  </h4>
    =>Call this routine to convert a chunk pointer to a local ID. 
    =><h4> See Also  </h4>
    =>MemLocalIDToPtr <br> <br> <br> <h3>
MemPtrUnlock()
    =><h4> Purpose  </h4>
    =>Unlock a chunk, given a pointer to the chunk. 
    =><h4> Prototype  </h4>
    =><code> Err MemPtrUnlock (MemPtr&nbsp;p) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> p </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to a chunk. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>0 if no error, or memErrInvalidParam if an error occurs. 
    =><h4> Comments  </h4>
    =>A chunk must  <strong> not </strong>  be unlocked more times than it was locked. 
    =><h4> See Also  </h4>
    =>MemHandleLock <br> <br> <br> <h3>
MemSet()
    =><h4> Purpose  </h4>
    =>Set a memory range in a dynamic heap to a specific value. 
    =><h4> Prototype  </h4>
    =><code> Err MemSet (void*&nbsp;dstP, Int32&nbsp;numBytes, UInt8&nbsp;value) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> dstP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to the destination. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> numBytes </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Number of bytes to set. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> value </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Value to set. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Always returns 0. 
    =><h4> Comments  </h4>
    =>For operations where the destination is in a data heap, see  DmSet ,  DmWrite , and related functions.  <br> <br> <br> <h3>
MemSetDebugMode()
    =><h4> Purpose  </h4>
    =>Set the debugging mode of the memory manager. 
    =><h4> Prototype  </h4>
    =><code> Err MemSetDebugMode (UInt16&nbsp;flags) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> flags </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Debug flags. <br> </td> </tr> </tbody> </table>
    =><h4> Comments  </h4>
    =>Use the logical OR operator ( <code> | </code> ) to provide any combination of one, more, or none of the following flags:  <code> memDebugModeCheckOnChange <br> memDebugModeCheckOnAll <br> memDebugModeScrambleOnChange <br> memDebugModeScrambleOnAll <br> memDebugModeFillFree <br> memDebugModeAllHeaps <br> memDebugModeRecordMinDynHeapFree </code>
    =><h4> Result  </h4>
    =>Returns 0 if no error, or -1 if an error occurs.  <br> <br> <br> <h3>
MemStoreInfo()
    =><h4> Purpose  </h4>
    =>Return information on either the RAM store or the ROM store for a memory card. 
    =><h4> Prototype  </h4>
    =><code> Err MemStoreInfo (UInt16&nbsp;cardNo, UInt16&nbsp;storeNumber, UInt16*&nbsp;versionP, UInt16*&nbsp;flagsP, Char*&nbsp;nameP, UInt32*&nbsp;crDateP, UInt32*&nbsp;bckUpDateP, UInt32*&nbsp;heapListOffsetP, UInt32*&nbsp;initCodeOffset1P, UInt32*&nbsp;initCodeOffset2P, LocalID*&nbsp;databaseDirIDP) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> cardNo </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Card number, either 0 or 1. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> storeNumber </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Store number; 0 for ROM, 1 for RAM. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;-&gt;  <code> versionP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to version variable, or 0. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;-&gt;  <code> flagsP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to flags variable, or 0. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;-&gt;  <code> nameP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to character array (32 bytes), or 0. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;-&gt;  <code> crDateP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to creation date variable, or 0. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;-&gt;  <code> bckUpDateP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to backup date variable, or 0. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;-&gt;  <code> heapListOffsetP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to  <code> heapListOffset </code>  variable, or 0. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;-&gt;  <code> initCodeOffset1P </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to  <code> initCodeOffset1 </code>  variable, or 0. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;-&gt;  <code> initCodeOffset2P </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to initCodeOffset2 variable, or 0. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;-&gt;  <code> databaseDirIDP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to database directory chunk ID variable, or 0. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns 0 if no error, or memErrCardNotPresent, memErrRAMOnlyCard, or memErrInvalidStoreHeader if an error occurs. 
    =><h4> Comments  </h4>
    =>Call this routine to retrieve any or all information on either the RAM store or the ROM store for a card. Pass 0 for variables that you don't wish returned.  <strong> </strong> <br> <h3>
FileClearerr()
    =><h4> Purpose  </h4>
    =>Clear I/O error status, end of file error status, and last error. 
    =><h4> Prototype  </h4>
    =><code> Err FileClearerr (FileHand&nbsp;stream)  </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> --&gt;  <code> stream </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Handle to open stream.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>0 if no error, or a  <code> fileErr  </code> code if an error occurs. See the section  "File Streaming Error Codes"  for more information. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  3.0 New Feature Set  is present. 
    =><h4> See Also  </h4>
    =>FileGetLastError ,  FileRewind <br> <br> <br> <h3>
FileClose()
    =><h4> Purpose  </h4>
    =>Close the file stream and destroy its handle. If the stream was opened with  <code> fileModeTemporary </code> , it is deleted upon closing. 
    =><h4> Prototype  </h4>
    =><code> Err FileClose (FileHand&nbsp;stream) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> --&gt;  <code> stream </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Handle to open stream.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>0 if no error, or a  <code> fileErr  </code> code if an error occurs. See the section  "File Streaming Error Codes"  for more information. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  3.0 New Feature Set  is present.  <br> <br> <br> <h3>
FileControl()
    =><h4> Purpose  </h4>
    =>Perform the operation specified by the  <code> op </code>  parameter on the  <code> stream </code>  file stream. 
    =><h4> Prototype  </h4>
    =><code> Err FileControl (FileOpEnum&nbsp;op, FileHand&nbsp;stream, void*&nbsp;valueP, Int32*&nbsp;valueLenP) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> op </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> The operation to perform, and its associated formal parameters. See the Comments section for a list of possible values.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> --&gt;  <code> stream </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Open stream handle if required for file stream operation.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;--&gt;  <code> valueP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to value or buffer, as required. This parameter is defined by the selector passed as the value of the  <code> op </code>  parameter. For details, see the Comments section.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;--&gt;  <code> valueLenP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to value or buffer, as required. This parameter is defined by the selector passed as the value of the  <code> op </code>  parameter. For details, see the Comments section. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns either a value defined by the selector passed as the argument to the  <code> op </code>  parameter, or an error code resulting from the requested operation. For details, see the Comments section. 
    =><h4> Comments  </h4>
    =>Normally, you do not call the  FileControl  function yourself; it is called for you by most of the other file streaming functions and macros to perform common file streaming operations. You can call  FileControl  yourself to enable specialized read modes.  <p> </p> <p> <div>
    =><table border="3"> <caption> <br> </caption> <tbody> <tr>
    =><td> <code> fileOpNone </code> </td>
    =><td> No-op.  </td> </tr> <tr>
    =><td> <code> fileOpDestructiveReadMode </code> </td>
    =><td> Enter destructive read mode, and rewind stream to its beginning. Once in this mode, there is no turning back: stream's contents after closing (or crash) are undefined.  </td> </tr> <tr>
    =><td> </td>
    =><td> Destructive read mode deletes blocks as data are read, thus freeing storage automatically. Once in destructive read mode, you cannot re-use the file stream--the contents of the stream are undefined after it is closed or after a crash.  </td> </tr> <tr>
    =><td> </td>
    =><td> Writing to files opened without write access or those that are in destructive read state is not allowed; thus, you cannot call the  FileWrite ,  FileSeek , or  FileTruncate  functions on a stream that is in destructive read mode. One exception to this rule applies to streams that were opened in "write + append" mode and then switched into destructive read state. In this case, the  FileWrite  function can append data to the stream, but it also preserves the current stream position so that subsequent reads pick up where they left off (you can think of this as a pseudo-pipe).  </td> </tr> <tr>
    =><td> </td>
    =><td> ARGUMENTS:  <code> stream </code>  = open stream handle  <code> valueP </code>  =  <code> NULL </code> <code> valueLenP </code>  =  <code> NULL </code> </td> </tr> <tr>
    =><td> </td>
    =><td> RETURNS:  zero on success;  <code> fileErr </code> ... on error  </td> </tr> <tr>
    =><td> <code> fileOpGetEOFStatus </code> </td>
    =><td> Get end-of-file status (like C runtime's  <code> feof </code> ) (err =  <code> fileErrEOF </code> ). Indicates end of file condition. Use  FileClearerr  to clear this error status.  </td> </tr> <tr>
    =><td> </td>
    =><td> ARGUMENTS:  <code> stream </code>  = open stream handle  <code> valueP </code>  =  <code> NULL </code> <code> valueLenP </code>  =  <code> NULL </code> </td> </tr> <tr>
    =><td> </td>
    =><td> RETURNS:  zero if not end of file;  non-zero if end of file  </td> </tr> <tr>
    =><td> <code> fileOpGetLastError </code> </td>
    =><td> Get error code from last operation on stream, and clear the last error code value. Doesn't change status of EOF or I/O errors --use  FileClearerr  to reset all error codes.  </td> </tr> <tr>
    =><td> </td>
    =><td> ARGUMENTS:  <code> stream </code>  = open stream handle  <code> valueP </code>  =  <code> NULL </code> <code> valueLenP </code>  =  <code> NULL </code> </td> </tr> <tr>
    =><td> </td>
    =><td> RETURNS:  Error code from last file stream operation  </td> </tr> <tr>
    =><td> <code> fileOpClearError </code> </td>
    =><td> Clear I/O and EOF error status and last error.  </td> </tr> <tr>
    =><td> </td>
    =><td> ARGUMENTS:  <code> stream </code>  = open stream handle  <code> valueP </code>  =  <code> NULL </code> <code> valueLenP </code>  =  <code> NULL </code> </td> </tr> <tr>
    =><td> </td>
    =><td> RETURNS:  zero on success;  <code> fileErr </code> ... on error  </td> </tr> <tr>
    =><td> <code> fileOpGetIOErrorStatus </code> </td>
    =><td> Get I/O error status (like C runtime's  <code> ferror </code> ). Use  FileClearerr  to clear this error status.  </td> </tr> <tr>
    =><td> </td>
    =><td> ARGUMENTS:  <code> stream </code>  = open stream handle  <code> valueP </code>  =  <code> NULL </code> <code> valueLenP </code>  =  <code> NULL </code> </td> </tr> <tr>
    =><td> </td>
    =><td> RETURNS:  zero if not I/O error;  non-zero if I/O error is pending.  </td> </tr> <tr>
    =><td> <code> fileOpGetCreatedStatus </code> </td>
    =><td> Find out whether file was created by  FileOpen  function  </td> </tr> <tr>
    =><td> </td>
    =><td> ARGUMENTS:  <code> stream </code>  = open stream handle  <code> valueP </code>  = Pointer to Boolean  <code> valueLenP </code>  = Pointer to  <code> Int32 </code>  variable set to sizeof(Boolean)  </td> </tr> <tr>
    =><td> </td>
    =><td> RETURNS:  zero on success;  <code> fileErr </code> ... on error. The Boolean variable will be set to non-zero if the file was created.  </td> </tr> <tr>
    =><td> <code> fileOpGetOpenDbRef </code> </td>
    =><td> Get the open database reference (handle) of the underlying database that implements the stream ( <code> NULL </code>  if none); this is needed for performing Palm OS-specific operations on the underlying database, such as changing or getting creator and type, version, backup/reset bits, and so on.  </td> </tr> <tr>
    =><td> </td>
    =><td> ARGUMENTS:  <code> stream </code>  = open stream handle  <code> valueP </code>  = Pointer to  <code> DmOpenRef </code>  variable  <code> valueLenP </code>  = Pointer to Int32 variable set to sizeof(DmOpenRef)  </td> </tr> <tr>
    =><td> </td>
    =><td> RETURNS:  zero on success;  <code> fileErr </code> ... on error. The  <code> DmOpenRef </code>  variable will be set to the file's open db reference that may be passed to Data Manager calls;  </td> </tr> <tr>
    =><td> </td>
    =><td> WARNING: Do not make any changes to the data of the underlying database -- doing so will corrupt the file stream.  </td> </tr> <tr>
    =><td> <code> fileOpFlush </code> </td>
    =><td> Flush any cached data to storage.  </td> </tr> <tr>
    =><td> </td>
    =><td> ARGUMENTS:  <code> stream </code>  = open stream handle  <code> valueP </code>  =  <code> NULL </code> <code> valueLenP </code>  =  <code> NULL </code> </td> </tr> <tr>
    =><td> </td>
    =><td> RETURNS:  zero on success;  <code> fileErr </code> ... on error;  </td> </tr> </tbody> </table>
    =><table> <tbody> <tr>
    =><td> <br> </td> </tr> </tbody> </table> </div> </p>
    =><h4> Compatibility  </h4>
    =>Implemented only if  3.0 New Feature Set  is present. 
    =><h4> See Also  </h4>
    =>FileClearerr ,  FileEOF ,  FileError ,  FileFlush ,  FileGetLastError ,  FileRewind <br> <br> <br> <h3>
FileDelete()
    =><h4> Purpose  </h4>
    =>Deletes the specified file stream from the specified card. Only a closed stream may be passed to this function. 
    =><h4> Prototype  </h4>
    =><code> Err FileDelete (UInt16&nbsp;cardNo, Char*&nbsp;nameP) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> cardNo </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Card on which the file stream to delete resides. Currently, no Palm OS <sup> &reg; </sup>  devices support multiple cards, so this value must be 0. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> nameP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> String that is the name of the stream to delete.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>0 if no error, or a  <code> fileErr  </code> code if an error occurs. See the section  "File Streaming Error Codes"  for more information. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  3.0 New Feature Set  is present. 
    =><h4> See Also  </h4>
    =>FileOpen <br> <br> <br> <h3>
FileDmRead()
    =><h4> Purpose  </h4>
    =>Read data from a file stream into a chunk, record, or resource residing in a database. 
    =><h4> Prototype  </h4>
    =><code> Int32 FileDmRead (FileHand&nbsp;stream, void*&nbsp;startOfDmChunkP, Int32&nbsp;destOffset, Int32&nbsp;objSize, Int32&nbsp;numObj, Err*&nbsp;errP)  </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> --&gt;  <code> stream </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Handle to open stream.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> --&gt;  <code> startOfDmChunkP </code> <br> </code> </td>
    =><td valign="top" align="left" width=""> Pointer to beginning of chunk, record or resource residing in a database.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> destOffset </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Offset from  <code> startOfDmChunkP </code>  (base pointer) to the destination area (must be &gt;= 0).  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> objSize </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Size of each stream object to read.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> numObj </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Number of stream objects to read.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;--&gt;  <code> errP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to variable that is to hold the error code returned by this function. Pass  <code> NULL </code>  to ignore. See the section  "File Streaming Error Codes"  for more information.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>The number of whole objects that were read--note that the number of objects actually read may be less than the number requested. 
    =><h4> Comments  </h4>
    =>When the number of objects actually read is less than the number requested, you may be able to determine the cause of this result by examining the return value of the  <code> errP </code>  parameter or by calling the  FileGetLastError  function. If the cause is insufficient data in the stream to satisfy the full request, the current stream position is at end-of-file and the "end of file" indicator is set. If a non- <code> NULL </code>  pointer was passed as the value of the  <code> errP </code>  parameter when the  <code> FileDmRead </code>  function was called and an error was encountered,  <code> *errP </code>  holds a non-zero error code when the function returns. In addition, the  FileError  and  FileEOF  functions may be used to check for I/O errors. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  3.0 New Feature Set  is present. 
    =><h4> See Also  </h4>
    =>FileRead ,  FileError ,  FileEOF <br> <br> <br> <h3>
FileEOF()
    =><h4> Purpose  </h4>
    =>Get end-of-file status (err =  <code> fileErrEOF </code>  indicates end of file condition). 
    =><h4> Prototype  </h4>
    =><code> Err FileEOF (FileHand&nbsp;stream)  </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> --&gt;  <code> stream </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Handle to open stream.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>0 if  <em> not </em>  end of file; non-zero if end of file. See the section  "File Streaming Error Codes"  for more information. 
    =><h4> Comments  </h4>
    =>This function's behavior is similar to that of the  <code> feof </code>  function provided by the C programming language runtime library.  Use  FileClearerr  to clear the I/O error status. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  3.0 New Feature Set  is present. 
    =><h4> See Also  </h4>
    =>FileClearerr ,  FileGetLastError ,  FileRewind <br> <br> <br> <h3>
FileError()
    =><h4> Purpose  </h4>
    =>Get I/O error status. 
    =><h4> Prototype  </h4>
    =><code> Err FileError (FileHand&nbsp;stream)  </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> --&gt;  <code> stream </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Handle to open stream.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>0 if no error, and non-zero if an I/O error indicator has been set for this stream. See the section  "File Streaming Error Codes"  for more information. 
    =><h4> Comments  </h4>
    =>This function's behavior is similar to that of the C programming language's  <code> ferror </code>  runtime function.  Use  FileClearerr  to clear the I/O error status. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  3.0 New Feature Set  is present. 
    =><h4> See Also  </h4>
    =>FileClearerr ,  FileGetLastError ,  FileRewind <br> <br> <br> <h3>
FileFlush()
    =><h4> Purpose  </h4>
    =>Flush cached data to storage. 
    =><h4> Prototype  </h4>
    =><code> Err FileFlush (FileHand&nbsp;stream)  </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> --&gt;  <code> stream </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Handle to open stream.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>0 if no error, or a  <code> fileErr  </code> code if an error occurs. See the section  "File Streaming Error Codes"  for more information. 
    =><h4> Comments  </h4>
    =>It is not always necessary to call this function explicitly--certain operations flush the contents of a stream automatically; for example, streams are flushed when they are closed. Because this function's behavior is similar to that of the  <code> fflush </code>  function provided by the C programming language runtime library, you only need to call it explicitly under circumstances similar to those in which you would call  <code> fflush </code>  explicitly. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  3.0 New Feature Set  is present.  <br> <br> <br> <h3>
FileGetLastError()
    =><h4> Purpose  </h4>
    =>Get error code from last operation on file stream, and clear the last error code value (will not change end of file or I/O error status -- use  FileClearerr  to reset all error codes) 
    =><h4> Prototype  </h4>
    =><code> Err FileGetLastError (FileHand&nbsp;stream)  </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> --&gt;  <code> stream </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Handle to open stream.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Error code returned by the last file stream operation. See the section  "File Streaming Error Codes"  for more information. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  3.0 New Feature Set  is present. 
    =><h4> See Also  </h4>
    =>FileClearerr ,  FileEOF ,  FileError <br> <br> <br> <h3>
FileOpen()
    =><h4> Purpose  </h4>
    =>Open existing file stream or create an open file stream for I/O in the mode specified by the  <code> openMode </code>  parameter. 
    =><h4> Prototype  </h4>
    =><code> FileHand FileOpen (UInt16&nbsp;cardNo, Char*&nbsp;nameP, UInt32&nbsp;type, UInt32&nbsp;creator, UInt32&nbsp;openMode, Err*&nbsp;errP) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> cardNo </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Card on which the file stream to open resides. Currently, no Palm OS devices support multiple cards, so this value must be 0. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> --&gt;  <code> nameP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to text string that is the name of the file stream to open or create. This value must be a valid name--no wildcards allowed, must not be  <code> NULL </code> .  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> type </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> File type of stream to open or create. Pass  <code> 0 </code>  for wildcard, in which case  <code> sysFileTFileStream </code>  is used if the stream needs to be created and  <code> fileModeTemporary </code>  is not specified. If type is  <code> 0 </code>  and  <code> fileModeTemporary </code>  is specified, then  <code> sysFileTTemp </code>  is used for the file type of the stream this function creates. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> creator </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Creator of stream to open or create. Pass  <code> 0 </code>  for wildcard, in which case the current application's creator ID is used for the creator of the stream this function creates. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> openMode </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Mode in which to open the file stream. You must specify only one primary mode selector. Additionally, you can use the  <code> |  </code> operator (bitwise inclusive OR) to append one or more secondary mode selectors to the primary mode selector. See  "Primary Open Mode Constants"  and  "Secondary Open Mode Constants"  for the list of possible values.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> </code> <br> </td>
    =><td valign="top" align="left" width=""> <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;--&gt;  <code> errP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to variable that is to hold the error code returned by this function. Pass  <code> NULL </code>  to ignore. See the section  "File Streaming Error Codes"  for a list of error codes.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>If successful, returns a handle to an open file stream; otherwise, returns  <code> 0 </code> . 
    =><h4> Comments  </h4>
    =>The  <code> fileModeReadOnly </code> ,  <code> fileModeReadWrite </code> ,  <code> fileModeUpdate </code> , and  <code> fileModeAppend </code>  modes are mutually exclusive--pass only one of them to the  <code> FileOpen </code>  function!  When the  <code> fileModeTemporary </code>  open mode is used and the file type passed to  <code> FileOpen </code>  is  <code> 0 </code> , the  <code> FileOpen </code>  function uses  <code> sysFileTTemp </code>  (defined in  <code> SystemMgr.rh) </code>  for the file type, as recommended. In future versions of Palm OS, this configuration will enable the automatic cleanup of undeleted temporary files after a system crash. Automatic post-crash cleanup is not implemented in current versions of Palm OS.  To open a file stream even if it has a different type and creator than specified, pass the  <code> fileModeAnyTypeCreator </code>  selector as a flag in the  <code> openMode </code>  parameter to the  FileOpen  function.  The  <code> fileModeLeaveOpen </code>  mode is an esoteric option that most applications should not use. It may be useful for a library that needs to open a stream from the current application's context and keep it open even after the current application quits. By default, Palm OS automatically closes all databases that were opened in a particular application's context when that application quits. The  <code> fileModeLeaveOpen </code>  option overrides this default behavior. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  3.0 New Feature Set  is present.  <br> <br> <br> <h3>
FileRead()
    =><h4> Purpose  </h4>
    =>Reads data from a stream into a buffer. Do not use this function to read data into a chunk, record or resource residing in a database--you must use the  FileDmRead  function for such operations. 
    =><h4> Prototype  </h4>
    =><code> Int32 FileRead (FileHand&nbsp;stream, void*&nbsp;bufP, Int32&nbsp;objSize, Int32&nbsp;numObj, Err*&nbsp;errP)  </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> --&gt;  <code> stream </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Handle to open stream.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> --&gt;  <code> bufP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to beginning of buffer into which data is read <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> objSize </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Size of each stream object to read.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> numObj </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Number of stream objects to read.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;--&gt;  <code> errP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to variable that is to hold the error code returned by this function. Pass  <code> NULL </code>  to ignore. See the section  "File Streaming Error Codes"  for a list of error codes.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>The number of whole objects that were read--note that the number of objects actually read may be less than the number requested. 
    =><h4> Comments  </h4>
    =>Do not use this function to read data into a chunk, record or resource residing in a database--you must use the  FileDmRead  function for such operations.  When the number of objects actually read is fewer than the number requested, you may be able to determine the cause of this result by examining the return value of the  <code> errP </code>  parameter or by calling the  FileGetLastError  function. If the cause is insufficient data in the stream to satisfy the full request, the current stream position is at end-of-file and the "end of file" indicator is set. If a non- <code> NULL </code>  pointer was passed as the value of the  <code> errP </code>  parameter when the  <code> FileRead </code>  function was called and an error was encountered,  <code> *errP </code>  holds a non-zero error code when the function returns. In addition, the  FileError  and  FileEOF  functions may be used to check for I/O errors. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  3.0 New Feature Set  is present. 
    =><h4> See Also  </h4>
    =>FileDmRead <br> <br> <br> <h3>
FileRewind()
    =><h4> Purpose  </h4>
    =>Reset position marker to beginning of stream and clear all error codes. 
    =><h4> Prototype  </h4>
    =><code> Err FileRewind (FileHand&nbsp;stream)  </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> --&gt;  <code> stream </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Handle to open stream.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>0 if no error, or a  <code> fileErr  </code> code if an error occurs. See the section  "File Streaming Error Codes"  for more information. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  3.0 New Feature Set  is present. 
    =><h4> See Also  </h4>
    =>FileSeek ,  FileTell ,  FileClearerr ,  FileEOF ,  FileError ,  FileGetLastError <br> <br> <br> <h3>
FileSeek()
    =><h4> Purpose  </h4>
    =>Set current position within a file stream, extending the stream as necessary if it was opened with write access. 
    =><h4> Prototype  </h4>
    =><code> Err FileSeek (FileHand&nbsp;stream, Int32&nbsp;offset, FileOriginEnum&nbsp;origin)  </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> --&gt;  <code> stream </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Handle to open stream.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> offset </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Position to set, expressed as the number of bytes from origin. This value may be positive, negative, or  <code> 0 </code> . <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> origin </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Describes the origin of the position change. Possible values are: <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="35%"> &nbsp;  </td>
    =><td valign="top" align="left" width="25%"> <code> <code> fileOriginBeginning </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> From the beginning (first data byte of file). <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="35%"> &nbsp;  </td>
    =><td valign="top" align="left" width="25%"> <code> <code> fileOriginCurrent </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> From the current position. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="35%"> &nbsp;  </td>
    =><td valign="top" align="left" width="25%"> <code> <code> fileOriginEnd </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> From the end of file (one position beyond last data byte). <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>0 if no error, or a  <code> fileErr  </code> code if an error occurs. See the section  "File Streaming Error Codes"  for more information. 
    =><h4> Comments  </h4>
    =>Attempting to seek beyond end-of-file in a read-only stream results in an I/O error.  This function's behavior is similar to that of the  <code> fseek </code>  function provided by the C programming language runtime library. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  3.0 New Feature Set  is present. 
    =><h4> See Also  </h4>
    =>FileRewind ,  FileTell <br> <br> <br> <h3>
FileTell()
    =><h4> Purpose  </h4>
    =>Get current position and, optionally, file size. 
    =><h4> Prototype  </h4>
    =><code> Int32 FileTell (FileHand&nbsp;stream, Int32*&nbsp;fileSizeP, Err*&nbsp;errP)  </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> --&gt;  <code> stream </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Handle to open stream.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;-&gt;  <code> fileSizeP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to variable that holds value describing size of stream in bytes when this function returns. Pass  <code> NULL </code>  to ignore.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;--&gt;  <code> errP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to variable that is to hold the error code returned by this function. Pass  <code> NULL </code>  to ignore. See the section  "File Streaming Error Codes"  for a list of possible error codes.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>If successful, returns current position, expressed as an offset in bytes from the beginning of the stream. If an error was encountered, returns  <code> -1 </code>  as a signed long integer. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  3.0 New Feature Set  is present. 
    =><h4> See Also  </h4>
    =>FileRewind ,  FileSeek <br> <br> <br> <h3>
FileTruncate()
    =><h4> Purpose  </h4>
    =>Truncate the file stream to a specified size; not allowed on streams open in destructive read mode or read-only mode. 
    =><h4> Prototype  </h4>
    =><code> Err FileTruncate (FileHand&nbsp;stream, Int32&nbsp;newSize)  </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> --&gt;  <code> stream </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Handle of open stream.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> newSize </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> New size; must not exceed current stream size.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>0 if no error, or a  <code> fileErr  </code> code if an error occurs. See the section  "File Streaming Error Codes"  for a list of possible error codes. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  3.0 New Feature Set  is present. 
    =><h4> See Also  </h4>
    =>FileTell <br> <br> <br> <h3>
FileWrite()
    =><h4> Purpose  </h4>
    =>Write data to a stream. 
    =><h4> Prototype  </h4>
    =><code> Int32 FileWrite (FileHand&nbsp;stream, void*&nbsp;dataP, Int32&nbsp;objSize, Int32&nbsp;numObj, Err*&nbsp;errP)  </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> --&gt;  <code> stream </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Handle to open stream.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> --&gt;  <code> dataP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Pointer to buffer holding data to write.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> objSize </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Size of each stream object to write; must be  <kbd> &gt;= </kbd> <code> 0 </code> . <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> numObj </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Number of stream objects to write.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> &lt;--&gt;  <code> errP </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Optional pointer to variable that holds the error code returned by this function. Pass  <code> NULL </code>  to ignore. See the section  "File Streaming Error Codes"  for a list of possible error codes.  <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>The number of whole objects that were written--note that the number of objects actually written may be less than the number requested. Should available storage be insufficient to satisfy the entire request, as much of the requested data as possible is written to the stream, which may result in the last object in the stream being incomplete. 
    =><h4> Comments  </h4>
    =>Writing to files opened without write access or those that are in destructive read state is not allowed; thus, you cannot call the  FileWrite ,  FileSeek , or  FileTruncate  functions on a stream that is in destructive read mode. One exception to this rule applies to streams that were opened in "write + append" mode and then switched into destructive read state. In this case, the  <code> FileWrite </code>  function can append data to the stream, but it also preserves the current stream position so that subsequent reads pick up where they left off (you can think of this as a pseudo-pipe). 
    =><h4> Compatibility  </h4>
    =>Implemented only if  3.0 New Feature Set  is present.  <h2> File Streaming Error Codes </h2> This section lists all error codes returned by the file streaming functions.  <p> </p> <p> <div>
    =><table border="3"> <caption> <br> </caption> <tbody> <tr> <th> <strong> Error Code  </strong> </th> <th> <strong> Value </strong> </th> <th> <strong> Meaning </strong> </th> </tr> <tr>
    =><td> <code> fileErrMemErr  </code> </td>
    =><td> ( <code> fileErrorClass </code> |1)  </td>
    =><td> Out of memory error  </td> </tr> <tr>
    =><td> <code> fileErrInvalidParam </code> </td>
    =><td> ( <code> fileErrorClass </code> |2)  </td>
    =><td> Invalid parameter value passed  </td> </tr> <tr>
    =><td> <code> fileErrCorruptFile  </code> </td>
    =><td> ( <code> fileErrorClass </code> |3)  </td>
    =><td> Alleged stream is corrupted, invalid, or not a stream  </td> </tr> <tr>
    =><td> <code> fileErrNotFound </code> </td>
    =><td> ( <code> fileErrorClass </code> |4)  </td>
    =><td> Couldn't find the stream  </td> </tr> <tr>
    =><td> <code> fileErrTypeCreatorMismatch </code> </td>
    =><td> ( <code> fileErrorClass </code> |5)  </td>
    =><td> Type and/or creator not what was specified  </td> </tr> <tr>
    =><td> <code> fileErrReplaceError </code> </td>
    =><td> ( <code> fileErrorClass </code> |6)  </td>
    =><td> Couldn't replace existing stream  </td> </tr> <tr>
    =><td> <code> fileErrCreateError </code> </td>
    =><td> ( <code> fileErrorClass </code> |7)  </td>
    =><td> Couldn't create new stream  </td> </tr> <tr>
    =><td> <code> fileErrOpenError </code> </td>
    =><td> ( <code> fileErrorClass </code> |8)  </td>
    =><td> Generic open error  </td> </tr> <tr>
    =><td> <code> fileErrInUse </code> </td>
    =><td> ( <code> fileErrorClass </code> |9)  </td>
    =><td> Stream couldn't be opened or deleted because it is in use  </td> </tr> <tr>
    =><td> <code> fileErrReadOnly </code> </td>
    =><td> ( <code> fileErrorClass </code> |10)  </td>
    =><td> Couldn't open in write mode because existing stream is read-only  </td> </tr> <tr>
    =><td> <code> fileErrInvalidDescriptor </code> </td>
    =><td> ( <code> fileErrorClass </code> |11)  </td>
    =><td> Invalid file descriptor  <code> (FileHandle) </code> </td> </tr> <tr>
    =><td> <code> fileErrCloseError </code> </td>
    =><td> ( <code> fileErrorClass </code> |12)  </td>
    =><td> Error closing the stream  </td> </tr> <tr>
    =><td> <code> fileErr </code> OutOfBounds  </td>
    =><td> ( <code> fileErrorClass </code> |13)  </td>
    =><td> Attempted operation went out of bounds of the stream  </td> </tr> <tr>
    =><td> <code> fileErrPermissionDenied </code> </td>
    =><td> ( <code> fileErrorClass </code> |14)  </td>
    =><td> Couldn't write to a stream open for read-only access  </td> </tr> <tr>
    =><td> <code> fileErrIOError </code> </td>
    =><td> ( <code> fileErrorClass </code> |15)  </td>
    =><td> Generic I/O error  </td> </tr> <tr>
    =><td> <code> fileErrEOF </code> </td>
    =><td> ( <code> fileErrorClass </code> |16)  </td>
    =><td> End-of-File error  </td> </tr> <tr>
    =><td> <code> fileErrNotStream </code> </td>
    =><td> ( <code> fileErrorClass </code> |17)  </td>
    =><td> Attempted to open an entity that is not a stream  </td> </tr> </tbody> </table>
    =><table> <tbody> <tr>
    =><td> <br> </td> </tr> </tbody> </table> </div> <br> </p> <h3>
ErrAlert()
    =><h4> Purpose  </h4>
    =>Macro that displays an alert dialog for runtime errors. 
    =><h4> Prototype  </h4>
    =><code> ErrAlert (err) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> err </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> An error code (as type  <code> Err </code> ). <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Returns 0, which indicates that the OK button has been clicked to dismiss the dialog. 
    =><h4> Comments  </h4>
    =>This macro is intended for use by applications that are likely to receive runtime errors when the application itself is not at fault. For example, a networking application might use it to display an alert if the remote server cannot be found.  The error message displayed on the dialog is stored in a 'tSTL' resource. A 'tSTL' resource contains a list of strings that can be looked up by index. The  <code> err </code>  parameter is used as the index into this list.  To use application-defined error codes in  <code> ErrAlert </code> , make sure that all of your error codes are greater than or equal to  <code> appErrorClass </code> . This way, the error manager looks up the code in the application's 'tSTL' resource number 0. All other error codes are taken from 'tSTL' resource stored in the system. 
    =><h4> Compatibility  </h4>
    =>Implemented only if  3.2 New Feature Set  is present.  <br> <br> <br> <br> <h3>
ErrDisplay()
    =><h4> Purpose  </h4>
    =>Macro that displays an error alert if error checking is set to partial or full. 
    =><h4> Prototype  </h4>
    =><code> ErrDisplay (msg) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> msg </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Error message text as a string. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>No return value. 
    =><h4> Comments  </h4>
    =>Call this macro to display an error message, source code filename, and line number. This macro is compiled into the code only if the compiler define  <code> ERROR_CHECK_LEVEL </code>  is set to 1 or 2 ( <code> ERROR_CHECK_PARTIAL </code>  or  <code> ERROR_CHECK_FULL </code> ). 
    =><h4> See Also  </h4>
    =>ErrFatalDisplayIf ,  ErrNonFatalDisplayIf <br> <br> <br> <h3>
ErrDisplayFileLineMsg()
    =><h4> Purpose  </h4>
    =>Display a nonexitable dialog with an error message. Do not allow the user to continue. 
    =><h4> Prototype  </h4>
    =><code> void ErrDisplayFileLineMsg (const&nbsp;Char&nbsp;*&nbsp;const&nbsp;filename, UInt16&nbsp;lineno, const&nbsp;Char&nbsp;*&nbsp;const&nbsp;msg) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> filename </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Source code filename.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> lineno </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Line number in the source code file.  <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> msg </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Message to display. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Never returns. 
    =><h4> Comment </h4>
    =>Called by  ErrFatalDisplayIf  and  ErrNonFatalDisplayIf . This function is useful when the application is already on the device and being tested by users.  On Japanese systems, the system displays a generic message indicating that an error has occurred instead of displaying the English message. 
    =><h4> See Also </h4>
    =>ErrFatalDisplayIf ,  ErrNonFatalDisplayIf ,  ErrDisplay <br> <br> <br> <h3>
ErrFatalDisplayIf()
    =><h4> Purpose  </h4>
    =>Macro that displays an error alert dialog if  <code> condition </code>  is  <code> true </code>  and error checking is set to partial or full. 
    =><h4> Prototype  </h4>
    =><code> ErrFatalDisplayIf (condition, msg) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> condition </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A boolean value. If  <code> true </code> , display the error. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> msg </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Error message text as a string. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>No return value. 
    =><h4> Comments  </h4>
    =>Call this macro to display a fatal error message, source code filename, and line number. The alert is displayed only if  <code> condition </code>  is  <code> true </code> . The dialog is cleared only when the user resets the system by responding to the dialog.  This macro is compiled into the code if the compiler define  <code> ERROR_CHECK_LEVEL </code>  is set to 1 or 2 ( <code> ERROR_CHECK_PARTIAL </code>  or  <code> ERROR_CHECK_FULL </code> ). 
    =><h4> See Also  </h4>
    =>ErrNonFatalDisplayIf ,  ErrDisplay ,  <br> <br> <br> <h3>
ErrNonFatalDisplayIf()
    =><h4> Purpose  </h4>
    =>Macro that displays an error alert dialog if condition is  <code> true </code>  and error checking is set to full. 
    =><h4> Prototype  </h4>
    =><code> ErrNonFatalDisplayIf (condition, msg) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> condition </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> A boolean value. If  <code> true </code> , display the error. <br> </td> </tr> </tbody> </table>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> msg </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Error message text as a string. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>No return value. 
    =><h4> Comments  </h4>
    =>Call this macro to display a nonfatal error message, source code filename, and line number. The alert is displayed only if  <code> condition </code>  is  <code> true </code> . The alert dialog is cleared when the user selects to continue (or resets the system).  This macro is compiled into the code only if the compiler define  <code> ERROR_CHECK_LEVEL </code>  is set to 2 ( <code> ERROR_CHECK_FULL </code> ). 
    =><h4> See Also  </h4>
    =>ErrFatalDisplayIf ,  ErrDisplay ,  <br> <br> <br> <h3>
ErrThrow()
    =><h4> Purpose  </h4>
    =>Cause a jump to the nearest Catch block. 
    =><h4> Prototype  </h4>
    =><code> void ErrThrow (Int32&nbsp;err) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> -&gt;  <code> err </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Error code. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Never returns. 
    =><h4> Comments  </h4>
    =>Use the macros ErrTry, ErrCatch, and ErrEndCatch in conjunction with this function. 
    =><h4> See Also  </h4>
    =>ErrFatalDisplayIf ,  ErrNonFatalDisplayIf ,  ErrDisplay <strong> </strong> <br> <p> <br> </p> <h3>
SysAppLauncherDialog()
    =><h4> Purpose  </h4>
    =>Display the launcher popup, get a choice, ask the system to launch the selected application, clean up, and leave. If there are no applications to launch, nothing happens. 
    =><h4> Prototype  </h4>
    =><code> void SysAppLauncherDialog() </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> </code> <br> </td>
    =><td valign="top" align="left" width=""> <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>The system may be asked to launch an application. 
    =><h4> Comments  </h4>
    =>Typically, this routine is called by the system as necessary. Most applications do not need to call this function themselves.  In Palm OS <sup> &reg; </sup>  version 3.0 and higher the launcher is an application, rather than a popup. This function remains available for compatibility purposes only. 
    =><h4> See Also  </h4>
    =>SysAppLaunch , the  "Application Launcher"  section in the  <em> Palm OS Programmer's Companion </em> <br> <br> <br> <h3>
SysFatalAlert()
    =><h4> Purpose  </h4>
    =>Display a fatal alert until the user taps a button in the alert. 
    =><h4> Prototype  </h4>
    =><code> UInt16 SysFatalAlert (const&nbsp;Char&nbsp;*msg) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> msg </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Message to display in the dialog. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>The button tapped; first button is zero.  <br> <br> <br> <h3>
SysGraffitiReferenceDialog()
    =><h4> Purpose  </h4>
    =>Pop up the Graffiti <sup> &reg; </sup>  Reference Dialog. 
    =><h4> Prototype  </h4>
    =><code> void SysGraffitiReferenceDialog (ReferenceType&nbsp;referenceType) </code>
    =><h4> Parameters  </h4>
    =><table width="95%"> <tbody> <tr>
    =><td valign="top" align="right" width="5%"> &nbsp;  </td>
    =><td valign="top" align="left" width="30%"> <code> <code> referenceType </code> </code> <br> </td>
    =><td valign="top" align="left" width=""> Which reference to display. See  <code> GraffitiReference.h </code>  for more information. <br> </td> </tr> </tbody> </table>
    =><h4> Result  </h4>
    =>Nothing returned.  <strong> </strong> <br> <br> <br> <br> <br> <br> <br>
