Documentation for
             Gordo's MC68000 Tiny BASIC version 1.0


     This  is  an adaptation of Li Chen Wang's  'Palo  Alto  Tiny 
BASIC' for the Motorola MC68000 microprocessor.  It includes more 
functions and program save and load. As distributed, it is set up 
for  a Motorola MEX68KECB Educational Computer Board connected to 
a  host  CP/M computer.  The source code should give  you  enough 
details to allow you to install it on a different system.  If you 
have any problems, you can write to me at:
     Gordon Brandly
     R.R. 2
     Fort Sask., AB, Canada
     T8L 2N8


                          The Language

Numbers

In  this Tiny BASIC,  all numbers are integers and must be in the 
range 2147483647 to -2147483648.


Variables

There are 26 variables denoted by the letters A through Z.  There 
is  also a single array @(I).  The dimension of this array (i.e., 
the  range of value of the index I) is set automatically to  make 
use  of all the memory space that is left unused by  the  program 
(i.e.,  0 through SIZE/4, see SIZE function below). All variables 
and array elements are 4 bytes long.


Functions

There are 4 functions:
     ABS(X) gives the absolute value of X.
     RND(X) gives a random number between 1 and X (inclusive).
     SIZE gives the number of bytes left unused by the program.
     PEEK(X) gives the value of the byte at memory location X.

Arithmetic and Compare Operators

     /    Divide. (Note that since we have integers only, 2/3=0)
     *    Multiply.
     -    Subtract.
     +    Add.
     >    Greater than. (comparison)
     <    Less than. (comparison)
     =    Equal to.  (comparison)   Note that to certain versions 
          of BASIC "LET A=B=0" means "set both A and B to 0".  To 
          this  version  of Tiny BASIC,  it means "set A  to  the 
          result of comparing B with 0".
     <>   Not equal to. (comparison)
     >=   Greater than or equal to. (comparison)
     <=   Less than or equal to. (comparison)

+,  -,  *,  and / operations result in values between -2147483647 
and 2147483647.  (-2147483648 is also allowed in some cases.) All 
compare operators result in a 1 if true and a 0 if not true.


Expressions

Expressions  are formed with numbers,  variables,  and  functions 
with arithmetic and compare operators between them. + and - signs 
can also be used at the beginning of an expression.  The value of 
an expression is evaluated from left to right,  except that * and 
/  are  always done first,  and then + and - ,  and then  compare 
operators.  Parentheses  can also be used to alter the  order  of 
evaluation.  Note  that  compare  operators can be  used  in  any 
expression. For example:

     10 LET A=(X>Y)*123+(X=Y)*456+(X<Y)*789
     20 IF (U=1)*(V<2)+(U>V)*(U<99)*(V>3) PRINT "Yes"
     30 LET R=RND(100), A=(R>3)+(R>15)+(R>56)+(R>98)

In line 10,  A will be set to 123 if X>Y,  to 456 if X=Y,  and to 
789 if X<Y. In line 20, the "*" operator acts like a logical AND, 
and the "+" operator acts like a logical OR.  In line 30,  A will 
be a random number between 0 and 4 with a prescribed  probability 
distribution of: 3% of being 0, 15-3=12% of being 1, 56-15=41% of 
being 2, 98-56=42% of being 3, and 100-98=2% of being 4.


Program Lines

A  Tiny BASIC line consists of a line number between 1 and  65534 
followed  by one or more commands.  Commands in the same line are 
separated by a colon ":".
     "GOTO",  "STOP",  and  "RETURN"  commands must be  the  last 
command on any given line.


Program

A Tiny BASIC program consists of one or more lines. When a direct 
command  "RUN"  is issued,  the line with the  lowest  number  is 
executed  first,  then the one with the next lowest line  number, 
etc.  However, the "GOTO", "GOSUB", "STOP", and "RETURN" commands 
can  alter  this normal sequence.  Within a  line,  execution  of 
commands  is from left to right.  The "IF" command can cause  the 
remaining commands on the same line to be skipped over.


Commands

Tiny BASIC commands are listed below with examples. Remember that 
multiple commands can be put on one line if colons separate them. 
In  order to store the line,  you must also have a line number at 
the beginning of the line.  (The line number and multiple-command 
lines aren't shown in the examples.


REM or REMARK Command

REM anything goes

This line will be ignored by Tiny BASIC.


LET Command

LET A=234-5*6, A=A/2, X=A-100, @(X+9)=A-1

Will  set  the variable A to the value of the expression  234-5*6 
(i.e.  204),  set  the  variable A (again) to the  value  of  the 
expression A/2 (i.e. 102), set the variable X to the value of the 
expression A-100 (i.e. 2), and then set the variable @(11) to 101 
(where 11 is the value of the expression X+9 and 101 is the value 
of the expression A-1).

LET U=A<>B, V=(A>B)*X+(A<B)*Y

Will  set the variable U to either 1 or 0 depending on whether  A 
is  not  equal  to or is equal to B;  and set the variable  V  to 
either  X,  Y or 0 depending on whether A is greater  than,  less 
than, or equal to B.


Print Command

PRINT

Will  cause  a carriage-return (CR) and a line-feed (LF)  on  the 
output device.

PRINT A*3+1, "abc 123 !@#", ' cba '

Will  print the value of the expression  A*3+1  (i.e.  307),  the 
string  of  characters "abc 123 !@#" and the string" cba  ",  and 
then  a CR-LF.  Note that either single or double quotes  can  be 
used to quote strings, but pairs must be matched.

PRINT A*3+1, "abc 123 !@#", ' cba ',

Will produce the same output as before,  except that there is  no 
CR-LF  after the last item printed.  This enables the program  to 
continue printing on the same line with another "PRINT".

PRINT A, B, #3, C, D, E, #10, F, G

Will  print the values of A and B in 11 spaces,  the values of C, 
D,  and E in 3 spaces, and the values of F and G in 10 spaces. If 
there  aren't  enough  spaces specified for a given value  to  be 
printed, the value will be printed in full anyway.

PRINT 'abc',_,'xxx'

Will  print the string "abc",  a CR without a LF,  and  then  the 
string "xxx" (over the "abc") followed by a CR-LF.


INPUT Command

INPUT A, B

When  this  command is executed,  Tiny BASIC will print "A:"  and 
wait to read in an expression from the input device. The variable 
A  will  be set to the value of this  expression,  then  "B:"  is 
printed and variable B is set to the value of the next expression 
read  from the input device.  Note that whole expressions as well 
as numbers can be entered.

INPUT 'What is the weight'A, "and size"B

This is the same as the command above,  except the prompt "A:" is 
replaced by "What is the weight:" and the prompt "B:" is replaced 
with  "and size:".  Again,  both single and double quotes can  be 
used as long as they are matched.

INPUT A, 'string',_, "another string", B

The strings and the "_" have the same effect as in "PRINT".


POKE Command

POKE 4000+X,Y

This  command puts the value produced by expression "Y" into  the 
byte memory location specified by the expression "4000+X".


CALL Command

CALL X

This  command  will  call a machine language  subroutine  at  the 
address  specified  by  the expression  "X".  All  of  the  CPU's 
registers   (except  the  stack  pointer)  can  be  used  in  the 
subroutine.


IF Command

IF A<B LET X=3: PRINT 'this string'

This will test the value of the expression A<B.  If it isn't zero 
(i.e.  if it is true), the rest of the commands on this line will 
be executed.  If the value of the expression is zero (i.e.  if it 
is  not  true),  the rest of this line will be skipped  over  and 
execution continues on the next line.  Note that the word  "THEN" 
is not used.


GOTO Command

GOTO 120

Will  cause execution to jump to line 120.  Note that the  "GOTO" 
command cannot be followed by a colon and other commands. It must 
be ended with a CR.

GOTO A*10+B

Will  cause  the execution to jump to a different line number  as 
computed from the value of the expression.


GOSUB and RETURN Commands

GOSUB 120

Will cause execution to jump to line 120.

GOSUB A*10+B

Will cause execution to jump to different lines as computed  from 
the value of the expression A*10+B.

RETURN

A  RETURN command must be the last command on a line and must  be 
followed by a CR.  When a RETURN command is encountered,  it will 
cause  execution  to jump back to the command following the  most 
recent GOSUB command.
     GOSUB's can be nested with a depth limited only by the stack 
space.


FOR and NEXT Commands

FOR X=A+1 TO 3*B STEP C-1

The  variable X is set to the value of the  expression  A+1.  The 
values  of  the expressions (not the expressions themselves)  3*B 
and  C-1 are remembered.  The name of the variable  X,  the  line 
number  and the position of this command within the line are also 
remembered.  Execution then continues the normal way until a NEXT 
command is encountered.
     The step can be positive,  negative or even zero.  The  word 
STEP  and  the  expression  following it can be  omitted  if  the 
desired step is +1.

NEXT X

The  name  of  the variable X is checked with that  of  the  most 
recent  FOR  command.  If they do not agree,  then  that  FOR  is 
terminated and the next recent FOR is checked,  etc. When a match 
is found, this variable will be set to its current value plus the 
value  of  the  step expression saved by  the  FOR  command.  The 
updated  value  is  then  compared  with  the  value  of  the  TO 
expression  also  saved by the FOR command.  If this  within  the 
limit,  execution will jump back to the command following the FOR 
command.  If  this  is  outside the  limit,  execution  continues 
following the NEXT command itself.
     FOR's  can also be nested with a depth limited only  by  the 
stack space.  If a new FOR command with the same control variable 
as that of an old FOR command is encountered, the old FOR will be 
terminated automatically.


STOP Command

STOP

This  command  stops  the execution of the  program  and  returns 
control  to direct commands from the console.  It can appear many 
times  in  a program but must be the last command  on  any  given 
line, i.e. it cannot be followed by a colon and other commands.


BYE Command

Will  return  you  to the resident monitor program  or  operating 
system.  (Tutor in the case of the ECB.)


Direct Commands

As defined earlier,  a line consists of a line number followed by 
commands.  If  the  line number is missing,  or if it is  0,  the 
commands  will be executed after you have typed the CR.  All  the 
commands  described above can be used as direct  commands.  There 
are  five  more commands that can be used as direct commands  but 
not as part of a program line:

RUN

Will  start  to  execute  the  program  starting  at  the  lowest 
line number.

LIST

Will print out all the lines in numerical order.

LIST 120

Will  print out all the lines in numerical order starting at line 
120.

NEW

Will delete the entire program.

SAVE

Will save the present program on the storage device you  provide. 
Details  on installing this device are given in the source  code. 
As  set  up for the MEX68KECB Educational  Computer  Board,  this 
command  will  send  the program out to the host computer  in  an 
easily-stored text form.  It isn't, however, pure program text as 
the line numbers are stored in hexadecimal.

LOAD

Will  delete  the program in memory and load in a file from  your 
storage device.


Stopping Program Execution

The  execution  of the program or listing of the program  can  be 
stopped   by   pressing  the  control-C  key  on   the   console. 
Additionally,  a listing can be paused by pressing control-S, and 
then pressing any key to continue.


Abbreviations and Blanks

You  may use blanks freely within a program except that  numbers, 
command  key  words,  and  function names  cannot  have  embedded 
blanks.
     You  may  truncate all command key words and function  names 
and follow each by a period.   "P.",  "PR.",  "PRI.", and "PRIN." 
all stand for "PRINT".  The word LET in LET commands may also  be 
omitted.  The shortest abbreviations for all the key words are as 
follows:
A.=ABS    C.=CALL   F.=FOR    GOS.=GOSUB     G.=GOTO
IF=IF     I.=INPUT  L.=LIST   LO.=LOAD       N.=NEW
N.=NEXT   P.=PEEK   PO.=POKE  P.=PRINT       REM=REMARK
R.=RETURN R.=RND    R.=RUN    S.=SAVE        S.=SIZE
S.=STEP   S.=STOP   TO=TO
no key word = LET


Error Reports

There  are  only three error conditions in Tiny BASIC.  The  line 
with  the error is printed out with a question mark  inserted  at 
the point where the error is detected.

(1) "What?" means it doesn't understand you.  For example:

What?
260 LET A=B+3, C=(3+4?. X=4

(2) "How?" means it understands you but doesn't know how to do it.

How?
210 P?TINT "This"   <- where PRINT is misspelled

How?
310 LET A=B*C?+2    <- where B*C is larger than 2147483647

How?
380 GOTO 412?       <- where 412 does not exist

(3)  "Sorry." means it understands you and knows how to do it but 
     there isn't enough memory to accomplish the task.


Error Corrections

If you notice an error in your entry before you press the CR, you 
can delete the last character with the backspace (control-H)  key 
or delete the entire line with control-X.  To correct a line, you 
can  retype the line number and the correct commands.  Tiny BASIC 
will  replace the old line with the new one.  To delete  a  line, 
type  the  line  number  and  a  CR  only.  You  can  verify  the 
corrections to line 'nnnn' by typing "LIST nnnn" and pressing the 
control-C key while the line is being printed.