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/Palm 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/Palm 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 shared library. They are much more easily used from that library.

When calling routines in shared 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 shared library. A shared library will expect each argument passed to it to be the proper type.

If you use literals, NS Basic/Palm 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 Palm 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:

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

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)

A trapnum greater than 882 is Palm OS 3.5 or newer.
A trapnum greater than 1000 is Palm OS 4.0 or newer.
A trapnum greater than 1115 is Palm OS 5.0 or newer.
Palm has Palm OS 5.0 Simulator on its website:
http://www.palmos.com/dev/tools/simulator/

Palm OS 5 trap numbers contributed by Adrian Nicolaiev