Chipmunk Tiny Basic for Pilot README and Command Summary for cbasPad version 0.82 Please see the Revision History for important changes. Abstract: This README is a description of cbasPad, a Tiny Basic programming language interpreter with integrated text editor for the USR Pilot. Features include math functions, sounds and morse code and simple graphics. See below for a complete list of commands, statements & functions. Contents: Introduction Installation Running a cbasPad Basic program Basic Statement, Command & Function Summary Additional Commands & Functions Some Warnings Examples Revision History FAQ Copyright and Disclaimer notice Introduction This a version of Tiny Basic for the USR Pilot palmtop computer. 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). The cbasPad interpreter was written as an experiment in writing a small Basic interpreter in portable c. After the 1st versions of integer cbasPad were written, various features were added to make it more useful. These added features include some limited floating point math, and various "op" commands and "fn" functions to access the Pilot hardware and databases. Please note that no formal or complete verification has been done on any of cbasPad's functionality. *** Installation: - Use the USR Install Application and then HotSync. - You may need to select "All File Types" since a zip file doesn't preserve the Mac file creator type info. - If HotSync fails, you may need to manually delete any prc files left in your install directory in order to get HotSync working again. - If you have the 1.0 OS, you may need to install the OS 1.0.6 patch to install a program this large. - Use yMFrag app to check for memory fragementation if you still have out-of-memory problems during an install hotsync. - cbasPad 0.77+ requires a memory heap with at least one 30K block. Installing cbasPad Basic programs: - cbasPad uses it's own memo database and it's own built in memo editor. This is to prevent any accidental overwriting of the MemoPad database. - You can just hit "New";and write you own Basic program. - You can use the "import" menu item to import a page from the MemoPad. A dialog box will ask you for the Memo title. - The following web site has win32 tools for combining several cbasPad programs into one pdb file: - The following web site has a Win95 HotSync conduit for cbasPad: Running a cbasPad Basic program: - From the edit page, you can select a range of unnumbered lines and hit the "Exec" button. - From an edit page, you can hit the "Select All" button and then the "Exec" button to run either direct mode statements or the first program on the page. - From the main cbasPad index page, you can select a program from the list and hit the "Exec" button. - To stop a running program, hit the "Done" button. - To stop a running program when an input dialog is present, use the "Stop" menu item. *** The cbasPad BASIC Programming Language The cbasPad 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. cbasPad is a minimal subset of the Basic language, so many features of a full version of the Basic language are not present. cbasPad requires that every program begin with the "new" command and end with the "run" command. These commands should not have line numbers. Any un-numbered lines before the first "new" command are executed in direct mode (as they are encountered.) cbasPad either requires that every program line have a line number, or requires the use of the #autonum comment. If #autonum is present, then any lines without numbers are automatically assumed to have a line number that is one greater than the line number of the previous line. This means that any line numbers used as labels for "goto" and "gosub" targets must be in order and spaced far enough apart for all the intervening lines. cbasPad-memo's are limited to about 4000 characters in length. To create a longer program, one can use the #include <#TITLE> comment. cbasPad will look for a cbasPad-memo titled "#TITLE" and insert lines from that memo as an in-line [sub]routine The "print" command will append output at the end of the current cbasPad-memo. Use "dprint" or "?" to send output to a dialog box instead. You can also change the cbasPad-memo used for print output by using the op "page" command. A program can use the op "page",-1 command to create a new cbasPad-memo page for print output. There is a fairly complete list of www pointers to information on the generic Basic language near the end of my 'Basic' web page: *** Basic Statement, Command & Function Summary: Comment lines are lines that start with the '#' character. Operators, Statements, Functions and Reserved Keywords: Operators: + - * / mod ^ = <> > >= < <= and or xor not Commands and Statements: let print dprint ? input if then for to step next gosub return goto : dim float end run new rem # Functions: int() rnd() sqr() exp() log() sin() cos() tan() atn() len() val() str$() chr$() hex$() mid$() Special functions and commands: fre peek() poke call varptr() eval() fn op grline sound sersend Variables and Constants: Hex constants may be entered by preceding them with "0x". Variable names may be up to 15 characters in length. Integer variables should end with the '%' character. Floating point variables should be declared with the float command. Floating point numbers and variable are represented by a format similar to IEEE single extended. When the '#opt int' pragma is present, variables without a suffix start out as integer variables; but promote to floating point if a floating point value is assigned. String variables must end with the '$' character. There is a limit of 12 string variables and 1 built-in string array. Notes: ALL keywords must entered in be lower case. Lines starting with the character '#' are ignored (comments). The '#include ' comment will include statements from the cbasPad page starting with TITLE in its first line. The include comments may not be nested. Exponentiation must be parenthesized. e.g. x = (y ^ 2.0) The "and", "or" and "xor" operators do bit-wise operations; "not" is a boolean operator and only returns 1 or 0. print : appends to the end of the cbasPad-memo text. dprint : prints to a mini-dialog box. ? : a question mark is an alternate symbol for dprint. The "let" before an assignment is optional. float : Declares a list of floating point variables. dim : Numeric arrays must be dimensioned before use and are limited to one dimension. float arrays must first be declared as float. fre : returns size of free dynamic heap space. rnd(n) : returns a pseudo random integer in the range 0..n-1 int(x) : truncates toward zero. Transcendental functions only work with explicit floating point operands. log(x) : natural log (base e) sin(x) : trig function, x in radians Current String Limitations: There are a maximum of 12 string variables plus one string array; use more than 12 and you may just get aliases to existing strings. The maximum length of a string is 31 characters. Only the "=" comparison works for strings. Use "+" to concatenate two strings. Complex expressions involving strings don't work. Only 1 string array is allowed: s$(). (auto-dimensioned to 31) Current Floating Point Limitations: Power operation x = (x ^ y) raises x to the y power; parenthesis are required. The error of transcendental functions is unknown. Integer addition/subtraction can overflow 2^31. Integer values greater than 2^31 may overflow unless declared float. If '#opt int' comment is present, mul/div of integer operands will default to integer math. *** Program Execution Statements without line numbers, but before a "new" statement, are executed in direct execution mode in the order they are listed. Statements with line numbers or between a "new" statement and the "run" command are executed in deferred mode; that is, only after a "run" command. If the "#autonum" comment is present, unnumbered statements between the "new" statement and the first "run" command are automatically given sequential line numbers incrementing by 1 from the previous line. Any line number labels present should be in increasing order and differ by at least the number of intervening lines plus two. All statements after the first "run" command are ignored. Program execution terminates after encountering the "end" statement. When making any changes to numbered program lines, it's good form to precede the entire program with a "new" command. Single statements without line numbers can be executed by selecting just the line the statement is on, and then hitting the "Exec" button. To stop a running program, hit the "Done" button. To stop a running program when an input dialog is present, use the "Stop" menu item. *** Some Examples: # this is a comment line (because of the leading '#'). # multiple statements per line allowed. x = 7 : y = 3 + 4 # dprint prints 1 line to a dialog box. dprint "hello ",123 dprint "hello "; dprint 23+7 # ? is an abbreviation for "dprint" ? x # print appends text to your program file. print chr$(65) print "0x";hex$(255) # input can read numbers or strings. input "prompt", y input "prompt", a$ # Arrays must be dimensioned. # Arrays are limited to one dimension. dim a(4) for i=0 to 4 : a(i) = i : next i Example Statements: 10 rem - this is also a comment 20 if (x = 7) then y = 4 30 for i=0 to 10 step 2 : print i, 40 next i 50 gosub 100 90 end 100 print "sub @ 100" 120 return Additional Commands: float x - declare x as a float var dprint - redirects 1 line of print to a dialog box. grline x1,y1,x2,y2,1 - draw line on display [0..159] grline x1,y1,x2,y2,2 - draw gray line grline x1,y1,x2,y2,-1 - erases a line grline x1,y1,x2,y2,4 - draw rect (topLeft, extent) grline x1,y1,x2,y2,5 - draw gray rect grline x1,y1,x2,y2,7 - draw filled rect grline x1,y1,x2,y2,-7 - erase rect sound { frequency in Hz }, { duration in mS }, { vol 0..64 } sound freq, c_wpm, vol64, morse$ [ , Farnsworth_wpm ] sound 660, 18, 10, "cq de n6ywu", 13 : rem An example. sersend { mem_address }, { len }, { baud_rate 2400..19200 } op "ds",a$,x,y - draws text at (x,y) op "ds",a$, n*1000 + x, y - draws text using font n - there are only 6 fonts, most have many missing chars. op "sety",y - replaces line y with following print output. op "page","title" - changes cbasPad input/output page op "page","",n - changes output page to record #n op "page","",-1 - adds a new output page and changes to it. op "dt",t$ - changes fn 30 dialog title op "it",t$ - changes input dialog title to t$ op "mfind",x$,n - finds MemoPad entry starting with x$ - returns Memo index or -1 for fail. op "dbrd","memo",n,m - reads MemoPad entry n into s$(0). - m is a char offset into the memo. - if m is -1, then read the next line - returns category number or -1 for fail. op "dbrd","addr",n - reads AddressBook entry n into s$ array. - strings longer than 31 chars will truncate. - returns category number or -1 for fail. op "dbrd","date",n - might read something interesting in s$() op "dbrd","todo",n - might read something interesting in s$() op "dbwr!","memo",n,1 - appends s$(0) to the end of MemoPad memo n - the last parameter appends a linefeed. op "dbwr!","addr",n - writes s$(0..18) to AddressBook item n - returns 1 if successful ( #added disclaimer: you can trash your MemoPad and AddressBook databases using "dbwr!". This is an *untested* function! ) op "db",type,creat,i - returns length of DB record i - if non zero then 'fn 80' returns pointer to DB record - for type & creat, convert (e.g. 'DATA' & 'memo') to 32-bit integers. call a - 68k machine jsr to addr a (You can stuff 68K machine code in integer arrays. Remember that integers are 4 bytes long.) (These commands may change or be removed in future versions!) Additional Functions: sqr(x) - square root exp(x) - e ^ x log(x) - natural log of x sin(x) cos(x) tan(x) atn(x) - trig functions for x in radians len(a$) - returns length of string a$ val(a$) - returns numeric value of a$ or 0 str$(x) - returns string representation of x chr$(c) - returns string of ascii char c, length 1 hex$(n) - returns hex string mid$(a$,s,n) - returns substring of a$ starting at s length n eval(q$) - evaluates string q$ as a numeric expression ("1+2") varptr(y) - returns memory address of variable y (or y$). peek(a) - returns 8-bit byte at address a peek(a,2) - returns the 16-bit value at word aligned address a peek(a,4) - ... 32-bit value at word aligned address a fn 16 - returns seconds timer fn 17 - returns tick timer (100 Hz) fn 24 - returns decimal date fn 25 - returns decimal time fn 22 - waits (pauses) for 2 seconds, returns 0 fn 20 - returns scaled battery voltage fn 19 - returns length of the clipboard text fn 18 - returns memory address of the clipboard text fn 33 - returns asc(input$(1)). Waits for 1 graffiti char. - also captures presses on the rightmost 5 button. fn 38 - asc(inkey$) e.g. non-blocking form of fn 33 fn 34 - returns tick time of last pendown or input$ char fn 30 - display 9 line dialog, returns dialog button status fn 39 - returns last input or dialog button status fn 42 - temporarily clears middle of screen, returns 0 op "gnum", n - returns the first number from line n of the page op "get$", n - returns a string from line n of the current page sersend { buffer_mem_address }, { max_len }, -2 - returns length of serial data received in buffer. This function can only be used after the baud rate has been initialized by a prior "sersend" in the current running program. Use a varptr to a string variable for the buffer address and a max of 31 for the length. If the return is n > 0, then n bytes have been read from the serial port input into your string variable . Warning: Using sersend drains your battery around 4 times faster. (These functions may change or be removed in future versions!) Additional Operators: x = (x ^ y) - raise x to a power; parenthesis are required. Additional Variables: String variable name must end with a '$', e.g. name$ The print, dprint and input commands will take string vars. let a$ = "hello" : dprint a$,a$ There is one string array: s$() - auto-dimensioned on first use with 31 elements s$(0) .. s$(30) Additional Dialog Form: fn 30 - displays a dialog form with 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 Some Warnings: Integer overflow (> 2^32-1) will not signal any warnings. If you don't use the "new" command, old deleted program statements may still be in the execution buffer. You may have to turn off alarms when running cbasPad programs that leave less than 5000 bytes of free memory (use the fre function to determine how much a program uses.) An alarm occuring while having a program running, or still open after running, that leave less than 5000 bytes of free memory may cause your Pilot to crash. You can lock up your pilot and corrupt ALL your data when using peek, poke and call. Use at your own risk. HotSync and backup often if you want to play with these functions. Memory above the first 32K is protected and cannot be poked without an OS write enable call (read the SDK docs). Using sersend will drain the battery much faster than normal. Installing 0.5x, or later, over 0.02x will cause hotsync to crash. Bugs: Many. Please send bug reports to rhn@nicholson.com * Bug reports without the version number will be ignored. * Some floating point values may print incorrectly. (ROM bug.) Some syntax errors are reported without line numbers. Deep GOSUB nesting may cause stack overflow crashes. Complex expression nesting may cause stack overflow crashes. Divide by 0, log(0), overflow, etc. produce undefined results. *** Examples Example 1: # example 1 new 10 for i=1 to 7 : print 3 * i, 20 next i run # Now use the menus to "select all" # and to "run selection". Example 2: # print out character set new 10 for c=33 to 255:print chr$ c;:next run Example 3: # send the clipboard text # out the serial port new 10 a=fn 18 : n=fn 19 20 if n > 0 then sersend a,n,19200 run *** Revision History: For compatibility with the latest version, please add the comment #opt int before the first numbered line in pre 0.74 cbasPad program. Please DELETE versions 0.2b9 or older BEFORE installing this version. -- Version 0.82 -- (97Jul20) Fixed a bug in importing non-existent memos into cbasPad. -- Version 0.81 -- (97Jul03) Fixed a bug in the int(0) function. Expanded the range over which exp(), log() and sqr() might have some resemblence of correctness. Added some protection against too deep expression nesting which could cause a stack overflow crashes. (limit is 4 or 5 parens.) op "dbrd","todo" does something which might change in future revs. -- Version 0.80 -- (97Jun27) Changed all variables and multiply to floating point by default. Up to 3 lines may now be placed in the dprint dialog by seperating the lines with the VT (ascii 0x0b) character. e.g. dprint "line 1";chr$(11);"line 2" Fixed an if-then goto freeze up bug. Fixed a 0.0^n exponent bug. -- Version 0.79 -- (97Jun20) Changed divide to produce floating point results by default. Added op command to set input & dialog titles. Added more grline options (grey lines, rects, etc.) Fixed a display bug with long strings in the fn 30 dialog. Fixed a quit during import bug. -- Version 0.78 -- (97May24) Fixed s$() init problem with op "dbrd". Added op "mfind" and op "dbwr!" commands. Added custom launch codes for scriptability from other apps. -- Version 0.77 -- (97May20) Integer variables names can end with '%' (e.g. a%, foo%). Other variables will auto-promote to floats on fp assignment. Added the '#opt int' pragma to disable auto-promotion. Bugs: In 0.77, the sersend,,-2 function might return 7608, instead of 0, if there are no bytes in the serial port receive buffer. -- Version 0.76 -- (97May17) Added a menu item to import new programs from the MemoPad. Added #include <#title> capability for longer programs. Includes cannot be nested. Added #autonum to auto number lines by +1 between "new" and "run". Linenumber labels must be in order and be different by greater than the number of intervening lines. The mod operator now coerces float operands to integer. The op "dbrd","addr,n function now returns the category number. Fixed a dialog field cursor restore bug. Now remembers top visible record shown on startup. Now hides the exec and select-all buttons when running a program. -- Version 0.75 -- (97May16) Fixed an array assignment bug (crashed mileage and battery log). Fixed a rounding error in the int() function. Added op "dbrd","addr",n to read AddressBook entry n into s$. -- Version 0.74 -- (97May12) Variables now auto promote to floats when assigned a float. Added for-next support for float index variables. Added op "ds" to draw strings. Now displays record numbers on main screen. Changed op "page","",-1 to add a new output page. Fix a float assignment bug in 0.72b & resource crash in 0.73b. -- Version 0.71 -- (97Apr09) Increased memory efficiency; cbasPad now uses a temporary DB for tokens. Added "cbasPad working..." while loading program. 0.70 was broken and only ran programs once before crashing. -- Version 0.68 -- (97Feb05) Fixed 1 fp compare bug. Fixed 1 low memory application switch problem. Changed fre function. Added op "pclip",s$ to paste string to clipboard. -- Version 0.67 -- (97Jan27) Fixed op "gnum" bug. Fixed a small memory leak. Better out-of-memory behavior, less crashes. -- Version 0.65 -- (97Jan18) Increased number of string vars from 8 to 12. fn 39 now returns button status of last dprint statement. -- Version 0.64 -- (97Jan09) Fixed bug in float array assignment. fn 34 returns last pendown tickcount. -- Version 0.62 -- (97Jan06) Increased the maximum program text size to 4000 characters. Added playing morse code tones via the sound command. sound 660,18,10,"cq de n6ywu",13 Added op "get$",n function (reads string from page). Added limited form of serial input polling. Added fn 22 wait/delay/pause function. Reduced code 0 rsrc size (should fix some install problems.) -- Version 0.58 -- (96Dec12) Fixed a string memory leak. Removed op "dpr" command. -- Version 0.57 -- (96Dec11) Changed the ? shortcut to dprint instead of print. Fixed a string array assignment bug. Fixed yet another floating point bug (division sign). -- Version 0.55 -- (96Dec03) Fixed op "sety" initialization bug. Disallow sound 0,d,v (frequency = 0 causes a crash). Added morse-code-like beeping. -- Version 0.54 -- (96Nov23) Fix to create non null database on first use. Added "Stop" to input dialog menus. -- Version 0.53 -- (96Nov17) Fixed length bug in the mid$(s$,start,length) function. Fixed peek() to require parenthesis around all parameters. Cosmetic cleanup of dprint dialog. Enabled use of float vars as tests in if-then statements. Added floating point equality test. -- Version 0.52 -- (96Nov16) Physical scroll buttons now scroll by page. Enabled editing in the input dialog. Added mid$() function. Reduced screen flash when executing from the main form. -- Version 0.51 -- (96Nov15) Added eval() to evaluate a string as an expression. Fixed a print bug when executing from the main form. Fixed a few float to int number conversions. -- Version 0.50 -- (96Oct25) Fixed a memory allocation leak. Changed the creator signature type to 'cBAS'. *** *** WARNING *** *** The application signature has changed in versions 0.5X from that of old versions 0.02X. You will have to *DELETE* old version 0.2b9, or earlier, of cbasPad *BEFORE* upgrading. First copy any Basic programs that you wish to save to the Memo Pad, delete the old version, and then copy your saved programs back after installing the new version of cbasPad. If you don't do this your hotsync may crash. -- Version 0.02b9 -- (96Oct19) Exec from main screen now returns to main screen. Fixed reading the 9th line of input dialog. Fixed op "db" command item indexing. Fixed val() to work with hex strings ("0x1abc"). Added hex$() to string functions. Added standard edit menu to input dialogs. -- Version 0.02b8 -- (96Oct06) Fixed integer input statement bug. Fixed string parameter precedence bugs in val() and len(). Increased size of s$() to 20 elements. Increased size of dialog form to 9 input fields. -- Version 0.02b7 -- (96Oct05) Added dialog form with 8 input fields. Added auto-dimensioned s$() array of 16 elements. Edit button replaces auto-edit mode. Exec button added to main form. -- Version 0.02b5 -- (96Oct01) Fixed string initialization bug that can hang machine. -- Version 0.02b4 -- (96Sept26) Added dprint command to replace op "dpr". Restored printing of characters with ASCII value > 129. Added alpha test versions of trig functions. Added very limited string variables (max of 8 total). -- Version 0.02b3 -- (96Sept22) Fixed handling of tabs in comment lines. Fixed printing of a few floating point values. Added rnd() function. -- Version 0.02b2 -- (96Sept14) Added experimental versions of sqr(), exp(), log() and ^. Fixed printing of a few floating point values. Cleaned up "dpr" dialog box just a little. Added method to peek at the data of other applications. -- Version 0.02b1 -- (96Sept09) Fixed a bug in array assignment. Fixed a bug that caused crashes on empty input statements. Disabled tap text select during print output. Added the command 'op "dpr"' to print to the dialog box. -- Version 0.02b0 -- (96Sept08) More floating point expressions allowed. -- Version 0.02a9 -- (96Sept07) Added limited function floating point variables. *** See the floating point limitations section below. *** Fixed an error dialog bug. Error messages are no longer repeated in the text output. Fixed a bug in illegal string variable names. -- Version 0.02a8 -- (96Sept05) Added the "new" command to clear out old programs. Stopped cursor blink when running. Increased max "run" time before sleep to 5 minutes. -- Version 0.02a7 -- (96Aug31) Fixed input form background display. Added "input" statement. Increased maximum text form length to 2K. -- Version 0.02a5 -- (96Aug24) Fixed bug in dimensioning arrays on repeated runs. Added error report dialog. Renamed Buttons to "SelectAll" and "Exec" Halt script execution after the first "run" command. Removed ability to search cbas database. Added functions to get clipboard Ptr and len. (I use this and the sersend command to upload memos to my Unix workstation.) -- Version 0.02a4 -- (96Aug18) Fixed printing negative numbers. Fixed crash on done button while running. Fixed HotSync of DB. Added print hex$(), print chr$() Cleaned up mislabled resources. Changed type of app and DB (You should delete the old cBASpadDB.) Added poke, varptr(), call, serial port transmit. -- Version 0.02a1 -- (96Aug17) Initial Experimental Release. ---------------------------------------------------------------- End of release notes. *** FAQ There are several Pilot FAQ's on the Web. Try these URL's: http://home.pacific.net.sg/~kokmun/tips.htm http://www.nicholson.com/rhn/pfaq4.txt http://www.pilotfaq.com/ *** Credits: cbasPad is based on the Pilot MemoPad tutorial, which is Copyright © Palm Computing 1996, and on Chipmunk Basic. Permission: Pilot cbasPad is Copyright 1996,1997 by Ronald H. Nicholson, Jr., All Rights Reserved. There is NO shareware fee required for personal, educational or noncommercial use of this version of cbasPad. $0.00 (USD) ! Permission to use, copy and distribute this software without fee for non-commercial or educational purposes is hereby granted, provided that the above copyright notice appear in all copies, and that both the copyright notice and this permission notice with the following disclaimer appear in all documentation. Disclaimer: The cbasPad program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY OF ANY KIND; not even the implied warranty of MERCHANTABILITY or fitness for ANY particular purpose. *** -- 97Jul20 Copyright 1997 Ronald H. Nicholson, Jr. rhn@nicholson.com ***