HotPaw Basic

for the Palm Computing Platform

Owner's Manual

Operating Manual | Programmer's Guide | Language Definition
Legal Notices | License | Appendices
Newest documentation at: < http://www.hotpaw.com/rhn/hotpaw/ >

Contents

Contents  Legal Notices   License

Section I - Operating Manual
1.0 Introducing BASIC and HotPaw Basic   2.0 Installation   3.0 Orientation  4.0 Getting Started   5.0 FAQs

Section II - Programmer's Guide
6.0 Writing Programs  7.0 Program Execution  8.0 Example Code  9.0 Example Programs  10.0 Some Warnings

Section III - Language Definition
Basic language 11.0 Synopsis  12.0 Description  14.0 Conventions  15.0 Basic Basic 
PalmOS Features 16.0 PalmOS Interface Commands  17.0 PalmOS Database Commands  18.0 PalmOS Scripting Commands  19.0 Macintosh Commands

Appendices
Appendix 1 - Reserved Words and Symbols   Appendix 2 - Unimplemented Standard Keywords   Appendix 3 - Diagnostics  Appendix 4 - Advanced Topics   Appendix 5 - Changes  Appendix 6 - Bugs

Section I - HotPaw Basic Operating Manual (Top)

( 1.0 Introducing BASIC and HotPaw Basic  2.0 Installation   3.0 Orientation  4.0 Getting Started   5.0 FAQs )

1.0 Introducing BASIC and HotPaw Basic (Up)

( 1.1 What is HotPaw Basic   1.2 HotPaw Basic Interpreter History   1.3 BASIC Programming Language History )

1.1 What is HotPaw Basic  (Up)
The BASIC programming language has been in use for over 3 decades; it's continued popularity is due to its simplicity and ease of learning. HotPaw brings this language to the palm of your hand and enables you to better use your Palm handheld as a true personal computer.
HotPaw(tm) Basic is a full-featured and easy-to-use scripting language which allows you to create and execute small Basic programs directly on your Palm handheld organizer/computer.
HotPaw Basic has many features including:
* over 75 functions and 30 commands built-in
* execution of Basic programs contained in your MemoPad
* simple built-in dialogs for displaying results and prompting for input parameters
* custom form creation with user definable buttons, fields and checkboxes
* access to several standard database formats (JFile Pro, HanDBase, DB and List) instead of a proprietary format
* sound and graphics drawing commands (including COLOR support)
* programmable ToDo, DateBook appointment and alarm creation
* serial port and infrared (SIR) communication
* support for the majority of the ANSI/ISO Minimal Basic programming language standard, as well as many MSBasic(tm) functions and statements
* support for double precision floating point arithmetic and for the MathLib transcendental function library
HotPaw Basic comes with several example programs, as well as a small application which allows you to start a Basic program directly from the Application Launcher (or even a button press).
1.2 HotPaw Basic Interpreter History  (Up)
Basic is an easy to learn computer programming language, invented at Dartmouth college around 1963. Various Tiny Basic implementations were written around 1976 for use in early personal computers with very limited memory configurations (8 KBytes, or less).
An earlier PalmPilot Basic interpreter, called cbasPad, was an experimental Tiny BASIC interpreter (written in portable C) which could run in the very tight memory requirements of a USR Pilot 1000 (PalmOS 1.0). It had many deficiencies due to these restrictions. HotPaw cbasPad Pro Basic is an new interpreter supporting a full version of the Basic language and taking advantage of many new features of PalmOS 3.0 and above, including much better support for accurate floating point math and for database access.
1.3 BASIC Programming Language History  (Up)
The BASIC programming language was developed in 1963 at Dartmouth College by Professors John G. Kemeny and Thomas Kurtz. It was meant as a simple, easy to learn method for even non-science students to learn to write computer programs. The acronym "BASIC" originally stood for "Beginner's All-purpose Symbolic Instruction Code".
The year 1964 was in an era when even the smallest computers were larger than refrigerators and cost several times more than a single-family house. Computers sat inside special rooms and had to be shared by many students and researchers. Students would communicate with these minicomputers via teletypes, which were consoles that had keyboards, but no pointing device and no video display, instead having only a slow printer capable of printing one line at a time.
Because of the simplicity and small size of the original BASIC programming language, it was widely adopted in the late '70's and early '80's as the most common and prevalent language for almost all personal computers. Microsoft's first product was a BASIC interpreter for the Altair computer. Most personal computers of this era (the Apple II, TRS-80, Commodore-64, Timex Sinclair, and the original IBM PC) came with a BASIC interpreter included. Many dozens of books on programming in BASIC were also published during this era. Since this occurred before the advent of the internet and before CDROMS were widely available, most people typed-in BASIC programs that were published in books and magazines.
Most early BASIC interpreters had an interactive mode, where one could type simple commands and see results after hitting the "return" key. For instance, typing the commands:
LET A = 7
LET B = A + 2
PRINT B
would result in the console printing "9" (the result of 7 + 2)
These simple BASIC interpreters also had a stored program mode, where one would write a many line program, with each line numbered; be able to save the program and to run the program at a later time.
In order for BASIC to be a complete programming language it included statements to allow calculation, simple logic, input, output, looping and conditional branching.
Currently, the Basic programming language is used as the core of Visual Basic, Visual Basic for Application (VBA), and VBScript (or basicscript) for web page scripting.

2.0 Installation   (Up)

2.1 System Requirements   2.2 Loading HotPaw Basic Application   2.3 Installing HotPaw Basic Programs   2.4 Important Notes for cbasPad classic users   2.5 Important Note for new HotPaw Basic users

2.1 System Requirements  (Up)
PalmOS 3.0 or later (Palm III, Palm Vx, etc.) is REQUIRED.
The MathLib.prc (1.0 or 1.1) library is required. See: <http://www.probe.net/~rhuebner/mathlib.html> or
< ftp://ftp.rahul.net/pub/rhn/mathlib11.zip > .
The use of the SwitchHack extension for switching between the MemoPad and the HotPaw Basic interpreter is highly recommended.
2.2 Loading HotPaw Basic Application  (Up)
You can download HotPaw Basic from < http://www.hotpaw.com/rhn/hotpaw/ >
or from PalmGearHQ < http://www.palmgear.com/ >
HotPaw Basic will run in demo mode or trial mode for 30 days after first installation. Licenses for registered versions can be obtained at PalmGearHQ.
To prevent possible data loss, be sure to make backup copies of all your important data prior to installing and operating this application.

Install (the usual way), using the 3Com/Palm Install and HotSync utilities on a Windows or MacOS based PC, or using the linux pilot-xfer utility on a computer running linux or unix.
You can have both HotPaw Basic, and the older cbasPad Classic Tiny-Basic interpreter, installed on your Palm handheld at the same time; however cbasPad should be installed and run first if you want to share the ScratchPad.
2.3 Installing HotPaw Basic Programs  (Up)
Basic programs are text files or memos containing statements in the Basic language. The HotPaw Basic application can run Basic programs whose text is contained in memos of the built-in Palm MemoPad.
If you have a HotPaw compatible Basic program on your desktop PC, you can copy and paste the Basic program text into the Desktop MemoPad application and HotSync. On a linux system, you can use the pilot-link install-memo utility to copy a short text file into your Palm MemoPad.
2.4 Important Notes for cbasPad classic users  (Up)
HotPaw Basic now runs programs from the MemoPad.
Many commands and functions have changed or been removed!
Some old cbasPad programs may be compatible; but one needs to test each program for compatibility.
2.5 Important Note for new HotPaw Basic users  (Up)
This manual assumes you already know a little about the classic BASIC programming language.

3.0 The HotPaw Basic Application - Orientation   (Up)

3.1 PalmOS Menu Items   3.2 PalmOS PalmOS Buttons

3.1 PalmOS Menu Items  (Up)
MAIN PROGRAM LIST VIEW
HotPaw Basic starts on its main page and displays available programs.
New    Opens ScratchPad.
Edit    Opens a selected program in whichever editing program it was written. If the program was written in ScratchPad, ScratchPad is opened. If it was written in MemoPad, MemoPad is opened.
Run    Runs a selected program.
Get Info    Displays Application Info
EDIT SCRATCHPAD VIEW
Go to top of page
   Move cursor to top of page.
Go to bottom    Move cursor to bottom of page.
Execute Selection    Run HotPaw Basic Interpreter on selected item.
Copy    Allows copying selected text to the clipboard.
Paste    Allows copying of text from the clipboard.
Delete Page    Allows deleting the current ScratchPad Page.
3.2 PalmOS PalmOS Buttons (Up)
MAIN PROGRAM LIST VIEW
New    In ScratchPad mode, starts a new scratchpad in the edit mode.
Edit    Allows editing the current program. Uses the MemoPad for editing programs that are contained in the MemoPad.
Run    Runs the selected program.
EDIT SCRATCHPAD VIEW
Done    When editing, exits to the Main List View. When executing a program, halts execution.
SelectAll    Selects all test in the current ScratchPad page.
Exec    Starts executing the currently selected text as a sequence of Basic statements.

4.0 Getting Started (Up)

4.1 Tutorial (Up)
Try entering a short Basic program into your Palm MemoPad.
Start a new Memo (in any category).
Any memo starting with the '#' character and ending with the 4 characters ".bas" in the first line will be recognized as a Basic program in the HotPaw Basic Show Programs selection screen.
Here's an example first line:

# My Example 1 .bas

Here's a short test program that will ask you to guess a number:
#guess_a_number.bas
x = 0
# set the variable "secret" to a number between 1 and 5
secret = 1 + rnd(5)
while (x <> secret)
input "Guess a number between 1 and 5", x
wend
display a$; " is correct!"
end
Switch to the Basic application. If there is not a border around a list of programs, use the menubar to select "Show Programs". If you can't see your new program, check the name to make sure it starts with a # and ends with .bas on the first line.
Select your program and hit the "Exec" button to execute it.
If you use the Hackmaster extension utility, then try using the SwitchHack extension to switch back and forth between Basic to the MemoPad application when writing and testing your Basic programs.
The "Show ScratchPad" is for small calculations that do not require any loops or subroutines. Just enter a list of equations and a print statement for the result, then the statements you wish executed, and hit the "Exec" button.

5.0 FAQs   (Up)

Q: How do I share my HotPaw Basic programs?  (Up)
A: Because HotPaw Basic programs are contained in MemoPad memo's as plain text, one can HotSync them to the desktop and email (or post on the web) the contents of these memo's as text files.
Q: Can HotPaw Basic compile stand-alone prc applications?  (Up)
A: No. A compiler is a completely different, much bigger, and far more complex application.
There are already a several compilers for Palm handhelds, among them Quartus Forth for on-board compilation, and Metrowerks Codewarrior for Palm for a complete Mac/Win hosted IDE.
HotPaw Basic is designed for people who want to be able to see and modify programs and scripts directly on their Palm handheld.
Q: What's the difference between HotPaw Basic and cbasPad?  (Up)
A: cbasPad classic was written as a spare time hobby in 1996 for USRobotic Pilot 1000's and 5000's running PalmOS 1.0 with only 128k/512k of memory. Some of the arithmetic and math routines built into PalmOS 1.0 which cbasPad classic depends upon, are neither reliable or accurate. Because of its design for the single segment restriction of PalmOS 1.0, cbasPad classic is no longer expandable. In spite of its limitations, cbasPad classic will remain free for non-commercial and non-mission-critical use on old PalmOS 1.0 devices.
HotPaw Basic was written to take advantage of Palm 3.x and has a more complete feature set and much more accurate math calculation capability.
Q: Where are the other FAQs?  (Up)
A: There are several Palm Platform related FAQ's on the Web.
Try these URL's:
< http://www.nicholson.com/rhn/palmfaq.txt >
<http://www.palmpilotfaq.com/>

Section II - HotPaw Basic Programmer's Guide (Top)

6.0 Writing Programs  7.0 Program Execution   8.0 Example Code  9.0 Example Programs  10.0 Some Warnings

6.0 Writing Programs (Up)

6.1 Overview   6.2 Syntax Tips

6.1 Overview (Up)
The HotPaw Basic language is mostly compatible with books on programming in the BASIC language that were published between 1977 and 1988. Since these books are mostly out of print, your best bet is to try your local public library. HotPaw Basic is a subset of the full Basic language; so some features present in a full version of the Basic language are not present. One key difference from "classic" BASIC programming is that line numbers are optional and not required in HotPaw cbasPad Basic (when running programs written in the MemoPad).
There is a fairly complete list of www pointers to information on the generic Basic language near the end of my 'Basic' web page at: <http://www.nicholson.com/rhn/basic/>
6.2 Syntax Tips (Up)
* You can write a Basic program in the built-in Palm MemoPad.
* Memos are limited to about 4000 characters in length.
* To create longer programs, one can use the
#include <#TITLE>
comment (pragma). HotPaw Basic will find a memo with the string "#TITLE" as its first line or at the beginning of its first line; and then insert lines from the found memo as in-line statements. This "include" pragma may not be nested.
* ALL keywords must entered in be lower case.
* Multiple statements may be used on one line when separated by the colon (":") character.
* All lines have a maximum length limit of 80 characters.
* Comment lines in HotPaw cbasPro Basic start with the '#' character.

7.0 Program Execution (Up)

( 7.1 Using MemoPad   7.2 Using HotPaw Basic ScratchPad   )

7.1 Using MemoPad  (Up)
How HotPaw Basic interprets text files stored in MemoPad.
* Unnumbered statements in the MemoPad are automatically given sequential line numbers incrementing by 1 from the previous line. Any numeric line number labels present should be in increasing order and differ by at least the number of intervening lines plus one.
* All statements after the first "run" command are ignored. A "run" command is automatically assumed at the end of a Basic program contained in the MemoPad.
* Program execution terminates after encountering the "end" statement.
* If you have a Basic program entitled "#startup.bas" (without the quote marks, of course) in your MemoPad, then you may use the included yLaunch.prc application to launch yBasic and automatically run your startup Basic program.
7.2 Using HotPaw Basic ScratchPad  (Up)
When and how to use the ScratchPad
* Use the ScratchPad most commonly for direct execution statements, e.g. calculations or sequences of statements that require no branches, loops or subroutines.
* One can write very short Basic programs in the ScratchPad, but with several limitations:
1) programs must start with a "new" statement and end with a "run" statement (without line numbers),
2) all other statements must have sequential and non-overlapping line numbers.
(This mode is primarily for backward compatibility with old cbasPad programs.)
* Execute statements in the ScratchPad view without line numbers by:
Select the statement you wish to have executed.
Hit the "Exec" button.
* Stop a running program by:
Hit the "Done" button or the Calendar application button.
* Stop a running program when an input dialog is present by:
Use the "Stop" menu item
* If you have a Basic program entitled "startup.bas" (without the quote marks, of course) in your MemoPad, then you may use the included yLaunch.prc application to launch yBasic and automatically run your startup Basic program.

8.0 Example Statements (Up)

# this is a comment line (because of the leading '#').
# multiple statements per line allowed.
x = 7 : y = 3 + 4
# a "?" statement prints 1 line to a dialog box.
? "hello ", 23+7
# Arrays must be dimensioned before use.
# Here's an example of a loop to initialize an array:
dim a(4) : for i=0 to 4 : a(i) = i : next i

9.0 Example Programs   (Up)

( 9.1 Loop and Print  9.2 Input and Display  9.3 Financial Calculation  9.4 Graphics  9.5 Database  9.6 Dynamic Button   9.7 Benchmark )

Here are a few example programs. Cut and paste these examples into your desktop MemoPad; then perform a HotSync operation to install them onto your Palm handheld. Make sure to cut after the "--" marks so that the Memo begins with a the pound sign character: "#".

Check with your Palm handheld MemoPad to make sure that the very first character in the Memo is a # character and that the last 4 characters on the first line of the memo end in .bas with no trailing spaces. Then the example program should then show up in the HotPaw Basic "Show Programs" display. If there is not a rectangle drawn around the display, select "Show Programs" from the HotPaw Basic menu. If the program does not show up, use the MemoPad to check the first line of the Basic program and make sure the first line was not changed, nor a new first line added, during the transfer process.
9.1 Loop and Print  (Up)
-- -- cut here -- --
# example 1 .bas
# enter this into the MemoPad and start yBasic
# prints a small "TIMES THREE" multiplication table
#
for i=1 to 4
print 3 * i,
next I
print
end

-- -- cut here -- --
9.2 Input and Display  (Up)
9.2.1 (this space left blank)  (Up)
9.2.2 Writing to the MemoPad  (Up)
-- -- cut here -- --
#memopad table .bas
open new "memo","trig table 1" as #4
m = db.index :' memo number
for d = 0 to 180 step 15
r = fn rad(d)
print #4, d,sin(r),cos(r)
next d
close #4
end

-- -- cut here -- --
9.2.3 MemoPad Read  (Up)
-- -- cut here -- --
#memopad table .bas
m = db.find("memo","trig table")
if (m < 0) then end :' not found
open "memo",m as #1
input #1,title$
input #1,a$
display a$ :' display 1st non-title line
close #1
end

-- -- cut here -- --
9.3 Financial Calculation  (Up)
-- -- cut here -- --
# loan payment .bas
# calculates loan payments
for i=0 to 17:s$(i)="":next I
s$(0)="Principal"
s$(2)="Years"
s$(4)="Interest %
s$(6)="Periods/Yr":s$(7)=12
L50:
j=form(9,5,"Payment Calc")
if (j=0) then end
i=(val(s$(5))/100)/val(s$(7))
p=val(s$(1))
n=12*val(s$(3))
a=fn pmt(p,i,n)
a$=str$(a,8,2)
s$(8)="Payment"
s$(9)="$"+a$
goto L50
end

-- -- cut here -- --

9.4 Graphics (Up)
-- -- cut here -- --
# circle demo .bas
draw -1 :' clear screen
cx = 80 : cy = 80 :' set center
r = 30 :' set radius
moveto cx+r,cy
for a = 0 to 6.28 step 0.1
x = cos(a)
y = sin(a)
lineto cx+r*x, cx-r*y
next d
w = fn pen(0) :' wait for tap
end

-- -- cut here -- --

9.5 Database (Up)
Create and explore a new database.
-- -- cut here -- --
# db new+find .bas
# create a new DB database
# fill it with 5 records
# and search for 1 item
f$ = "test-db-1"
mydb=open f$ as new "DBOS",4
if mydb<0 then end
d=fn days(fn date$(0))
for i=0 to 5
# make up some fields
s$(20)=chr$(asc("A")+i) +"2"
s$(21)=right$(fn date$(d+i),4)
s$(23)="00" + str$( i)
s$(22)=str$(timer)
put mydb,i,104
next I
# now find a record
j=db.find(f$,"C")
if j >= 0 then
rem # get 2nd field
a$=get$(mydb,j,2)
endif
# display found item
? j,a$
end

-- -- cut here -- --
9.6 Dynamic Button (Up)
-- -- cut here -- --
# mybutton.bas
draw -1
form btn 60,80,40,12,"DoIt",1
form fld 60,120,80,12,"Nobody",1
draw "Enter your name",60,100
x = asc(input($1)) "'wait for button
? "Your name is ",s$(0);"."
end
-- -- cut here -- --

9.7 Benchmark (Up)
-- -- cut here -- --
# sieve.bas
# prime number sieve benchmark
# from Byte magazine 1984
new
20 t = fn 17
25 s = 8192 : rem full size
30 dim f%(s+2)
40 for i = 0 to s-1 : f%(i) = 1 : next I
50 c=0
60 for i = 0 to s-1
70 if f%(i) = 0 then 110
80 p = i+i+3 : if i+p > s then 100
90 for k = i+p to s step p : f%(k) = 0 : next k
100 c = c+1
110 next I
120 ? c ; " primes found in " ;
130 t =(fn 17)-t : t=t/100
140 ? t ; " seconds"
150 end
run

-- -- cut here -- --

10.0 Some Warnings (Up)

Remember that the s$() array can be modified by db and form commands.
Divide by 0 errors are not trapped, the return "NaN" (not a number).

Section III - HotPaw Basic Language Definition (Top)

( 11.0 Synopsis  12.0 Description  13.0 Flags  14.0 Conventions  15.0 Basic Basic  Palm O/S Stuff   16.0 PalmOS Interface Commands  17.0 PalmOS Database Commands  18.0 PalmOS Scripting Commands  19.0 Macintosh Commands )

A much more complete HotPaw Basic BASIC language reference is located here:
< http://www.hotpaw.com/rhn/hotpaw/language_manual.txt >

11.0 Synopsis (Up)

HotPaw Basic Programs are executed by the HotPaw Basic programming language interpreter (a PalmOS application). To run, start the HotPaw Basic application, select a program written according to the HotPaw Basic language description, and tap the "Execute" button. HotPaw Basic Programs contained in the MemoPad must begin with the "#" comment character and the first line must end with the string ".bas". 

12.0 Description (Up)

See below for the BASIC language commands and statements that the interpreter recognizes. See the README file for tutorial and PalmOS specific commands and functions.

13.0 Flags (Up)

None

14.0 Conventions (Up)

EXPR     An expression that evaluates to a numeric value.
STRINGEXPR     A string expression.
VAR     A numeric variable.
STRINGVAR    A string variable. Name must end with a "$"
INTEGERVAR    A 32-bit integer var. Name must end with a "%".
Subroutine names starting with "fn" are reserved for the built-in fn and def fn functions.
Hexadecimal numbers can be entered by preceding them with a "0x" as in 0x02ae, or by "&h" as in &h0172.
Multiple statements may be given on one line, separated by colons:
10 INPUT X : PRINT X : STOP

15.0 Basics of the BASIC language (Up)

15.1 Operators  15.2 Commands and Statement Keywords  15.3 Functions  15.4 Special Functions and Commands  15.5 Variables and Constants  15.6 Expressions and Operators  15.7 Flow of Control Statements 

15.1 Operators (Up)
+, -, *, /, mod, ^, =, <>, >, >=, <, <=, and, or, xor, not, &
15.1.1 Arithmetic
+ - * / mod ^
15.1.2 Logical
= <> > >= < <= and or xor not &
15.2 Commands and Statement Keywords (Up)
A much more complete reference to BASIC language statements is located here:
< http://www.hotpaw.com/rhn/hotpaw/language_manual.txt >
data, dim, else, end, endif, for, gosub, goto, if, let, new, next, read, rem, restore, return, run, step, then, to, wend, while
15.3 Functions  (Up)
abs(), acos(), asc(), asin(), atn(), bool(), chr$(), cos(), exp(), field($), hex$(), instr$(),int(), lcase$(), left$(), len(), log(), log10(), mid$(), right$(),rnd(), sgn(), sin(), sqr(), str$(), tan(), ucase$(), val()
chr$(c) Returns string of ascii char c, length 1
exp(x)    e ^ of x
hex$(n)    Returns hex string of value n
int(x    Truncates toward zero.
len(a$)    Returns length of string a$
log(x)    Natural log of x
log10(x)    Log base 10 of x
mid$(a$, n, m)    Returns substring of a$ starting at n length m
rnd(n)    Returns a Pseudo random integer in the range 0..n-1
sin(x) cos(x) tan(x) atn(x)    Trig functions for x in radians
sqr(x)    Square root of x
str$(x)    Returns string representation of x
val(a$)    Returns numeric value of a$ or 0
round(x)    Rounds to nearest integer.
round(x,d)    Rounds to d places right of the decimal point.
round(x,0,n)    Rounds to about n significant digits.
str$(x,n)    Returns string padded to n characters
str$(x,n,2)    Returns n char string with 2 decimal places
fn str$(x,1,14)     Returns double precision (15 decimal places) conversion to string (exponential notation).
mid$(a$, n, 1)    Returns a single character out of a$
field$(a$,n, "," )    Returns the Nth field (comma seperated)
instr(a$, b$)    Finds b$ in a$ or returns 0 for not found
fn strw(a$,n,0)     Returns width in screen pixels of the 1st n chars of a string
fn trim$(a$)     Trims off leading and trailing white space. Returns trimmed string.
15.4 Special Functions and Commands (Up)
display, as, call, close, db$(), draw, end sub, oef, eval(), find(), float(), fn, form, fre, get$(), input, input$(), inputbox, kill, morse, msgbox, on, op, open, peek$(), peek(), poke, print, ?, put, sound, sub(), timer, using, varptr()
fre    Returns amount of dynamic heap memory left
timer    Returns running seconds timer
timer(100)    Returns running tickcount timer (100ths of a second on a Palm III)
15.5 Variables and Constants  (Up)
15.5.1 Constants

Hex constants may be entered by preceding with "0x".

Floating point constants may use the "e" notation, e.g. -2e3, 6.022e23, 6.6261e-34
Floating point numbers and variables are represented by a format similar to IEEE double. This is a binary format, which means that many decimal fractions will not be exactly represented.
16.5.2 Variables

Variable names may be up to 15 characters in length.
Integer variable names must end with the '%' character.
String variables must end with the '$' character.
There is a limit of 63 string variables.
String arrays must be dimensioned before use (except s$() and r$()). String arrays are limited to one dimension and may not be redimensioned.
There are 2 built-in string arrays: r$() and s$(), both auto-dimensioned to 64 elements: e.g. r$(0)...r$(63).
The string array S$(0) to S$(63) is for passing parameters and for temporary use by many of the built-in database, dialog, display and code resource functions and commands.
15.6 Expressions and Operators  (Up)
Assignment
let a = b + 2
Using the "let" keyword before an assignment is optional.
Example: a = b + 2
Complexity
Arithmetic expressions are limited in complexity to around 8 levels of parenthesis so as to not overflow the very small PalmOS application stack.
Example: a = (b^2 + (d/(2+2))) * c
"and", "or", "xor" and "not"
"and", "or" and "xor" operators do bit-wise operations.
"not" is a boolean operator and only returns 1 or 0.
"amp;"
Use the "&" or the "+" operator for string concatenation.
Example: a$ = "hello "
Example: b$ = a$ & "there!" ' -> result "hello there!"
15.7 Flow of Control Statements  (Up)
end, if then endif, Multiline block IF ENDIF, Standard BASIC subroutine usage, Named subroutines usage, goto, on goto,
:     A colon may be used to separate multiple statements on one line.
end     Program execution ends at the first end command.
if then endif
Standard single line IF THEN
Example:
if x > 1 then y = 2
if y = 3 then goto 300
Multistatement IF THEN (acts as a single block if-endif)
Example:
if x > 1 then 6 = 2; z = 3
Multiline block IF ENDIF (No "then" keyword used.)
Example:
if (x > 1)
y = 2
z = 3
endif

for step next
#Example:
for i=1 to 5 step 2 : print i : next I
while wend
#Example:
n = 1
while (n < 100) : rem - loop until this condition is false
n = n * 2
wend
print n
gosub sub return
Standard BASIC subroutine usage
Example:
100 gosub 500
200 end
...
500 print x+1
510 return
Named subroutines usage
Example:
gosub foo(5)
end
sub foo(x)
print x+1
end sub
(Note that HotPaw Basic user-defined subroutines are static (no true local variables), and may not be used recursively. The name of a user-defined subroutine may be used as a global return variable.)
goto N on N goto M     No example. (Old syntax. See BASIC programming books.)
labelx:
goto labelx
No example. An initial variable name followed by a colon is a label that can be used as a target by a GOTO statement. This allow using GOTO statements in programs without using line numbers.

16.0 PalmOS Interface Commands and Functions  (Up)

16.1 Output Commands  16.2 Input Functions  16.3 Dialog Form Functions  16.4 Math Functions  16.5 Date and Time Functions   16.6 Financial Functions   16.7 Graphics Commands  16.75 Advanced Form Statements  16.8 Sound Commands  16.9 Serial Port Commands   16.14 Miscellaneous Commands

16.1 Output Commands (Up)
msgbox(message$ [ , title$ [ , n ] ] )
Displays a message box with a message string. If n = 2 then display "OK" & "Cancel" buttons. The test message will word-wrap up to 2 lines.
msgbox(line1$ + chr$(10) + line2$ [...] )
Displays 2 lines (up to 3 lines are possible) separated by linefeeds (hex 0x0A).
print x,y     Display x and y in a message box.
?     Same as PRINT command (for compatibility with old programs)
16.2 Input Functions (Up)
fn pen(0), fn pen(1), fn pen(2),fn pen(3), fn pen(4), fn pen(5), get$("data",n), inkey$, input [ prompt$ , ] stringvar$, input$( prompt$, [ title$ [ , n ] ] ), input$(1), input$(1), return 0, val(input$(prompt$))
input [ prompt$ , ] stringvar$    uses input$() dialog to LINE INPUT 1 string (for compatibility with old programs)
input$( prompt$,[title$[ , default$ ] ] )
input$( prompt$, [ title$ [ , n ] ] )    Displays input dialog & Returns input string. If n = 1 then only display "OK" button. If n = 2 then display both "OK" & "Cancel". Use val(input$(prompt$)) to input a number
input$(1)     Waits for 1 graffiti char or button press; captures presses on the rightmost 5 button (11 up, 12 down, 5,6,7 = 3 app buttons). Leftmost app button halts interpreter.
Use val(input$(prompt$))    to input a number.
inkey$    Checks for 1 graffiti char or button press
nonblocking, returns "" for no input
fn pen(0)    Waits for a pen tap (blocking); returns x
fn pen(1)    Returns last pen x coordinate
fn pen(2)    Returns last pen y coordinate
fn pen(3)    Returns tickcount time of last pen tap
fn pen(4)    Returns non-zero if the pen is still down
fn pen(5)    Waits for a display tap, key or graffiti char
get$("data",n)    Returns line from current program page with "#" comment character stripped
16.3 Dialog Form Functions (Up)
form(0)     Returns last msgbox or dialog button status; also clears the button status to 0.
form(9,n,title$)     Displays n line 2 column form from 2 to 9 lines
S$(0), S$(2) ... are the prompt strings
S$(1), S$(3) ... are the default & return values. Return value is 1 for OK, 2 for A button, 3 for B button
form(10,n,title$)     Displays n line single column form
s$(0), s$(2) ... will display text, 1st line bolded
if s$(0) is empty, s$(1) will display as an input field
form(12,0,title$)     Displays 2 column form (with 8 rows) with a calculator keypad
s$(0), s$(2)display text at the top and bottom
s$(2), s$(4) ... are the prompt strings
s$(3), s$(5) ... are the default and return values
return values are 0 for Done, 1 for OK, 2 for Calc button, and 3 for Calc2 button
16.4 Math Functions  (Up)
16.4.1 Numeric Functions
atn(x,y)     4 quadrant arctan,
only if MathLib is present. Mathlib.prc should be installed for accurate transcendental functions.
fn deg(r)    Converts radians to degrees
fn rad(d)     Converts degrees to radians
fn snorm(x)     statistics library function. returns the standard normal integral (-inf to x). This function is only available if the bcmdsnorm.prc bcmd-extension is installed.
16.4.2 String Functions
ucase$(a$)    Returns uppercase string
lcase$(a$)    Returns lowercase string
right$(a$,n)    Returns the right justified substring of a$
left$(a$,n)    Returns the leftmost n char substring of a$
eval(q$)    Evaluates string q$ as a numeric expression ("1+2")
16.4.3 Arrays
Arrays must be dimensioned before use (except s$() and r$()).
String arrays are limited to one dimension.
Numeric arrays must be dimensioned before use with the DIM statement. Numeric arrays are limited to two dimensions.
    dim a(10), b(10,10)
16.5 Date and Time Functions (Up)
fn date$(0) Returns todays date as 8-digit string, e.g. "19991225"
fn date$(0,1)    Returns todays date as in text form, e.g. "Dec 25, 1999"
fn date$(-1)    Returns 8-digit string result from date chooser
fn time$(0)    Returns 6-digit time string, e.g. "120000"
fn time$(-1)    Results from time chooser dialog
fn days(m)    Converts 8-digit date number to days from 1904
fn days(d$)    Converts 8-digit date string to days from 1904
fn dayow(n)    returns day-of-week (1=Sunday) from 8-digit date
fn date$(n)    Converts days from 1904 to 8-digit string
fn wait(n)    Delays n seconds (uses 0.02 second increments).
returns > -1 if a screen tap occurred before timeout.
fn sleep(n)    Sleeps for between n & n+60 seconds (n >= 120).
returns approximate seconds elapsed
16.6 Financial Functions (Up)
fn pmt(p, r, n)     Calculate payment, given principle, interest% and number of periods
fn pv(a, r, n)    Calculate present value
fn fv(a, r, n)    Calculate future value
16.7 Graphics Commands (Up)
draw -1 Clears the middle of the display
draw x1,y1,x2,y2,1     Draws line on display [0..159]
draw x1,y1,x2,y2,2    Draws gray line
draw x1,y1,x2,y2,-1    Erases a line
draw x1,y1,x2,y2,4    Draws rectangle (topLeft, extent)
draw x1,y1,x2,y2,5    Draws gray rectangle
draw x1,y1,x2,y2,7    Draws filled rectangle
draw x1,y1,x2,y2,-7    Erases rectangle
draw circle x1,y1,r    Draw circle of radius r
draw circle x1,y1,r,7    Paint a filled circle
moveto x1,y1    Sets current pen location to x1,y1
lineto x2,y2    Draws a line from current loc to x2,y2
draw t$, x,y [,f]    Draws text t$ (optionally with font f)
draw t$, x,y, 32     Draws text using SingleHander jumbo font. This requires installation of the singlehand.prc app
fn colord()    Returns the color depth available or 0 for PalmOS versions prior to 3.5
fn colord(n)    Where n = 1,2,4 (& PalmOS >= 3.5 only) sets grayscale depth to n if possible. Returns prior depth
fn scrn(x,y,k)    Returns index, r, g or b value of screen pixel at (x,y) for k = 0, 1, 2 or 3 respectively under PalmOS 3.5 or later.
draw x,y, w,h, 100,a$(0)    Draws a 1 bit/pix bitmap.
w & h must be less than or equal to 32. Bitmap described row-wise by hex strings which are contained in string array a$(0) .. a$(n). Bitmap strings must be multiples of 4 in length and the beginning of each row is byte aligned.
draw x,y, 0,k, 400,s$    Draws resource ('Tbmp') bitmap bitmap with resource ID k contained in the prc or app named by the variable s$. Draws nothing if prc or resource is missing.
If you have the new PalmOS 3.5 color ROMS:
draw color r,g,b,c    Sets the foreground color for c = 1, background color for c = 2, text color for c = 3, r,g,b for red green blue respectively [0 thru 255]
draw color i,-1,0,c    Sets the color by color index [0-255]
fn rgb2i(r,g,b)     Returns color index of nearest RGB color
draw circle x1,y1,r,a1,a2    Paint a filled arc from a1 to a2 radians
fn test(-100)    Returns PalmOS version or highest version supported (e.g. 3.1, 3.5 ...) or negative for old non-color yBasic
16.75 Advanced Form Statements  (Up)
Dynamic objects (buttons, field, checkboxes) should only be added near the beginning of a program (after a "draw,-1" statement) and before any user interaction (print or input). Form buttons should be created before any other form items. There is a limit of 15 form buttons, 2 pop-up list and 32 total form items. The total amount of list selections among all pop-up lists is 63.
See the "#counter.bas" example program, which uses both form commands to create buttons, and database commands to save data between program runs.
Use "draw -1" to clear the form before adding any dynamic objects.
Draw text and graphics only when done creating all form items.
Dynamic objects will change the behavior of the current running main Basic program form. Form statements may only be used in a program contained in a Memo or run from a program select view.
Form statements will produce an error message when run from the ScratchPad Edit view.
** Warning: The use of dynamic forms under PalmOS 3.0 and earlier is NOT recommended by Palm. These commands have only been tested under PalmOS 3.1 and later. **
form btn x,y,w,h, title$, 1 Creates one button x,y location. w,h width & height.
fn btnkey()     Returns ascii keycode of last form item. The first button returns 14 to "form(0)" or ascii key chr$(14) to the "input$(1)" function. Note that if you use the "form btn" statement more than once, for instance in a loop, you will get multiple buttons that will return different key codes. Use "fn btncode()" to get the keycode for that new button.
form fld x,y, w,h, default$, 1     Creates a text input field. w is in pixel units, h is normally set to 12
form cbx x,y, w,h, "", 1    Creates a 14x14 checkbox. w&h are dummy parameters. First field or checkbox returns a string in s$(0) after a form btn press. Second field or checkbox returns in s$(1), etc.
form lst x,y, n,sel, a$, 1     Creates a pop-up list with trigger at x,y. n is the number of items in a list ( < 31 ). a$ must be a dimensioned array larger than n the 1st list element is taken from a$(1). sel is the initially selected item number. Form fields, checkboxes and lists return their value in array strings s$(0) thru s$(19) after any form button is pressed. s$(0) gets the value of the first field created, s$(1) the next, etc...
form title 0,0,0,0, newtitle$,1     Changes form title to the string newtitle$
form redraw 0,0,0,0, "", -1     Erases all graphics except for form objects.
form reset 0,0,0,0, newtitle$, -1     clears all dynamic objects from dynamic form and resets initial btnkey count to 14
form btn 0,160,0,0, qbtn$, 1     if qbtn$ is less than 6 characters in length changes the title of the "Quit" button to the contents of qbtn$, and sets that buttons keycode to ctrl-c (ASCII 0x03)
16.8 Sound Commands (Up)
sound f,d,v    { f = frequency in Hz }, { d = duration in mS }, { v = volume 0..63 }
morse string$, wpm, freq, vol, [ cwpm ]    { wpm = words per minute code speed }, { cwpm Farnsworth }
16.9 Serial Port Commands  (Up)
Warning: Using serial port I/O will drain the battery much faster than normal.
open "com1:", baud_rate as #5   Sets baud_rate { 2400..19200 }
open "com1:",rate,ir as #5   Opens serial port in SIR Ir mode. The serial port only stays open during a program execution, and is automatically closed at the end of a program or "exec selection".
open ... #5 else label   goto statement@label on open error
open "PalmPrint: for output as #5    Enables Stevens Creek Software print server.
close #5   Closes serial port
fn serial(5)   Returns number of input bytes waiting
input #5, a$   Waits for 1 line of text
get$(#5, 0)   Returns 1 ascii byte from serial port, or returns -1 if no input is waiting
get$(#5, n)   Returns a string up to n bytes long
print #5, a$   Prints to serial port
put #5,byte   Serial output one byte
put #5,-3    Start break.
put #5,-2    Stop break.
fn serial(-5)    Get CTS (2) and DSR (1) status.
fn serctrl(7,2,0)    Sets 7 bits, even parity, return 0.
Only descriptor #5 is recognized for serial port use.
The serial port only stays open during program execution, and is automatically closed at the end of a program or "exec selection".
16.14 Miscellaneous Commands  (Up)
fn linenum(label)     Returns line number for any label. This is very useful when trying to debug.
fn battery()   Returns scaled battery voltage (V*100)
fn p(18)   Returns memory address of the clipboard text
fn p(19)   Returns length of the clipboard text
fn p(36)   Returns current memo get$ offset
fn p(66)   Force warm reset of PalmOS
fn p(67)   Relaunches the HotPaw Basic interpreter application
fn ftr(sig$, n)    Reads Feature Manager long int.
Warning: Use of undocumented fn or fn p() numbers may cause your Palm to crash or Corrupt data.

17.0 MemoPad and Database Commands  (Up)

( 17.1 MemoPad Access 17.2 DB Database ('DBOS') 17.3 List Database ('LSdb') 17.4 JFile Pro('JFil') 17.5 JFile ('JBas') 17.6 HanDBase ('PmDB') 17.7 MobileDB ('Mdb1') 17.8 Aportis Doc Text ('REAd') 17.9 General Database Functions )

17.1 MemoPad Access  (Up)

( 17.1.1 MemoPad Access Commands 17.2 MemoPad Access Functions )

17.1.1 MemoPad Access Commands  (Up)
open "memo",n as #1     Opens memo number n for r/w #1 thru #4 are legal file nos. Use db.find to get n from title$
open new "memo",title$ as #4     Creates and opens new memo. The title string must not be blank.
db.index    Returns the new memo index number
print #4, x$    Appends to open memo. Memos are limited to 4k characters. Use db.len to check for truncation    
input #1, a$    Inputs one line from open memo
close #1    Kill "memo",(db.find("memo"),n,-9. Deletes memo n
chain n    runs Basic program in memo index n. Does not clear variables. Use db.find("memo", title$) to find n. n must be greater than 0. Use fn launch() to start other applications.
Only descriptors #1 thru #4 are allowed for MemoPad files.
17.1.2 MemoPad Access Functions  (Up)
db.find("memo", t$)     Finds memo with title t$, returns index; searches in reverse order, so always finds last/latest
db.find("memo", t$, 0)     Searches in forward order
db.len("memo", n)    Returns length of memo #n
db$("memo", n, 0)    Returns first line of memo #n
db$("memo", n)    Returns the next line or memo #n
db$("memo", n, k)    Returns text at byte offset k
eof    Returns true if last input or db$ read was past end of memo
fn newcat(n)    returns 0. Sets the category of the next new record or memo to category number n.

Note that the level of support varies for each type of database listed below.

17.2.0 DB Database ('DBOS') Access  (Up)

( 17.2.2 Reading From Database Field 17.2.3 Searching 17.2.4 Modifying A Database Field 17.2.5 Adding Records 17.2.6 Creating New Database )

The DB application is a Free Open Source database for the PalmOS, ctype = "DBOS",
found at: < http://vger.rutgers.edu/~tdyas/pilot/ >

17.2.2 Reading From DB, List, JFile Pro, JFile, HanDBase or MobileDB Database Field  (Up)

db$(dbname$, r, f)    Returns field f of record r first record has r = 0. Only returns first 63 characters of any longer fields. This function may modify s$(20) thru s$(29)
db$(dbname$, r, f, z)    If field f of record r is longer than z characters then returns up to 63 characters of field f starting with the z-th byte (offset).
db$(d, r, f)    Returns field f of database index d. Database d must be opened first.

17.2.3 Searching a DB, List or JFile Pro Database  (Up)

db.find(dbname$, x$)    Finds x$ in first record of database dbname$. Returns -1 for failure
open DATABASE_NAME$    Open for r/w
db.index    Returns last opened db index

17.2.4 Modifying a DB, List, JFile Pro or HanDBase Database Field  (Up)

let db$(dbname$, r, f) = x$    Modifies 1 field of a database, record r. Field f this statements may modify s$(20 thru 39). The LET keyword is optional.
let db$(d, r, f) = x$    ...with database id #d. r must be in range and d must be open

17.2.5 Adding Records to DB Databases  (Up)

It is up to your program to make sure that you only add records of the proper format. Only text fields are currently supported.
put d,new,(n)    Adds a new db record with n fields taken from s$(20) thu s$(20+n), (max of 19 fields usable).
db.index    Returns new index.

17.2.6 Creating New DB ('DBOS') Database   (Up)

db.open dbname$ as new "DBOS",n    Creates a new DB database with n fields per record
db.open ... else label    Goto statement@label on open error
db.index    Returns last created or opened db index.
Only one new database can be created and accessed at a time. Creating a new database will close all other databases. Therefore any new database should be created before opening any other databases for access.
kill dbname$,dbindex,-99,-9 '- deletes database    Index must match database name

17.3.0 List Databases (type 'LSdb')  (Up)

( 17.3.2 Reading From List Database Field 17.3.3 Searching List Databases 17.3.4 Modifying A List Database Field 17.3.5 Adding Records to a List Database 17.3.6 Creating a New List ('LSdb') Database )

List is a Freeware 3 column database application, ctype = "LSdb",
found at: < http://www.magma.ca/~roo/list/list.html >
The level of support varies for each type of database. HotPaw Basic can create new databases of ctype "LSdb".

17.3.2 Reading From List Database Field  (Up)

See above ( Reading From Database Field)

17.3.3 Searching List Databases  (Up)

See above ( Database Searching)

17.3.4 Modifying A List Database Field  (Up)

let db$(dbname$, r, f) = x$    Modifies 1 field of a database, record r. Field f this statements may modify s$(20 thru 39). The LET keyword is optional.
let db$(d, r, f) = x$    With database id #d r must be in range and d must be open
If the database is of ctype "LSdb" then the above statement will work only if all fields are shorter than 63 characters.
Warning: Any longer fields in the List database record modified may be silently truncated.
db.len(dbname$, -16)    Returns count of non-deleted records in database. Note that deleted records may appear in the middle of some databases.

17.3.5 Adding Records to List Databases  (Up)

put d,new,103 Adds a new db record with n fields taken from s$(20) thu s$(23)

17.3.6 Creating New List ('LSdb') Database  (Up)

db.open dbname$ as new "LSdb",3    Creates a new List database with 3 fields per record.
db.index    Returns last created or opened db index.
Only one new database can be created and accessed at a time. Creating a new database will close all other databases. Therefore any new database should be created before opening any other databases for access.

17.4 JFile Pro (JFil)  (Up)

JFile Pro is a shareware database application, ctype = "JFil". Only reading this database format is currently supported.

17.4.1 Reading a JFile or JFile Pro database field:

See above ( Reading From Database Field)

17.4.2 Searching a JFile Pro database

See above ( DB Database Searching)

17.4.3 Modifying a JFile Pro database field:

See above ( Modifying A Database Field)

17.5.0 JFile  (Up)

JFile is an obsolete database application, ctype = "JBas",
found at < http://www.land-j.com/pilprogs.html > See JFile Pro for a newer application from this author.

17.5.4 Adding JFile database records

It is up to your program to make sure that you only add records of the proper format. Only text fields are currently supported.
put d,new,(n) Adds a new db record with n fields taken from s$(20) thu s$(20+n), (max of 19 fields usable).
db.index    Returns new record index.

17.6 HanDBase  (Up)

HanDBaseis a commercial database application, ctype = "PmDB".
HanDBase databases are supported by calling code in the actual HanDBase application. If a registered copy of the HanDBase application is not installed, HotPaw Basic commands to access HanDBase databases will fail.

17.6.1 Reading a HanDBase field:

See above ( Reading From Database Field)

17.6.4 Modifying a HanDBase Database Field

See above ( Modifying A Database Field)

17.7 MobileDB  (Up)

MobileDB is a Commercial database application, ctype = "Mdb1". Only field reads are supported for MobileDB databases. Note that for MobileDB databases, the actual data records start with record number 4.

17.6.1 Reading a MobileDB database field:

See above ( Reading From Database Field)

17.8 Doc format text  (Up)

For Doc format text databases (Aportis "Doc" format, ctype 'REAd'):
db$(d, r, k)     Reads a string from record r starting at offset k. Uncompresses compressed Doc format text.
A max of 63 characters at a time can be read. Record number r must be greater than 0. Returned string may include a CR or LF at the end. Sets eof if k is past end of record. Use db.find() to get database index d.

17.9 Misc. Database Functions  (Up)

db.open name$     Returns access index for named database or returns -1 for not found.
db.len(dbname$)     Returns number of records in database.
db.len(dbname$,r)     Returns length in bytes of record r.
db.find(dbname$)    Returns db index# of named database
db.len(dbindex)    Returns number of records in database #
db.len(dbindex,r)    Returns length in bytes of record r
db.peek(dbindex, r, n, 1)    Returns byte n of record r
db.peek(dbindex, r, n, 64)     Returns string starting at byte offset n
    Returns a string resource with resource the given resource id number.
The database referenced by dbindex must be a resource database (e.g. from a .prc file).
err    Returns a negative number if any database open or read errors occur.
err(0)    Returns error code and then clears it.

18.0 PalmOS Scripting Commands (Up)

find("date", 0, 19991225 )    Finds 1st DateBook record on Dec 25, 1999
find("date", -12, 19991225)    Finds subsequent DateBook records on given date. Use val(fn date$(0)) for today's date
get$("date", n, 10)    Reads DateBook record #n into s$(20 thru 29)
s$(20)    title
s$(21) = year
s$(22) = month
s$(23) = day
s$(24) = hour (blank for "UnTimed")
s$(25) = minute
s$(26) = ending hour
s$(27) = ending minute
s$(28) = alarm minutes (0 for no alarm)
s$(29) = first 63 characters of note
put "date",new,10 Creates new DateBook entry from data in s$(20..29)
find("todo", title$, n)    Finds ToDo record with given title starting search with record n. Return -1 for none found.
find("todo", -11, d)    Finds 1st ToDo record matching 8-digit date d
find("todo", -12, d)    Finds subsequent ToDo's matching 8-digit date d
find("todo", -13, d)    Finds 1st undone ToDo record due on or before d
find("todo", -14, d)    Finds subsequent undone ToDo's due
find("todo", -16, n)    Finds ToDo record modified since last HotSync starting search with record n
get$("todo", n, 10)    Reads ToDo list record #n into s$(20 thru 29). s$(20 will contain "error" if the ToDo is not found.
s$(20) = description (up to 63 characters only)
s$(21) = year (or blank for no Due Date)
s$(22) = month
s$(23) = day
s$(24) = priority
s$(25) = done
s$(26) = category number
s$(27) = category name
s$(29) = first 63 characters of note
put "todo", new, 10    Creates ToDo entry from data in s$()
put "todo", n, 10    Modifies ToDo record #n modifying only non-blank fields in s$(20..29). A category number will override any category name.
WARNING:    The order of records (possibly every record number( is changed in the ToDo database when any ToDo record is changed or modified. So you can't just loop through the ToDoDB by record number.
get("addr", n, 20)     Reads Address Book record entry #n into s$(20..39)
fn.launch(app$, n)    Launch application by app Creator or appname. Use -1 for no data index, e.g. i=fn launch("lnch", 01) to return to Launcher

18.0 Macintosh Chipmunk Basic Compatible Commands  (Up)

moveto VAL, VAL    Sets the (x,y) location of the graphics pen.
lineto VAL, VAL    Draws a line from the current pen location to location (x,y) in the graphics window.
sound VAL, VAL, VAL    The parameters are: frequency{in Hz}, milliseconds_duration, volume{0..63}

Appendices

Appendix 1 - Reserved Words and Symbols   Appendix 2 - Unimplemented ISO/ANSI Minimal Basic Standard Keywords   Appendix 3 - Diagnostics  Appendix 4 - Advanced Topics   Appendix 5 - Changes  Appendix 6 - Bugs

Appendix 1 - Reserved Words and Symbols  (Up)

+ - * / ^ mod and or xor not > < >= <= = () sqr log exp sin cos tan atn abs sgn int rnd val asc len mid$ right$ left$ str$ chr$ lcase$ ucase$ goto if then else endif gosub return for to step next while wend select case rem let dim erase data read restore field$ input print open for output append as close# load save random lof loc get put inkey$ input$ eof files fgetbyte# fseek# fputbyte run stop end exit quit cont renum new clear date$ time$ timer sound morse say doevents home cls gotoxy htab vtab pos graphics sprite pset moveto lineto window scrn mouse varptr peek poke fre push pop isarray sub call usr def fn type class extends string integer single double asin acos sinh cosh tanh log10 floor true false ubound eqv imp static option degrees radians redim do loop until break method private public local menu dialog memstat() draw play bload bsave min max mat each resume function key is each set width swap db$ morse dialog msgbox

Appendix 2 - Unimplemented ISO/ANSI Minimal Basic Standard Keywords  (Up)

option base [ 0 | 1 ]    (default sets array lower bound to 0)
tab   (this command is not implemented)
def fn    (this command is not implemented)

Appendix 3 - Diagnostic and Error Messages  (Up)

Error Message Details

Out of Memory Too long a program. Too large an array. Too many variables.
Out of string memory Too many string variables. Too large a string array.
Line number too big Line number greater than 30000.
Line number duplicated Duplicate line number. Too many lines between numbered lines. Unwanted line break in a program line (creating an extra line number.)
Unsupported subroutine call Subroutine call inside an expression.
Undefined line or subroutine Subroutine target not found
Out of Data Read statement without enough data statements
IF without ENDIF or THEN Missing statement.
Missing THEN error Missing statement.
Missing ENDIF Missing statement.
Missing GOSUB RETURN found outside of a called subroutine
Unsupported index var Label, string variable or constant as FOR index.
Missing FOR NEXT found without a matching FOR statement.
FOR w/o NEXT
WHILE without WEND

WEND without WHILE Missing loop control statements.
Syntax error Miscellaneous errors in statement syntax.
Type mismatch error String/numeric parameter mismatch
Subscript err Missing subscript. Subscripting a non-array variable.
Nesting error Expression too complex. Too many parenthesis.
Program line too long Program line longer than 80 characters.
Include file not found #include <> pragma with incorrect memo title or spelling.
ScratchPad programs require line numbers and a 'run' command. LOOP or GOSUB was found in direct execution mode.
Missing return, next or wend Program ended inside a loop or subroutine.
Form item error Too many buttons, fields or checkboxes. Attempting to recreate a previously created button. Running a From statement from the ScratchPad Edit view.
Only #5 available for serial
Only #5 available for printer OPEN #5 ... statement used with a number other than #5.
Out-of-range error
Database not open Database not opened for write. Database closed by prior database or memo creation statement.
Many errors are unreported.

Appendix 4 - Advanced Topics   (Up)

( A4.1 Advanced Functions  A4.10 features  A4.6 Example Programs )

Advanced functions:
varptr(y)    Returns memory address of variable y (or y$)
peek(a)    Returns the 8-bit byte at address a
peek(a,2)...    16-bit value at word aligned address a
peek(a,4)...    32-bit value at word aligned address a
peek$(a)     Returns zero terminated string at address a
Warning: Peek, Poke and Call are dangerous statements. You can lock up your Palm unit and corrupt ALL your data when using the poke and call statements. Use at your own risk. HotSync and backup often if you want try these functions. Memory above the dynamic heap is protected and cannot be poked without an OS write enable call. (Please read the PalmOS SDK docs for details).
Advanced Features (registered versions only):

  The registered version of HotPaw Basic can use added commands to
  support laser bar code scanning using Symbol SPT 1500/1700 model
  handhelds.  Registered owners please contact HotPaw for details.

  Doc format support:
  
    chain 1, docfilename$
	'- runs a program contained in a Doc file.
	'- (maximum program length of 8k characters).
  
  pedit32 support:
  
    chain n, "Memo32DB"
	'- runs a program contained in pedit32 memo #n
  
    db.find("Memo32DB", title$)
    	'- finds pedit32 memo by title string.

  The "chain" statements only works when used in programs contained
  in the MemoPad.

Debugging Aids:

  In order to save memory, HotPaw Basic does not store the text
  of program lines or the text location when loading a program.
  Thus, the only way for it to display a program line with a given
  line number is to actually load the program again from the main
  program selector view.  The "fn debugline(n)" function will set
  a listing breakpoint that will stop loading whenever the next
  program line with line number n is read.  After viewing the line,
  you can tap the screen to continue loading, or hit the
  "Applications" icon to exit HotPaw Basic.

    fn debugline(n)	'- sets listing breakpoint, returns 0
    
  Another way is to find linenumbers is to add some statements
  with labels, then print the following function value for the
  desired labels:

    fn linenum(label)	'- returns line number for any label
A4.3.1 Advanced Feature - Code Plugin Functions  (Up)
HotPaw Basic can call 'code' resource plugins modules. These can be developed similarly to DA code modules. The resource type must be 'bCmd' or 'BCmd' and the code ResID must be 1000. The executable routine must be at the start of the code resource, use no globals, and should be prototyped:
'bCmd'
long int main(long int param, long int param2, char *s64);
'BCmd'
double main(double param, double param2, char *s64); Call from yBasic by using:
fn bcmd("module_name", param) '- returns a -1 on errors The database name in this example should be "bcmdmodule_name". The second calling parameter is optional and set to zero if not present in the bcmd function call. The s64 character pointer will point to s$(48) which is only 64 chars in length. There will be a source code example on the HotPaw web site.
DA (Desk accessory) modules may also be called; the parameter is ignored.
See <http://member.nifty.ne.jp/yamakado/da/> for details on using and writing DA's.
A4.3.2 Advanced Feature - Laser Bar Code Scanning  (Up)
The registered version of HotPaw Basic can use added commands to support laser bar code scanning using Symbol SPT 1500/1700 model handhelds. Registered owners may contact HotPaw for details.
A4.3.3 Advanced Feature - Feature Manager Data Storage  (Up)
To save a Feature Manager feature (32-bit), use the command
put "ftr", "cBA3", n, d    with the feature number #n in the range 1024...1123, and d the 32-bit data you wish to store. Feature manager data is saved between application uses.

Advanced Example Programs

A4.6 Scripting Palm Apps Examples   A4.7 Serial Port

A4.6 Scripting Palm Apps Examples  (Up)

A4.6.1 Find Today's Appointments A4.6.2 Count Items In ToDo List A4.6.3 Find ToDo Items Due Today A4.6.4 Today's Due ToDos Into DateBook A4.6.5 Put Appointments in ToDo list

A4.6.1Find Today's Appointments (datebooktoday.bas)  (Up)
-- -- cut here -- --
# datebook today .bas
# find todays DateBook items
d=val(fn date$(0))
k=find("date",0,d)
while (k >= 0)
if k < 0 then end
a$ = get$("date",k,10)
? k,a$
k=find("date",-12,d)
wend
end
-- -- cut here -- --
A4.6.2Count Items In ToDo List(countdonetodos.bas) (Up)
-- -- cut here -- --
# count done todos .bas
# counts up items in your ToDo list
c=db.len("ToDoDB")
n=0
# count only priority 2
p=2 : p$=str$(p)
for i=0 to c-1
get$("todo",i,10)
draw str$(i),80,80
# count only done todos
if s$(25) = "1" and s$(24) = p$
n=n+1
endif
next I
? n," done todos with priority ", p
end
-- -- cut here -- --
A4.6.3Find ToDo Items Due Today (todotoday.bas)  (Up)
-- -- cut here -- --
# todo today .bas
# find ToDos due today
k=0
k=find("todo", -11, val(fn date$(0)) )
30:
if k<0 then end
a$=get$("todo",k,10)
if s$(25)="0" then ? k, a$
# ? "+",k,a$,s$(25)
k=find("todo", -12, val(fn date$(0)) )
goto 30
end
-- -- cut here -- --
A4.6.4 Today's Due ToDos Into DateBook  (Up)
# put todays due ToDos into DateBook
(left blank...)
A4.6.5 Put Appointments in ToDo list (datebook2todo.bas)   (Up) -- -- cut here -- --
#datebook2todo.bas
# HotPaw Basic ( cbasPad Pro ) program
# to make new ToDo's
# from todays appointments.
t$="make new ToDo ?"
d=val(fn date$(0)) :' today date
k=find("date",0,d) :' find 1st
while (k >= 0) :' anything?
a$ = get$("date",k,10) :' get it
s$(24) = 5 :' priority 5
s$(25) = 0 :' not complete
s$(26) = 0 :' unfiled
s$(27) = ""
s$(29) = "" :' no note
y = msgbox(a$,t$,2)
if (y = 1)
put "todo",new,10 :' make todo
endif
k=find("date",-12,d) :' find next
wend
msgbox( "done")
end
-- -- cut here -- --
A4.7 Serial Port  (Up)
-- -- cut here -- --
# serial port I/O
# emulates a 1 line terminal
# at 19200 baud
open "com1:",19200 as #5
a$=""
k$=inkey$
while asc(k$) <> 12
# use the scroll down button to exit
if len(k$) > 0
rem # send graffiti out serial port
print #5,k$;
if asc(k$) = 10
print #5, chr$(13);
endif
endif
# check for serial input
s = fn serial(5)
if s > 0 then
a$ = a$ + get$(#5,s)
rem # display input
draw a$+" ",10,90
if len(a$) > 32 then a$=""
endif
k$=inkey$
wend
close #5
end

-- -- cut here -- --

Appendix 5 - Changes (Up)

HotPaw cbasPad Pro Basic Version 1.2.0 (2000May25) Added some HanDBase search capability. Fixed an algebraic operator precedence bug. Fixed a problem with reading Doc file strings that cross pages.
HotPaw cbasPad Pro Basic Version 1.1.9 (2000May08) Added database functions to check type and creator. Fixed a compatibility bug in the val("") function.
HotPaw cbasPad Pro Basic Version 1.1.8 (2000May02) Added double precision numeric input capability. Added a double precision number display routine (str$()). Added fn trim$(). Added a method to set the open new memo category. Added a standard normal (statistics) bcmd extension. Uploaded new html documentation to website. Fixed a bug in reading data from "Doc" files.
HotPaw cbasPad Pro Basic Version 1.1.7 (2000Apr14) Added a way to display source code at a given line number. Added support for programs contained in pedit32 memos. Added support for programs contained Doc files. Added the capability to read string resources. Fixed a problem with reading Address/Phone List records. Fixed a problem creating "no time" datebook appointments. Fixed a problem with using fn time$(-1) bug in pre 3.5 OS versions. Fixed a bug in using the "exit while" statement.
HotPaw cbasPad Pro Basic Version 1.1.6 (2000Mar24) Fixed a bug with integer variable comparisons. Fixed a bug with the default popup list selection. Added beta test support for custom launchcode calls.
HotPaw cbasPad Pro Basic Version 1.1.5 (2000Mar16)
Added beta test support for custom launchcode calls. Fixed a problem with rounding numbers smaller than one. Fixed a problem with finding a program in the last Memo. Fixed a problem with stopping programs in the ScratchPad.
HotPaw cbasPad Pro Basic Version 1.1.4(2000Mar14)
Added the asin() and acos() inverse trig functions. Added a significant figure option to the round() function. Added "Doc" format string read support. Added a method to print the linenumbers of labels. Added beta test support for 7-bit serial port mode. Fixed a problem with HotSync behavior of modified ToDo's. Fixed a problem with db.peek().
HotPaw cbasPad Pro Basic Version 1.1.3 (2000Mar08)
Added support for writing HanDBase database fields. Added support for determining HanDBase database size. Added support for reading MobileDB database fields. Added the "elseif" statement. Improved automatic width of form pop-up lists. Increased the max number of form popup lists to 4. Removed some syntax restrictions on bitmap drawing commands. Fixed a bug in the mid$() function. Fixed a bug in fn pen(0) waiting for a tap. Fixed an occasional crash when stopping inside dialogs. Fixed a crash caused by trying to empty the scratchpad.
HotPaw cbasPad Pro Basic Version 1.1.2 (2000Mar01)
Added day-of-week function. Added draw bitmap resource command. Changed form lists to now return values on selection. Changed Application Icon and Added Color Icon. Changed fn test(). Fixed a problem with large and small hex bitmaps. Fixed a bug in finding repeated datebook events.
HotPaw cbasPad Pro Basic Version 1.1.0 (2000Feb21)
Fixed a bug in the "line too long" error message.
HotPaw cbasPad Pro Basic Version 1.0.9 (2000Feb20)
Added the field$() function to find the Nth string field. Documented the instr() function. Fixed fn wait(). Fixed an occasional memory error with #include files. Fixed a memo scroll position bug. Fixed a form reset bug.
HotPaw cbasPad Pro Basic Version 1.0.8 (2000Feb16)
Increased the max number of form popup lists to 2. Increased popup list selections limit to 63 items total. Fixed a bug with print data hiding input fields. Fixed a problem with setting form titles.
HotPaw cbasPad Pro Basic Version 1.0.7 (2000Feb11)
Added the "fn strw()" string pixel width function. Added the "form redraw" command. Added the "form lst" command to create a pop-up list. Fixed a bug with the db.find() command and open memos.
HotPaw cbasPad Pro Basic Version 1.0.6 (2000Feb10)
Added up/down button field selection to built-in form 12. Fixed a bug in chaining from yLaunch'd programs. Fixed a bug in JFile Pro database writes.
HotPaw cbasPad Pro Basic Version 1.0.5 (2000Feb09)
Added beta test COLOR drawing support for PalmOS 3.5 running under the POSE emulator. Added circular arcs drawing support. Added the form reset command. Added ability to find repeating DateBook events. Added the "eof" function. Added the "stop" command. Fixed a bug where yLaunch required a "new" statement. Fixed a problem in using db$() to read from memos.
(see Versions history for older revision notes)

Appendix 6 - Bugs (Up)

Many string functions (except +, MID$, LEN and INSTR) silently truncate their results to 63 characters (e.g. without warning).
Comments starting with ' sometimes can't be used after statements that can end with a string parameter. ( : ' should always work.)
There are many undocumented graphics and database commands and keywords in the PalmOS runtime engine. See the accompanying README and HotPaw Basic Quick-Reference file.
 

License (Top)

TITLE. HotPaw Basic ("the Software") is Copyright 1999 by Ronald H Nicholson, Jr., All Rights Reserved. Title, ownership rights, and intellectual property rights in the Software shall remain in Ronald H. Nicholson, Jr. The Software is protected by the copyright laws and treaties of the United States.
TERMS: Ronald H. Nicholson, Jr. grants you the right to use this copy of the Software if you agree to the following license terms:
You may use the Software without a license key and in Demo mode for educational or non-commercial purposes.
You may not reverse engineer, decompile, or disassemble the Software or license key database.
You may transfer or copy a license key or license key database for the Software only if required in the normal use of one PalmOS handheld unit. You may also make one copy of the Software license key if required for backup purposes. You are required to keep all HotPaw license keys confidential. You may not loan, rent, transfer or assign the license key to another user except with (a) the permission of HotPaw and (b) as a permanent transfer of the Software and the license key.
Commercial distribution of the Software is not allowed without the express permission of the copyright holder. Contact HotPaw for details about obtaining a license.
Usage of the Software is also subject to the following limitations and disclaimers.
DISTRIBUTION. Contact HotPaw for details on obtaining a license.
WARRANTY AND DISCLAIMER. The HotPaw Basic application is distributed in the hope that it might be useful, but WITHOUT ANY WARRANTY OF ANY KIND; not even the implied warranties of MERCHANTABILITY, fitness for ANY particular purpose, or for non-infringement.
LIMITATION OF LIABILITY. UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, TORT, CONTRACT, OR OTHERWISE, SHALL RONALD NICHOLSON, HOTPAW OR ITS SUPPLIERS OR RESELLERS BE LIABLE TO YOU OR ANY OTHER PERSON FOR ANY INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER COMMERCIAL DAMAGES OR LOSSES. IN NO EVENT WILL HOTPAW BE LIABLE FOR ANY DAMAGES IN EXCESS OF THE AMOUNT HOTPAW RECEIVED FROM YOU FOR A LICENSE TO THIS SOFTWARE, EVEN IF RONALD NICHOLSON OR HOTPAW SHALL HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY. THIS LIMITATION OF LIABILITY SHALL NOT APPLY TO LIABILITY FOR DEATH OR PERSONAL INJURY TO THE EXTENT APPLICABLE LAW PROHIBITS SUCH LIMITATION. FURTHERMORE, SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THIS LIMITATION AND EXCLUSION MAY NOT APPLY.
HIGH RISK ACTIVITIES. HotPaw Basic is not fault-tolerant and is not designed, manufactured or intended for use or resale as on-line control equipment in hazardous environments requiring fail-safe performance, such as in the operation of nuclear facilities, aircraft navigation or communication systems, air traffic control, direct life support machines, or weapons systems, in which the failure of the Software could lead directly to death, personal injury, or severe physical or environmental damage ("High Risk Activities"). Ronald Nicholson, HotPaw, and its suppliers SPECIFICALLY disclaim ANY express or implied warranty of fitness for High Risk Activities.
If you do not agree to the terms of this LICENSE, you are not authorized to use the Software.

More Legal Notices (Top)

Information in this document is subject to change without notice and does not represent a commitment on the part of HotPaw or Palm Computing. There is no warranty that this document is accurate (it isn't). The software described in this document is furnished under a license agreement or nondisclosure agreement. The software may be used or copied only in accordance with the terms of the agreement. It is against the law to copy this software for any purpose other than the purchaser's personal use.
PalmPilot and and the PalmPilot logo are registered trademarks of Palm Computing. Palm, PalmOS and HotSync are trademarks of Palm Computing.
HotPaw and cbasPad are trademarks of the HotPaw company.
Applesoft and Macintosh are registered trademarks of Apple Computer Inc.
MS BASIC and MSDOS are registered trademarks of Microsoft Corporation.
Portions of this document are Copyright (C) 1989 Dave Gillespie.
This document is Copyright 1990-2000 Ronald H. Nicholson, Jr. (rhn@nicholson.com) ALL RIGHTS RESERVED
© 2000 By Ronald H. Nicholson, Edited by Charlene A. Gibson

All rights reserved.
Document number 122399-00052503