Tech Note 14: Using the NSBSystemLib Shared Library

July 25, 2005

© 2009 NS BASIC Corporation. All rights reserved.

Contents:

    Introduction
    Function Index and Quick Reference
    Function Reference

Introduction:

The NSBSystemLib Shared Library contains functions that provide access to the PalmOS System. Some of these functions allow calls to PalmOS APIs that can not currently be called using NSBasic's SysTrap statements. Others, just provide a simplified interface to the PalmOS.

The functions in this library are divided into the following categories:

Alarms, Databases, Events, Field and Forms, HotSync Data, Localization, Preferences, Progress Manager, and System Time. With the version 2.0 release, additional categories for bitwise, encryption, decryption, and screen/color operations have been added.

This document, with its examples, should provide all the information necessary to use the functions in the NSBSystemLib. If more information about the underlying PalmOS functions is desired, please consult the PalmOS SDK Reference or the SDK C header files (*.h). The PalmOS SDK Reference can be downloaded from:

    http://www.palmos.com/dev/tech/docs/
The PalmOS SDK (Software Development Kit) can be downloaded from:
    http://www.palmos.com/dev/tech/tools/

In order to use the NSBSystemLib Shared Library, the library must be loaded using the NSBasic LoadLibrary statement. This statement should be located in the program's Startup code so that the functions will be available throughout the program. The LoadLibrary statement has an optional second parameter to allow you to specify an abbreviated reference name for the library's functions. The examples in this document use "NSL" for this reference name. Example:

Program's Startup code:

	Sub main()
	    LoadLibrary "NSBSystemLib", "NSL"
	End Sub

Also, in order to use the NSBSystemLib Shared Library, the NSBSystemLib.INF file must be present in your "nsbasic\lib" directory and the NSBSystemLib.prc file must be downloaded to your device.

Except for the functions that return version numbers, all the parameter and return data types are either "Integer" or "String". Version numbers are returned as a "Double".


Function Index and Quick Reference:

Version Information
        Version version = Version()
        CompileInfo compileDateTime = CompileInfo()
        SystemVersion version = SystemVersion()
Access To Shared Library Global Variables
        GlobalVersionMajor gblMajor = GlobalVersionMajor()
        GlobalVersionMinor gblMinor = GlobalVersionMinor()
        GlobalY x = GlobalX()
        GlobalX y = GlobalY()
        GlobalStartX startX = GlobalStartX()
        GlobalStartY startY = GlobalStartY()
        GlobalEndX endX = GlobalEndX()
        GlobalEndY endY = GlobalEndY()
        GlobalStartPos startPos = GlobalStartPos()
        GlobalEndPos endPos = GlobalEndPos()
        GlobalWidth width = GlobalWidth()
        GlobalHeight height = GlobalHeight()
        GlobalHour gblHour = GlobalHour()
        GlobalMinute gblMinute = GlobalMinute()
Alarm Functions
        SetAlarmReset SetAlarmReset resetTime, resetLimit
        SetAlarm status = SetAlarm(alarmPgm, alarmTime, alarmCmd, alarmMsg)
        CancelAlarm status = CancelAlarm(alarmPgm)
        GetAlarm alarmTime = GetAlarm(alarmPgm, alarmCmd, alarmMsg)
        GetAlarmTime alarmTime = GetAlarmTime(alarmPgm)
        GetAlarmResetTime resetTime = GetAlarmResetTime(alarmPgm)
        GetAlarmResetLimit resetLimit = GetAlarmResetLimit(alarmPgm)
        GetAlarmCommand alarmCmd = GetAlarmCommand(alarmPgm)
        GetAlarmMessage alarmMsg = GetAlarmMessage(alarmPgm)
        AlarmLog alarmTime = AlarmLog(alarmPgm, alarmCmd, alarmMsg)
        AlarmLogAlarmTime alarmTime = AlarmLogAlarmTime(alarmPgm)
        AlarmLogResetTime resetTime = AlarmLogResetTime(alarmPgm)
        AlarmLogResetLimit resetLimit = AlarmLogResetLimit(alarmPgm)
        AlarmLogResetCount resetCount = AlarmLogResetCount(alarmPgm)
        AlarmLogCommand alarmCmd = AlarmLogCommand(alarmPgm)
        AlarmLogMessage alarmMsg = AlarmLogMessage(alarmPgm)
        ClearAlarmLog alarmPgm = ClearAlarmLog()
Database Functions
        FindDatabase dbID = FindDatabase(cardNo, dbName)
        DatabaseInfo dbName = DatabaseInfo(cardNo, dbID)
        DatabaseName dbName = DatabaseName()
        DatabaseAttributes dbAttributes = DatabaseAttributes()
        DatabaseVersion dbVersion = DatabaseVersion()
        DatabaseCreationDate dbCreationDate = DatabaseCreationDate()
        DatabaseModificationDate dbModificationDate = DatabaseModificationDate()
        DatabaseBackupDate dbBackupDate = DatabaseBackupDate()
        DatabaseModificationNumber dbModificationNumber = DatabaseModificationNumber()
        DatabaseAppInfoID dbAppInfoID = DatabaseAppInfoID()
        DatabaseSortInfoID dbSortInfoID = DatabaseSortInfoID()
        DatabaseType dbType = DatabaseType()
        DatabaseCreatorID dbCreatorID = DatabaseCreatorID()
        DatabaseTotalSize dbTotalSize = DatabaseTotalSize(cardNo, dbID)
        DatabaseNumRecords dbNumRecords = DatabaseNumRecords()
        DatabaseDataSize dbDataSize = DatabaseDataSize()
        DeleteDatabase status = DeleteDatabase(cardNo, dbID)
        GetNextDatabaseByTypeCreator dbID = GetNextDatabaseByTypeCreator(newSearch, dbType, dbCreatorID, onlyLatestVersion)
        DatabaseCardNo dbCardNo = DatabaseCardNo()
        NumDatabases nbr = NumDatabases(cardNo)
        NumCards nbr = NumCards()
        GetDatabase dbID = GetDatabase(cardNo, index)
        SetDatabaseName status = SetDatabaseName(cardNo, dbID, dbName)
        SetDatabaseAttributes status = SetDatabaseAttributes(cardNo, dbID, dbAttributes)
        SetDatabaseVersion status = SetDatabaseVersion(cardNo, dbID, dbVersion)
        SetDatabaseCreationDate status = SetDatabaseCreationDate(cardNo, dbID, dbCreationDate)
        SetDatabaseModificationDate status = SetDatabaseModificationDate(cardNo, dbID, dbModificationDate)
        SetDatabaseBackupDate status = SetDatabaseBackupDate(cardNo, dbID, dbBackupDate)
        SetDatabaseModificationNumber status = SetDatabaseModificationNumber(cardNo, dbID, dbModificationNumber)
        SetDatabaseAppInfoID status = SetDatabaseAppInfoID(cardNo, dbID, dbAppInfoID)
        SetDatabaseSortInfoID status = SetDatabaseSortInfoID(cardNo, dbID, dbSortInfoID)
        SetDatabaseType status = SetDatabaseType(cardNo, dbID, dbType)
        SetDatabaseCreatorID status = SetDatabaseCreatorID(cardNo, dbID, dbCreatorID)
Event Functions
        GetEvent eventType = GetEvent(timeoutTicks, consumePenEvents, returnVirtualEvents)
        SysHandleEvent SysHandleEvent()
        FlushEvents FlushEvents()
        KeyEventChr keyChr = KeyEventChr()
        KeyEventKeyCode keyCode = KeyEventKeyCode()
        KeyEventModifiers modifiers = KeyEventModifiers()
Field and Form Functions
        ControlHitControl ControlHitControl objID
        FieldCopy FieldCopy objID
        FieldCut FieldCut objID
        FieldInsert FieldInsert objID, insString
        FieldPaste FieldPaste objID
        FieldUndo FieldUndo objID
        FieldGetInsPtPosition pos = FieldGetInsPtPosition(objID)
        FieldGetSelection startPos = FieldGetSelection(objID)
        FieldAnyDirty dirty = FieldAnyDirty()
        FieldDirty dirty = FieldDirty(objID)
        FieldSetDirty FieldSetDirty objID, dirty
        FieldSetAllDirty FieldSetAllDirty dirty
        FieldSetSelection FieldSetSelection objID, startPos, endPos
        FieldSetInsertionPoint FieldSetInsertionPoint objID, pos
        FieldSetInsPtPosition FieldSetInsPtPosition objID, pos
        FieldGetAttributes attributes = FieldGetAttributes(objID)
        FieldSetAttributes FieldSetAttributes objID, attributes
        FieldGetFont fontId = FieldGetFont(objID)
        FieldSetFont FieldSetFont objID, fontId
        FieldGetScrollPosition position = FieldGetScrollPosition(objID)
        FieldSetScrollPosition FieldSetScrollPosition objID, position
        FieldGetScrollValues totalLines = FieldGetScrollValues(objID)
        FieldGetVisibleLines lines = FieldGetVisibleLines(objID)
        FieldGetNumberOfBlankLines lines = FieldGetNumberOfBlankLines(objID)
        FieldScrollable yesNo = FieldScrollable(objID, direction)
        FieldScrollField FieldScrollField objID, nbrLines, direction
        FieldSetBounds FieldSetBounds objID, topLeftX, topLeftY, width, height
        FormGetNumberOfObjects nbr = FormGetNumberOfObjects()
        FormGetObjectBounds x = FormGetObjectBounds(objID)
        FormGetObjectPosition x = FormGetObjectPosition(objID)
        FormGetObjectType type = FormGetObjectType(objID)
        FormSetObjectPosition FormSetObjectPosition objID, x, y
        FormSetObjectBounds FormSetObjectBounds objID, topLeftX, topLeftY, width, height
        FormGetTitle title = FormGetTitle()
        FormReplaceTitle FormReplaceTitle title, forceLength
        ListGetTopItem topItem = ListGetTopItem(objID)
        ListSetTopItem ListSetTopItem objID, topItem
        ListGetVisibleItems visibleItems = ListGetVisibleItems(objID)
        ListScrollList result = ListScrollList(objID, direction, nbrItems)
Font Support
        FontGetFont fontId = FontGetFont()
        FontSetFont oldFontId = FontSetFont(fontId)
        FontSelect fontId = FontSelect()
        FontCharWidth width = FontCharWidth(charString)
        FontCharsWidth width = FontCharsWidth(charString, optionalLen)
        FontWidthToOffset offset = FontWidthToOffset(charString, optionalLen, width)
        FontCharsInWidth length = FontCharsInWidth(charString, optionalLen, width)
        FontWordWrap length = FontWordWrap(charString, width)
HotSync Data
        SyncUserName userName = SyncUserName()
        SuccessfulSync syncDate = SuccessfulSync()
        LastSync syncDate = LastSync()
Localization Functions
        LocalizeNumber localNbrStr = LocalizeNumber(stdNbrStr)
        DelocalizeNumber stdNbrStr = DelocalizeNumber(localNbrStr)
        LocalizeDate localDateStr = LocalizeDate(stdDateStr, ToDateFormat, longDateFormat)
Preference Functions
        GetAppPreferences data = GetAppPreferences(pgmName, prefId, saved)
        SetAppPreferences status = SetAppPreferences(pgmName, prefId, data, saved)
        GetSysPreference data = GetSysPreference(prefID)
        SetSysPreference SetSysPreference prefID, data
Progress Manager Functions
        ProgressStartDialog ProgressStartDialog title
        ProgressStopDialog ProgressStopDialog force
        ProgressUpdateDialog ProgressUpdateDialog error, message
        ProgressUserCancel canceled = ProgressUserCancel()
        ProgressPercent percent = ProgressPercent(current, count)
        ProgressPercentString strValue = ProgressPercentString(percent, resolution, completeChar, incompleteChar)
String Functions
        String4ToInt intValue = String4ToInt(fourByteString)
        IntToString4 fourByteString = IntToString4(intValue)
        DelimitedItem item = DelimitedItem(inputStr, delimiter, nbr)
        FixedWidthString fixedStr = FixedWidthString(origStr, width, options)
        NormalSpacedString normalStr = NormalSpacedString(origStr)
System Time Functions
        SelectOneTime newTimeSelected = SelectOneTime(defHour, defMinute, title)
        IncrementSystemTime newSysTime = IncrementSystemTime(oldSysTime, hours, minutes, seconds)
        SystemTime sysTime = SystemTime(strDate, strTime, seconds, ToDateFormat)
        StringDateTime strDateTime = StringDateTime(sysTime, ToDateFormat, ToTimeFormat, AMPMFormat)
        StringDate strDate = StringDate(sysTime, ToDateFormat)
        StringTime strTime = StringTime(sysTime, ToTimeFormat, AMPMFormat)
Version 1.4 Changes and Additions
        PostEvent PostEvent eventNbr
        FormGetFocus objID = FormGetFocus()
        FieldGetTextLength txtLen = FieldGetTextLength(objID)
        RandomNumber nbr = RandomNumber(seed, minNbr, maxNbr)
        ResetAutoOffTimer ResetAutoOffTimer()
        SetAutoOffTime oldSeconds = SetAutoOffTime(newSeconds)
        ProgramVersionString verStr = ProgramVersionString(cardNbr, pgmName)
        DynamicHeapSize heapSize = DynamicHeapSize()
        DynamicHeapFree freeSize = DynamicHeapFree()
        DynamicHeapMaxChunk maxChunkSize = DynamicHeapMaxChunk()
        SortInit error = SortInit(maxItems, itemType)
        SortAddString error = SortAddString(strItem)
        SortAddInteger error = SortAddInteger(intItem)
        SortAddDouble error = SortAddDouble(dblItem)
        SortGetString strItem = SortGetString(index)
        SortGetInteger intItem = SortGetInteger(index)
        SortGetDouble dblItem = SortGetDouble(index)
        SortQSort numItems = SortQSort(reverseSort, caselessSort)
        SortInsertionSort numItems = SortInsertionSort(reverseSort, caselessSort)
        ListQSort numItems = ListQSort(objID, reverseSort, caselessSort)
        ListInsertionSort numItems = ListInsertionSort(objID, reverseSort, caselessSort)
Version 2.0 Changes and Additions
        FormGetAllObjectTypes type = FormGetAllObjectTypes(objID)
        FieldClearAll FieldClearAll()
        ObjectWithPoint obj = ObjectWithPoint(x, y, returnType, searchOption)
        ANDInt result = ANDInt(int1, int2)
        ORInt result = ORInt(int1, int2)
        XORInt result = XORInt(int1, int2)
        OnesComplement result = OnesComplement(intValue)
        BitValue result = BitValue(intValue, bitNumber)
        BitsValue result = BitsValue(intValue, startBit, endBit)
        SetBitValue result = SetBitValue(intValue, bitNumber, bitValue)
        SetBitsValue result = SetBitsValue(intValue, bitsValue, startBit, endBit)
        IntToHex hexValue = IntToHex(intValue, trimLeading)
        HexToInt intValue = HexToInt(hexValue)
        IntToBin binValue = IntToBin(intValue, trimLeading)
        BinToInt intValue = BinToInt(binValue)
Screen and Color Functions
        GetSupportedDepths depths = GetSupportedDepths()
        DepthSupported boolean = DepthSupported(depth)
        ColorSupported boolean = ColorSupported()
        SetDepth SetDepth depth
        SetColor SetColor boolean
        SaveScreenMode SaveScreenMode()
        RestoreScreenMode RestoreScreenMode()
        CurrentDepth depth = CurrentDepth()
        CurrentColor boolean = CurrentColor()
        SetToDefaults SetToDefaults()
        DefaultDepth depth = DefaultDepth()
        DefaultColor boolean = DefaultColor()
        GetTableEntryIndex index = GetTableEntryIndex(which)
        GetTableEntryRGB index = GetTableEntryRGB(which)
        GetRGBIndex index = GetRGBIndex()
        GetRGBRed red = GetRGBRed()
        GetRGBGreen green = GetRGBGreen()
        GetRGBBlue blue = GetRGBBlue()
        SetTableEntryIndex SetTableEntryIndex which, index
        SetTableEntryRGB SetTableEntryRGB which, red, green, blue
        BrightnessAdjust BrightnessAdjust()
        ContrastAdjust ContrastAdjust()
        PickColorIndex changed = PickColorIndex(index, title)
        PickColorRGB changed = PickColorRGB(red, green, blue, title)
        IndexToRGB IndexToRGB index
        RGBToIndex index = RGBToIndex(red, green, blue)
        SetForeColor oldIndex = SetForeColor(newIndex)
        SetBackColor oldIndex = SetBackColor(newIndex)
        SetTextColor oldIndex = SetTextColor(newIndex)
        DrawLine DrawLine x1, y1, x2, y2
        DrawGrayLine DrawGrayLine x1, y1, x2, y2
        EraseLine EraseLine x1, y1, x2, y2
        InvertLine InvertLine x1, y1, x2, y2
        DrawPixel DrawPixel x, y
        ErasePixel ErasePixel x, y
        InvertPixel InvertPixel x, y
        GetPixel index = GetPixel(x, y)
        ScreenLock success = ScreenLock(mode)
        ScreenUnlock ScreenUnlock()
        WinSaveBits WinSaveBits index, x, y, width, height
        WinRestoreBits WinRestoreBits index, x, y
Sleep and Wake Event Functions
        SetSleepEvent SetSleepEvent eventNbr
        SetWakeEvent SetWakeEvent eventNbr
        GetSleepEvent eventNbr = GetSleepEvent()
        GetWakeEvent eventNbr = GetWakeEvent()
        GetSleepEventTime eventTime = GetSleepEventTime()
        GetWakeEventTime eventTime = GetWakeEventTime()
String Encryption and Decryption Functions
        EncryptDESString encryptedStr = EncryptDESString(decryptedStr)
        DecryptDESString decryptedStr = DecryptDESString(encryptedStr)
        SetDESKey SetDESKey keyStr

NSBSystemLib Function Reference:


Version Information

The version information functions provide information about the version of the NSBSystemLib Shared Library and about the user's PalmOS System.

Version

version = NSBSystemLib.Version()
Returns the version number of the NSBSystemLib Shared Library.

Returns version as Double

Example Dim version as Double version = NSL.Version()

CompileInfo

compileDateTime = NSBSystemLib.CompileInfo()
Returns the date and time that the NSBSystemLib was compiled.

Returns compileDateTime as String

Example Dim compileDateTime as String compileDateTime = NSL.CompileInfo()

SystemVersion

version = NSBSystemLib.SystemVersion()
Returns the version number of the PalmOS system.

Returns version as Double

Example Dim version as Double version = NSL.SystemVersion()

See also: GlobalVersionMajor(), GlobalVersionMinor()

Access To Shared Library Global Variables

Currently, shared libraries may return only one numeric value from a function call. A number of functions in this library, however, have multiple numeric values that they retrieve. In order to make these values available, they are stored as a library global variable. The following functions return the values of these global variables.

In general, the global access functions are used after making a specific function call.

GlobalVersionMajor

gblMajor = NSBSystemLib.GlobalVersionMajor()
Returns the major version number portion of the PalmOS version. This value is stored as a library global variable at library load time.

Returns gblMajor as Integer

Example Dim gblMajor as Integer gblMajor = NSL.GlobalVersionMajor()

See also: SystemVersion()

GlobalVersionMinor

gblMinor = NSBSystemLib.GlobalVersionMinor()
Returns the minor version number portion of the PalmOS version. This value is stored as a library global variable at library load time.

Returns gblMinor as Integer

Example Dim gblMinor as Integer gblMinor = NSL.GlobalVersionMinor()

See also: SystemVersion()

GlobalX

x = NSBSystemLib.GlobalX()
Returns the value of the global variable "x" in the NSBSystemLib Shared Library.

Returns x as Integer

Example Dim x as Integer x = NSL.GlobalX()

GlobalY

y = NSBSystemLib.GlobalY()
Returns the value of the global variable "y" in the NSBSystemLib Shared Library.

Returns y as Integer

Example Dim y as Integer y = NSL.GlobalY()

GlobalStartX

startX = NSBSystemLib.GlobalStartX()
Returns the value of the global variable "startX" in the NSBSystemLib Shared Library.

Returns startX as Integer

Example Dim startX as Integer startX = NSL.GlobalStartX()

GlobalStartY

startY = NSBSystemLib.GlobalStartY()
Returns the value of the global variable "startY" in the NSBSystemLib Shared Library.

Returns startY as Integer

Example Dim startY as Integer startY = NSL.GlobalStartY()

GlobalEndX

endX = NSBSystemLib.GlobalEndX()
Returns the value of the global variable "endX" in the NSBSystemLib Shared Library.

Returns endX as Integer

Example Dim endX as Integer endX = NSL.GlobalEndX()

GlobalEndY

endY = NSBSystemLib.GlobalEndY()
Returns the value of the global variable "endY" in the NSBSystemLib Shared Library.

Returns endY as Integer

Example Dim endY as Integer endY = NSL.GlobalEndY()

GlobalStartPos

startPos = NSBSystemLib.GlobalStartPos()
Returns the value of the global variable "startPos" in the NSBSystemLib Shared Library.

Returns startPos as Integer

Example Dim startPos as Integer startPos = NSL.GlobalStartPos()

GlobalEndPos

endPos = NSBSystemLib.GlobalEndPos()
Returns the value of the global variable "endPos" in the NSBSystemLib Shared Library.

Returns endPos as Integer

Example Dim endPos as Integer endPos = NSL.GlobalEndPos()

GlobalWidth

width = NSBSystemLib.GlobalWidth()
Returns the value of the global variable "width" in the NSBSystemLib Shared Library.

Returns width as Integer

Example Dim width as Integer width = NSL.GlobalWidth()

GlobalHeight

height = NSBSystemLib.GlobalHeight()
Returns the value of the global variable "height" in the NSBSystemLib Shared Library.

Returns height as Integer

Example Dim height as Integer height = NSL.GlobalHeight()

GlobalHour

gblHour = NSBSystemLib.GlobalHour()
Returns the value of the global variable "hour" in the NSBSystemLib Shared Library.

Returns gblHour as Integer

Example Dim gblHour as Integer gblHour = NSL.GlobalHour()

See also: SelectOneTime()

GlobalMinute

gblMinute = NSBSystemLib.GlobalMinute()
Returns the value of the global variable "minute" in the NSBSystemLib Shared Library.

Returns gblMinute as Integer

Example Dim gblMinute as Integer gblMinute = NSL.GlobalMinute()

See also: SelectOneTime()

Alarm Functions

Alarms, under PalmOS, are implemented by the system calling a program as a specially launched subprogram. As such, a program must be written specifically to be able to process alarms. Some of the requirements of such a program include the acceptance of special launch codes and the inability to access any global variables. NSBasic programs can not currently adhere to these requirements and thus, can not process alarms by themselves. NSBasic programs can, however, utilize alarms by using alarm "proxy" programs.

An alarm proxy program, as its name implies, acts on behalf of an NSBasic program. The alarm functions described here, are intended to be used with the NSBAlarmProxy programs that are distributed with this library. Currently, PalmOS only supports one active alarm for any one particular program. For this reason, there are 5 NSBAlarmProxy programs available. With 5 proxy programs, your single NSBasic program can set up to 5 active alarms, you can have 5 NSBasic programs, each with 1 active alarm, or any other combination. If you are only setting one alarm, then you only need to install one alarm proxy program. The NSBAlarmProxy programs are named:
NSBAlarmProxy1, NSBAlarmProxy2, NSBAlarmProxy3, NSBAlarmProxy4, and NSBAlarmProxy5
The NSBAlarmProxy programs can do a number of different things on behalf of your NSBasic program. They can just simply wake up a device, sound an alarm, display an alert, start a named program, or enqueue an event that can be detected by a running NSBasic program. Alarms can also be set to automatically reset or reschedule themselves. By using the reset feature with event enqueueing, you can easily implement a crude "interrupt timer".

In most cases, when an alarm is triggered, the alarm proxy program will write a "log" of its activity. This log is written to the proxy program's application preferences. As such, only the last activity will be available and no separate database is created. This information can be used for a variety of purposes. One of which is to determine if your NSBasic program was started by a user or by an alarm. This is done in your startup code by checking the alarm's log time against the current time. If they are the same, or reasonably close, and your program's name is also in the log, then you can conclude that your program was started by an alarm. With this information, you can choose to have your program start with a different form than normal or some other alternate startup processing.

SetAlarmReset

NSBSystemLib.SetAlarmReset resetTime, resetLimit
Establishes an automatic alarm reset interval for the next alarm that is set.

Parameters resetTime as Integer Reset interval in seconds 0 = do not automatically reset alarm resetLimit as Integer Limit to the number of automatic resets that can occur. -1 = resets are not limited - CancelAlarm() must be used to stop automatic resets. 0 = do not automatically reset alarm

Example Dim resetTime as Integer Dim resetLimit as Integer resetTime = 10 resetLimit = -1 NSL.SetAlarmReset resetTime, resetLimit

If this feature is to be used, it must be called before each SetAlarm() function.

Note: Care should be taken when using automatic resets to avoid a potential infinite loop. This is especially true when the alarm enqueues events. An infinite loop can occur when alarms occur at a rate faster than they can be processed. In general, reset intervals should not be less than 2 seconds.

SetAlarm

status = NSBSystemLib.SetAlarm(alarmPgm, alarmTime, alarmCmd, alarmMsg)
Sets an alarm for the specified program. The alarm features in this library are intended to be used only with the NSBAlarmProxy programs. While it is possible to use these functions with other programs, it is highly discouraged. This is because these functions write to the program's application preferences. Non-proxy programs that may use the same preferences may become corrupt and require a hard reset and restoration. The program names have not been restricted to allow for future additional alarm proxy programs.

Parameters alarmPgm as String Alarm program. alarmTime as Integer Absolute alarm time in system time format or a time increment in seconds from the current time. This time is considered as an absolute time if its value is greater or equal to the value of the current system time minus 5 minutes. alarmCmd as Integer Alarm Command explanations: -32767 to -30001 = "Timer" commands These commands have the least amount of overhead associated with them. They do not write to the alarm log information. In addition, they automat- ically reset the alarm. As such, they must be specifically cancelled using the CancelAlarm() function. These commands queue an event which is the absolute (positive) value of the command. The reset interval (seconds) used is calculated as: abs(cmd) - 30000 example: -30005 has a reset interval of 5 seconds and queues an event with an event type of 30005. 0 = enqueue a "nilEvent" - can be used to just simply wake up or turn on a PalmOS device 1 = sound a system alarm sound only 2 = sound a system alarm sound and produce an Alert with the message specified in the alarmMsg parameter. 3 = start the program with the name specified in the alarmMsg parameter. The alarmMsg parameter, in this case, is a coded string with the following format: <programName>[,<launcherWaitTime>][;<userInfo>] examples: "Address" "Address;started by MyProg" "Address,6;started by MyProg" notes: The launcherWaitTime is the time, in in seconds to wait for the current program to terminate - the default is 2 seconds. The userInfo, as well as the entire string, is written to the alarmLog. It can be used for any purpose you like. 4 to 255 = enqueue a Key Event with a value equal to the specified alarmCmd 24832 to 30000 = enqueue a generic event with an event type equal to the specified alarmCmd. alarmMsg as String A string of 80 characters or less that is used as the message for alarmCmd 2 or the program code for alarmCmd 3. It is also written to the alarm log to provide any info. that may be useful.

Returns status as Integer 0 = no error -1 = specified alarm program is not installed -2 = almErrorMemory - insufficient memory -3 = almErrorFull - alarm queue is full -4 = unexpected/unrecognized error

Example Dim status as Integer Dim alarmPgm as String Dim alarmTime as Integer Dim alarmCmd as Integer Dim alarmMsg as String alarmPgm = "NSBAlarmProxy1" alarmTime = 3600 ' 1 hour from now alarmCmd = 3 alarmMsg = "Hey Wake UP!" status = NSL.SetAlarm(alarmPgm, alarmTime, alarmCmd, alarmMsg)

See also: SystemTime()

Note: Care should be taken when using automatic resets to avoid a potential infinite loop. This is especially true when the alarm enqueues events. An infinite loop can occur when alarms occur at a rate faster than they can be processed. In general, reset intervals should not be less than 2 seconds.

CancelAlarm

status = NSBSystemLib.CancelAlarm(alarmPgm)
Cancel an alarm set, if any, for the specified program.

Parameter alarmPgm as String Alarm program.

Returns status as Integer 0 = no error -1 = specified alarm program is not installed -2 = almErrorMemory - insufficient memory -3 = almErrorFull - alarm queue is full -4 = unexpected/unrecognized error

Example Dim status as Integer Dim alarmPgm as String alarmPgm = "NSBAlarmProxy1" status = NSL.CancelAlarm(alarmPgm)

GetAlarm

alarmTime = NSBSystemLib.GetAlarm(alarmPgm, alarmCmd, alarmMsg)
Retrieves information about a currently set alarm.

Parameters alarmPgm as String Alarm program. alarmCmd as String AlarmCmd as a string. This value is returned and must be initialized to a maximum length before calling the function. This value should never be more than 6 characters in length. alarmMsg as String Alarm message as a string. This value is returned and must be initialized to a maximum length before calling the function. This value should never be more than 80 characters in length.

Returns alarmTime as Integer Alarm time in system time format. This value is expressed as the number of seconds since January 1st, 1904.

Example Dim alarmTime as Integer Dim alarmPgm as String Dim alarmCmd as String Dim alarmMsg as String alarmPgm = "NSBAlarmProxy1" alarmCmd = "123456" alarmMsg = "1234567890123456789012345678901234567890" _ + "1234567890123456789012345678901234567890" alarmTime = NSL.GetAlarm(alarmPgm, alarmCmd, alarmMsg)

See also: StringDateTime(), StringDate(), StringTime()

GetAlarmTime

alarmTime = NSBSystemLib.GetAlarmTime(alarmPgm)
Retrieves information about a currently set alarm.

Parameter alarmPgm as String Alarm program.

Returns alarmTime as Integer Alarm time in system time format. This value is expressed as the number of seconds since January 1st, 1904.

Example Dim alarmTime as Integer Dim alarmPgm as String alarmPgm = "NSBAlarmProxy1" alarmTime = NSL.GetAlarmTime(alarmPgm)

See also: StringDateTime(), StringDate(), StringTime()

GetAlarmResetTime

resetTime = NSBSystemLib.GetAlarmResetTime(alarmPgm)
Retrieves information about a currently set alarm.

Parameter alarmPgm as String Alarm program.

Returns resetTime as Integer Alarm reset time in seconds.

Example Dim resetTime as Integer Dim alarmPgm as String alarmPgm = "NSBAlarmProxy1" resetTime = NSL.GetAlarmResetTime(alarmPgm)

GetAlarmResetLimit

resetLimit = NSBSystemLib.GetAlarmResetLimit(alarmPgm)
Retrieves information about a currently set alarm.

Parameter alarmPgm as String Alarm program.

Returns resetLimit as Integer Alarm reset limit.

Example Dim resetLimit as Integer Dim alarmPgm as String alarmPgm = "NSBAlarmProxy1" resetLimit = NSL.GetAlarmResetLimit(alarmPgm)

GetAlarmCommand

alarmCmd = NSBSystemLib.GetAlarmCommand(alarmPgm)
Retrieves information about a currently set alarm.

Parameter alarmPgm as String Alarm program.

Returns alarmCmd as Integer Alarm command.

Example Dim alarmCmd as Integer Dim alarmPgm as String alarmPgm = "NSBAlarmProxy1" alarmCmd = NSL.GetAlarmCommand(alarmPgm)

GetAlarmMessage

alarmMsg = NSBSystemLib.GetAlarmMessage(alarmPgm)
Retrieves information about a currently set alarm.

Parameter alarmPgm as String Alarm program.

Returns alarmMsg as String Alarm message.

Example Dim alarmMsg as String Dim alarmPgm as String alarmPgm = "NSBAlarmProxy1" alarmMsg = NSL.GetAlarmMessage(alarmPgm)

AlarmLog

alarmTime = NSBSystemLib.AlarmLog(alarmPgm, alarmCmd, alarmMsg)
Retrieves information about an alarm that has already been processed.

Parameters alarmPgm as String Alarm program. alarmCmd as String AlarmCmd as a string. This value is returned and must be initialized to a maximum length before calling the function. This value should never be more than 6 characters in length. alarmMsg as String Alarm message as a string. This value is returned and must be initialized to a maximum length before calling the function. This value should never be more than 80 characters in length.

Returns alarmTime as Integer Alarm time in system time format. This value is expressed as the number of seconds since January 1st, 1904.

Example Dim alarmTime as Integer Dim alarmPgm as String Dim alarmCmd as String Dim alarmMsg as String alarmPgm = "NSBAlarmProxy1" alarmCmd = "123456" alarmMsg = "1234567890123456789012345678901234567890" _ + "1234567890123456789012345678901234567890" alarmTime = NSL.AlarmLog(alarmPgm, alarmCmd, alarmMsg)

See also: StringDateTime(), StringDate(), StringTime()

AlarmLogAlarmTime

alarmTime = NSBSystemLib.AlarmLogAlarmTime(alarmPgm)
Retrieves information about an alarm that has already been processed.

Parameter alarmPgm as String Alarm program.

Returns alarmTime as Integer Alarm time in system time format. This value is expressed as the number of seconds since January 1st, 1904.

Example Dim alarmTime as Integer Dim alarmPgm as String alarmPgm = "NSBAlarmProxy1" alarmTime = NSL.AlarmLogAlarmTime(alarmPgm)

See also: StringDateTime(), StringDate(), StringTime()

AlarmLogResetTime

resetTime = NSBSystemLib.AlarmLogResetTime(alarmPgm)
Retrieves information about an alarm that has already been processed.

Parameter alarmPgm as String Alarm program.

Returns resetTime as Integer Alarm time reset time in seconds.

Example Dim resetTime as Integer Dim alarmPgm as String alarmPgm = "NSBAlarmProxy1" resetTime = NSL.AlarmLogResetTime(alarmPgm)

AlarmLogResetLimit

resetLimit = NSBSystemLib.AlarmLogResetLimit(alarmPgm)
Retrieves information about an alarm that has already been processed.

Parameter alarmPgm as String Alarm program.

Returns resetLimit as Integer Alarm time reset limit.

Example Dim resetLimit as Integer Dim alarmPgm as String alarmPgm = "NSBAlarmProxy1" resetLimit = NSL.AlarmLogResetLimit(alarmPgm)

AlarmLogResetCount

resetCount = NSBSystemLib.AlarmLogResetCount(alarmPgm)
Retrieves information about an alarm that has already been processed.

Parameter alarmPgm as String Alarm program.

Returns resetCount as Integer The number of times the alarm as been automatically reset.

Example Dim resetCount as Integer Dim alarmPgm as String alarmPgm = "NSBAlarmProxy1" resetCount = NSL.AlarmLogResetCount(alarmPgm)

AlarmLogCommand

alarmCmd = NSBSystemLib.AlarmLogCommand(alarmPgm)
Retrieves information about an alarm that has already been processed.

Parameter alarmPgm as String Alarm program.

Returns alarmCmd as Integer Alarm command.

Example Dim alarmCmd as Integer Dim alarmPgm as String alarmPgm = "NSBAlarmProxy1" alarmCmd = NSL.AlarmLogCommand(alarmPgm)

AlarmLogMessage

alarmMsg = NSBSystemLib.AlarmLogMessage(alarmPgm)
Retrieves information about an alarm that has already been processed.

Parameter alarmPgm as String Alarm program.

Returns alarmMsg as String Alarm message.

Example Dim alarmMsg as String Dim alarmPgm as String alarmPgm = "NSBAlarmProxy1" alarmMsg = NSL.AlarmLogMessage(alarmPgm)

ClearAlarmLog

alarmPgm = NSBSystemLib.ClearAlarmLog()
Clears the alarm log data for a specified alarm program.

Returns alarmPgm as String

Example Dim alarmPgm as String alarmPgm = "NSBAlarmProxy1" alarmPgm = NSL.ClearAlarmLog()


Database Functions

The database functions provide methods for determining the databases residing on the PalmOS device. They also provide information about these databases and allow some of this information to be changed. These functions do not provide methods for reading and writing the data actually contained in a database.

FindDatabase

dbID = NSBSystemLib.FindDatabase(cardNo, dbName)
Returns the database ID (LocalID) of the named database.

Parameters cardNo as Integer This value will most likely be 0. dbName as String Database name.

Returns dbID as Integer dbID if the named database is found. 0 if the named database is not found.

Example Dim dbID as Integer Dim cardNo as Integer Dim dbName as String cardNo = 0 dbName = "NSBRuntime" dbID = NSL.FindDatabase(cardNo, dbName)

DatabaseInfo

dbName = NSBSystemLib.DatabaseInfo(cardNo, dbID)
Returns the database name for the specified card number and database ID (LocalID). It also retrieves many other fields of database information. See the example and notes for for more information on how to access this data.

Parameters cardNo as Integer dbID as Integer

Returns dbName as String

Example Dim cardNo as Integer Dim dbID as Integer Dim dbName as String Dim dbVersion as Integer Dim dbCreationDate as Integer Dim dbModificationDate as Integer Dim dbBackupDate as Integer Dim dbModificationNumber as Integer Dim dbAppInfoID as Integer Dim dbSortInfoID as Integer Dim dbType as Integer Dim dbCreatorID as Integer cardNo = 0 dbName = "NSBRuntime" dbID = NSBNSL.FindDatabase(cardNo, dbName) If dbID <> 0 Then dbName = NSL.DatabaseInfo(cardNo, dbID) If dbName <> "" Then dbVersion = NSL.DatabaseVersion() dbCreationDate = NSL.DatabaseCreationDate() dbModificationDate = NSL.DatabaseModificationDate() dbBackupDate = NSL.DatabaseBackupDate() dbModificationNumber = NSL.DatabaseModificationNumber() dbAppInfoID = NSL.DatabaseAppInfoID() dbSortInfoID = NSL.DatabaseSortInfoID() dbType = NSL.DatabaseType() dbCreatorID = NSL.DatabaseCreatorID() EndIf EndIf

See also: DatabaseName(), DatabaseAttributes(), DatabaseVersion(), DatabaseCreationDate(), DatabaseModificationDate(), DatabaseBackupDate(), DatabaseModificationNumber(), DatabaseType(), DatabaseCreatorID()

DatabaseName

dbName = NSBSystemLib.DatabaseName()
Returns a database name that was previously retrieved by a call to DatabaseInfo().

Returns dbName as String

Example See the example provided with the DatabaseInfo() function.

DatabaseAttributes

dbAttributes = NSBSystemLib.DatabaseAttributes()
Returns database attributes that were previously retrieved by a call to DatabaseInfo().

Returns dbAttributes as Integer The attributes value is a bitmapped value. The following list contains the bit mask values available: Bit 0 (0x0001) - dmHdrAttrResDB Bit 1 (0x0002) - dmHdrAttrReadOnly Bit 2 (0x0004) - dmHdrAttrAppInfoDirty Bit 3 (0x0008) - dmHdrAttrBackup Bit 4 (0x0010) - dmhdrAttrOKToInstallNewer Bit 5 (0x0020) - dmHdrAttrResetAfterInstall Bit 6 (0x0040) - dmHdrAttrCopyPrevention Bit 7 (0x0080) - dmHdrAttrStream Bit 8 (0x0100) - dmHdrAttrHidden Bit 9 (0x0200) - hmHdrAttrLaunchableData Bit 15 (0x8000) - dmHdrAttrOpen

Example See the example provided with the DatabaseInfo() function.

DatabaseVersion

dbVersion = NSBSystemLib.DatabaseVersion()
Returns the database version that was previously retrieved by a call to DatabaseInfo().

Returns dbVersion as Integer

Example See the example provided with the DatabaseInfo() function.

DatabaseCreationDate

dbCreationDate = NSBSystemLib.DatabaseCreationDate()
Returns the database creation date that was previously retrieved by a call to DatabaseInfo(). This date is in system time format. It is expressed as the number of seconds since January 1st, 1904.

Returns dbCreationDate as Integer

Example See the example provided with the DatabaseInfo() function.

See also: StringDateTime(), StringDate(), StringTime()

DatabaseModificationDate

dbModificationDate = NSBSystemLib.DatabaseModificationDate()
Returns the database modification date that was previously retrieved by a call to DatabaseInfo(). This date is in system time format. It is expressed as the number of seconds since January 1st, 1904.

Returns dbModificationDate as Integer

Example See the example provided with the DatabaseInfo() function.

See also: StringDateTime(), StringDate(), StringTime()

DatabaseBackupDate

dbBackupDate = NSBSystemLib.DatabaseBackupDate()
Returns the database backup date that was previously retrieved by a call to DatabaseInfo(). This date is in system time format. It is expressed as the number of seconds since January 1st, 1904.

Returns dbBackupDate as Integer

Example See the example provided with the DatabaseInfo() function.

See also: StringDateTime(), StringDate(), StringTime()

DatabaseModificationNumber

dbModificationNumber = NSBSystemLib.DatabaseModificationNumber()
Returns the database modification number that was previously retrieved by a call to DatabaseInfo(). This number is incremented every time that a record is added, modified, or deleted.

Returns dbModificationNumber as Integer

Example See the example provided with the DatabaseInfo() function.

DatabaseAppInfoID

dbAppInfoID = NSBSystemLib.DatabaseAppInfoID()
Returns the LocalID of the database Application Info block that was previously retrieved by a call to DatabaseInfo().

Returns dbAppInfoID as Integer 0 if this optional block is not available.

Example See the example provided with the DatabaseInfo() function.

DatabaseSortInfoID

dbSortInfoID = NSBSystemLib.DatabaseSortInfoID()
Returns the LocalID of the database's sort table that was previously retrieved by a call to DatabaseInfo().

Returns dbSortInfoID as Integer 0 if this optional sort table is not available.

Example See the example provided with the DatabaseInfo() function.

DatabaseType

dbType = NSBSystemLib.DatabaseType()
Returns the database type that was previously retrieved by a call to DatabaseInfo().

Returns dbType as Integer

Example See the example provided with the DatabaseInfo() function.

See also: IntToString4()

DatabaseCreatorID

dbCreatorID = NSBSystemLib.DatabaseCreatorID()
Returns the database Creator ID that was previously retrieved by a call to DatabaseInfo().

Returns dbCreatorID as Integer

Example See the example provided with the DatabaseInfo() function.

See also: IntToString4()

DatabaseTotalSize

dbTotalSize = NSBSystemLib.DatabaseTotalSize(cardNo, dbID)
Returns the total database size, including overhead, for the specified card number and database ID. It also retrieves the number of records and the size of just the data in the database. See the example and notes for for more information on how to access this data.

Parameters cardNo as Integer dbID as Integer

Returns dbTotalSize as Integer

Example Dim cardNo as Integer Dim dbID as Integer Dim dbTotalSize as Integer Dim dbNumRecords as Integer Dim dbDataSize as Integer cardNo = 0 dbName = "NSBRuntime" dbID = NSL.FindDatabase(cardNo, dbName) If dbID <> 0 Then dbTotalSize = NSL.DatabaseSize(cardNo, dbID) dbNumRecords = NSL.DatabaseNumRecords() dbDataSize = NSL.DatabaseDataSize() EndIf

See also: DatabaseNumRecords(), DatabaseDataSize()

DatabaseNumRecords

dbNumRecords = NSBSystemLib.DatabaseNumRecords()
Returns the number of database records that was previously retrieved by a call to DatabaseTotalSize().

Returns dbNumRecords as Integer

Example See the example provided with the DatabaseTotalSize() function.

DatabaseDataSize

dbDataSize = NSBSystemLib.DatabaseDataSize()
Returns the database data size (minus overhead) that was previously retrieved by a call to DatabaseTotalSize().

Returns dbDataSize as Integer

Example See the example provided with the DatabaseTotalSize() function.

DeleteDatabase

status = NSBSystemLib.DeleteDatabase(cardNo, dbID)
Deletes the specified database.

Parameters cardNo as Integer dbID as Integer

Returns status as Integer 0 = successful 257 = memErrChunkLocked 258 = memErrNotEnoughSpace 259 = memErrInvalidParam 517 = dmErrDatabaseOpen 518 = dmErrCantOpen 519 = dmErrCantFind 526 = dmErrROMBased

Example Dim cardNo as Integer Dim dbID as Integer Dim status as Integer cardNo = 0 dbName = "NSBAlarmProxy5" dbID = NSL.FindDatabase(cardNo, dbName) If dbID <> 0 Then status = NSL.DeleteDatabase(cardNo, dbID) EndIf

See also: FindDatabase()

GetNextDatabaseByTypeCreator

dbID = NSBSystemLib.GetNextDatabaseByTypeCreator(newSearch, dbType, dbCreatorID, onlyLatestVersion)
This function is used to retrieve a list of all the specified databases on the device.

Parameters newSearch as Integer 0 = continue searching for databases 1 = start a new search dbType as Integer Integer database type. 0 = wildcard search. dbCreatorID as Integer Integer Creator ID. 0 = wildcard search. onlyLatestVersion as Integer 0 = return all versions. 1 = return only the latest database version for supplied type and Creator ID.

Returns dbID as Integer dbID (LocalID) of the database.

Example Dim dbID as Integer Dim newSearch as Integer Dim dbType as Integer Dim dbCreatorID as Integer Dim onlyLatestVersion as Integer Dim dbCardNo as Integer Dim dbName as String onlyLatestVersion = 0 dbType = NSL.String4ToInt("libr") dbCreatorID = 0 newSearch = 1 dbID = 1 Do While dbID <> 0 dbID = NSL.GetNextDatabaseByTypeCreator(newSearch, _ dbType, dbCreatorID, onlyLatestVersion) If dbID <> 0 Then dbCardNo = NSL.DatabaseCardNo() dbName = NSL.DatabaseInfo(dbCardNo, dbID) End If newSearch = 0 Loop

See Also: DatabaseCardNo(), DatabaseInfo()

DatabaseCardNo

dbCardNo = NSBSystemLib.DatabaseCardNo()
Returns the database card number that was previously retrieved by a call to GetNextDatabaseByTypeCreator().

Returns dbCardNo as Integer

Example See the example provided with the GetNextDatabaseByTypeCreator() function.

NumDatabases

nbr = NSBSystemLib.NumDatabases(cardNo)
This function is used to retrieve the number of databases on the specified card number.

Parameter cardNo as Integer

Returns nbr as Integer

Example Dim nbr as Integer Dim cardNo as Integer cardNo = 0 nbr = NSL.NumDatabases(cardNo)

This routine is helpful for getting a directory of all databases on a card. The function GetDatabase() accepts an index from 0 to (NumDatabases -1) and returns a database ID by index. See also: GetDatabase()

NumCards

nbr = NSBSystemLib.NumCards()
This function returns the number of memory card slots in the system. Not all slots need to be populated.

Returns nbr as Integer

Example Dim nbr as Integer nbr = NSL.NumCards()

GetDatabase

dbID = NSBSystemLib.GetDatabase(cardNo, index)
This function is used to retrieve a database ID for the supplied card number and index.

Parameters cardNo as Integer index as Integer

Returns dbID as Integer 0 = Invalid index

Example Dim nbr as Integer Dim dbID as Integer Dim cardNo as Integer Dim index as Integer Dim dbName as String cardNo = 0 nbr = NSL.NumDatabases(cardNo) index = 0 Do While index < nbr dbID = NSL.GetDatabase(cardNo, index) If dbID <> 0 Then dbName = NSL.DatabaseInfo(cardNo, dbID) End If index = index + 1 Loop

See also: NumDatabases()

SetDatabaseName

status = NSBSystemLib.SetDatabaseName(cardNo, dbID, dbName)
This function is used to change the name of the specified database.

Parameters cardNo as Integer dbID as Integer dbName as String

Returns status as Integer 0 = success 515 = dmErrInvalidParam 537 = dmErrAlreadyExists 538 = InvalidDatabaseName

Example Dim status as Integer Dim dbID as Integer Dim cardNo as Integer Dim dbName as String cardNo = 0 dbName = "NSBAlarmProxy5" dbID = NSL.FindDatabase(cardNo, dbName) dbName = "oldNSBAlarmProxy5" status = NSL.SetDatabaseName(cardNo, dbID, dbName)

SetDatabaseAttributes

status = NSBSystemLib.SetDatabaseAttributes(cardNo, dbID, dbAttributes)
This function is used to change the attributes of the specified database.

Parameters cardNo as Integer dbID as Integer dbAttributes as Integer The attributes value is a bitmapped value. The following list contains the bit mask values available: Bit 0 (0x0001) - dmHdrAttrResDB Bit 1 (0x0002) - dmHdrAttrReadOnly Bit 2 (0x0004) - dmHdrAttrAppInfoDirty Bit 3 (0x0008) - dmHdrAttrBackup Bit 4 (0x0010) - dmhdrAttrOKToInstallNewer Bit 5 (0x0020) - dmHdrAttrResetAfterInstall Bit 6 (0x0040) - dmHdrAttrCopyPrevention Bit 7 (0x0080) - dmHdrAttrStream Bit 8 (0x0100) - dmHdrAttrHidden Bit 9 (0x0200) - hmHdrAttrLaunchableData Bit 15 (0x8000) - dmHdrAttrOpen

Returns status as Integer 0 = success 515 = dmErrInvalidParam 537 = dmErrAlreadyExists 538 = InvalidDatabaseName

Example Dim status as Integer Dim dbID as Integer Dim cardNo as Integer Dim dbAttributes as Integer cardNo = 0 dbName = "NSBAlarmProxy5" dbID = NSL.FindDatabase(cardNo, dbName) dbAttributes = 2 status = NSL.SetDatabaseAttributes(cardNo, dbID, dbAttributes)

SetDatabaseVersion

status = NSBSystemLib.SetDatabaseVersion(cardNo, dbID, dbVersion)
This function is used to change the version number of the specified database.

Parameters cardNo as Integer dbID as Integer dbVersion as Integer

Returns status as Integer 0 = success 515 = dmErrInvalidParam 537 = dmErrAlreadyExists 538 = InvalidDatabaseName

Example Dim status as Integer Dim dbID as Integer Dim cardNo as Integer Dim dbVersion as Integer cardNo = 0 dbName = "NSBAlarmProxy5" dbID = NSL.FindDatabase(cardNo, dbName) dbVersion = 6 status = NSL.SetDatabaseVersion(cardNo, dbID, dbVersion)

SetDatabaseCreationDate

status = NSBSystemLib.SetDatabaseCreationDate(cardNo, dbID, dbCreationDate)
This function is used to change the creation date of the specified database.

Parameters cardNo as Integer dbID as Integer dbCreationDate as Integer

Returns status as Integer 0 = success 515 = dmErrInvalidParam 537 = dmErrAlreadyExists 538 = InvalidDatabaseName

Example Dim status as Integer Dim dbID as Integer Dim cardNo as Integer Dim dbCreationDate as Integer cardNo = 0 dbName = "NSBAlarmProxy5" dbID = NSL.FindDatabase(cardNo, dbName) dbCreationDate = NSL.SystemTime("", "", 0, 0) status = NSL.SetDatabaseCreationDate(cardNo, dbID, _ dbCreationDate)

SetDatabaseModificationDate

status = NSBSystemLib.SetDatabaseModificationDate(cardNo, dbID, dbModificationDate)
This function is used to change the modification date of the specified database.

Parameters cardNo as Integer dbID as Integer dbModificationDate as Integer

Returns status as Integer 0 = success 515 = dmErrInvalidParam 537 = dmErrAlreadyExists 538 = InvalidDatabaseName

Example Dim status as Integer Dim dbID as Integer Dim cardNo as Integer Dim dbModificationDate as Integer cardNo = 0 dbName = "NSBAlarmProxy5" dbID = NSL.FindDatabase(cardNo, dbName) dbModificationDate = NSL.SystemTime("", "", 0, 0) status = NSL.SetDatabaseModificationDate(cardNo, dbID, _ dbModificationDate)

SetDatabaseBackupDate

status = NSBSystemLib.SetDatabaseBackupDate(cardNo, dbID, dbBackupDate)
This function is used to change the backup date of the specified database.

Parameters cardNo as Integer dbID as Integer dbBackupDate as Integer

Returns status as Integer 0 = success 515 = dmErrInvalidParam 537 = dmErrAlreadyExists 538 = InvalidDatabaseName

Example Dim status as Integer Dim dbID as Integer Dim cardNo as Integer Dim dbBackupDate as Integer cardNo = 0 dbName = "NSBAlarmProxy5" dbID = NSL.FindDatabase(cardNo, dbName) dbBackupDate = NSL.SystemTime("", "", 0, 0) status = NSL.SetDatabaseModificationDate(cardNo, dbID, _ dbBackupDate)

SetDatabaseModificationNumber

status = NSBSystemLib.SetDatabaseModificationNumber(cardNo, dbID, dbModificationNumber)
This function is used to change the modification number of the specified database.

Parameters cardNo as Integer dbID as Integer dbModificationNumber as Integer

Returns status as Integer 0 = success 515 = dmErrInvalidParam 537 = dmErrAlreadyExists 538 = InvalidDatabaseName

Example Dim status as Integer Dim dbID as Integer Dim cardNo as Integer Dim dbModificationNumber as Integer cardNo = 0 dbName = "NSBAlarmProxy5" dbID = NSL.FindDatabase(cardNo, dbName) dbModificationNumber = 0 status = NSL.SetDatabaseModificationNumber(cardNo, dbID, _ dbModificationNumber)

SetDatabaseAppInfoID

status = NSBSystemLib.SetDatabaseAppInfoID(cardNo, dbID, dbAppInfoID)
This function is used to change the Application Information LocalID of the specified database.

Parameters cardNo as Integer dbID as Integer dbAppInfoID as Integer

Returns status as Integer 0 = success 515 = dmErrInvalidParam 537 = dmErrAlreadyExists 538 = InvalidDatabaseName

Example Dim status as Integer Dim dbID as Integer Dim cardNo as Integer Dim dbAppInfoID as Integer cardNo = 0 dbName = "NSBAlarmProxy5" dbID = NSL.FindDatabase(cardNo, dbName) dbAppInfoID = 0 status = NSL.SetDatabaseAppInfoID(cardNo, dbID, _ dbAppInfoID)

SetDatabaseSortInfoID

status = NSBSystemLib.SetDatabaseSortInfoID(cardNo, dbID, dbSortInfoID)
This function is used to change the Sort Table LocalID of the specified database.

Parameters cardNo as Integer dbID as Integer dbSortInfoID as Integer

Returns status as Integer 0 = success 515 = dmErrInvalidParam 537 = dmErrAlreadyExists 538 = InvalidDatabaseName

Example Dim status as Integer Dim dbID as Integer Dim cardNo as Integer Dim dbSortInfoID as Integer cardNo = 0 dbName = "NSBAlarmProxy5" dbID = NSL.FindDatabase(cardNo, dbName) dbSortInfoID = 0 status = NSL.SetDatabaseSortInfoID(cardNo, dbID, _ dbSortInfoID)

SetDatabaseType

status = NSBSystemLib.SetDatabaseType(cardNo, dbID, dbType)
This function is used to change the database type of the specified database.

Parameters cardNo as Integer dbID as Integer dbType as Integer

Returns status as Integer 0 = success 515 = dmErrInvalidParam 537 = dmErrAlreadyExists 538 = InvalidDatabaseName

Example Dim status as Integer Dim dbID as Integer Dim cardNo as Integer Dim dbType as Integer cardNo = 0 dbName = "NSBAlarmProxy5" dbID = NSL.FindDatabase(cardNo, dbName) dbType = String4ToInt("appl") status = NSL.SetDatabaseType(cardNo, dbID, dbType);

SetDatabaseCreatorID

status = NSBSystemLib.SetDatabaseCreatorID(cardNo, dbID, dbCreatorID)
This function is used to change the Creator ID of the specified database.

Parameters cardNo as Integer dbID as Integer dbCreatorID as Integer

Returns status as Integer 0 = success 515 = dmErrInvalidParam 537 = dmErrAlreadyExists 538 = InvalidDatabaseName

Example Dim status as Integer Dim dbID as Integer Dim cardNo as Integer Dim dbCreatorID as Integer cardNo = 0 dbName = "NSBAlarmProxy5" dbID = NSL.FindDatabase(cardNo, dbName) dbCreatorID = String4ToInt("TEST") status = NSL.SetDatabaseCreatorID(cardNo, dbID, dbCreatorID);


Event Functions

The event functions are provided to give you more control of event detection and processing than is currently available using the standard NSBasic Events code section and SysEventAvailable() function.

GetEvent

eventType = NSBSystemLib.GetEvent(timeoutTicks, consumePenEvents, returnVirtualEvents)
Returns an system event type, if one is available. The timeoutTicks parameter is used to provide a "non-blocking" delay. If an event occurs before the timeout period expires the function will return immediately. This can be useful for use with animation or game programming.

Parameters timeoutTicks as Integer The number of system ticks to wait before returning. consumePenEvents as Integer 0 = do not consume pen events 1 = consume pen events This function calls the PalmOS EvtGetEvent function. EvtGetEvent removes events from the events queue. In order for these events to still be available for other processing, this shared library function requeues the events that it detects. This may not be desired if this function is used for capturing pen events for drawing. When consumePenEvents is set to 1, the pen events are not requeued but the pen data is still available. returnVirtualEvents as Integer 0 = do not return with virtual key events 1 = return with virtual key events Virtual key events are events generated by the PalmOS system or other third party system level features. These events include things like low battery warning, backlight change of state, etc. For the most part, virtual key events should not be returned. If they are returned, it is probably wise to let the system handle them by calling this library's SysHandleEvent() function.

Returns eventType as Integer -1 if no event was available within the timeout specified. 0 = nilEvent 1 = penDownEvent Retrieve pen coordintates with: GlobalX(), and GlobalY() 2 = penUpEvent Retrieve pen coordintates with: GlobalX(), GlobalY() Retrieve pen stroke coordinates with: GlobalStartX(), GlobalStartY(), GlobalEndX(), and GlobalEndY() 3 = penMoveEvent Retrieve pen coordintates with: GlobalX(), and GlobalY() 4 = keyDownEvent Retrieve key data with: KeyEventChr(), KeyEventKeyCode(), and KeyEventModifiers() 5 = winEnterEvent 6 = winExitEvent 7 = ctlEnterEvent 8 = ctlExitEvent 9 = ctlSelectEvent 10 = ctlRepeatEvent 11 = lstEnterEvent 12 = lstSelectEvent 13 = lstExitEvent 14 = popSelectEvent 15 = fldEnterEvent 16 = fldHeightChangedEvent 17 = fldChangedEvent 18 = tblEnterEvent 19 = tblSelectEvent 20 = daySelectEvent 21 = menuEvent 22 = appStopEvent 21 = frmOpenEvent 22 = frmGotoEvent 23 = frmUpdateEvent 24 = frmSaveEvent 25 = frmCloseEvent 26 = frmTitleEnterEvent 27 = frmTitleSelectEvent 28 = tblExitEvent 29 = sclEnterEvent 30 = sclExitEvent 31 = sclRepeatEvent 35 = tsmConfirmEvent 36 = tsmFepButtonEvent 37 = tsmFepModeEvent 2048 = menuCmdBarOpenEvent 2049 = menuOpenEvent 2050 = menuCloseEvent 2051 = frmGadgetEnterEvent 2052 = frmGadgetMiscEvent 4096 = firstINetLibEvent 4352 = firstWebLibEvent 24576 = firstUserEvent

Example Dim eventType as Integer Dim timeoutTicks as Integer NSL.FlushEvents() eventType = 0 Do While eventType <= 0 'do something eventType = NSL.GetEvent(timeoutTicks, 0, 0) Loop

If this function is used as part of a button's event code, you may want to flush pending key and pen events before calling this function. This is because the "pen up" event resulting from the button push will cause this function to to return immediately. See the example and FlushEvents() function.

SysHandleEvent

NSBSystemLib.SysHandleEvent()
Consume and handle the event most recently returned by the GetEvent() function. It does this by calling EvtGetEvent() and then SysHandleEvent();

Example NSL.SysHandleEvent()

FlushEvents

NSBSystemLib.FlushEvents()
Flushes all pending key and pen events. It does this by calling the PalmOS EvtFlushKeyQueue() and EvtFlushPenQueue() functions. It then empties and handles all remaing events by calling EvtGetEvent() and SysHandleEvent().

Example NSL.FlushEvents()

KeyEventChr

keyChr = NSBSystemLib.KeyEventChr()
Returns the "chr" data member of of a key event. The GetEvent() function must have returned an event type of 4 (keyDownEvent) for this value to be valid.

Returns keyChr as Integer

Example Dim keyChr as Integer keyChr = NSL.KeyEventChr()

KeyEventKeyCode

keyCode = NSBSystemLib.KeyEventKeyCode()
Returns the "keyCode" data member of of a key event. The GetEvent() function must have returned an event type of 4 (keyDownEvent) for this value to be valid.

Returns keyCode as Integer

Example Dim keyCode as Integer keyCode = NSL.KeyEventKeyCode()

KeyEventModifiers

modifiers = NSBSystemLib.KeyEventModifiers()
Returns the "modifiers" data member of of a key event. The GetEvent() function must have returned an event type of 4 (keyDownEvent) for this value to be valid.

Returns modifiers as Integer

Example Dim modifiers as Integer modifiers = NSL.KeyEventModifiers()


Field and Form Functions

The field and form functions provide convenient methods for manipulating field and form objects. These functions allow you to perform operations that aren't available using the standard NSBasic language. While many of these operations can be performed with SysTrapSub and SysTrapFunc statements, these functions provide a simpler interface.

A number of these functions allow the use of 0 as the first argument to refer to the current field. Starting with the LifeDrive, Tungsten E2 and some Treo models, this feature is no longer supported. The underlying Palm OS call, FrmGetFocus, no longer returns a valid value. To correct for this, you will need to keep track the of current field yourself.

Here is how to program around this:

1. In your Startup code create a global to contain the object id of the last field that had focus :

    Sub main()
        Global focus as Integer
        LoadLibrary "NSBSystemLib","NSL"
    End Sub

2. Double-click each field to create a "click" event subroutine. Set the value of your new global to the value of your field's object id. Its really convenient that the subroutine has the object id in it's name! ;-) :

    Sub object1005()
        focus = 1005
    End Sub

    Sub object1023()
        focus = 1023
    End Sub

    Sub object1025()
        focus = 1025
    End Sub

3. Now, since we know the last field with focus, we can use the object id instead of trying to get the current field with focus (which we know doesn't work on some newer devices):

    Sub object1015()
        NSL.FIeldInsert focus, "1"
    End Sub

Granted, it's not quite as elegant as the way NSL used to work on older devices but it's not too bad.

ControlHitControl

NSBSystemLib.ControlHitControl objID
Simulate tapping a control. This function adds a ctlSelectEvent to the event queue.

Parameter: objID as Integer 0 = use field that currently has focus (not on all devices, see above.) objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID.

Example Dim objID as Integer objID = 1008 NSL.ControlHitControl objID

FieldCopy

NSBSystemLib.FieldCopy objID
Copy the current selection to the text clipboard.

Parameter: objID as Integer 0 = use field that currently has focus (not on all devices, see above.) objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID.

Example Dim objID as Integer objID = 1008 NSL.FieldCopy objID

FieldCut

NSBSystemLib.FieldCut objID
Copy the current selection to the text clipboard, delete the selection from the field, and redraw the field.

Parameter: objID as Integer 0 = use field that currently has focus (not on all devices, see above.) objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID.

Example Dim objID as Integer objID = 1008 NSL.FieldCut objID

FieldInsert

NSBSystemLib.FieldInsert objID, insString
Replace the current selection if any with the specified string and redraw the field.

Parameters objID as Integer 0 = use field that currently has focus (not on all devices, see above.) objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID. insString as String

Example Dim objID as Integer Dim insString as String objID = 1008 insString = "Insert This!" NSL.FieldInsert objID, insString

FieldPaste

NSBSystemLib.FieldPaste objID
Replace the current selection in the field, if any, with the contents of the text clipboard.

Parameter: objID as Integer 0 = use field that currently has focus (not on all devices, see above.) objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID.

Example Dim objID as Integer objID = 1008 NSL.FieldPaste objID

FieldUndo

NSBSystemLib.FieldUndo objID
Undo the last change made to the field object, if any. Changes include paste and cut.

Parameter: objID as Integer 0 = use field that currently has focus (not on all devices, see above.) objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID.

Example Dim objID as Integer objID = 1008 NSL.FieldUndo objID

FieldGetInsPtPosition

pos = NSBSystemLib.FieldGetInsPtPosition(objID)
Returns the insertion point position within the string.

Parameter objID as Integer 0 = use field that currently has focus (not on all devices, see above.) objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID.

Returns pos as Integer

Example Dim pos as Integer Dim objID as Integer objID = 1008 pos = NSL.FieldGetInsPtPosition(objID)

The insertion point is to the left of the byte offset that this function returns. That is, if this function returns 0, the insertion point is to the left of the first character in the string. In multiline fields, line feeds are counted as a single character in the string, and the byte offset after the line feed character is the beginning of the next line. See also: FieldSetInsertionPoint() and FieldSetInsPtPosition()

FieldGetSelection

startPos = NSBSystemLib.FieldGetSelection(objID)
Retrieves the start and end position of a field's selected text. It only returns the start position. To get the end position, use the GlobalEndPos() funtion.

Parameter objID as Integer 0 = use field that currently has focus (not on all devices, see above.) objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID.

Returns startPos as Integer

Example Dim startPos as Integer Dim objID as Integer Dim endPos as Integer objID = 1008 startPos = NSL.FieldGetSelection(objID) endPos = NSL.GlobalEndPos()

FieldAnyDirty

dirty = NSBSystemLib.FieldAnyDirty()
Returns 1 if one or more of the active form's field values have changed since the last time that they were set.

Returns dirty as Integer

Example Dim dirty as Integer dirty = NSL.FieldAnyDirty()

FieldDirty

dirty = NSBSystemLib.FieldDirty(objID)
Returns 1 if the field's value has changed since the last time that it was set.

Parameter objID as Integer 0 = check field that currently has focus objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID.

Returns dirty as Integer

Example Dim dirty as Integer Dim objID as Integer objID = 1008 dirty = NSL.FieldDirty(objID)

FieldSetDirty

NSBSystemLib.FieldSetDirty objID, dirty
Sets a field's "dirty" property. A field is considered as dirty if its value has changed since the last time it was set.

Parameters objID as Integer 0 = use field that currently has focus (not on all devices, see above.) objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID. dirty as Integer 0 = not dirty 1 = dirty

Example Dim objID as Integer Dim dirty as Integer objID = 1008 dirty = 1 NSL.FieldSetDirty objID, dirty

FieldSetAllDirty

NSBSystemLib.FieldSetAllDirty dirty
Sets the "dirty" property of all of the active form's field values.

Parameter: dirty as Integer 0 = not dirty 1 = dirty

Example Dim dirty as Integer NSL.FieldSetAllDirty dirty

FieldSetSelection

NSBSystemLib.FieldSetSelection objID, startPos, endPos
Set the current selection in a field and highlight the selection if the field is visible.

Parameters objID as Integer 0 = use field that currently has focus (not on all devices, see above.) objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID. startPos as Integer endPos as Integer

Example Dim objID as Integer Dim startPos as Integer Dim endPos as Integer objID = 1008 NSL.FieldSetSelection objID, startPos, endPos

FieldSetInsertionPoint

NSBSystemLib.FieldSetInsertionPoint objID, pos
Set the location of the insertion point based on a specified string position.

Parameters objID as Integer 0 = use field that currently has focus (not on all devices, see above.) objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID. pos as Integer

Example Dim objID as Integer Dim pos as Integer objID = 1008 NSL.FieldSetInsertionPoint objID, pos

This routine differs from FieldldSetInsPtPosition in that it doesn't make the character position visible. FieldSetInsertionPoint also doesn't make the field the current focus of input if it was not already. See Also: FieldSetInsPtPosition() and FieldGetInsPtPosition()

FieldSetInsPtPosition

NSBSystemLib.FieldSetInsPtPosition objID, pos
Set the location of the insertion point based on a specified string position.

Parameters objID as Integer 0 = use field that currently has focus (not on all devices, see above.) objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID. pos as Integer

Example Dim objID as Integer Dim pos as Integer objID = 1008 NSL.FieldSetInsPtPosition objID, pos

If the position is beyond the visible text, the field is scrolled until the position is visible. See also: FieldSetInsertionPoint() and FieldGetInsPtPosition()

FieldGetAttributes

attributes = NSBSystemLib.FieldGetAttributes(objID)
Returns a field's attributes as a bitmapped integer. The BitsNbytes shared library contains functions for manipulating bit values.

Parameter objID as Integer 0 = use field that currently has focus (not on all devices, see above.) objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID.

Returns attributes as Integer A bitmapped integer with the following values: bit 0 - reserved bit 1 - numeric bit 2 - hasScrollBar bit 3 - autoShift bits 4 and 5 - justification 00 - leftAlign 01 - centerAlign (may not be supported) 10 - rightAlign bits 6 and 7 - underlined 00 - noUnderline 01 - grayUnderline 10 - solidUnderline bit 8 - dirty bit 9 - insPtVisible bit 10 - dynamicSize bit 11 - hasFocus bit 12 - singleLine bit 13 - editable bit 14 - visible bit 15 - usable

Example Dim attributes as Integer Dim objID as Integer objID = 1008 attributes = NSL.FieldGetAttributes(objID)

FieldSetAttributes

NSBSystemLib.FieldSetAttributes objID, attributes
Sets a field's attributes. Attributes are specified as a bitmapped integer. The BitsNbytes shared library contains functions for manipulating bit values.

Parameters objID as Integer 0 = use field that currently has focus (not on all devices, see above.) objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID. attributes as Integer A bitmapped integer with the following values: bit 0 - reserved bit 1 - numeric bit 2 - hasScrollBar bit 3 - autoShift bits 4 and 5 - justification 00 - leftAlign 01 - centerAlign (may not be supported) 10 - rightAlign bits 6 and 7 - underlined 00 - noUnderline 01 - grayUnderline 10 - solidUnderline bit 8 - dirty bit 9 - insPtVisible bit 10 - dynamicSize bit 11 - hasFocus bit 12 - singleLine bit 13 - editable bit 14 - visible bit 15 - usable

Example Dim objID as Integer Dim attributes as Integer objID = 1008 NSL.FieldSetAttributes objID, attributes

FieldGetFont

fontId = NSBSystemLib.FieldGetFont(objID)
Returns a field's Font ID.

Parameter objID as Integer 0 = use field that currently has focus (not on all devices, see above.) objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID.

Returns fontId as Integer

Example Dim fontId as Integer Dim objID as Integer objID = 1008 fontId = NSL.FieldGetFont(objID)

FieldSetFont

NSBSystemLib.FieldSetFont objID, fontId
Sets a field's Font ID.

Parameters objID as Integer 0 = use field that currently has focus (not on all devices, see above.) objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID. fontId as Integer

Example Dim objID as Integer Dim fontId as Integer objID = 1008 fontId = 2 'large font NSL.FieldSetFont objID, fontId

FieldGetScrollPosition

position = NSBSystemLib.FieldGetScrollPosition(objID)
Returns a field's scroll position. This is the offset of the first character in the first visible line of a field.

Parameter objID as Integer 0 = use field that currently has focus (not on all devices, see above.) objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID.

Returns position as Integer

Example Dim position as Integer Dim objID as Integer objID = 1008 position = NSL.FieldGetScrollPosition(objID)

FieldSetScrollPosition

NSBSystemLib.FieldSetScrollPosition objID, position
Sets a field's scroll position. This is the offset of the first character in the first visible line of a field.

Parameters objID as Integer 0 = use field that currently has focus (not on all devices, see above.) objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID. position as Integer

Example Dim objID as Integer Dim position as Integer objID = 1008 position = 20 NSL.FieldSetScrollPosition objID, position

FieldGetScrollValues

totalLines = NSBSystemLib.FieldGetScrollValues(objID)
Returns a field's scroll values. These are the values necessary to update a scroll bar. This function retreives the scroll position (offset line number), the text height (total lines required to display the field's text), and the field's height. Only the text height (total lines) is returned. Use GlobalStartPos() to return the scroll position and GlobalHeight() to return the field's height.

Parameter objID as Integer 0 = use field that currently has focus (not on all devices, see above.) objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID.

Returns totalLines as Integer

Example Dim totalLines as Integer Dim objID as Integer Dim position as Integer Dim height as Integer objID = 1008 totalLines = NSL.FieldGetScrollValues(objID) position = GlobalStartPos() height = GlobalHeight()

FieldGetVisibleLines

lines = NSBSystemLib.FieldGetVisibleLines(objID)
Return the number of lines that can be displayed within the visible bounds of the field.

Parameter objID as Integer 0 = use field that currently has focus (not on all devices, see above.) objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID.

Returns lines as Integer

Example Dim lines as Integer Dim objID as Integer objID = 1008 lines = NSL.FieldGetVisibleLines(objID)

FieldGetNumberOfBlankLines

lines = NSBSystemLib.FieldGetNumberOfBlankLines(objID)
Return the number of blank lines that are displayed at the bottom of a field.

Parameter objID as Integer 0 = use field that currently has focus (not on all devices, see above.) objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID.

Returns lines as Integer

Example Dim lines as Integer Dim objID as Integer objID = 1008 lines = NSL.FieldGetNumberOfBlankLines(objID)

FieldScrollable

yesNo = NSBSystemLib.FieldScrollable(objID, direction)
Returns 1 if the field is scrollable in the specified direction. Otherwise, it returns 0

Parameters objID as Integer 0 = use field that currently has focus (not on all devices, see above.) objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID. direction as Integer 0 = up 1 = down

Returns yesNo as Integer

Example Dim yesNo as Integer Dim objID as Integer Dim direction as Integer objID = 1008 yesNo = NSL.FieldScrollable(objID, direction)

FieldScrollField

NSBSystemLib.FieldScrollField objID, nbrLines, direction
Scroll a field up or down by the number of lines specified.

Parameters objID as Integer 0 = use field that currently has focus (not on all devices, see above.) objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID. nbrLines as Integer direction as Integer 0 = up 1 = down

Example Dim objID as Integer Dim nbrLines as Integer Dim direction as Integer objID = 1008 NSL.FieldScrollField objID, nbrLines, direction

FieldSetBounds

NSBSystemLib.FieldSetBounds objID, topLeftX, topLeftY, width, height
Change the position or size of a field.

Parameters objID as Integer 0 = use field that currently has focus (not on all devices, see above.) objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID. topLeftX as Integer topLeftY as Integer width as Integer height as Integer

Example Dim objID as Integer Dim topLeftX as Integer Dim topLeftY as Integer Dim width as Integer Dim height as Integer objID = 1008 NSL.FieldSetBounds objID, topLeftX, topLeftY, width, height

May raise a fatal error message if the memory block that contains the word-wrapping information needs to be resized and there is not enough space to do so.

FormGetNumberOfObjects

nbr = NSBSystemLib.FormGetNumberOfObjects()
Retrieves the number of objects on the active form.

Returns nbr as Integer -1 if no form is active

Example Dim nbr as Integer nbr = NSL.FormGetNumberOfObjects()

FormGetObjectBounds

x = NSBSystemLib.FormGetObjectBounds(objID)
Retrieves the x, y, width, and height values of a form object.

Parameter objID as Integer 0 = use object that currently has focus objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID.

Returns x as Integer -1 if the object is invalid or no object has focus

Example Dim x as Integer Dim objID as Integer Dim y as Integer Dim width as Integer Dim height as Integer objID = 1008 x = NSL.FormGetObjectBounds(objID) y = NSL.GlobalY() width = NSL.GlobalWidth() height = NSL.GlobalHeight()

This function only returns the x position. Use the GlobalY(), GlobalWidth(), and GlobalHeight() functions to retrieve the other values.

FormGetObjectPosition

x = NSBSystemLib.FormGetObjectPosition(objID)
Retrieves the starting X and Y position values of a form object.

Parameter objID as Integer 0 = use object that currently has focus objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID.

Returns x as Integer -1 if the object is invalid or no object has focus

Example Dim x as Integer Dim objID as Integer Dim y as Integer objID = 1008 x = NSL.FormGetObjectPosition(objID) y = NSL.GlobalY

This function only returns the X position. Use the GlobalY(), function to retrieve the Y position.

FormGetObjectType

type = NSBSystemLib.FormGetObjectType(objID)
Retrieves the object type of the specified object.

Parameter objID as Integer 0 = use object that currently has focus objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID.

Returns type as Integer -1 if the object is invalid or no object has focus 0 = frmFieldObj 1 = frmControlObj 2 = frmListObj 3 = frmTableObj 4 = frmBitmapObj 5 = frmLineObj 6 = frmFrameObj 7 = frmRectangleObj 8 = frmLabelObj 9 = frmTitleObj 10 = frmPopupObj 11 = frmGraffitiStateObj 12 = frmGadgetObj 13 = frmScrollbarObj

Example Dim type as Integer Dim objID as Integer objID = 1008 type = NSL.FormGetObjectType(objID)

This function does not provide information regarding all the different Control object types. To retrieve a complete list of object types use the FormGetAllObjectTypes() function.

FormSetObjectPosition

NSBSystemLib.FormSetObjectPosition objID, x, y
Changes an object's current position.

Parameters objID as Integer 0 = use object that currently has focus objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID. x as Integer y as Integer

Example Dim objID as Integer Dim x as Integer Dim y as Integer objID = 1008 x = 120 y = 40 NSL.FormSetObjectPosition objID, x, y

FormSetObjectBounds

NSBSystemLib.FormSetObjectBounds objID, topLeftX, topLeftY, width, height
Set the bounds or position of an object.

Parameters objID as Integer 0 = use object that currently has focus objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID. topLeftX as Integer topLeftY as Integer width as Integer height as Integer

Example Dim objID as Integer Dim topLeftX as Integer Dim topLeftY as Integer Dim width as Integer Dim height as Integer objID = 1008 NSL.FormSetObjectBounds objID, topLeftX, topLeftY, width, height

FormGetTitle

title = NSBSystemLib.FormGetTitle()
Returns the form's current title.

Returns title as String

Example Dim title as String title = NSL.FormGetTitle()

FormReplaceTitle

NSBSystemLib.FormReplaceTitle title, forceLength
Replace the current form's title. The length of the title string can not exceed the original title string length. If the forceLength parameter is 0, then the replacement string will automatically be truncated to the current title length. If you will vary the length of your title string, you should use the FormGetTitle() function to retrieve the original title string before you ever change it. Then obtain its length using the NSBasic Len() function. Use this value as the forceLength parameter for all subsequent title replacements.

Parameters title as String forceLength as Integer

Example Dim title as String Dim forceLength as Integer NSL.FormReplaceTitle title, forceLength

ListGetTopItem

topItem = NSBSystemLib.ListGetTopItem(objID)
Returns the top item number of the specified list box.

Parameter objID as Integer

Returns topItem as Integer

Example Dim topItem as Integer Dim objID as Integer topItem = NSL.ListGetTopItem(objID)

ListSetTopItem

NSBSystemLib.ListSetTopItem objID, topItem
Sets the top item number of the specified list box. The item cannot become the top item if it's on the last page.

Parameters objID as Integer topItem as Integer

Example Dim objID as Integer Dim topItem as Integer NSL.ListSetTopItem objID, topItem

ListGetVisibleItems

visibleItems = NSBSystemLib.ListGetVisibleItems(objID)
Returns the number of visible items in the specified list box.

Parameter objID as Integer

Returns visibleItems as Integer

Example Dim visibleItems as Integer Dim objID as Integer visibleItems = NSL.ListGetVisibleItems(objID)

ListScrollList

result = NSBSystemLib.ListScrollList(objID, direction, nbrItems)
Scroll the specified list box by the number of items and in the direction indicated.

Parameters objID as Integer direction as Integer 0 = up 1 = down nbrItems as Integer

Returns result as Integer 0 = if the list box could not be scrolled 1 = if the list box was scrolled successfully

Example Dim result as Integer Dim objID as Integer Dim direction as Integer Dim nbrItems as Integer result = NSL.ListScrollList(objID, direction, nbrItems)


Font Support

The Font Support functions provide support for determining and changing the default font. They also provide support for working with the PalmOS variable width fonts.

FontGetFont

fontId = NSBSystemLib.FontGetFont()
Return the Font ID of the current font.

Returns fontId as Integer

Example Dim fontId as Integer fontId = NSL.FontGetFont()

FontSetFont

oldFontId = NSBSystemLib.FontSetFont(fontId)
Set the current font.

Parameter fontId as Integer

Returns oldFontId as Integer

Example Dim oldFontId as Integer Dim fontId as Integer oldFontId = NSL.FontSetFont(fontId)

FontSelect

fontId = NSBSystemLib.FontSelect()
Displays a dialog box in which the user can choose one of three system-supplied fonts, and returns a FontID value representing the user's choice.

Returns fontId as Integer

Example Dim fontId as Integer fontId = NSL.FontSelect()

FontCharWidth

width = NSBSystemLib.FontCharWidth(charString)
Return the width of the specified character. If the specified character does not exist within the current font, the Missing Character Symbol is substituted.

Note: Even though the parameter to this function is a string, only the first character of the string is evaluated.

Parameter charString as String

Returns width as Integer

Example Dim width as Integer Dim charString as String width = NSL.FontCharWidth(charString)

FontCharsWidth

width = NSBSystemLib.FontCharsWidth(charString, optionalLen)
Return the width of the specified character string. The Missing Character Symbol is substituted for any character which does not exist in the current font.

Parameters charString as String optionalLen as Integer 0 = use actual string length

Returns width as Integer

Example Dim width as Integer Dim charString as String Dim optionalLen as Integer width = NSL.FontCharsWidth(charString, optionalLen)

FontWidthToOffset

offset = NSBSystemLib.FontWidthToOffset(charString, optionalLen, width)
Given a pixel position, return the offset of the character displayed at that location. If the pixel position was on the left side of the character, GlobalStartPos() will return 1, otherwise, it will return 0. GlobalWidth() will return the pixel width of the text up to the returned offset.

Parameters charString as String optionalLen as Integer 0 = use actual string length width as Integer

Returns offset as Integer

Example Dim offset as Integer Dim charString as String Dim optionalLen as Integer Dim width as Integer offset = NSL.FontWidthToOffset(charString, optionalLen, width)

FontCharsInWidth

length = NSBSystemLib.FontCharsInWidth(charString, optionalLen, width)
Find the length in bytes of the characters from a specified string that fit within a passed width. GlobalWidth() will return the actual pixel width of the characters that fit within the passed width.

Parameters charString as String optionalLen as Integer 0 = use actual string length width as Integer

Returns length as Integer

Example Dim length as Integer Dim charString as String Dim optionalLen as Integer Dim width as Integer length = NSL.FontCharsInWidth(charString, optionalLen, width)

Spaces at the end of a string are ignored and removed. Characters after a carriage return are ignored, the string is considered truncated.

FontWordWrap

length = NSBSystemLib.FontWordWrap(charString, width)
Given a string, determine how many bytes of text can be displayed within the specified width.

Parameters charString as String width as Integer 0 = use actual string length

Returns length as Integer

Example Dim length as Integer Dim charString as String Dim width as Integer length = NSL.FontWordWrap(charString, width)


HotSync Data

The HotSync data functions provide information from the HotSync application.

SyncUserName

userName = NSBSystemLib.SyncUserName()
Returns the HotSync user name.

Returns userName as String

Example Dim userName as String userName = NSL.SyncUserName()

SuccessfulSync

syncDate = NSBSystemLib.SuccessfulSync()
Returns the date, in system format, of the last successful HotSync operation. System format dates are expressed as the number of seconds since January 1st, 1904. Use the StringDateTime(), StringDate(), or StringTime() functions to retrieve a string representation of a system format date.

Returns syncDate as Integer

Example Dim syncDate as Integer syncDate = NSL.SuccessfulSync()

LastSync

syncDate = NSBSystemLib.LastSync()
Returns the date, in system format, of the last successful or unsuccessful HotSync operation. System format dates are expressed as the number of seconds since January 1st, 1904. Use the StringDateTime(), StringDate(), or StringTime() functions to retrieve a string representation of a system format date.

Returns syncDate as Integer

Example Dim syncDate as Integer syncDate = NSL.LastSync()


Localization Functions

The localization functions are used to convert date and number strings from Standard/US format to the user's preferred format as specified in the system preferences. For instance, in some European countries, the "thousands" separator in a number is a "." and the "decimal" separator is a ",". Dates are usually preferred in dd/mm/yy format. These functions look up the user's set preference for these formats and provide any conversion necessary.

LocalizeNumber

localNbrStr = NSBSystemLib.LocalizeNumber(stdNbrStr)
Convert a number string in standard/US format to a localized format as determined by system preferences.

Parameter stdNbrStr as String

Returns localNbrStr as String

Example Dim localNbrStr as String Dim stdNbrStr as String stdNbrStr = "4,123.56" localNbrStr = NSL.LocalizeNumber(stdNbrStr)

DelocalizeNumber

stdNbrStr = NSBSystemLib.DelocalizeNumber(localNbrStr)
Convert a number string in a localized format to a standard/US format as determined by system preferences.

Parameter localNbrStr as String

Returns stdNbrStr as String

Example Dim stdNbrStr as String Dim localNbrStr as String locNbrStr = "4.123,56" stdNbrStr = NSL.DelocalizeNumber(localNbrStr)

LocalizeDate

localDateStr = NSBSystemLib.LocalizeDate(stdDateStr, ToDateFormat, longDateFormat)
Convert a date string in standard/US format to a localized date format as determined by system preferences.

Parameters stdDateStr as String The date string may also contain the time. Time values will be ignored. ToDateFormat as Integer 0 = stdDateStr format is "MM/DD/YY[YY]" 1 = stdDateStr format is "[YY]YY/MM/DD" longDateFormat as Integer 0 = use short date format preference 1 = user long date format preference

Returns localDateStr as String

Example Dim localDateStr as String Dim stdDateStr as String Dim ToDateFormat as Integer Dim longDateFormat as Integer stdDateStr = DateMMDDYY(Today()) ToDateFormat = 0 longDateFormat = 0 localDateStr = NSL.LocalizeDate(stdDateStr, ToDateFormat, longDateFormat)


Preference Functions

Preferences are divided into two categories - System Preferences and Application Preferences. System Preferences include such things as auto-off time, date formats, etc. Application Preferences are used for storing information about a particular application. These preferences can be used to store program state, registration codes, etc. Using application preferences can eliminate the need to create a specific database for this purpose. Application preferences are not intended to contain very large amounts of data.

GetAppPreferences

data = NSBSystemLib.GetAppPreferences(pgmName, prefId, saved)
Get an application preference string.

Parameters pgmName as String Program Name - This is case sensitive prefId as Integer Preference ID saved as Integer 0 = preference does not get restored after a hard reset 1 = preference does get restored after a hard reset

Returns data as String

Example Dim data as String Dim pgmName as String Dim prefId as Integer Dim saved as Integer pgmName = "SysLibTest" prefId = 1 saved = 0 data = NSL.GetAppPreferences(pgmName, prefId, saved)

SetAppPreferences

status = NSBSystemLib.SetAppPreferences(pgmName, prefId, data, saved)
Set an application preference string.

Parameters pgmName as String Program Name - This is case sensitive prefId as Integer Preference ID data as String saved as Integer 0 = preference does not get restored after a hard reset 1 = preference does get restored after a hard reset

Returns status as Integer 0 = Success -1 = Invalid program name

Example Dim status as Integer Dim pgmName as String Dim prefId as Integer Dim data as String Dim saved as Integer pgmName = "SysLibTest" prefId = 1 data = "anything I want!" saved = 0 status = NSL.SetAppPreferences(pgmName, prefId, data, saved)

Currently preference strings are limited to 250 bytes or less.

GetSysPreference

data = NSBSystemLib.GetSysPreference(prefID)
Get the value of a system preference.

Parameter prefID as Integer From Preferences.h in the PalmOS SDK: 0 = prefVersion 1 = prefCountry 2 = prefDateFormat 3 = prefLongDateFormat 4 = prefWeekStartDay 5 = prefTimeFormat 6 = prefNumberFormat 7 = prefAutoOffDuration prefAutoOffDurationSecs is now preferred (prefAutoOffDuration is in minutes) 8 = prefSysSoundLevelV20 9 = prefGameSoundLevelV20 10 = prefAlarmSoundLevelV20 11 = prefHidePrivateRecordsV33 12 = prefDeviceLocked 13 = prefLocalSyncRequiresPassword 14 = prefRemoteSyncRequiresPassword 15 = prefSysBatteryKind 16 = prefAllowEasterEggs 17 = prefMinutesWestOfGMT deprecated old unsigned minutes EAST of GMT 18 = prefDaylightSavings deprecated old daylight saving time rule 19 = prefRonamaticChar 20 = prefHard1CharAppCreator App creator for hard key #1 21 = prefHard2CharAppCreator 22 = prefHard3CharAppCreator 23 = prefHard4CharAppCreator 24 = prefCalcCharAppCreator 25 = prefHardCradleCharAppCreator 26 = prefLauncherAppCreator 27 = prefSysPrefFlags 28 = prefHardCradle2CharAppCreator 29 = prefAnimationLevel Additions for PalmOS 3.0: ------------------------- 30 = prefSysSoundVolume actual amplitude - error beeps and other non-alarm/game sounds 31 = prefGameSoundVolume 32 = prefAlarmSoundVolume 33 = prefBeamReceive not used - use ExgLibControl with ir(Get/Set) ScanningMode instead 34 = prefCalibrateDigitizerAtReset True makes the user calibrate at soft reset time 35 = prefSystemKeyboardID ID of the preferred keyboard resource 36 = prefDefSerialPlugIn creator ID of the default serial plug-in Additions for PalmOS 3.1: ------------------------- 37 = prefStayOnWhenPluggedIn 38 = prefStayLitWhenPluggedIn Additions for PalmOS 3.2: ------------------------- 39 = prefAntennaCharAppCreator App creator for antenna key Additions for PalmOS 3.3: ------------------------- 40 = prefMeasurementSystem English, Metric, etc. Additions for PalmOS 3.5: ------------------------- 41 = prefShowPrivateRecords returns privateRecordViewEnum 42 = prefAutoOffDurationSecs Additions for PalmOS 4.0: ------------------------- 43 = prefTimeZone GMT offset in minutes, + for east of GMT, - for west 44 = prefDaylightSavingAdjustment current DST adjustment in minutes (typically 0 or 60) 45 = prefAutoLockType Never, on poweroff, after preset delay or at preset time. 46 = prefAutoLockTime Auto lock preset time or delay. 47 = prefAutoLockTimeFlag For Minutes or Hours. 48 = prefLanguage Language spoken in country selected via Setup app/Formats panel 49 = prefLocale Locale for country selected via Setup app/Formats panel 50 = prefTimeZoneCountry Country used to specify time zone. 51 = prefAttentionFlags User prefs for getting user's attention 52 = prefDefaultAppCreator Default application launched on reset.

Returns data as Integer

Example Dim data as Integer Dim prefID as Integer prefID = 7 'prefAutoOffDuration - in seconds data = NSL.GetSysPreference(prefID)

SetSysPreference

NSBSystemLib.SetSysPreference prefID, data
Set the value of a system preference.

Parameters prefID as Integer See GetSysPreference() for preference ID values data as Integer

Example Dim prefID as Integer Dim data as Integer prefID = 7 'prefAutoOffDuration - in minutes data = 3 '3 minutes NSL.SetSysPreference prefID, data


Progress Manager Functions

The Progress Manager functions provide methods for providing and updating a dialog that is displayed during long operations. They provide feedback to the user about the progress of the operation.

ProgressStartDialog

NSBSystemLib.ProgressStartDialog title
Start a Progress Dialog. The Progress Dialog functions are used to display a special type of alert that informs the user of the progress being made during operations that take a long time.

Parameter: title as String must be 20 characters or less.

Example Dim title as String Dim message as String Dim stage as Integer Dim error as Integer Dim force as Integer Dim canceled as Integer Dim strValue as String Dim resolution as Integer Dim completeChar as String Dim incompleteChar as String Dim percent as Integer Dim count as Integer completeChar = "|" incompleteChar = "." resolution = 5 count = 100 title = "Progress Test..." NSL.ProgressStartDialog title Delay 1 error = 0 stage = 1 Do While stage <= count canceled = NSL.ProgressUserCancel() If canceled = 1 Then Exit Do End If percent = NSL.ProgressPercent(stage, count) strValue = NSL.ProgressPercentString(percent, resolution, _ completeChar, incompleteChar) Message = strValue + Chr(10) + Str(percent) _ + "% complete" + Chr(10) _ + "stage = " + Str(stage) NSL.ProgressUpdateDialog error, message stage = stage + 1 Delay 0.25 Loop force = 0 Delay 1 NSL.ProgressStopDialog(force)

See also: ProgressStopDialog(), ProgressUpdateDialog()

ProgressStopDialog

NSBSystemLib.ProgressStopDialog force
Stops a Progress Dialog. This function must be called to make the dialog disappear.

Parameter: force as Integer 0 = do not force an immediate exit of the dialog 1 = force an immediate exit of the dialog This parameter only has meaning if the dialog is in the process of displaying an error message. If "force" is set to 0, then the user must press the "OK" button on the dialog before the dialog disappears.

Example See the example provided with ProgressStartDialog()

ProgressUpdateDialog

NSBSystemLib.ProgressUpdateDialog error, message
Update the message that is displayed in the Progress Dialog.

Parameters error as Integer 0 = no error 1 = use error processing if "error" is set to 1, the dialog will display the specified message and only present one button - "OK". message as String Message string to display. This string must be less than 128 characters in length.

Example See the example provided with ProgressStartDialog().

ProgressUserCancel

canceled = NSBSystemLib.ProgressUserCancel()
Returns 1 if the user pressed the "Cancel" button on the Progress dialog. If you have an operation that should not or can not be canceled, then do not call this function. The "Cancel" button will still be present, but it will not do anything. Currently, with PalmOS, this button can not be made invisible or grayed out.

Returns canceled as Integer

Example See the example provided with ProgressStartDialog().

ProgressPercent

percent = NSBSystemLib.ProgressPercent(current, count)
Calculates a percentage complete number based on the input values. This function is not really part of the Progress Manager API. It is just provided as a convenient way to calculate a percentage complete value that can be included in your Progress Dialog message.

Parameters current as Integer Current iteration number of your process loop. count as Integer Number of iterations required to be 100 percent complete.

Returns percent as Integer

Example See the example provided with ProgressStartDialog().

ProgressPercentString

strValue = NSBSystemLib.ProgressPercentString(percent, resolution, completeChar, incompleteChar)
Constructs a string with characters representing the percentage complete and incomplete for your process loop. This function is not really part of the Progress Manager API. It is just provided as a convenient way to display a crude "graphic" representation of your loop's progress. This string can be included as part of your Progress Dialog message.

Parameters percent as Integer Percent complete - see also ProgressPercent(). resolution as Integer The resolution size of the percent string. A resolution of 1 means that there will be 100 characters in the percent string. Every 1% change will be reflected in the percent string. A resolution of 5 means that there will be 20 characters in the percent string. Every 5% change will be reflected in the percent string. As you can see, the total length of the percent string is calculated as (100 / resolution). As such, resolution values should be one of the following: 1, 2, 4, 5, 10, 20, 25, or 50 completeChar as String The character to display for the percent completed. "|" is recommended. incompleteChar as String The character to display for the percent incomplete. "." is recommended. The "completeChar" and "incompleteChar" characters should probably be characters with the exact same pixel width. Otherwise, the percent string display width will vary as the percentage complete changes.

Returns strValue as String

Example See the example provided with ProgressStartDialog().


String Functions

The following string functions provide convenient methods for manipulating strings for use with the other functions in this library.

String4ToInt

intValue = NSBSystemLib.String4ToInt(fourByteString)
Returns the integer value of a 4 byte string. This function is useful for calculating the integer value of Creator IDs, Application Types, Resource Types, etc.

Parameter fourByteString as String

Returns intValue as Integer

Example Dim intValue as Integer Dim fourByteString as String fourByteString = "libr" intValue = NSL.String4ToInt(fourByteString)

See also: IntToString4()

IntToString4

fourByteString = NSBSystemLib.IntToString4(intValue)
Returns a 4 byte string from an integer value. This function is useful for retrieving the string value of integer Creator IDs, Application Types, Resource Types, etc.

Parameter intValue as Integer

Returns fourByteString as String

Example Dim fourByteString as String Dim intValue as Integer intValue = 1818845810 '"libr" fourByteString = NSL.IntToString4(intValue)

See also: String4ToInt()

DelimitedItem

item = NSBSystemLib.DelimitedItem(inputStr, delimiter, nbr)
Returns a particular substring item from a string that contains multiple items separated by a particular delimiter.

Parameters inputStr as String A string containing delimited items. delimiter as String A string containing the delimiter character or characters. nbr as Integer The item number to return. Item numbers begin with 1.

Returns item as String The delimiter string will be returned if the requested item is not present.

Example Dim item as String Dim inputStr as String Dim delimiter as String Dim nbr as Integer inputStr = "Joe;Mary;Jane" delimiter = ";" nbr = 2 'Returns the string "Mary" item = NSL.DelimitedItem(inputStr, delimiter, nbr)

FixedWidthString

fixedStr = NSBSystemLib.FixedWidthString(origStr, width, options)
This function returns a fixed width string. It can be used to create columns of data that line up nicely in fields, popups, or list boxes. A combination of "wide" spaces (chr(25)) and "normal" spaces (chr(32)) are appended, if necessary, to pad the string to the desired pixel width. Strings that can not fit within the specified width are truncated.

A wide space is 5 pixels wide. A normal space is 2 pixels wide. This function only works with the standard font - font id 0.

Parameters origStr as String Original string. width as Integer Width in pixels. options as Integer 0 = left justify string 1 = right justify string 2 = left justify string and use ellipsis (...) if truncated 3 = right justify string and use ellipsis (...) if truncated 4 = center justify string and use ellipsis (...) if truncated 5 = center justify string

Returns fixedStr as String Fixed width string

Example Dim fixedStr as String Dim origStr as String Dim width as Integer Dim options as Integer origStr = "This is a test" width = 80 options = 0 fixedStr = NSL.FixedWidthString(origStr, width, options)

Use the NormalSpacedString() function to translate a fixed width string back to a string containing only normal spaces.

NormalSpacedString

normalStr = NSBSystemLib.NormalSpacedString(origStr)
Translates a fixed width string to a string containing only normal spaces. This function replaces all "wide" spaces (chr(25)) with "normal" spaces (chr(32)).

Parameter origStr as String

Returns normalStr as String

Example Dim normalStr as String Dim origStr as String normalStr = NSL.NormalSpacedString(origStr)

See also: FixedWidthString()

System Time Functions

The PalmOS system time format is an integer that contains the number of seconds since January 1st, 1904. Most of the PalmOS API functions that have date and time parameters use this format. The system time functions provide methods for creating and interpretting system time format values.

SelectOneTime

newTimeSelected = NSBSystemLib.SelectOneTime(defHour, defMinute, title)
Calls the SelectOneTime() PalmOS function to display a dialog that allows a user to select 1 time value. This function returns 1 if a newTime was selected, otherwise it returns 0. use the GlobalHour() and GlobalMinute() functions to retrieve selected time values.

Parameters defHour as Integer Default hour for selection defMinute as Integer Default minute for selection title as String

Returns newTimeSelected as Integer

Example Dim newTimeSelected as Integer Dim defHour as Integer Dim defMinute as Integer Dim title as String defHour = 10 defMinute = 30 title = "Some Title" newTimeSelected = NSL.SelectOneTime(defHour, defMinute, title) If newTimeSelected = 1 Then defHour = NSL.GlobalHour() defMinute = NSL.GlobalMinute() End If

IncrementSystemTime

newSysTime = NSBSystemLib.IncrementSystemTime(oldSysTime, hours, minutes, seconds)
Returns a system time value that is incremented by the specified number of hours, minutes, and seconds. A system time value is an integer that is expressed as the number of seconds since January 1st, 1904.

Parameters oldSysTime as Integer 0 = use current system time. hours as Integer minutes as Integer seconds as Integer

Returns newSysTime as Integer

Example Dim newSysTime as Integer Dim oldSysTime as Integer Dim hours as Integer Dim minutes as Integer Dim seconds as Integer oldSysTime = 0 hours = 0 minutes = 30 seconds = 0 'Add 30 minutes newSysTime = NSL.IncrementSystemTime(oldSysTime, hours, minutes, seconds)

SystemTime

sysTime = NSBSystemLib.SystemTime(strDate, strTime, seconds, ToDateFormat)
Returns a "System Time" value. This value is expressed as the number of seconds since January 1st, 1904. The time to return is supplied as strings in the strDate and strTime parameters. The strDate parameter may contain only a date value or both a date and a time value. If the strTime parameter is blank (""), the time, if specified, in the strDate parameter will be used. If both the strDate and the strTime parameters are blank, the current system time will be used. The additional seconds parameter is used to provide an easy way to increment or decrement the returned system time. For example: systemTime = NSL.SystemTime("", "", 5, 0) returns the current time plus 5 seconds.

Parameters strDate as String See the ToDateFormat parameter for date string formats. strTime as String The time string is specified as: "HH[:MM[:SS]][AM|PM|am|pm]" (actually, if the character 'P' or 'p' is present, the time will be interpreted as AM/PM format and the hour will be appropriately adjusted). seconds as Integer Increment (or decrement, if negative) the returned systemTime by the specified number of seconds. ToDateFormat as Integer 0 = strDate string is in MM/DD/YYYY or MM/DD/YY format. 1 = strDate string is in YYYY/MM/DD or YY/MM/DD format.

Returns sysTime as Integer Integer time as expressed as the number of seconds since January 1st, 1904.

Example Dim sysTime as Integer Dim strDate as String Dim strTime as String Dim seconds as Integer Dim ToDateFormat as Integer strDate = "" strTime = "" Seconds = 5 ToDateFormat = 0 sysTime = NSL.SystemTime(strDate, strTime, seconds, ToDateFormat)

See also: StringDateTime(), StringDate(), and StringTime()

StringDateTime

strDateTime = NSBSystemLib.StringDateTime(sysTime, ToDateFormat, ToTimeFormat, AMPMFormat)
Returns a string representation of the supplied "System Time" value. The sysTime value is an integer value expressed as the number of seconds since January 1st, 1904. The returned value is a string containing both the date and time. If the sysTime parameter is specified as 0, the current system date and time will be returned.

Parameters sysTime as Integer Integer time as expressed as the number of seconds since January 1st, 1904. ToDateFormat as Integer 0 = the date string will be in MM/DD/YY format. 1 = the date string will be in YYYY/MM/DD format. 2 = the date string will be in MM/DD/YYYY format. 3 = the date string will be in YY/MM/DD format. ToTimeFormat as Integer 0 = the time string will be in HH:MM format. 1 = the time string will be in HH:MM:SS format. AMPMFormat as Integer 0 = no AM/PM indicators will be added. 1 = " AM" or " PM" indicator will be added and the hour will will be adjusted appropriately.

Returns strDateTime as String

Example Dim strDateTime as String Dim sysTime as Integer Dim ToDateFormat as Integer Dim ToTimeFormat as Integer Dim AMPMFormat as Integer sysTime = SystemTime("", "", 0, 0) strDateTime = NSL.StringDateTime(sysTime, ToDateFormat, ToTimeFormat, AMPMFormat)

See also: SystemTime(), StringDate(), and StringTime()

StringDate

strDate = NSBSystemLib.StringDate(sysTime, ToDateFormat)
Returns a string representation of the supplied "System Time" value. The sysTime value is an integer value expressed as the number of seconds since January 1st, 1904. The returned value is a string containing only the date. If the sysTime parameter is specified as 0, the current system date will be returned.

Parameters sysTime as Integer Integer time as expressed as the number of seconds since January 1st, 1904. ToDateFormat as Integer 0 = the date string will be in MM/DD/YY format. 1 = the date string will be in YYYY/MM/DD format. 2 = the date string will be in MM/DD/YYYY format. 3 = the date string will be in YY/MM/DD format.

Returns strDate as String

Example Dim strDate as String Dim sysTime as Integer Dim ToDateFormat as Integer sysTime = SystemTime("", "", 0, 0) strDate = NSL.StringDate(sysTime, ToDateFormat)

See also: SystemTime(), StringDateTime(), and StringTime()

StringTime

strTime = NSBSystemLib.StringTime(sysTime, ToTimeFormat, AMPMFormat)
Returns a string representation of the supplied "System Time" value. The sysTime value is an integer value expressed as the number of seconds since January 1st, 1904. The returned value is a string containing only the time. If the sysTime parameter is specified as 0, the current system time will be returned.

Parameters sysTime as Integer Integer time as expressed as the number of seconds since January 1st, 1904. ToTimeFormat as Integer 0 = the time string will be in HH:MM format. 1 = the time string will be in HH:MM:SS format. AMPMFormat as Integer 0 = no AM/PM indicators will be added. 1 = " AM" or " PM" indicator will be added and the hour will will be adjusted appropriately.

Returns strTime as String

Example Dim strTime as String Dim sysTime as Integer Dim ToTimeFormat as Integer Dim AMPMFormat as Integer sysTime = SystemTime("", "", 0, 0) strTime = NSL.StringTime(sysTime, ToTimeFormat, AMPMFormat)

See also: SystemTime(), StringDateTime(), and StringDate()

Version 1.4 Changes and Additions

Version 1.4 contains additional options for the FixedWidthString, StringDateTime, and StringDate functions.

The "rightJustify" parameter of the FixedWidthString function has been changed to "options". This parameter still controls justification but it is also now used to control whether an ellipsis ("...") is appended to a string that had to be truncated.

The StringDateTime and StringDate functions now have 2 new option values for the "ToDateFormat" parameter. These options provide more flexibility in how the year is formatted.

The following functions are new in this version of the NSBSystemLib shared library. It would be wise to check the NSBSystemLib version number to ensure that it is version 1.4 or greater before using any of these new functions.

PostEvent

NSBSystemLib.PostEvent eventNbr
Posts an event to the event queue by calling EvtAddEventToQueue. The event number should be a custom event in the range of 24576 to 32767.

Parameter: eventNbr as Integer

Example Dim eventNbr as Integer eventNbr = 30000 NSL.PostEvent eventNbr

FormGetFocus

objID = NSBSystemLib.FormGetFocus()
Returns the object ID of the object that currently has focus.

Returns objID as Integer -1 if no object has focus.

Example Dim objID as Integer objID = NSL.FormGetFocus()

FieldGetTextLength

txtLen = NSBSystemLib.FieldGetTextLength(objID)
Returns the length of a field's text.

Parameter objID as Integer 0 = use field that currently has focus (not on all devices, see above.) objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID.

Returns txtLen as Integer

Example Dim txtLen as Integer Dim objID as Integer objID = 1008 txtLen = NSL.FieldGetTextLength(objID)

RandomNumber

nbr = NSBSystemLib.RandomNumber(seed, minNbr, maxNbr)
Returns a random integer number in the range from min to max.

Parameters seed as Integer New seed value, use 0 to use the existing seed. minNbr as Integer Min must be >= 0 and less than Max maxNbr as Integer Max must be <= 32767 and greater than Min

Returns nbr as Integer

Example Dim nbr as Integer Dim seed as Integer Dim minNbr as Integer Dim maxNbr as Integer minNbr = 1 maxNBR = 10 nbr = NSL.RandomNumber(seed, minNbr, maxNbr)

ResetAutoOffTimer

NSBSystemLib.ResetAutoOffTimer()
Reset the AutoOffTimer. This function is typically called in a loop to keep the auto off timer from turning off the device during long running operations.

Example NSL.ResetAutoOffTimer()

SetAutoOffTime

oldSeconds = NSBSystemLib.SetAutoOffTime(newSeconds)
Set the auto off time in seconds. This function returns the previous setting so that it can be restored when the program or function ends.

Parameter newSeconds as Integer

Returns oldSeconds as Integer

Example Dim oldSeconds as Integer Dim newSeconds as Integer newSeconds = 600 '10 minutes oldSeconds = NSL.SetAutoOffTime(newSeconds)

ProgramVersionString

verStr = NSBSystemLib.ProgramVersionString(cardNbr, pgmName)
Returns a program's version string by reading it's first 'tver' resource. If this resource is not available, the database version number is returned.

Parameters cardNbr as Integer pgmName as String

Returns verStr as String

Example Dim verStr as String Dim cardNbr as Integer Dim pgmName as String cardNbr = 0 pgmName = "NSBSystemLib" verStr = NSL.ProgramVersionString(cardNbr, pgmName)

DynamicHeapSize

heapSize = NSBSystemLib.DynamicHeapSize()
Returns the size of the Dynamic Heap.

Returns heapSize as Integer

Example Dim heapSize as Integer heapSize = NSL.DynamicHeapSize()

DynamicHeapFree

freeSize = NSBSystemLib.DynamicHeapFree()
Returns the number of free bytes in the Dynamic Heap.

Returns freeSize as Integer

Example Dim freeSize as Integer freeSize = NSL.DynamicHeapFree()

DynamicHeapMaxChunk

maxChunkSize = NSBSystemLib.DynamicHeapMaxChunk()
Returns the size of the largest chunk in the Dynamic Heap.

Returns maxChunkSize as Integer

Example Dim maxChunkSize as Integer maxChunkSize = NSL.DynamicHeapMaxChunk()

SortInit

error = NSBSystemLib.SortInit(maxItems, itemType)
Initializes a sort array to be used with the SortQSort and SortInsertionSort functions. The maxItems parameter specifies the maximum number of items to be sorted/added to the sort array. This number does not have to be exact, but it must be equal to or greater than the number of items actually added. To free the memory used by a sort array, specify maxItems as 0. The previous sort array is automatically freed when the library is closed at program termination or when a new sort array is initialized.

When maxItems is > 0, the itemType parameter specifies the type of data that will be sorted. The itemType parameter is not case sensitive and must be one of the following strings: "string", "integer", or "double". After the sort array is initialized, only data of the itemType specified may be added to or retrieved from the sort array.

Parameters maxItems as Integer The maximum number of data items to be added to the sort array. itemType as String The data type to be sorted. Valid values are: "string", "integer", or "double"

Returns error as Integer 0 = no error -1 = insufficient dynamic memory -2 = invalid itemType parameter

Example See either the SortQSort() or SortInsertionSort() functions.

SortAddString

error = NSBSystemLib.SortAddString(strItem)
Add a string data item to the sort array.

Parameter strItem as String String data to add.

Returns error as Integer 0 = no error -1 = insufficient dynamic memory -2 = sort array has not been initialized -3 = sort array was not initialized for string data -4 = exceeded the initialized number of items for the sort array

Example See either the SortQSort() or SortInsertionSort() functions.

SortAddInteger

error = NSBSystemLib.SortAddInteger(intItem)
Add an integer data item to the sort array.

Parameter intItem as Integer String data to add.

Returns error as Integer 0 = no error -1 = insufficient dynamic memory -2 = sort array has not been initialized -3 = sort array was not initialized for integer data -4 = exceeded the initialized number of items for the sort array

Example See either the SortQSort() or SortInsertionSort() functions.

SortAddDouble

error = NSBSystemLib.SortAddDouble(dblItem)
Add a double data item to the sort array.

Parameter dblItem as Double String data to add.

Returns error as Integer 0 = no error -1 = insufficient dynamic memory -2 = sort array has not been initialized -3 = sort array was not initialized for double data -4 = exceeded the initialized number of items for the sort array

Example See either the SortQSort() or SortInsertionSort() functions.

SortGetString

strItem = NSBSystemLib.SortGetString(index)
Retrieve a string data item from the sort array.

Parameter index as Integer The index or subscript of a data item in the sort array.

Returns strItem as String

Example See either the SortQSort() or SortInsertionSort() functions.

SortGetInteger

intItem = NSBSystemLib.SortGetInteger(index)
Retrieve an integer data item from the sort array.

Parameter index as Integer The index or subscript of a data item in the sort array.

Returns intItem as Integer

Example See either the SortQSort() or SortInsertionSort() functions.

SortGetDouble

dblItem = NSBSystemLib.SortGetDouble(index)
Retrieve a double data item from the sort array.

Parameter index as Integer The index or subscript of a data item in the sort array.

Returns dblItem as Double

Example See either the SortQSort() or SortInsertionSort() functions.

SortQSort

numItems = NSBSystemLib.SortQSort(reverseSort, caselessSort)
Performs a "quick sort" of the items in the sort array that was initialized with SortInit() and populated with either SortAddString(), SortAddInteger(), or SortAddDouble(). This function calls the SysQSort PalmOS API function. The SortInsertionSort function can also be used. Here is how the PalmOS SDK documentation describes the SysQSort API function:

Equal records can be in any position relative to each other because a quick sort tends to scramble the ordering of records. As a result, calling SysQSort multiple times can result in a different order if the records are not completely unique. If you don't want this behavior, use the insertion sort instead (see SysInsertionSort).

To pick the pivot point, the quick sort algorithm picks the middle of three records picked from around the middle of all records. That way, the algorithm can take advantage of partially sorted data.

These optimizations are built in:

The routine contains its own stack to limit uncontrolled recursion. When the stack is full, an insertion sort is used because it doesn't require more stack space.

An insertion sort is also used when the number of records is low. This avoids the overhead of a quick sort which is noticeable for small numbers of records.

If the records seem mostly sorted, an insertion sort is performed to move only those few records that need to be moved.

Parameters reverseSort as Integer 0 = list is sorted from lowest to highest values 1 = list is sorted from highest to lowest values caselessSort as Integer 0 = sort is case sensitive 1 = sort is not case sensitive

Returns numItems as Integer the number of items sorted Use the appropriate function (SortGetString(), SortGetInteger(), or SortGetDouble()) to return the items from the sort array.

Example Dim error as Integer Dim maxItems as Integer Dim itemType as String Dim numItems as Integer Dim reverseSort as Integer Dim caselessSort as Integer Dim i as Integer Dim tmpStr as String maxItems = 100 itemType = "string" error = NSL.SortInit(maxItems, itemType) If error <> 0 Then MsgBox "SortInit error = " + Str(error) Exit Sub End If For i = 1 to someNumber error = NSL.SortAddString(someStringArray(i)) If error <> 0 Then MsgBox "SortAddString error = " + Str(error) Exit Sub End If Next reverseSort = 0 'Sort from lowest to highest caselessSort = 1 'Case insensitive sort numItems = NSL.SortQSort(reverseSort, caselessSort) For i = 1 to numItems tmpStr = NSL.SortGetString(i) someStringArray(i) = tmpStr Next

SortInsertionSort

numItems = NSBSystemLib.SortInsertionSort(reverseSort, caselessSort)
Performs an "insertion sort" of the items in the sort array that was initialized with SortInit() and populated with either SortAddString(), SortAddInteger(), or SortAddDouble(). This function calls the SysInsertionSort PalmOS API function. The SortQSort function can also be used. Here is how the PalmOS SDK documentation describes the SysInsertionSort API function:

Only elements which are out of order move. Moved elements are moved to the end of the range of equal elements. If a large amount of elements are being sorted, try to use the quick sort (see SysQSort).

This is the insertion sort algorithm: Starting with the second element, each element is compared to the preceding element. Each element not greater than the last is inserted into sorted position within those already sorted. A binary search for the insertion point is performed. A moved element is inserted after any other equal elements.

Parameters reverseSort as Integer 0 = list is sorted from lowest to highest values 1 = list is sorted from highest to lowest values caselessSort as Integer 0 = sort is case sensitive 1 = sort is not case sensitive

Returns numItems as Integer the number of items sorted Use the appropriate function (SortGetString(), SortGetInteger(), or SortGetDouble()) to return the items from the sort array.

Example Dim error as Integer Dim maxItems as Integer Dim itemType as String Dim numItems as Integer Dim reverseSort as Integer Dim caselessSort as Integer Dim i as Integer Dim tmpStr as String maxItems = 100 itemType = "string" error = NSL.SortInit(maxItems, itemType) If error <> 0 Then MsgBox "SortInit error = " + Str(error) Exit Sub End If For i = 1 to someNumber error = NSL.SortAddString(someStringArray(i)) If error <> 0 Then MsgBox "SortAddString error = " + Str(error) Exit Sub End If Next reverseSort = 0 'Sort from lowest to highest caselessSort = 1 'Case insensitive sort numItems = NSL.SortInsertionSort(reverseSort, caselessSort) For i = 1 to numItems tmpStr = NSL.SortGetString(i) someStringArray(i) = tmpStr Next

ListQSort

numItems = NSBSystemLib.ListQSort(objID, reverseSort, caselessSort)
Performs a "quick sort" of the items in an existing List object. This routine uses the SysQSort PalmOS API function. The ListInsertionSort function can also be used. To compare the differences between the quick sort and insertion sort algorythms, please review the descriptions of the SortQSort and SortInsertionSort functions in this library.

Parameters objID as Integer objectID of the list object Use 0 to specify the object that currently has focus. reverseSort as Integer 0 = list is sorted from lowest to highest values 1 = list is sorted from highest to lowest values caselessSort as Integer 0 = sort is case sensitive 1 = sort is not case sensitive

Returns numItems as Integer the number of items sorted

Example Dim numItems as Integer Dim objID as Integer Dim reverseSort as Integer Dim caselessSort as Integer objID = 1008 reverseSort = 0 caselessSort = 0 numItems = NSL.ListQSort(objID, reverseSort, caselessSort)

ListInsertionSort

numItems = NSBSystemLib.ListInsertionSort(objID, reverseSort, caselessSort)
Performs an "insertion sort" of the items in an existing List object. This routine uses the SysInsertionSort PalmOS API function. The ListQSort function can also be used. To compare the differences between the quick sort and insertion sort algorythms, please review the descriptions of the SortQSort and SortInsertionSort functions in this library.

Parameters objID as Integer objectID of the list object Use 0 to specify the object that currently has focus. reverseSort as Integer 0 = list is sorted from lowest to highest values 1 = list is sorted from highest to lowest values caselessSort as Integer 0 = sort is case sensitive 1 = sort is not case sensitive

Returns numItems as Integer the number of items sorted

Example Dim numItems as Integer Dim objID as Integer Dim reverseSort as Integer Dim caselessSort as Integer objID = 1008 reverseSort = 0 caselessSort = 0 numItems = NSL.ListInsertionSort(objID, reverseSort, caselessSort)


Version 2.0 Changes and Additions

Version 2.0 contains additional options for the FixedWidthString, StringDateTime, and StringDate functions.

The "rightJustify" parameter of the FixedWidthString function has been changed to "options". This parameter still controls justification but it is also now used to control whether an ellipsis ("...") is appended to a string that had to be truncated.

The following functions are new in this version of the NSBSystemLib shared library. It would be wise to check the NSBSystemLib version number to ensure that it is version 2.0 or greater before using any of these new functions.

FormGetAllObjectTypes

type = NSBSystemLib.FormGetAllObjectTypes(objID)
Retrieves the object type of the specified object.

Parameter objID as Integer 0 = use object that currently has focus objID may be either an Object ID or an Object Index. If the value of objID is between 1 and the number of objects on the form, objID is assumed to be an Object Index, otherwise, it is assumed to be an Object ID.

Returns type as Integer -1 if the object is invalid or no object has focus 0 = frmFieldObj 2 = frmListObj 3 = frmTableObj 4 = frmBitmapObj 5 = frmLineObj 6 = frmFrameObj 7 = frmRectangleObj 8 = frmLabelObj 9 = frmTitleObj 10 = frmPopupObj 11 = frmGraffitiStateObj 12 = frmGadgetObj 13 = frmScrollbarObj 100 = buttonCtl 101 = pushButtonCtl 102 = checkboxCtl 103 = popupTriggerCtl 104 = selectorTriggerCtl 105 = repeatingButtonCtl 106 = sliderCtl 107 = feedbackSliderCtl

Example Dim type as Integer Dim objID as Integer objID = 1008 type = NSL.FormGetAllObjectTypes(objID)

This function differs from FormGetObjectType() in that it interprets the individual Control object types rather than just retuning a type of frmControlObj (value 1).

FieldClearAll

NSBSystemLib.FieldClearAll()
Clears/erases the text from all the fields on a form.

Example NSL.FieldClearAll()

ObjectWithPoint

obj = NSBSystemLib.ObjectWithPoint(x, y, returnType, searchOption)
Returns the first object that has the x and y coordinates within it's bounds.

Parameters x as Integer x coordinate y as Integer y coordinate returnType as Integer 0 = return the object's ID 1 = return the object's index This index is in the range of 1 to number of objects on the form. It is the PalmOS index incremented by 1 so that it can be used with other functions in this library. If you use this value with a Systrap, you must subtract 1 from the index. 2 = return the object's pointer (use variant as the return type) searchOption as Integer 0 = search for objects that are usable, visible, and enabled/editable 1 = search for objects that are usable and visible 2 = search for all objects

Returns obj as Integer object as either an object ID, index, or pointer -1 or NULL (0 if returning a pointer) when no object was found

Example Dim obj as Integer Dim x as Integer Dim y as Integer Dim returnType as Integer Dim searchOption as Integer obj = NSL.ObjectWithPoint(x, y, returnType, searchOption)

ANDInt

result = NSBSystemLib.ANDInt(int1, int2)
Returns a bitwise AND of the int1 and int2 parameters.

Parameters int1 as Integer int2 as Integer

Returns result as Integer

Example Dim result as Integer Dim int1 as Integer Dim int2 as Integer result = NSL.ANDInt(int1, int2)

ORInt

result = NSBSystemLib.ORInt(int1, int2)
Returns a bitwise OR of the int1 and int2 parameters.

Parameters int1 as Integer int2 as Integer

Returns result as Integer

Example Dim result as Integer Dim int1 as Integer Dim int2 as Integer result = NSL.ORInt(int1, int2)

XORInt

result = NSBSystemLib.XORInt(int1, int2)
Returns a bitwise XOR of the int1 and int2 parameters.

Parameters int1 as Integer int2 as Integer

Returns result as Integer

Example Dim result as Integer Dim int1 as Integer Dim int2 as Integer result = NSL.XORInt(int1, int2)

OnesComplement

result = NSBSystemLib.OnesComplement(intValue)
Returns the "one's complement" of the intValue parameter. This essentially turns all 1 bits to 0 and all 0 bits to 1.

Parameter intValue as Integer

Returns result as Integer

Example Dim result as Integer Dim intValue as Integer result = NSL.OnesComplement(intValue)

BitValue

result = NSBSystemLib.BitValue(intValue, bitNumber)
Returns 1 if the specified bit number is 1, otherwise it returns 0.

Parameters intValue as Integer bitNumber as Integer Bits are numbered from right to left from 0 to 31.

Returns result as Integer

Example Dim result as Integer Dim intValue as Integer Dim bitNumber as Integer result = NSL.BitValue(intValue, bitNumber)

BitsValue

result = NSBSystemLib.BitsValue(intValue, startBit, endBit)
Returns the integer value of the specified bits. The bits retrieved include the starting and ending bit numbers. Therefore, BitsValue(intValue, 5, 7) returns the value of bits 5, 6, and 7.

Parameters intValue as Integer startBit as Integer Bits are numbered from right to left from 0 to 31. endBit as Integer Bits are numbered from right to left from 0 to 31.

Returns result as Integer

Example Dim result as Integer Dim intValue as Integer Dim startBit as Integer Dim endBit as Integer result = NSL.BitsValue(intValue, startBit, endBit)

SetBitValue

result = NSBSystemLib.SetBitValue(intValue, bitNumber, bitValue)
Sets the bit specified by bitNumber to the specified bit value.

Parameters intValue as Integer bitNumber as Integer Bits are numbered from right to left from 0 to 31. bitValue as Integer

Returns result as Integer

Example Dim result as Integer Dim intValue as Integer Dim bitNumber as Integer Dim bitValue as Integer result = NSL.SetBitValue(intValue, bitNumber, bitValue)

SetBitsValue

result = NSBSystemLib.SetBitsValue(intValue, bitsValue, startBit, endBit)
Sets the specified bits to the integer value specified by bitValue. The bits set include the starting and ending bits. Therefore, SetBitsValue(intValue, 3, 5, 7) sets the value of bits 5, 6, and 7.

Parameters intValue as Integer bitsValue as Integer Bits are numbered from right to left from 0 to 31. startBit as Integer Bits are numbered from right to left from 0 to 31. endBit as Integer

Returns result as Integer

Example Dim result as Integer Dim intValue as Integer Dim bitsValue as Integer Dim startBit as Integer Dim endBit as Integer result = NSL.SetBitsValue(intValue, bitsValue, startBit, endBit)

IntToHex

hexValue = NSBSystemLib.IntToHex(intValue, trimLeading)
Convert the specified integer value to a hexadecimal string.

Parameters intValue as Integer trimLeading as Integer 0 = do not trim leading zeros from result string 1 = trim leading zeros from result string.

Returns hexValue as String

Example Dim hexValue as String Dim intValue as Integer Dim trimLeading as Integer hexValue = NSL.IntToHex(intValue, trimLeading)

HexToInt

intValue = NSBSystemLib.HexToInt(hexValue)
Convert the specified hexadecimal string to an integer value.

Parameter hexValue as String

Returns intValue as Integer

Example Dim intValue as Integer Dim hexValue as String intValue = NSL.HexToInt(hexValue)

IntToBin

binValue = NSBSystemLib.IntToBin(intValue, trimLeading)
Convert the specified integer value to a binary string.

Parameters intValue as Integer trimLeading as Integer 0 = do not trim leading zeros from result string 1 = trim leading zeros from result string.

Returns binValue as String

Example Dim binValue as String Dim intValue as Integer Dim trimLeading as Integer binValue = NSL.IntToBin(intValue, trimLeading)

BinToInt

intValue = NSBSystemLib.BinToInt(binValue)
Convert the specified binary string to an integer value.

Parameter binValue as String

Returns intValue as Integer

Example Dim intValue as Integer Dim binValue as String intValue = NSL.BinToInt(binValue)


Screen and Color Functions

GetSupportedDepths

depths = NSBSystemLib.GetSupportedDepths()
Returns a bitmapped integer with each bit indicating a bitmap depth supported by the PalmOS device.

Returns depths as Integer

Example Dim depths as Integer depths = NSL.GetSupportedDepths()

The bit manipulation functions in this library or the NS Basic Shared Library "BitsNBytes" probably provide the best suited functions for evaluating the returned value from this function.

DepthSupported

boolean = NSBSystemLib.DepthSupported(depth)
Returns 1 if the specified depth is supported by the PalmOS device. Otherwise, it returns 0.

Parameter depth as Integer

Returns boolean as Integer

Example Dim boolean as Integer Dim depth as Integer depth = 4 boolean = NSL.DepthSupported(depth)

ColorSupported

boolean = NSBSystemLib.ColorSupported()
Returns 1 if the PalmOS device has color capabilities. Otherwise, it returns 0.

Returns boolean as Integer

Example Dim boolean as Integer boolean = NSL.ColorSupported()

SetDepth

NSBSystemLib.SetDepth depth
Sets the screen mode to support the specified bitmap bit depth.

Parameter: depth as Integer

Example Dim depth as Integer depth = 4 NSL.SetDepth depth

SetColor

NSBSystemLib.SetColor boolean
Sets the screen mode to support color bitmaps.

Parameter: boolean as Integer 1 = support color 0 = do not support color

Example Dim boolean as Integer boolean = 1 NSL.SetColor boolean

SaveScreenMode

NSBSystemLib.SaveScreenMode()
Saves the current screen mode parameters. These parameters can later be restored by calling "RestoreScreenMode". It is suggested that the current screen mode parameters be saved before any changes are requested and that these saved parameters are restored when the program exits.

Example NSL.SaveScreenMode()

RestoreScreenMode

NSBSystemLib.RestoreScreenMode()
Restores saved screen mode parameters. These parameters must have been saved by calling "SaveScreenMode". It is suggested that the current screen mode parameters be saved before any changes are requested and that these saved parameters are restored when the program exits.

Example NSL.RestoreScreenMode()

CurrentDepth

depth = NSBSystemLib.CurrentDepth()
Returns the current bitmap depth.

Returns depth as Integer

Example Dim depth as Integer depth = NSL.CurrentDepth()

CurrentColor

boolean = NSBSystemLib.CurrentColor()
Returns 1 if the PalmOS Device's screen mode is currently set to support color. Otherwise, it returns 0.

Returns boolean as Integer

Example Dim boolean as Integer boolean = NSL.CurrentColor()

SetToDefaults

NSBSystemLib.SetToDefaults()
Sets all screen mode parameters to their default values.

Example NSL.SetToDefaults()

DefaultDepth

depth = NSBSystemLib.DefaultDepth()
Returns the default bitmap depth.

Returns depth as Integer

Example Dim depth as Integer depth = NSL.DefaultDepth()

DefaultColor

boolean = NSBSystemLib.DefaultColor()
Returns 1 if the PalmOS Device's screen mode default is set to support color. Otherwise, it returns 0.

Returns boolean as Integer

Example Dim boolean as Integer boolean = NSL.DefaultColor()

GetTableEntryIndex

index = NSBSystemLib.GetTableEntryIndex(which)
This function calls the PalmOS UIColorGetTableEntryIndex function. It returns the index value for a UI color for the current system palette.

Parameter which as Integer UIObjectFrame = 0, UIObjectFill = 1 UIObjectForeground = 2 UIObjectSelectedFill = 3 UIObjectSelectedForeground = 4 UIMenuFrame = 5 UIMenuFill = 6 UIMenuForeground = 7 UIMenuSelectedFill = 8 UIMenuSelectedForeground = 9 UIFieldBackground = 10 UIFieldText = 11 UIFieldTextLines = 12 UIFieldCaret = 13 UIFieldTextHighlightBackground = 14 UIFieldTextHighlightForeground = 15 UIFieldFepRawText = 16 UIFieldFepRawBackground = 17 UIFieldFepConvertedText = 18 UIFieldFepConvertedBackground = 19 UIFieldFepUnderline = 20 UIFormFrame = 21 UIFormFill = 22 UIDialogFrame = 23 UIDialogFill = 24 UIAlertFrame = 25 UIAlertFill = 26 UIOK = 27 UICaution = 28 UIWarning = 29

Returns index as Integer -1 = PalmOS version is less than 3.5

Example Dim index as Integer Dim which as Integer which = 11 'UIFieldText index = NSL.GetTableEntryIndex(which)

This function requires PalmOS version 3.5 or greater.

GetTableEntryRGB

index = NSBSystemLib.GetTableEntryRGB(which)
This function calls the PalmOS UIColorGetTableEntryRGB function. It retrieves the RGB values for the UI Color. RGB Values are returned in a structure called "RGBColorType". It contains the following fields: index, red, green, blue. This function retrieves all these values, but only returns the index. To get the red, green, and blue values, call this function first and then call GetRGBRed, GetRGBGreen, and GetRGBBlue. See the example for more information.

Parameter which as Integer (see the GetTableEntryIndex function for a list of valid "Which" values")

Returns index as Integer -1 = PalmOS version is less than 3.5

Example Dim index as Integer Dim which as Integer Dim red as Integer Dim green as Integer Dim blue as Integer which = 11 'UIFieldText index = NSL.GetTableEntryRGB(which) red = SL.GetRGBRed() green = SL.GetRGBGreen() blue = SL.GetRGBBlue()

This function requires PalmOS version 3.5 or greater.

GetRGBIndex

index = NSBSystemLib.GetRGBIndex()
RGB Values are returned in a structure called "RGBColorType". It contains the following fields: index, red, green, blue.

This function returns the index value that was previously retrieved by either the GetTableEntryRGB or IndexToRGB functions.

Returns index as Integer

Example Dim index as Integer index = NSL.GetRGBIndex()

GetRGBRed

red = NSBSystemLib.GetRGBRed()
RGB Values are returned in a structure called "RGBColorType". It contains the following fields: index, red, green, blue.

This function returns the red value that was previously retrieved by either the GetTableEntryRGB or IndexToRGB functions.

Returns red as Integer

Example See the example provided with either the GetTableEntryRGB or IndexToRGB functions.

GetRGBGreen

green = NSBSystemLib.GetRGBGreen()
RGB Values are returned in a structure called "RGBColorType". It contains the following fields: index, red, green, blue.

This function returns the green value that was previously retrieved by either the GetTableEntryRGB or IndexToRGB functions.

Returns green as Integer

Example See the example provided with either the GetTableEntryRGB or IndexToRGB functions.

GetRGBBlue

blue = NSBSystemLib.GetRGBBlue()
RGB Values are returned in a structure called "RGBColorType". It contains the following fields: index, red, green, blue.

This function returns the blue value that was previously retrieved by either the GetTableEntryRGB or IndexToRGB functions.

Returns blue as Integer

Example See the example provided with either the GetTableEntryRGB or IndexToRGB functions.

SetTableEntryIndex

NSBSystemLib.SetTableEntryIndex which, index
This subroutine calls the PalmOS IndexToRGB function and then it calls UIColorSetTableEntry. It changes a value in the UI Color list.

Parameters which as Integer (see the GetTableEntryIndex function for a list of valid "Which" values") index as Integer

Example Dim which as Integer Dim index as Integer NSL.SetTableEntryIndex which, index

Some changes aren't reflected until the object or form is redrawn with the "Redraw" statement. Even then, some changes like the form background (UIFormFill - 22) aren't reflected until until you change forms with a "NextScreen" statement. You might want to set some table entries in either the programs "Startup" code or just before you use the "NextScreen" statement.

This function requires PalmOS version 3.5 or greater.

SetTableEntryRGB

NSBSystemLib.SetTableEntryRGB which, red, green, blue
This subroutine calls the PalmOS UIColorSetTableEntry function. It changes a value in the UI Color list.

Parameters which as Integer (see the GetTableEntryIndex function for a list of valid "Which" values") red as Integer green as Integer blue as Integer Red, Green, Blue valid values are 0 to 255

Example Dim which as Integer Dim red as Integer Dim green as Integer Dim blue as Integer NSL.SetTableEntryRGB which, red, green, blue

Some changes aren't reflected until the object or form is redrawn with the "Redraw" statement. Even then, some changes like the form background (UIFormFill - 22) aren't reflected until until you change forms with a "NextScreen" statement. You might want to set some table entries in either the programs "Startup" code or just before you use the "NextScreen" statement.

This function requires PalmOS version 3.5 or greater.

BrightnessAdjust

NSBSystemLib.BrightnessAdjust()
This subroutine calls the PalmOS UIBrightnessAdjust function. It displays the "Brightness Adjust" dialog.

Example NSL.BrightnessAdjust()

This function requires PalmOS version 3.5 or greater.

ContrastAdjust

NSBSystemLib.ContrastAdjust()
This subroutine calls the PalmOS UIContrastAdjust function. It displays the "Contrast Adjust" dialog.

Example NSL.ContrastAdjust()

The PalmOS documentation states that this function only works on the "Palm V Connected Organizer".

This function requires PalmOS version 3.5 or greater.

PickColorIndex

changed = NSBSystemLib.PickColorIndex(index, title)
This function calls the PalmOS UIPickColor function. It displays a Palette dialog to allow a user to select a color. The selected index and RGB values can be retrieved by calling the GetRGBIndex, GetRGBRed, GetRGBGreen and GetRGBBlue functions.

Parameters index as Integer Suggested index title as String Title to display on dialog

Returns changed as Integer -1 = PalmOS version is less than v3.5 0 = User cancelled or chose suggested index 1 = User chose a new index

Example Dim changed as Integer Dim index as Integer Dim title as String changed = NSL.PickColorIndex(index, title)

This function requires PalmOS version of 3.5 or greater.

PickColorRGB

changed = NSBSystemLib.PickColorRGB(red, green, blue, title)
This function calls the PalmOS UIPickColor function. It displays an RGB dialog to allow a user to select a color. The selected index and RGB values can be retrieved by calling the GetRGBIndex, GetRGBRed, GetRGBGreen and GetRGBBlue functions.

Parameters red as Integer green as Integer blue as Integer Suggested Red, Green, Blue values (0 to 255) title as String Title to display on dialog

Returns changed as Integer -1 = PalmOS version is less than 3.5 0 = User cancelled or chose suggested colors 1 = User chose a new index

Example Dim changed as Integer Dim red as Integer Dim green as Integer Dim blue as Integer Dim title as String changed = NSL.PickColorRGB(red, green, blue, title)

This function requires PalmOS version 3.5 or greater.

IndexToRGB

NSBSystemLib.IndexToRGB index
This subroutine calls the PalmOS WinIndexToRGB function. It converts an index in the currently active color table to an RGB value. RGB Values are returned in a structure called "RGBColorType". It contains the following fields: index, red, green, blue. To get the actual index, red, green, and blue values, call this function first and then call GetRGBIndex, GetRGBRed, GetRGBGreen, and GetRGBBlue. See the example for more information.

Parameter: index as Integer

Example Dim index as Integer NSL.IndexToRGB index

This function requires PalmOS version 3.5 or greater.

RGBToIndex

index = NSBSystemLib.RGBToIndex(red, green, blue)
This function calls the PalmOS WinRGBToIndex function. It converts RGB values to the index of the closest color in the currently active color lookup table (CLUT).

Parameters red as Integer green as Integer blue as Integer Red, Green, Blue valid values are 0 to 255

Returns index as Integer -1 = PalmOS version is less than 3.5

Example Dim index as Integer Dim red as Integer Dim green as Integer Dim blue as Integer index = NSL.RGBToIndex(red, green, blue)

This function requires PalmOS version 3.5 or greater.

SetForeColor

oldIndex = NSBSystemLib.SetForeColor(newIndex)
This function calls the PalmOS WinSetForeColor function. It sets the foreground color to use in subsequent draw operations.

Parameter newIndex as Integer

Returns oldIndex as Integer Previous foreground index -1 = PalmOS version is less than 3.5

Example Dim oldIndex as Integer Dim newIndex as Integer oldIndex = NSL.SetForeColor(newIndex)

Colors set with this function appear to be reset to default values when switching between forms or when a form is redrawn. It is probably best to call this function in the form's "After" code section.

This function requires PalmOS version 3.5 or greater.

SetBackColor

oldIndex = NSBSystemLib.SetBackColor(newIndex)
This function calls the PalmOS WinSetBackColor function. It sets the background color to use in subsequent draw operations.

Parameter newIndex as Integer

Returns oldIndex as Integer Previous background index -1 = PalmOS version is less than 3.5

Example Dim oldIndex as Integer Dim newIndex as Integer oldIndex = NSL.SetBackColor(newIndex)

Colors set with this function appear to be reset to default values when switching between forms or when a form is redrawn. It is probably best to call this function in the form's "After" code section.

This function requires PalmOS version 3.5 or greater.

SetTextColor

oldIndex = NSBSystemLib.SetTextColor(newIndex)
This function calls the PalmOS WinSetTextColor function. It sets the color to use for drawing characters in subsequent draw operations.

Parameter newIndex as Integer

Returns oldIndex as Integer Previous text color index -1 = PalmOS version is less than 3.5

Example Dim oldIndex as Integer Dim newIndex as Integer oldIndex = NSL.SetTextColor(newIndex)

Colors set with this function appear to be reset to default values when switching between forms or when a form is redrawn. It is probably best to call this function in the form's "After" code section.

This function requires PalmOS version 3.5 or greater.

DrawLine

NSBSystemLib.DrawLine x1, y1, x2, y2
This soubroutine calls the PalmOS WinDrawLine function. It draws a line in the draw window using the current foreground color.

Parameters x1 as Integer y1 as Integer x2 as Integer y2 as Integer

Example Dim x1 as Integer Dim y1 as Integer Dim x2 as Integer Dim y2 as Integer NSL.DrawLine x1, y1, x2, y2

This function was provided for completeness only. The built-in DrawLine NSBasic statement produces the same result.

DrawGrayLine

NSBSystemLib.DrawGrayLine x1, y1, x2, y2
This subroutine calls the PalmOS WinDrawGrayLine function. It does not draw in a gray color, but rather draws with alternating foreground and background colors.

Parameters x1 as Integer y1 as Integer x2 as Integer y2 as Integer

Example Dim x1 as Integer Dim y1 as Integer Dim x2 as Integer Dim y2 as Integer NSL.DrawGrayLine x1, y1, x2, y2

EraseLine

NSBSystemLib.EraseLine x1, y1, x2, y2
This subroutine calls the PalmOS WinEraseLine function. It draws a line in the draw window using the current background color.

Parameters x1 as Integer y1 as Integer x2 as Integer y2 as Integer

Example Dim x1 as Integer Dim y1 as Integer Dim x2 as Integer Dim y2 as Integer NSL.EraseLine x1, y1, x2, y2

InvertLine

NSBSystemLib.InvertLine x1, y1, x2, y2
This subroutine calls the PalmOS WinInvertLine function. It draws an inverted line in the draw window.

Parameters x1 as Integer y1 as Integer x2 as Integer y2 as Integer

Example Dim x1 as Integer Dim y1 as Integer Dim x2 as Integer Dim y2 as Integer NSL.InvertLine x1, y1, x2, y2

DrawPixel

NSBSystemLib.DrawPixel x, y
This subroutine calls the PalmOS WinDrawPixel function. It draws a pixel in the draw window using the current foreground color.

Parameters x as Integer y as Integer

Example Dim x as Integer Dim y as Integer NSL.DrawPixel x, y

ErasePixel

NSBSystemLib.ErasePixel x, y
This subroutine calls the PalmOS WinErasePixel function. It draws a pixel in the draw window using the current background color.

Parameters x as Integer y as Integer

Example Dim x as Integer Dim y as Integer NSL.ErasePixel x, y

InvertPixel

NSBSystemLib.InvertPixel x, y
This subroutine calls the PalmOS WinInvertPixel function. It draws an inverted pixel in the draw window.

Parameters x as Integer y as Integer

Example Dim x as Integer Dim y as Integer NSL.InvertPixel x, y

GetPixel

index = NSBSystemLib.GetPixel(x, y)
This function calls the PalmOS WinGetPixel function. It returns the color of the specified a pixel in the draw window.

Parameters x as Integer y as Integer

Returns index as Integer

Example Dim index as Integer Dim x as Integer Dim y as Integer index = NSL.GetPixel(x, y)

ScreenLock

success = NSBSystemLib.ScreenLock(mode)
This function calls the PalmOS WinScreenLock function. It "locks" the current screen by switching the UI concept of the screen base address to an area that is not reflected on the display. This routine can be used to "freeze" the display while doing lengthy drawing operations to avoid a flickering effect. Call ScreenUnlock to unlock the display and cause it to be updated with any changes. The screen must be unlocked as many times as it is locked to actually update the display.

Parameter mode as Integer winLockCopy = 0 - copy old screen to new winLockErase = 1 - erase new screen to white winLockDontCare = 2 - don't do anything

Returns success as Integer -1 = PalmOS version is less than 3.5 1 = success 0 = failure

Example Dim success as Integer Dim mode as Integer success = NSL.ScreenLock(mode)

This function requires PalmOS version 3.5 or greater.

ScreenUnlock

NSBSystemLib.ScreenUnlock()
This subroutine calls the PalmOS WinScreenUnlock function. Call ScreenUnlock to unlock the display and cause it to be updated with any changes. The screen, which was locked by calling ScreenLock, must be unlocked as many times as it is locked to actually update the display.

Example NSL.ScreenUnlock()

This function requires PalmOS version 3.5 or greater.

WinSaveBits

NSBSystemLib.WinSaveBits index, x, y, width, height

Parameters index as Integer x as Integer y as Integer width as Integer height as Integer

Example Dim index as Integer Dim x as Integer Dim y as Integer Dim width as Integer Dim height as Integer NSL.WinSaveBits index, x, y, width, height

WinRestoreBits

NSBSystemLib.WinRestoreBits index, x, y

Parameters index as Integer x as Integer y as Integer

Example Dim index as Integer Dim x as Integer Dim y as Integer NSL.WinRestoreBits index, x, y


Sleep and Wake Event Functions

The following functions provide the ability to determine when and if your system has gone to sleep or has been awakened - either through the use of the power button or because of the system's "Auto Off" feature. The primary uses of this fuction would include determining if you should end your program or prompt for a password during an extended period of inactivity.

SetSleepEvent

NSBSystemLib.SetSleepEvent eventNbr
Sets an event number to post when the device is powered off, either through an AutoOff or by the user pressing the power button. In General, the event number should be a custom event in the range of 24576 to 32767; however, any non-zero event number can be used. A particularly useful event number is the appStopEvent (event number 22). This will cause the program to terminate and the "Termination Code" section will be called. Using an event number of 22 (appStopEvent) may be necessary when a program must absolutely terminate. This is because displayed things like MsgBoxes and Alerts have their own event loops and may ignore custom events.

Parameter: eventNbr as Integer Use 0 to cause no event to be posted.

Example Dim eventNbr as Integer eventNbr = 30000 NSL.SetSleepEvent eventNbr

See the GetSleepEvent(), SetWakeEvent(), and GetWakeEvent() functions.

SetWakeEvent

NSBSystemLib.SetWakeEvent eventNbr
Sets an event number to post when the device is powered on while this library is loaded (ie. your NSBasic program is running and is using this library). In General, the event number should be a custom event in the range of 24576 to 32767; however, any non-zero event number can be used. A particularly useful event number is the appStopEvent (event number 22). This will cause the program to terminate and the "Termination Code" section will be called. Using an event number of 22 (appStopEvent) may be necessary when a program must absolutely terminate. This is because displayed things like MsgBoxes and Alerts have their own event loops and may ignore custom events.

Parameter: eventNbr as Integer Use 0 to cause no event to be posted.

Example Dim eventNbr as Integer eventNbr = 30001 NSL.SetWakeEvent eventNbr

Also see the GetWakeEvent(), SetSleepEvent(), and GetSleepEvent() functions.

GetSleepEvent

eventNbr = NSBSystemLib.GetSleepEvent()
Returns the event number that gets posted when the device is powered off either through an AutoOff or by the user pressing the power button. Note that a value of 0 means that no event is posted.

Returns eventNbr as Integer

Example Dim eventNbr as Integer eventNbr = NSL.GetSleepEvent()

Also see the SetSleepEvent(), SetWakeEvent(), GetWakeEvent(), GetSleepEventTime(), and GetWakeEventTime() functions.

GetWakeEvent

eventNbr = NSBSystemLib.GetWakeEvent()
Returns the event number that gets posted when the device is powered on while this library is loaded (ie. your NSBasic program is running and is using this library). Note that a value of 0 means that no event is posted.

Returns eventNbr as Integer

Example Dim eventNbr as Integer eventNbr = NSL.GetWakeEvent()

Also see the GetWakeEvent(), SetSleepEvent(), GetSleepEvent(), GetSleepEventTime(), and GetWakeEventTime() functions.

GetSleepEventTime

eventTime = NSBSystemLib.GetSleepEventTime()
Returns the event time that gets saved when the device is powered off either through an AutoOff or by the user pressing the power button. Note that this time only gets saved if an event number has been registered using the SetSleepEvent() function. A value of 0 means that no event has been posted.

Returns eventTime as Integer eventTime in system time format. This value is expressed as the number of seconds since January 1st, 1904.

Example Dim eventTime as Integer eventTime = NSL.GetSleepEventTime()

Also see the SetSleepEvent(), SetWakeEvent(), GetWakeEvent(), GetWakeEventTime(), StringDateTime(), StringDate(), and StringTime() functions.

GetWakeEventTime

eventTime = NSBSystemLib.GetWakeEventTime()
Returns the event time that gets saved when the device is powered on. Note that this time only gets saved if an event number has been registered using the SetWakeEvent() function. A value of 0 means that no event has been posted.

Returns eventTime as Integer eventTime in system time format. This value is expressed as the number of seconds since January 1st, 1904.

Example Dim eventTime as Integer eventTime = NSL.GetWakeEventTime()

Also see the SetSleepEvent(), SetWakeEvent(), GetWakeEvent(), GetSleepEventTime(), StringDateTime(), StringDate(), and StringTime() functions.

String Encryption and Decryption Functions

The following functions provide encryption and decryption capabilities for string values. These functions use the PalmOS EncDES() function which may or may not be available on all PalmOS devices. Furthermore, the length of these strings, currently, can not be longer than 248 characters. Consideration of these restrictions should be carefully evaluated before using these functions.

There is a Windows component of the EncryptDESString() and DecryptDESString() functions. This component is implemented as a Windows DLL file and can be called from Visual Basic/VBA and Visual C/C++. Its purpose is to allow a conduit or other Palm Database utility to be able to encrypt or decrypt data using the same algorythms as the NSBSystemLib routines.

To use it, the EncDec.dll file must be placed in a system directory or some directory that is currently in your PATH. For Visual Basic/VBA, include the EncDec.bas module. For Visual C/C++, include the EncDec.h header file and link with the EncDec.lib library (note that the EncDec.dll is still required).

The EncDec DLL functions have the same restrictions as their NSBSystemLib library counterparts. The main differences are that you specify the encryption key with every function call and that the functions return the length of the returned string.

The encrypted string carries 2 extra bytes. One at the front and one at the end. The first byte is an offset (+ 1) to the first null replaced. The null is replaced with the offset (+ 1) to the next null replaced, and so on. The last null is replaced with 255. If there are no nulls replaced, the first byte is set to 255. Here is an example:
0 1 2 3 4 5 6 7 8
--- --- --- --- --- --- --- --- ---
x 0 x x 0 x x x

becomes

3 x 6 x x 255 x x x
The extra byte at the end of the string indicates how many extra spaces were padded to the input to make the length an even multiple of 8 (a requirement of EncDES). Actually, it is the amount of padding + 1 - to keep it non-zero. This way, on decryption, the padding can be removed and the decrypted string can be compared exactly to the original input string.

So, an encrypted string will always be at least 2 bytes longer than the original string and can be up to 9 bytes longer (the extra bytes are due to the amount of padding required). This works well if you keep to a limit of of 250 characters being passed between NSBasic and a Shared Library. So, the offsets will always fit neatly into a single byte.

So, some clever coding could probably segment a string into 256 byte increments without much overhead, but it would require a library change (and would probably break backward compatibility). As you can see, EncDES in its current implementation is limited to less than 250 bytes regardless of changes in the NSBasic runtime - you just can't put a number greater than 255 in a single byte!

VB/VBA Example:
Dim KeyStr As String
Dim DecryptedStr As String
Dim EncryptedStr As String
Dim StrLen As Integer


KeyStr = "secret" DecryptedStr = "The quick brown fox jumps over the lazy dog!" StrLen = EncryptData(KeyStr, DecryptedStr, EncryptedStr) DecryptedStr = "" StrLen = DecryptData(KeyStr, EncryptedStr, DecryptedStr)
C++ Example:
char keyStr[25];
char decryptedStr[251];
char encryptedStr[251];
int  len;


strcpy(keyStr, "secret"); strcpy(decryptedStr, "The quick brown fox jumps over the lazy dog!"); len = encryptData(keyStr, decryptedStr, encryptedStr); strcpy(decryptedStr, ""); len = decryptData(keyStr, encryptedStr, decryptedStr);

EncryptDESString

encryptedStr = NSBSystemLib.EncryptDESString(decryptedStr)
Returns the encrypted value of the plainText string. The plainText string can not be more than 248 characters in length. The length of the encrypted string may be up to 9 characters longer than the plainText string. Note: the SetDESKey subroutine must have been called at least once prior to calling this function.

Parameter decryptedStr as String

Returns encryptedStr as String

Example Dim encryptedStr as String Dim decryptedStr as String encryptedStr = NSL.EncryptDESString(decryptedStr)

DecryptDESString

decryptedStr = NSBSystemLib.DecryptDESString(encryptedStr)
Returns the plain text value of the encryptedText string. The encryptedText string can not be more than 250 characters in length. Note: the SetDESKey subroutine must have been called at least once prior to calling this function.

Parameter encryptedStr as String

Returns decryptedStr as String

Example Dim decryptedStr as String Dim encryptedStr as String decryptedStr = NSL.DecryptDESString(encryptedStr)

SetDESKey

NSBSystemLib.SetDESKey keyStr
Establishes the encryption or decryption key to be used with the EncryptDESString() and DecryptDESString() functions. This key value must be set before using these functions. Once set, it will be used for all subsequent operations or until the program ends. If the length of the key is 8 characters or less, standard DES encryption will be used. If the key length is from 9 to 24 characters, Triple-DES encryption is used.

Parameter: keyStr as String

Example Dim keyStr as String NSL.SetDESKey keyStr