Palm Basic Manual

Palm Basic Manual

1. Introduction
2. Finding your way around
3. Language definition
4. Operators
5. Procedures
6. Functions

[Link] [2/5/2012 5:17:55 PM]

 Palm Basic Manual - Introduction

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.

[Link] [2/5/2012 5:18:06 PM]

 Palm Basic Manual - Finding Your Way Around

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.

[Link] (1 of 4) [2/5/2012 5:18:08 PM]

 Palm Basic Manual - Finding Your Way Around

● 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:

[Link] (2 of 4) [2/5/2012 5:18:08 PM]

 Palm Basic Manual - Finding Your Way Around

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.

[Link] (3 of 4) [2/5/2012 5:18:08 PM]

 Palm Basic Manual - Finding Your Way Around

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.

[Link] (4 of 4) [2/5/2012 5:18:08 PM]

 Palm Basic Manual - Language Definition

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.

[Link] (1 of 4) [2/5/2012 5:18:09 PM]

 Palm Basic Manual - Language Definition

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

[Link] (2 of 4) [2/5/2012 5:18:09 PM]

 Palm Basic Manual - Language Definition

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.

[Link] (3 of 4) [2/5/2012 5:18:09 PM]

 Palm Basic Manual - Language Definition

● 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.

[Link] (4 of 4) [2/5/2012 5:18:09 PM]

 Palm Basic Manual - Operators

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 +

[Link] (1 of 3) [2/5/2012 5:18:10 PM]

 Palm Basic Manual - Operators

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.

[Link] (2 of 3) [2/5/2012 5:18:10 PM]

 Palm Basic Manual - Operators

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.)

[Link] (3 of 3) [2/5/2012 5:18:10 PM]

 Palm Basic Manual - Procedures

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

[Link] (1 of 5) [2/5/2012 5:18:11 PM]

 Palm Basic Manual - Procedures

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.

[Link] (2 of 5) [2/5/2012 5:18:11 PM]

 Palm Basic Manual - Procedures

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

[Link] (3 of 5) [2/5/2012 5:18:11 PM]

 Palm Basic Manual - Procedures

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

[Link] (4 of 5) [2/5/2012 5:18:11 PM]

 Palm Basic Manual - Procedures

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().

[Link] (5 of 5) [2/5/2012 5:18:11 PM]

 Palm Basic Manual - Functions

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$)

[Link] (1 of 5) [2/5/2012 5:18:11 PM]

 Palm Basic Manual - Functions

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).

[Link] (2 of 5) [2/5/2012 5:18:11 PM]

 Palm Basic Manual - Functions

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

[Link] (3 of 5) [2/5/2012 5:18:11 PM]

 Palm Basic Manual - Functions

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)

[Link] (4 of 5) [2/5/2012 5:18:11 PM]

 Palm Basic Manual - Functions

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.

[Link] (5 of 5) [2/5/2012 5:18:11 PM]