Library Routines

---- Basic I/O ----

 puts(string text)  print a string to the output form. Does not append a newline.
 gets(string prompt)  presents an input dialog with the given string as a prompt. Returns a string if the user pressed OK, or zero if the user presses Cancel.
 alert(string msg)  pops up an alert dialog with the given text.
 confirm(string msg) - pops up an alert dialog with the given text and Yes/No buttons. Returns 1 for Yes, 0 for No.
 clear() - clears the output form.


---- Event System ----

 event(int blocking) - check for events in the event queue. If blocking is zero, event returns immediately, otherwise it waits for an event. Events are as follows: [0] none, [1] key (character), [2] penDown, [3] penUp, [4] penMove, [5] pageUpKey, [6] pageDownKey.
 key() - retrieve the character written during the last event()
 penx()  retrieve the x value of the pen event processed by the last call to wait, waitp, or event.
 peny()  retrieve the y value of the previous pen event.
 pstate() - returns 1 if the pen in down, 0 otherwise.
 bstate() - returns the state of the hard buttons. Returns [0] neither, [1] page up, [-1] page down.
 wait()  wait for a pen or character event. Returns the character written to the graffiti area or -1 for pen event.
 waitp()  wait for a pen event.
 getc()  wait for and return a character written to the graffiti area.


---- String ----

 strlen(string)  returns the length of a string.
 substr(string, int first, int len)  returns a string which consists of len characters from the original string starting at first character. (e.g. <code>substr(Hello, 1, 3)</code> returns ell)
 strleft(string, int len)  returns the len leftmost characters from the string.
 strright(string, int len)  returns the len rightmost characters from the string.
 strupr(string)  returns the original string in all uppercase.
 strlwr(string)  returns the original string in all lowercase.
 strstr(string str, string sub, int first) - searches str for a substring sub starting at the character first. Returns the starting position of sub within str or -1 on failure.
 hex(int n) - returns the hexadecimal representation of n
 format(float f, int prec) - returns the string representation of f with prec decimal places.


---- Math ----

 cos, sin, tan, acos, asin, atan, cosh, sinh, tanh, acosh, asinh, atanh (float)  returns the expected trigonometric value, using radians. These functions require MathLib to be present.
 pow(float x, float y)  returns x^y. This function requires MathLib to be present.
 atan2(float y, float x)  returns the arctangent of y/x. This function requires MathLib to be present.
 sqrt(float x) - returns square root of x. This function requires MathLib to be present.
 log(float x) - returns natural log of x. This function requires MathLib to be present.
 log10(float x) - returns log base 10 of x. This function requires MathLib to be present.
 exp(float x) - returns e^x. This function requires MathLib to be present.
 rand()  returns a random float between 0 and 1.
 random(int n)  returns a random int between 0 and n-1.
 hex(int n) - returns the hexadecimal representation of n
 mathlib() - returns 1 if MathLib is present, 0 otherwise.


Note: Functions that require MathLib will return integer 0 if the library is not present.

---- Graphics ----

 graph_on()  switches to the graphics form.
 graph_off()  swithces from the graphics form to the output form. The appearance of the graphics form is not preserved.
 text(int x, int y, string str)  display a string str at locations (x,y).
 textattr(int font, int color, int underline)  set the current text drawing attributes. font is a number 0-6. Available fonts are normal[0], bold[1], large[2], symbol[3], symbol11[4], symbol7[5], LED[6]. color is a number 0-2. Available colors are white[0], black[1], inverted[2]. underline is a number 0-2. Underline modes are none[0], solid[1], dotted[2].
 line(int col, int x1, int y1, int x2, int y2)  draws a line from (x1, y1) to (x2, y2) in color col. white[0], black[1], gray[2], XOR[3].
 rect(int col, int x1, int y1, int x2, int y2, int diam)  draws a rectangle from (x1, y1) to (x2, y2) in color col with corners of diameter diam. A diameter of 0 has square edges. white[0], black[1], XOR[3]. (This function doesn't support gray)
 frame(int col, int x1, int y1, int x2, int y2, int diam) - same as rect() but not filled. white[0], black[1], gray[2], XOR[3].
 frame2(int col, int x1, int y1, int x2, int y2, int diam, int width) - same as frame() but allows specification of width (1-3).
 title(string title)  set the graphic form title to title.
 clearg() - clears the graphics form.
 bitmap(int x, int y, string bits) - draw a bitmap at (x,y). The bits string is a list of hexadecimal digits in the following form: "wwxxxxxxxx..." where 'ww' is the width of the bitmap (i.e. '0a' is a 10-pixel wide bitmap), and 'xxx...' are the bits of the bitmap, each character representing 4 pixels. So, "0affc804804ffc" is a 10x4 bitmap of a rectangle ('ffc' is a solid line, '804' represents a left and right edge.)
 

---- Sound ----

 beep(int type)  generates a system sound, where type is between 1 and 7. Available sounds are info[1], warning[2], error[3], startup[4], alarm[5], confirmation[6], and click[7]. Note: not all sounds are unique in current versions of PalmOS.
 tone(int freq, int dur)  generates a tone of frequency freq (in Hz), and duration dur (in milliseconds).
 

---- Time/Date ----

 ticks() - the number of clock ticks since last reset
 seconds() - the number of seconds since Jan 1, 1904 minus 2^31
 time(int mode) - [mode 0] integer val (hour*100+minute) [mode 1] string val (as determined by system preferences)
 date(int mode) - [mode 0] integer val (year*10000+month*100+day) [mode 1] short string val [mode 2] long string val (as determined by system preferences)


---- Datbase I/O ----
All the database functions work on databases with creator id 'PktC' and type 'user'. An attempt to open or overwrite a database with a given name but different creator/type will fail. Only one database can be open at a time.

 dbopen(string name) - opens the database named name, returns 0 on failure.
 dbcreate(string name) - creates and opens a database named name, returns 0 on failure. If another database of the same name exists (with the proper creator/type), it will be overwritten.
 dbwrite(data) - write the value data to the end of the database. data can be of any type, use casting to ensure that data is the correct type. This funtion sets the position to -1.
 dbread(char type) - read a value from the current position in the database. A value must be read as the same type that it was written. Available types are 'c' char, 'i' int, 'f' float, 's' string.
 dbpos() - get the current location in the database. -1 indicates the end has been reached.
 dbseek(int loc) - set the current location. If this value is greater than the length of the database, the next call to dbread() will set the position to -1.
 dbbackup(int flag) - flag [0] clear backup bit, [1] set backup bit, [2] query backup bit.
 dbclose() - close the current database.
 dbdelete() - delete and close the current database.


---- Memo Pad I/O ----

 mmnew() - create a new, empty memo, returns 0 on failure.
 mmfind(string name) - opens the memo with name as its first line, returns 0 on failure.
 mmopen(int id) - opens the memo with the given id, returns 0 on failure. This function is not recommended, but is included for completeness.
 mmputs(string) - appends the given string to the end of the memo.
 mmgetl() - retrieves a string from the current position in the memo.
 mmeof() - returns 1 if at the end of the memo, 0 otherwise.
 mmrewind() - rewind the current memo to the beginning.
 mmclose() - close the current memo.
 mmdelete() - delete and close the current memo.


---- System ----

 sleep(int ms) - sleeps for ms milliseconds.
 resetaot() - resets the auto off timer.
 getsysval(int index) - gets a system value. Currently supported values: [0] Username.


---- Serial I/O ----

 seropen(int baud, string settings, int timeout) - open the serial port. Tested baud rates are 300-57600, higher rates are theoretically possible. settings is a 4-char string in the form "8N1C" [bits/char (6,7,8) parity (N,E,O) stop bits (1,2) flow control (X-software,C-CTS,R-RTS)]. timeout is the number of clock ticks (1/100 sec) to wait for data. Returns 0 for success.
 serclose() - close serial port.
 sersend(char byte) - send a byte, return 0 on success.
 serrecv() - receive a byte, returns an integer 0-255 on success, > 255 on failure.
 serdata() - return 1 if data is waiting, 0 otherwise.
