Syntax:
      SysTrapSub trapnum, numargs[, arg1[, arg2[, ...]]]
      foo = SysTrapFunc(trapnum, numargs[, arg1[, arg2[, ...]]])

   Description:
      Trapnum is a constant, defined in CoreTraps.h, that determines which system
      routine is being called.  System traps begin with 0xA000, so this value is
      added to trapnum at runtime.  Numargs is the number of arguments that are
      passed to the system procedure.  Additional arguments that are included will
      vary, depending on which system procedure is called.  Special attention must
      be paid to the types of arguments and return values that a system procedure
      uses.  
      
      NS Basic only supports calling OS Traps that have arguments and return 
      values of type char*, int, or double.
      
      SysTrapSub has a limit of 6 parameters, while SysTrapFunc has a limit of 5 parameters.
      
   Examples: (NS Basic IDE)
      SysTrapSub 564, 1, 3*256            'Calls trap 0xA234 (SndPlaySystemSound)
      SysTrapSub 531, 4, 80, 0, 80, 160   'Calls trap 0xA213 (WinDrawLine)

Some common SysTrap functions are in the NSBSystemLib library. They are much more easily used from that library.

When calling routines in libraries, it is important to use the correct variable types. The calling routine uses the variable type to place the values on the stack to be passed to the library. A library will expect each argument passed to it to be the proper type.

If you use literals, NS Basic will assume you mean certain data types. These are:

It is much safer, however, only to use variables defined by Dim statements when passing parameters to SysTrapFunc and SysTrapSub. For scalar values, the following data types will be used:

If an API function requires a char or Char parameter, you can pass it as a single Short.

Scalar types are normally passed by value, with the exception of strings and bytes, which are always passed by reference/pointer. You can also pass entire arrays of Byte, Short, Integer, Float, or Double. This allows you to use the API functions that fill arrays and even structures. You will have to interpret structures in your NSBasic program, of course. All structures filled by the API functions are big-endian, meaning that the most significant bytes and words come first.

The array mechanism also allows you to pass single parameters by reference/pointer. Declare an array using the Dim statement containing two or more elements of the desired data type. Use the first element as the value. (It is necessary to declare two or more elements because, at runtime, a single-element array is indistinguishable from a scalar.)

Example 1:

The following code shows how to display the current day and month using API calls:

Dim dt(7) as Short
Dim s as Integer

s = SysTrapFunc(245, 0)     ' TimGetSeconds
SysTrapSub 252, 2, s, dt    ' TimSecondsToDateTime
MsgBox str(dt(4))
MsgBox str(dt(5))

Rationale:

The TimGetSeconds and TimSecondsToDateTime functions are described in the OS Reference as follows:

UInt32 TimGetSeconds (void)
void TimSecondsToDateTime (UInt32 seconds, DateTimePtr dateTimeP)

TimGetSeconds is a function that returns a 32-bit integer, hence an Integer. TimSecondsToDateTime returns void, which means it should be used as a subroutine. It takes a 32-bit integer and a DateTimePtr as parameters and fills the DateTimeType structure pointed to by the DateTimePtr with information about the current date. The DateTimeType structure is described in the OS reference as follows:

typedef struct{
    Int16 second;
    Int16 minute;
    Int16 hour;
    Int16 day;
    Int16 month;
    Int16 year;
    Int16 weekDay;
} DateTimeType;

typedef DateTimeType *DateTimePtr;

This is a straighforward structure containing seven elements, all of which are 16-bit integers, so we can use a seven-element Short array. The day is element 4, and the month is element 5. The trap numbers are given in the headers as follows:

#define sysTrapTimGetSeconds							0xA0F5
#define sysTrapTimSecondsToDateTime						0xA0FC

When the A is removed, these are 0F5 and 0FC, which convert to decimal 245 and 252, respectively.

Example 2:

The following code changes the color theme, both in the current setting and the default:

Function SetTheme(filename as string) as Integer
Dim ResTypeInt as Integer
Dim ResID as Short
Dim ResSize as Integer
Dim resH as Variant
Dim PrefsDB as Variant
Dim dstP as Variant
Dim theme as String
Dim saved as Short
Dim i as Short
Dim which as Short
Dim color as String

'Set up some values to get started
ResID = 25
ResSize = 124
saved = 256 'boolean True
ResTypeInt=1886615923 'psys

'Read in the Theme record. It has a header (4 bytes), followed by 30 colors.
Dim db as Database
SetTheme=dbopen(db, filename, 0)
If SetTheme<>0 Then MsgBox str(1000+SetTheme) & " dbopen Theme"
SetTheme=dbposition(db,1,0)
SetTheme=dbget(db, theme)
If SetTheme<>0 Then MsgBox str(2000+SetTheme) & " dbRead Theme"
dbclose(db)

'Update the resource database's default colors
PrefsDB  = SysTrapFunc(736,1, saved)         'PrefOpenPreferenceDB
resH = SysTrapFunc(95, 2, ResTypeInt, ResID) 'DmGetResource
If resH=0 Then resH = SysTrapFunc(108,4, PrefsDB, ResTypeInt, ResID, ResSize) 'DmNewResource
dstP = SysTrapFunc(33,1,ResH)                'MemHandleLock
SysTrapSub 118, 4, dstP, 0, theme, ResSize   'DMWrite
SetTheme = SysTrapFunc(34,1,resH)            'MemHandleUnlock	
SetTheme = SysTrapFunc(97,1,resH)            'DmReleaseResource
SetTheme = systrapfunc(74,1,PrefsDB)         'DmCloseDatabase

'Update the current colors
For i=0 to 29
	which=i*256
	color=mid(theme, i*4+5, 4)
	setTheme = sysTrapFunc(934, 2, which, color) 'UIColorSetTableEntry	
Next

End Function

Palm has documention on the API calls on its website:
http://www.palmos.com/dev/tech/docs/

For more information on SysTraps, visit the Web Board at http://groups.yahoo.com/group/nsbasic-palmAPI

Table of Operating System APIs (SysTraps)

Palm OS 5 trap numbers contributed by Adrian Nicolaiev