Built-in Functions

Basic I/O

• puts(string text) – append a string to the output form. Does not add a newline. (To add a newline, add a "\n" to the end of your string).
• gets(string prompt) – presents an input dialog with the given string as a prompt. Returns a string if the user pressed OK, or an empty string if the user presses Cancel. The dialog can contain 2 lines of text, use the '\r' character to wrap to the second line.
• getsd(string prompt, string defaultValue) – presents an input dialog with the given string as a prompt and a default value in the input field. Returns a string if the user pressed OK, or an empty string if the user presses Cancel. The dialog can contain 2 lines of text, use the '\r' character to wrap to the second line.
• getsi(int x, int y, int w, string defaultValue) – presents an input dialog at the x, y coordinates specified, with the given string as a default value. The input dialog will have an edit field of width w (though the dialog will be larger). A string is returned when the user presses OK (there is no cancel option).
• getsm(int x, int y, int w, int lines, string defaultValue) – exactly like getsi(), but the edit field created is lines lines tall.
• 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 time) - check for events in the event queue. If time is zero, event returns immediately. If time is one, the function waits indefinitely for an event to occur. If time is >1, time represents the timeout period in 1/100s of a second, e.g. event(50) waits for up to one half second. Events are as follows: [0] none, [1] key (character), [2] pen down, [3] pen up, [4] pen move, [5] page up key, [6] page down key, [7-10] hard key1-4, [11] menu button, [12] launch/home button, [13] find button, [14] calc button, [15] HotSync button. In order to receive messages from the hard keys or silkscreen buttons (7-15), you must call the corresponding hook function (see below).
• 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. Use penx() and peny() to retrieve the location of a pen event, or key() to retrieve the character.
• waitp() – wait for a pen event. Use penx() and peny() to retrieve the location of a pen event.
• getc() – wait for and return a character written to the graffiti area.
• hookhard(int bHook) - if bHook is nonzero, hard keys (address button, etc.) are not processed by the OS. Instead, they are intercepted by the event() function. If bHook is zero, hard key presses are no longer intercepted.
• hookmenu(int bHook) - if bHook is nonzero, the menu silkscreen button is not processed by the OS. Instead, it is intercepted by the event() function. If bHook is zero, menu button presses are no longer intercepted.
• hooksilk(int bHook) - if bHook is nonzero, all silkscreen buttons are not processed by the OS. Instead, it is intercepted by the event() function. If bHook is zero, silkscreen button presses are no longer intercepted.
• hooksync(int bHook) - if bHook is nonzero, the HotSync cradle button is not processed by the OS. Instead, it is intercepted by the event() function. If bHook is zero, the button events are no longer intercepted.

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. substr(“Hello”, 1, 3) 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.
• strtoc(string str, pointer ptr) - fill the array of chars pointed to by ptr with the characters from the string str. ptr must either point to an array of pointers long enough to hold the string plus the terminating 0, or it must be a pointer alloced with malloc(). If the pointer was allocated by malloc(), you must be sure that all the memory is of type char by calling settype().
• ctostr(pointer ptr) - takes the char array pointed to by ptr, and returns a string composed of its characters. The memory pointed to by ptr must be of type char and must end with a 0.

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.
• 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() – switches 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], Large Bold[7] (OS 3.0 only). 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].
• textalign(char alignmentYX) – sets the alignment that text() uses. The parameter is a number between 0 and 22, where the first decimal digit describes the vertical alignment, and the second describes the horizontal. left[0], center[1], right[2].
• textwidth(string str) – returns the width in pixels of str with the current font settings.
• 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 radius) – draws a rectangle from (x1, y1) to (x2, y2) in color col with corners of radius radius. A radius 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 radius) - 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 radius, int width) - same as frame() but allows specification of width (1-3 only).
• title(string title) – set the graphic form title to title.
• clearg() - clear the graphics form.
• saveg() - save the graphics form internally. Returns 0 on failure, 1 otherwise.
• restoreg() - restore the graphics form previously saved by a call to saveg(). This can only be called once for each time saveg() is called.
• 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.) Note: there are several PocketC utilities available that will generate these strings for you.

  Example:
  A 10x4 rectangle "0affc804804ffc"
  8 4 2 1  8 4 2 1  8 4 2 1
  X X X X  X X X X  X X 0 0 = ffc
  X 0 0 0  0 0 0 0  0 X 0 0 = 804
  X 0 0 0  0 0 0 0  0 X 0 0 = 804
  X X X X  X X X X  X X 0 0 = ffc
  
  A small square (5x5) with a dot in the center would be "05f888a888f8"
  8 4 2 1  8 4 2 1
  X X X X  X 0 0 0 = f8
  X 0 0 0  X 0 0 0 = 88
  X 0 X 0  X 0 0 0 = a8
  X 0 0 0  X 0 0 0 = 88
  X X X X  X 0 0 0 = f8

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 value (hour*100+minute) [mode 1] string value (as determined by system preferences) [mode 2] integer value (hour*10000+minute*100+sec)
• date(int mode) - [mode 0] integer value (year*10000+month*100+day) [mode 1] short string value [mode 2] long string value (as determined by system preferences)

Database I/O

All the database functions work on databases with any creator id/type, but use of resource databases may cause unexpected results. When creating a new database, the database will have creator id 'PktC' and type 'user'. An attempt to 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. The current record is set to 0.
• dbcreate(string name) - creates and opens a database named name, returns 0 on failure. If another database of the same name and creator ID/type 'PktC' / 'user' exists, it will first be erased. The current record is set to 0.
• dbcreatex(string name, string creator, string type) - creates and and opens a database named name with creator ID creator and type type, returns 0 on failure. If another database of the same name and creator ID/type exists, it will first be erased. The current record is set to 0.
• dbrec(int recnum) - sets the current record to rec and the current position to 0. If the record is greater than the current number of records, future reads will fail. However, the next write will create a new record at the end of the database and set the current record to it.
• dbnrecs() - returns the number of records in the current database.
• dbsize() - returns the size of the current record in bytes.
• dbwrite(data) - write the value data at the end of the current record. data can be of any type, use casting to ensure that data is the correct type. Use caution when writing in the middle of a database with null-terminated strings, as they are of unknown length.
• 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.
• dbwritex(pointer ptr, string format) - Using the current database, write data pointed to by ptr and described by format at the current position in the current record. format contains a list of data types, one per value following ptr. Data types are 'c' - a single byte, 'i2' - a 2-byte word, 'i4' - 4-byte double word, 'f' - a 4-byte float, 'sz' - a null-terminated string, 's#' - a string of length #. Returns the number of values written.
• dbreadx(pointer ptr, string format) - Using the current database, read data of the the given format into the data pointed to by ptr. format is the same as dbwritex(). Returns the number of values read.
• 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.
• dberase() - erases the content of the current record (but does not remove the record).
• dbdelrec(int recnum) - deletes the specified record from the current database. This removes the contents of the record and sets its 'delete' bit, which will cause the record to be removed on the next HotSync. Returns 0 on error.
• dbarcrec(int recnum) - archives the specified record from the current database. This maintains the contents of the record and sets its 'delete' bit, which will cause the record to be removed and archived on the next HotSync. Returns 0 on error.
• dbremrec(int recnum) - removes the specified record from the current database. This removes all traces of the record. Returns 0 on error.
• dbenum(int first, string type, string creator) - enumerates the databases installed on the device, by type and/or creator. Returns 0 if no more databases are available. The type and creator are each 4 character strings, or the empty string for a wildcard. To get the first database, you must set first=1. To get the subsequent matching databases you must set first=0.
• dbgetcat() - returns the category ID for the current record.
• dbsetcat(int catID) - sets the category ID for the current record (must be a number between 0 and 15).
• dbcatname(int catID) - returns the name of the category given its category ID.
• dbmoverec(int from, int to) - remove the record at index from and insert it at index to.
• dbinfo(string name, pointer pstrType, pointer pstrCreator) - retrieve the type and creator ID of  the database named name. pstrType and pstrCreator must be pointers to strings. Returns 1 on success, 0 on failure.
• dbtotalsize(string name) - retrieves the total size of all records in the database named name. Returns 0 on failure.

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. Does not include the newline.
• 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.
• mmcount() - returns the number of records in the memo pad database.

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, H-CTS/RTS, N-None)]. 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 the number of bytes waiting in the receive buffer.
• serwait(int nBytes, int timeout) - wait until nBytes bytes are available in the receive buffer. timeout is the number of ticks (1 tick typically equals 1/100 second) allowed between consecutive bytes. Returns 0 for timeout, -1 for line error, 1 for success.
• serbuffsize(int size) - allocates a serial buffer of the given size (+32 bytes for PalmOS overhead). This function should only be called if you seem to be having serial overrun problems. Returns 1 on success, 0 on failure.
• sersenda(pointer pData, int size) - send size bytes of data from an array. The memory pointed to by pData must be ints or chars, and each element my be one byte.
• serrecva(pointer pData, int size) - receive size bytes of data into an array. The memory pointed to by pData must be ints or chars, and each element will be filled with one byte.
• unpack(pointer pInts, pointer pSerData, string dataSizes, int count) - unpack an array of count bytes into 1- 2- and 4-byte ints. pSerData is a memory block/array of bytes (either ints or chars); pInts is a memory block/array of ints which will be filled with unpacked ints; dataSizes is a string describing the data. Each number (1,2,4) in dataSizes represents an int. If a number is preceeded by '<', then the bytes are assumed to be in little-endian order; big-endian is assumed otherwise. The dataSizes string is repeatedly processed until count bytes are unpacked. Example: from serrecva(), you get 8 bytes which should be interpreted as a big-endian 16-bit it, a little-endian 16-bit int, and a 32-bit big-endian int. The code might be:

int data[3], sbuff[8];
...
serrecva(sbuff, 8);
unpack(data, sbuff, "2<24", 8);

System

• sleep(int ms) - sleeps for ms milliseconds.
• deepsleep(int sec) - turns the device off for sec seconds. This is only accurate to within 30 seconds, your mileage may vary.
• resetaot() - resets the auto off timer.
• getsysval(int index) - gets a system value. Currently supported values: [0] Username, [1] OS Version, [2] OS Version string, [3] Serial number.
• launch(string creatorID) - closes PocketC and launches the application with the given creator ID. Returns 0 on failure, does not return on success. Ex: launch("memo"); // Opens memo pad. Ex: launch("lnch"); // Opens the application launcher if running OS 3.0
• clipget() - returns the current clipboard contents (if text).
• clipset(string text) - sets the text clipboard contents.
• exit() - exits immediately. On OS 3.0+, exits to application launcher. On OS 2.x, exits to PocketC.
• atexit(pointer func) - The function whose address is passed to this function is called immediately when the user attempts to switch apps (but not when the user presses the Done button or the Applet|Stop menu item). Such a function must run very quickly and may not affect the display or use the event system (through event(), puts(), alert(), graphics functions, etc.). Warning: it is not generally safe to make assumptions about where your applet was suspended when func began to execute.
• version() - returns the installed PocketC version. For version 4.0.3, this returns 403.

Memory Management

A few notes that will help understand the following section: In a normal computer, memory is divided into bytes and words. PocketC divides its memory into elements called "values". Each value stores a basic PocketC type (int, char, float, string, pointer). Also, each element of memory knows its own type (thus the need for the settype() function).

• malloc(int size) - allocates a block of size values of type int, but of undefined value. Returns a pointer to the block or 0 on failure. The types of the elements in the returned block can be changed from int to any other type using the settype() function. This function is deprecated, malloct() should be used instead.
• malloct(int nBlocks, string blockTypes) - allocates nBlocks blocks of memory whose types are described by blockTypes. blockTypes is a string of characters representing data types ( 'i'-int, 'p'-pointer, 'c'-char, 'f'-float, 's'-string). The memory block is initialized to 0 for numeric types and "" for strings. e.g. malloct(3, "piis") will allocate 12 values -- the first will be a pointer, the second/third an int, the fourth a string, the fifth another pointer, the sixth/seventh ints...
• free(pointer ptr) - releases the memory of the block pointed to by ptr which was previously allocated by malloc(). When an applet exits, all blocks that are still allocated will automatically be freed to prevent memory leaks.
• settype(pointer ptr, int size, char type) - sets the type of the size contiguous values starting at ptr to the type specified by type ('i' for int or pointer, 'f' for float, 'c' for char, 's' for string). Use this function only on memory allocated by malloc(). Returns 0 on error.
• typeof(pointer ptr) - returns the type of the value pointed to by ptr, ('i' for int or pointer, 'c' for char, 'f' for float, 's' for string, 'o' for other).
• memcpy(pointer dest, pointer src, int size) - copies the data from the block of size size pointed to by src to the block pointed to by dest. The types of the destination values is not preserved. (i.e. if dest points to a string, and src points to an int, the memory pointed to by dest will be changed to an int)..