Tech Note 14: Using the NSBSystemLib Library

Tech Note 14: Using the NSBSystemLib Library

May 01, 2008

Copyright 2008 NS BASIC Corporation

Introduction:

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

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

Alarms, Databases, Events, Field and Forms, Localization, Preferences, Progress Manager, and System Time. In addition, 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 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 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 Library, the NSBSystemLib.INF file must be present in your "nsbasic\lib" directory and the NSBSystemLib.prc file must be added as a resource to your project.

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 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()`
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 Library and about the user's device.

Version

version = NSBSystemLib.Version()

Returns the version number of the NSBSystemLib 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 API functions on the device.

Returns

version as Double

Example

Dim version as Double
version = NSL.SystemVersion()

See also: GlobalVersionMajor(), GlobalVersionMinor()

Access To Library Global Variables

Currently, 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 API functions. 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()

GlobalVersionMinor

gblMinor = NSBSystemLib.GlobalVersionMinor()

Returns the minor version number portion of the API library. 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()

GlobalX

x = NSBSystemLib.GlobalX()

Returns the value of the global variable "x" in the NSBSystemLib 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 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 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 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 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 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 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 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 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 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 Library.

Returns

gblHour as Integer

Example

Dim gblHour as Integer
gblHour = NSL.GlobalHour()

GlobalMinute

gblMinute = NSBSystemLib.GlobalMinute()

Returns the value of the global variable "minute" in the NSBSystemLib Library.

Returns

gblMinute as Integer

Example

Dim gblMinute as Integer
gblMinute = NSL.GlobalMinute()

Alarm Functions

Alarms 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. There can be one one active alarm for a 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 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.

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.

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

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

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.

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

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

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 EvtGetEvent API function.
	  EvtGetEvent removes events from the events queue.  In
	  order for these events to still be available for other
	  processing, this 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 PalmOSare events generated by the 
	  device 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 EvtFlushKeyQueue() API function 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 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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 library contains functions for manipulating bit values.

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

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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