Palm Basic V1.

0
Welcome to the home page for Palm Basic, a Basic interpreter for PalmOS devices.
Download V1.0 build 2 here
Read the release notes for this version here.
Read full documentation online here.
Palm Basic should work on any version of Palm OS 3.0 or above
Palm Basic is 78k in size

License agreement
This version (V1.0) of Palm Basic is freeware.
By downloading this file you agree that we are not liable for any damages or issues arising
from use of the program, however caused.
This program may be distributed freely, but may not be modified.

Contact us
Please email any comments, feedback or bugs to us We would particularly appreciate hearing how you have found this program useful and/or how it could be enhanced to make it more useful.

Screenshots
Hopefully these will whet your appetite for programming your Palm ...

Palm Basic V1.0 Build 2 Release notes

This is a minor maintenance release to fix a small number of issues reported in V1.0 build 1. It also adds a few popularly requested functions to get the current time.

Bugs fixed:

Blinking cursor not appearing or appearing in wrong place when using input statement Crash when using input statement on certain Handspring devices Possible run time error caused by using goto to go forward passed an expression
containing the keydown function

Similar problem when using goto to jump forward passed an expression using array
elements

New functions:

Time() Seconds() Minutes() Hours() Days() Months() Years() Weekday()

Copyright
This site is copyright Paul Lawrence (c) 2003.
Palm Basic program is copyright Paul Lawrence (c) 2002-2003

1. Introduction

Palm Basic is a utility written for the Palm series of handheld devices. It is designed to allow you to write programs on your Palm for your Palm. The language is designed to be simple to use, yet sufficiently powerful to allow the construction of genuinely useful programs. Palm Basic consists of a program management screen, similar to memo pad. This allows you to organise your programs by category. From here, you can edit and run your programs, or you can go into console mode. Console mode allows you to execute single lines of BASIC, or to run your programs by name. Palm Basic supports integer, floating point, and string variables, as well as single and multi dimensional arrays. It supports the common structures found in BASICs i.e. for - next loops, do loop, if - else - then (either on a single line or over multiple lines), goto and gosub. It contains built in procedures for formatted printing and inputing, basic graphic operations, as well as a full set of floating point math functions.

Requirements
Palm Basic has a small footprint - it requires <100Kb of free memory. Palm Basic is compatible with any device running PalmOS 3.0 and above.

2. Finding Your Way Around

There are four modes that Palm Basic can be in. Each has a specific function. They are covered below individually.

2.1 The Program Manager

This is always the first screen that you see when you launch Palm Basic. It behaves very like the first screen in memo pad. From here, you can view the programs you have written, add new programs and shuffle programs around. Note that programs are organised into categories. A category is simply a name that describes a set of programs. Here is a list of what you can achieve from this screen:
Create a new program by pressing the 'new' button. You will be prompted for a name - enter a unique name for the program. You can change this later if required. You will then be taken to the editor. This program will be created in the current category, or 'Unfiled' if you are currently showing all categories. This too can be changed later. Select an existing program by tapping it with the pen. This will take you to the editor, allowing you to run or modify this program. Change the current category - this will change the set of programs displayed in the manager. You do this with the category control in the top right. Edit the current set of categories. You can add categories, renames categories and delete categories. You do this by selecting the category control in the top right, then touching 'Edit Categories...' with your stylus. Move programs up and down. You do this by touching the name of the program you wish to move, then dragging it up or down. A dotted line will show you where the program will be placed.

 From the menu, you can select Console, or you can use the shortcut key 'C'. This will take you to the console screen.

2.2 The Console Screen

The console screen is always initially blank, except for a flashing cursor at the top left. You can return to the program manager at any point, by selecing Manager from the menu or with the shortcut key 'M'. The purpose of the console screen is to allow you to type basic statements and have them executed immediately. For instance, try typing in: for a = 1 to 10:print a:next a You should see a screen similar to this:

You can recall the last ten commands you typed in this session. Use the Up and Down buttons to do this. You may then modify these commands before executing them. This is useful if you enter a command incorrectly, or you wish to enter many similar commands. You can assign values to variables and create arrays from the console. These will be remembered throughout your session, but will be deleted once you leave the screen. You can also execute programs you have written from the console. Do this by entering their name on a single line with no spaces at the beginning or end. Note that variables set up

before the program executes will not be cleared, and variables created by the program will be visible at the end. This has one problematic side-effect - if your program uses arrays, and you try to run it twice from the console, the second time around will cause an error when the program tries to Dim an already-existing array.

2.3 The Editor

The Editor allows you to write and run programs. It also contains the Properties dialog that allows you to rename a pogram, delete a program or change a program's category. It is much like memo pad; however there is one important difference. In line with most code editors, the editor does not wrap lines of text. Rather, it uses horizontal scroll bars to allow you to see very long lines.

2.4 Program execution

This screen shows the results of running your program. After the program has finished executing, you can run it again, or return to the editor. Note that variables are not preserved between successive runs of a program. When a program is requesting data, you can use any of the usual buttons (home, calculator, memopad etc) to leave Palm Basic. Note that the program will not still be running when you next launch Palm Basic - you will return to the manager as always. If a program is executing a long loop and you wish to interrupt its progress, press the power button. This will break the execution.

3. Language Definition

Here we define the basic elements of the language.

3.1 Name
A name is a letter, followed by a series of letters and numbers. Two names are the same if they consist of the same sequence of letters and numbers. This comparison is not case sensitive. Certain names are reserved for built in procedures, functions and operations. For instance, a, hello, h2o are valid names. 2a, a_b are not. a is equivalent to A.

3.2 Constants
There are three types of constants, integer, floating point and string. Integer constants are simple numbers, like 2, 0, -73. Floating point constants are similar, but are expressed with a decimal point e.g. 2.5, -27.3 etc. They can also be written in exponential format e.g. 2.5e12 or -1e-10. String constants are enclosed in either single or double quotes. They may contain any characters between the quotes except, of course, the matching quote. If you wish to put a " in a string constant, enclose the constant in single quotes '' and vice versa. If you need to use both, you will have to split the constant in two, and add them together.

3.3 Variables
There are three types of variables, floating point, integer and string. A floating point variable is expressed by a name. An integer variable is expressed by a name followed imediately by a % sign. A string variable is expressed by a name followed immediately by a $ sign. Note that a, a% and a$ can all be used in the same program, and are distinct. If a variable has not been defined when it is referenced, it will have the value 0 for an integer or floating variable, and "" for a string variable.

3.4 Arrays
Palm Basic supports floating point, integer and string arrays of arbitrary dimension. An element of an array is expressed by a suitable variable name followed by a '(', the expressions giving the dimension offsets separated by commas then a ')'. Dimension offsets are based from 1. So a(1) is the first element of the one dimensional array of floating point values named a. b$(7,4+4) is the (7,8)th element of the two dimensional array of strings names b. Note that the array a is distinct from the variable a, and both can coexist in the same program.

3.5 Functions
Palm Basic contains a number of built in functions, like sin, cos, mid$ etc. The syntax for a function is identical to that for an array. For example, sin(1) will return the sine of 1, cos(a) will return the cosine of the value in variable a.

3.6 Expressions
Expressions consist of constants, variables, array elements or functions separated by operators. Operators are evaluated according to the standard rules of precedence. Round brackets '(' and ')' can be used to group subexpressions to override the standard evaluation order. Examples of expressions are: 2+2, 2+a, 2+3*sin(x), (2+3)*sin(x), a$ + "fred"

3.7 Statements
There are four types of statement.
Label. A name, by itself, is a label. This can be used in a goto or a gosub to redirect program
flow.
Assignment. An assignment statement consists of a variable or array element followed by an
equals sign and an expression. For instance, a = 1 is an assignment, as is h$ = "hello", or x% =
73/12.
Procedure. A procedurual statement is the name of a built in procedure, like print, goto or rem,
optionally followed by the procedures arguments. If there is more than one argument, they are
typically separated by commas, except for the print and input statements, where there is a more
sophisticated punctuation system. Examples of procedural statements are print "hello" or
drawline 10, 10, 100, 100 or cls.
Structural statements. There are three structural statements in Palm Basic. These are
if...else...then, do...loop and for...to...step...next. We will cover these individually in the section
called Structural Statements later in this chapter.

3.7 Lines
A line is zero or more statements separated by colons. The following are valid lines: a=3:print a dim a$(30): a$(12) = "This is Palm Basic" : a$(30) = "This is the last string"

3.8 Programs
A program is a collection of lines entered into the editor. Each statement on each line is executed in order, unless a goto, gosub or control statement is encountered. These have the potential to move execution to another part of the program according to the rules laid down later. A simple program might be: for a = 1 to 10 print a, a*a next a

3.9 Structural statements

As mentioned above, there are three basic structural statements in Palm Basic, though each of these can consist of more than one statement.

3.9.1 For...To...Step...Next loops

The for...next loop consists of two statements. The first must be of the format: for variable = expression to expression (step expression) Note that the variable must be an integer or a floating point variable. The second expression must be of the format: next variable The named variable is initialised to the first expression. At each matching next statement, the variable is incremented by the amount of the step expression. It is then compared to the to expression. If the step expression is positive, and the resulting variable is greater than the to expression, the for loop is terminated and control proceeds to the statement after the next. Note that the final value of the variable is not altered. If the resulting variable is less than or equal to the to expression, execution resumes just after the for expression. If the step expression is negative, the behavior is the same, but the comparisons are opposite. Note that the step and to expressions

are evaluated once at the start of the for loop, and are not reevaluated each time. Also note that the loop will be executed at least once.

3.9.2 If...Else...Then statements

These statements always start with if expression There are two forms of the if...else...then statement. Single line. Here, the if expression is followed on the same line by optionally the keyword then, followed by one or more statements separated by colons. These in turn may be followed by the keyword else, followed by one or more expressions separated by colons. If the expression evaluates to a non-zero value, the first set of statements are executed. If the expression evaluates to a zero value, the second set of expressions (if they exist) are executed. Multi line. If there is either nothing following the if statement, or only the keywork then, this statement is the start of a multi-line if statement. If the expression evaluated to a non-zero value, control is passed to the next statement, and continues until an else is encountered. Control is then suspended until the terminating endif statement is encountered. If the expression evaluated to zero, statement execution is suspended until the matching else or endif is encountered.

3.9.3 Do...Loop statments

A loop statement passes control back to the matching do statement. Note that either do or
loop may be followed by while expression or until expression. Control passes to the
statement beyond the loop if the expression after a while evaluates to zero, or the
expression after an until evaluates to non-zero.
For instance:
do
input "Enter a string, or nothing to stop "a$
print a$
loop while a$ <> ""
Note that control statements can be safely nested. It is also possible to jump (with goto) out
of control statements, either forward or backward. It is not possible to jump into a control
statement - this will cause an error when the ending control is encountered.

4. Operators

Operators are grouped by precedence, highest first. Operators in the same section (4.x) have equal precedence. Most operators may only be used on numeric (integer or floating) values. Operators that may be used on string values are noted to that effect.

4.1 Unary Operators

4.1.1 Multiplies the following object by -1

4.1.2 NOT
1 if the following object is 0, 0 otherwise

4.2 Power

4.2.1 ^
Returns x^y. Note that if y is integral, this is achieved by repeated multiplication. If y is non integral, x^y is equivalent to exp(y ln(x)).

4.3 Multiply and Divide

4.3.1 *
Returns x*y. Note that if both x and y are integers, x*y is an integer. Otherwise x*y is a floating value

4.3.2 /
Returns x/y. Note that this value is always floating.

4.4 Add and Subtract

4.4.1 +

Returns x+y. Note that if y is integral, this is achieved by repeated multiplication. Note also that this operator may be used on strings.

4.4.2 Returns x-y. Note that if y is integral, this is achieved by repeated multiplication.

4.5 Comparison
All these operators return 1 if the expression is true, 0 otherwise. All may be used on numeric or string values. String comparison is case sensitive.

4.5.1 = 4.5.2 <> 4.5.3 < 4.5.4 <= 4.5.5 > 4.5.6 >=
4.6 Boolean operators
These final operators are commonly used for grouping comnparison operators. For example, if you
wish to perform an action only if two comparisons are true, you might write:
if a=1 and b=2 then ...

4.6.1 AND
x AND y is 1 if both x and y are non-zero. Otherwise it is 0.

4.6.2 OR
x OR y is 1 if either x or y or both are non-zero. Otherwise it is 0.

4.6.3 XOR
x XOR y is 1 if x is non-zero, or y is non-zero, but 0 if both are non-zero or both are zero. (XOR stands for exclusive o, meaning x or y but not both.)

5. Procedures

This documents all the procedures currently in Palm Basic. They are (roughly) organised into functional groups.

5.1 Print
This is the most complex procedure in Palm Basic. A print statement consists of a sequence of
expressions, commas and semicolons. An expression is evaluated, and the corresponding integer,
floating point number or string is printed at the current text position. A comma moves the text
position to the next tab stop. There are four tab stops per screen width. A semicolon has no effect,
and can usually be omitted except as the last element of the sequence. If the expression does not
end in a comma or a semicolon, the current text position is moved to the next line. If the current
text position is off the screen when characters have to be printed, the screen is scrolled vertically
until the current text position is on the screen.
Examples:
Print "hello"
Print a,,b
Print "hello";
Print

5.2 Let
Let defines this statement as an assignment statement. It is always optional.

5.3 Goto
Goto label. Execution continues at the statement after the named label.
Note that it is possible to use goto to leave a control structure (if...then, for...next or do...loop)
either forwards or backwards. It is not possible to use goto to enter a control loop. This will cause
an error when execution reaches the terminating statement of the control loop.

5.4 Gosub
Gosub label. Execution continues at the statement after the named label. When execution reaches a return statement, control resumes at the statement following the gosub statement.

5.5 Return
See gosub.

5.6 Input
An Input statement consists of a sequence of constant strings, commas, semicolons, variable names and array elements. A constant string is displayed. A comma moves the text position to the next tab stop (see Print above). A semicolon has no effect, and can usually be omitted except as the last element of the sequence. A variable name or array elements causes a cursor to be displayed at the current text position. The user of the program can then enter any characters. When they enter the return character, the text is read and used to alter the value of the variable. If the variable is numeric, the text is processed as a number and the value is placed in that variable (see the function val for the precise rules as to how this is done). (Note that if the user enters a floating point number and the variable is an integer, the number will be converted to an integer (see the function int for precise rules as to how this is done). If the variable is a string, the text is placed into that variable without alteration.

5.7 Dim
Dim array_name(size ,size ,size ...), array_name(size, ...)
Create one or more arrays of one or more dimensions. Note that you cannot create the same array
more than once.

5.8 Rem
Rem text Ignore the rest of this line (including colons and what follows them). Used for inserting comments (rem-arks) into programs.

5.9 End
Stops program execution. This is equivalent to reaching the end of the program.

5.10 Clear
Delete all variables and arrays.

5.11 Cls
Clear the screen, and restore the text position to the top left.

5.12 TextPos
TextPos x, y Set the current text position to (x,y). Note that 0 <= x < width and 0 <= y < height or an error will be thrown.

5.13 TextMode
TextMode n n must be 1, 2, 3 or 4. Affects how text is drawn by the print and input procedures. 1: Draw characters normally 2: Erase characters (draw in white) 3: Draw white characters on a black background 4: Invert characters

5.14 DrawLine
DrawLine x1, y1, x2, y2 Draw a line from (x1, y1) to (x2, y2). Note that coordinates are based from the top left.

5.15 EraseLine
EraseLine x1, y1, x2, y2 Erase (draw in white) a line from (x1, y1) to (x2, y2).

5.16 InvertLine
InvertLine x1, y1, x2, y2 Invert all pixels on a line from (x1, y1) to (x2, y2).

5.17 GrayLine
GrayLine x1, y1, x2, y2 Draw a gray line from (x1, y1) to (x2, y2). This in fact draws every other pixel on the line.

5.18 DrawRect
DrawRect x1, y1, width, height ,radius Draw a solid rectangle with top left (x1, y1), width width and height height. If the fifth argument is given, the corners of the rectangle are rounded with the specified radius.

5.19 EraseRect
EraseRect x1, y1, width, height ,radius Draw a solid rectangle with top left (x1, y1), width width and height height. If the fifth argument is given, the corners of the rectangle are rounded with the specified radius.

5.20 InvertRect
InvertRect x1, y1, width, height ,radius Invert all pixels in a solid rectangle with top left (x1, y1), width width and height height. If the fifth argument is given, the corners of the rectangle are rounded with the specified radius.

5.21 DrawFrame
DrawFrame x1, y1, width, height Draw a frame around the rectangle with top left (x1, y1), width width and height height. Note that this means that DrawRect 1,1,10,10 will draw a rectangle starting at (0,0) and finishing at (12,12).

5.22 EraseFrame
EraseFrame x1, y1, width, height The same as DrawFrame, except that the pixels are erased (drawn in white).

5.23 InvertFrame
InvertFrame x1, y1, width, height The same as DrawFrame, except that the pixels are inverted.

5.24 GrayFrame
EraseFrame x1, y1, width, height The same as DrawFrame, except that only every other pixel is drawn.

5.25 Randomize
Randomize n Sets the seed for the pseudo random number generator. If n is given, it is used. This is perhaps most useful if you want to ensure that a sequence of calls to rnd() always produces the same results. If n is omitted, the current time is used to try to generate apparently random behavior in subsequent calls to rnd().

6. Functions
This documents all the functions currently in Palm Basic. They are (roughly) organised into groups.

6.1 Left$(string A$, integer N)

Returns a string consisting of the first N characters of string A$. If N is less than or equal to zero, returns an empty string. If N is greater than the length of A$, returns a string equal to A$.

6.2 Right$(string A$, integer N)

Returns a string consisting of the last N characters of string A$. If N is less than or equal to zero, returns an empty string. If N is greater than the length of A$, returns a string equal to A$.

6.3 Mid$(string A$, integer P, integer N)

Returns a string consisting of the N characters of string A$ starting at position P within the string. Note that the first character is 0, so Mid$(A$, 0, N) is equivalent to Left$(A$, N) If N is less than or equal to zero, returns an empty string. If N is greater than the length of A$, returns a string equal to A$. Returns an error if P < 0, otherwise truncates the result if A$ isn't long enough.

6.4 Len(string A$)

Returns the length of A$.

6.5 Asc(string A$)

Returns the ascii code for the first character of A$.

6.6 Char$(integer N)
Returns a string consisting of the single character whose ascii code is N. Note that if N is outside the range 0 to 255, this function returns a string consisting of the character whose ascii code is N modulo 256.

6.7 Eval(string A$)

Evaluates the expression in string A$. If the expression is followed by extra characters, then the extra characters are ignored. If the expression is not complete, an error is thrown. For instance, eval("a+b ignored") will evaluate a+b. But eval("a+") will cause an error.

6.8 Val(string a$)

Evaluates the number in string A$. If the number is followed by extra characters, then the extra characters are ignored. Like eval, if the number is incomplete, an error is thrown. This can only happen if the number has an exponenet (i.e. is like 3.7e32) but there are no digits following the e.

6.9 Width()
Returns the width of the screen.

6.10 Height()
Returns the height of the screen.

6.11 Sin(floating theta)

Returns sin(theta) where theta is in radians.

6.12 Cos(floating theta)

Returns cos(theta) where theta is in radians.

6.13 Tan(floating theta)

Returns tan(theta) where theta is in radians.

6.14 ArcSin(floating x)
Returns inverse sin(x).

6.15 ArcCos(floating x)
Returns inverse cos(x).

6.16 ArcTan(floating x)
Returns inverse tan(x).

6.17 Log(floating x)
Returns the natural logarithm of x.

6.18 Exp(floating x)
Returns e to the power x.

6.19 Abs(floating or integer x)

Returns the absolute value of x i.e. x if x >= 0, -x if x < 0.

6.20 Int(floating x)
Returns the integral part of x. If x > 0, int(x) <= x. If x < 0, int(x) >= x.

6.21 Sign(floating or integer x)

Returns 1 if x is positive, 0 if x is 0 and -1 if x is negative.

6.22 KeyDown(integer x)
Allows a program to determine the state of the various buttons on the Palm. x must be in the range 1 to 10. If the appropriate key is pressed KeyDown, returns 1, else it returns 0. The numbers 1 to 10 correspond to the following keys: 1: Power key (note that since this causes an interrupt, this value is not useful) 2: Page up key 3: Page down key 4: App #1, typically calendar 5: App #2, typically address list 6: App #3, typically todo list 7: App #4, typically memo pad 8: Button on cradle 9: Antenna key 10: Contrast key

6.23 Rnd()
Returns a pseudo random number in the range 0 to 1. Note that the procedure randomize can be used to set the key. If you do not call randomize, note that the key will always be initialized to 0 when you start Palm Basic, so the sequence will always be the same.

6.24 Time()
N.B. For these following functions to exist, you must have Palm Basic v1.0 build 2 or later. Check the build number in the about box - if you do not have the latest build, download it here.

Returns the number of seconds since 12:00A.M. on January 1, 1904. Note that this number will
actually appear as a large negative number. It is not suggested that you use this value directly;
rather you can pass it to the following time-related functions, or you can subtract one time from
another to get an elapsed time:
t = time()
rem long loop
for a = 1 to 1000 next a print "The long loop took "time() - t1" seconds"

6.25 Seconds(integer t)
Used to convert the return value from time() into seconds, minutes, hours etc. Returns the number of seconds (0-59) elapsed in the current minute.

6.26 Minutes(integer t)
Used to convert the return value from time() into seconds, minutes, hours etc. Returns the number of minutes (0-59) elapsed in the current hour.

6.27 Hours(integer t)
Used to convert the return value from time() into seconds, minutes, hours etc. Returns the number of hours (0-23) elapsed in the current day.

6.28 Days(integer t)
Used to convert the return value from time() into seconds, minutes, hours etc. Returns the day of the month (1-31).

6.29 Months(integer t)
Used to convert the return value from time() into seconds, minutes, hours etc. Returns the month (1-12).

6.30 Years(integer t)
Used to convert the return value from time() into seconds, minutes, hours etc. Returns the year (1904-2040).

6.31 Weekday(integer t)
Used to convert the return value from time() into seconds, minutes, hours etc. Returns the day of the week (0-6) where 0 is Sunday.