
Start of Knights manual.


Page 1***********************************************************************
          KNIGHTS MZ700 FORTH.


Loading the language tape.
---------------------------
Switch on your MZ-700 and insert the language tape in the cassette
unit.  Type L & press the CR key, then depress the play button on the
tape recorder:  "LOADING MZ-700 FORTH" appears.

"Knights MZ-700 Forth Mem=AFF 6B0B" appears when the tape stops.

# indicates that Knights Forth is ready to use in the direct mode.



TWO MODES
---------
	Forth has two distinct modes.  Text editor mode is indicated by a *
prompt.  Keywords can be built up - either by loading saved keyword 
definitions from tape, or using the editor commands to write new Forth
programs. Direct mode is indicated by a # prompt, and is used to run
programs and test keywords.


PROGRAMMING IN FORTH.
---------------------
	The essence of Forth programming lies in defining new Forth words
which use previously defined commands to perform the desired task.
Effectively the programmer tailors the language to meet his own
specifications. It is this aspect of the language that makes Forth such 
fun to use. Calculations are stack based and utilises Reverse Polish
notation (This will be explained), making programming in Forth a
challenging alternative to languages such as BASIC or PASCAL.


TYPES OF WORD IN MZ-700 FORTH
------------------------------
F0  Machine language word i.e.  the relevant procedure is defined by a 
section of machine code. The SP register of the Z80 points to the data
stack, control is passed to the interpreter again by means of the
JP(IY) instruction // addin** use $FD $E9 as last instruction on return

F1  Word defined using previously defined words and constants. Most of
the definitions you write will be of this type.

F2 Variables -  when a variable name is used the storage address is
pushed to the top of the data stack. This then allows you to store 
numeric values at that address;  the net result is similar to integer
variables in BASIC. Forth also deals with strings, when a string is 
presented to the interpreter it is stored on the data stack.as two 
integers, the first being the address inmemory where the string has 
been stored, the second is the length of the string.

F5  Constant -  similar to an integer variable, however as
the name implies the initial value on assignment remains unchanged.

F6  Forth word defined by the system.




Page 2*********************************************************************
		TEXT EDITOR COMMANDS.

The text editor uses the concept of a current line monitor.

COMMANDS
--------
B :  move line pointer to the top of the text buffer.

Tn :  list n lines from the current line without altering position of the 
current line pointer. (If n is omitted then all lines after the LP
are listed).  Lines listed in this manner can be screen edited. The 
space bar can be used to pause the listing.

Pn :  place the LP on the nth line from the top of text (when n is
omitted the LP is placed on the final line).

+n :  move the line pointer n lines forward

-n :  move LP n lines backwards.

Dn :  deletes n lines after the LP (if n is omitted then all lines after
the LP are deleted.).

I  :  inserts text immediately before LP. To end insertion of text press
CR on a blank line or else press shift and break at the same time.

Sstring :  search text after LP for string - if found, display
line and place LP on next line. If string is not located the LP is moved to the final line.

F  :  compile trext from LP onwards. As each line is compiled  it
is listed to the screen.

Wstring :  writes source text to tape with filename string.

L  :  load text from tape.

=  :  display size of source text.

!  :  exclamation mark returns Forth to run mode.

&  :  clear text buffer.

%  :  denotes a comment in Forth. Any line with this as the first
character will be ignored by the compiler.


                     ERROR MESSAGES

XXX DATA?  wORD XXX has not been defined.

EMPTY   Data stack is empty.

THEN?   There is nowhere for control to be passed to after THEN.

DO-LOOP?  Loop not closed.

BEGIN-END?  Loop not closed.

NOT   FOUND  Specified word to forgotten has not been declared.

AVAIL?  Memory error.


Page 3****************************************************************
			ARITHMATIC OPERATORS.
			---------------------

+  (plus)        F0     2nd + TOP > TOP e.g. 3 2 +
			places 5 on TOP of the data stack

-  (minus)       F0     Subtraction e.g. 3 2 -  (Top - 2nd > TOP)
			places 1 on TOP of data stack.

*  (times)       F0     Multiplication e.g. 3 2 *
			places 6 on TOP of data stack

/  (divide)      F0     Integer division e.g. 3 2 /
			places 1 on the TOP of the data stack
/M (divide-mod)  F0     Places quotient on TOP and remainder on 2nd
			e.g. 5 2 /M TOP=2 2nd=1

OR               F0     2nd or TOP is placed on TOP of data stack.
			e.g. $231 $120F OR puts $123F on TOP of stack.

AND              F0     2nd AND TOP is placed on TOP of data stack.
			e.g.  $231 $120F AND puts $201 on TOP of the
			stack.

XOR              F0     2nd XOR TOP is placed on TOP of data stack.
			e.g. $231 $120F XOR puts $103E on TOP of the 
			stack.

=  (equals)      F0     If 2nd=TOP then TOP becomes -1 else TOP
			becomes 0 e.g.  3 3 = places -1 on TOP of the
			data stack. // 0= FALSE, -1=TRUE

< (Less)         F0   	If 2nd < TOP then then top becomes -1 else TOP
			becomes 0 e.g. 2 3 <  TOP becomes -1

>  (Greater)     F0     If 2nd > TOP then TOP becomes -1 else TOP
			becomes 0 e.g. 2 2 > TOP becomes 0

MV+              F0     This command allows a block of memory to be
			moved from the address stored in 3rd top to
			the address stored in 2nd top. The size of the 
			block to be moved is stored in TOP. The + sign 
			denotes the fact that the block is to be stored 
			upwards from the new location.
			e.g.  $1000 $D000 $100 MV+ has the effect of
			moving $100 bytes starting from $1000 and
			storing them from $D000 onwards.

MV-              F0     Performs in a manner similar to MV+ except
			that the command operates downwards in memory.
			e.g. $1000 $D000 $100 MV- has the effect of
			taking $100 bytes from address $1000 downwards
			and moving them to address $D000 downwards.

@   (Fetch)      F0     Takes the value of TOP as an address and 
			places the contents of the location pointed 
			in TOP.
			e.g. @1000 @
			puts the 16 bit number stored in locations
			$1000 and $1001 in TOP.

@B               F0     As for @ except that only 1 byte is 
			transferred. The effect is similar tothe PEEK
			command in BASIC.

!  (Store)       F0     Takes a 16 bit number from 2nd and places in
			the address specified by TOP.
			e.g. $1234 $1000 !
			location $1000 will contain $34 and $1001 will
			contain $12.


Page 4******************************************************************
WORD		TYPE	USE AND EXPLANATION
----		----	-------------------
[		F6	[ W1 W2 ....Wn ] is used to define a new Forth
			language command using previously defined 
			words W1 to Wn.
			e.g. [ NEG 0 SWAP - ] defines a new forth word
			NEG which when called negates the value on TOP
			of the data stack.  NEG may then be used in
			other more important definitions. Words inside 
			the definition must be separated by either a
			space or an end of line character.  N.B. a
			right hand square bracket terminates the word
		]       definition.

M[		F6	Defines a word using machine language.
			e.g.  M[ BYE $C3 0 0 ]M defines a word  BYE
			which when used returns the computer to
			monitor by executing an instruction similar to 
		]M	the USR(0) in BASIC.

VAR		F0	Allocates 2 bytes of store to referenced by
			a variable name. The initial value of the 
			variable is taken from the TOP of the data
			stack.
			e.g. -1 VAR X will declare a variable X with 
			initial value of -1.

,	(comma)	F0	Extend the most recently defined variable or 
			any other definition by two bytes and alters the
			TOP of the stack accordingly.
			e.g. -1 VAR X 0 , defines X and extends it by
			2 bytes. As a result X is a 4 byte word and 
			has content FFFF0000 hex.

CONST		F6	Defines a constant, the value of which is
			taken to be the top of the data stack.
			e.g. 1 CONST ONE declares a constant ONE of
			value 1.
			Therefore ONE ONE + . displays 2.

FORGET XXX  	F6	Removes word XXX from the dictionary stack. Any
			words defined after the word to be forgotten
			are also removed.

.  (DOT)	F0	Removes the value from the top of the data
			stack and displays it on the screen in the 
			current base.

#.  (sharp-dot)	F0	Removes the number from the topp of the data
			stack and displays it as an unsigned base 10
			number (0 to 65535)
			e.g. -1 #. will display 65535

$.		F0	Removes the value from the TOP of the
			data stack and displays as an unsigned base 16
			number in the range (0-FFFF).

S.		F0	Prints a string to the screen. The top of the 
			data stack must contain the address of the
			string, and 2nd TOP the length of the string.
			Format is " string...." S.

LF		F6	Outputs a line feed to the screen.

?		F6	Prompts for integer input and adds it to the
			data stack. If the user input is not of the
			correct type it is ignored and the procedure
			will be repeated.

GETKY		F0	Scans keyboard & places the ASCII code of the key
			pressed on the data stack. 0 indicates no key.

Page 5******************************************************************

!B		F0	Takes 1 byte from 2nd and places in the 
			address specified by top. Like a BASIC POKE.

LOOP STRUCTURES
----------------

IF  (ELSE)	F6	IF (treatment when TOP<>0) ELSE
THEN			(treatment when top =0) THEN
			e.g. 0 > IF "PLUS" ELSE "NOT PLUS" THEN S.
			when TOP is positive the word "PLUS" is 
			displayed, otherwise "NOT PLUS" is displayed.

F.IF  (ELSE)	F6	IF (treatment when TOP = 0) ELSE
THEN			(treatment when TOP <> 0) THEN.
			e.g.  F.IF "ZERO" S. THEN
			When TOP is zero, "ZERO" is displayed.

DO..LOOP	F6	Take the contents of TOP as the initial value,
			2nd as the final value and repeatedly execute 
			the section of code in between the words DO
			and LOOP, incrementing the counter on top of
			the return stack until such time as it is 
			equal to the final value. This performs in a
			manner similar to the FOR-NEXT loop in BASIC.

BEGIN..END	F6	If TOP is 0 on reaching END jump back to BEGIN
			and repeat the section of code.
			e.g. BEGIN GETKY END will wait until the user
			presses a key

I		F6	Used within a DO..LOOP section, this command
			copies the current value of the loop counter 
			(which lies on the top of the return stack) on to
			TOP.
			e.g. 10 0 DO i . LOOP if used within a Forth
			word will output 0123456789

J		F6	Also used within a Forth word, this command
			has the effect of copying the 2nd top of the
			return stack on to TOP. TOP will then contain
			the upper value of the loop section.

PE		F2	Var which points to compile address of new word.


GRAPHIC COMMANDS
----------------

SETG		F0	sets the screen at position x=2nd and y=TOP
			e.g. 30 24 SETG is like set 30,24 in BASIC.

RESG		F0	Resets the screen at x=2nd and y=TOP.
			e.g. 30 24 RESG is like RESET 30,24 in BASIC.

LINE 		F0	Draws a line between two points on the screen.
			e.g. 0 0  79 79 LINE draws a diagonal line 
			between (0,0) and (79,79)

VRCL		F0	These commands are designed to allow the 
VRMV		F0	animation of pictures. VRCL reserves an area
			of memory into which all subsequent SETG,RESG
			and LINE commands are directed. A picture can 
			then be built up as though setting points on
			the screen. VRMV will then copy the entire
			picture on to the screen giving the impression
			of a quick change. After VRMV the graphics
			commands are restored.

LIMIT		F6	Changes bottom address of data and return
			stacks. 2nd gives the bottom address of the
			data stack, TOP gives the bottom address of
			the return stack. After LIMIT the data and
			return stacks become empty and the interpreter
			is initialised.

Page 6****************************************************************

CORDR		F0	Coordinate rotate - if :
			3rd contains value X
			2nd contains value Y
			TOP contains value Z
			Then if (x,y) are the coordinates of a point
			and Z is twice an angle theta, then the values 
			returned after CORDR are called are :

			TOP contains Y'
			2nd contains X'

			Where  (X',Y') are the coordinates of the
			point rotated through theta degrees. The 
			transformations themselves are:
				X*COS(Z/2)-Y*SIN(Z/2) into 2nd

				X*SIN(z/2)+Y*COS(Z/2) into TOP

CORDV		F0	Assuming X,Y,Z as before then if Z is zero and
			(X,Y) are the coordinates of a point then the
			values returned are the polar coordinates of
			the point expressed as (theta,R) where theta
			is the angle and R is the radius from the
			origin to that point.
			The transformations themselves are:
			X + Y into 2nd
			Z +2 * (TAN (Y/X)) into TOP.
			NB. X must not be negative.
			Top contains 2* theta.


STACK OPERATORS.
----------------
For all the following operations the stack is assumed to be as per
Diagram initially                    1       Top
				     2       2nd
				     3       3rd
				     4       4th
				     5       5th

STK		F6	Writes out the contents of the stack without
			alteration.
			e.g. STK outputs 1 2 3 4 5

CLR		F0	Clears the stack.

DUP		F0	Duplicates TOP
			e.g. DUP STK gives 1 1 2 3 4 5 

DDUP		F0	Duplicates TOP and 2nd.
			e.g. DDUP STK gives 1 2 1 2 3 4 5

OVER		F0	Duplicates 2nd
			e.g. OVER STK gives 2 1 2 3 4 5

2OVER		F0	Duplicates 3rd
			e.g. 2OVER STK gives 3 1 2 3 4 5

3OVER		F0	Duplicates 4th
			e.g. 3OVER STK gives 4 1 2 3 4 5

SWAP		F0	Swaps TOP and 2nd.
			e.g. SWAP STK gives 2 1 3 4 5

DROP		F0	Removes TOP
			e.g. DROP STK gives 2 3 4 5

ROT		F0	Transfers Bottom to TOP
			e.g. ROT STK gives 5 1 2 3 4


Page 6****************************************************************

WORD 		TYPE 	EXPLANATION
----		----	----------

SAVE		F6	saves the Forth dictionary stack to tape using
			named files.
			e.g. SAVE KNIGHT DEMO

LOAD		F6	Load the next object file from tape. The
			filename is not checked.

VERI		F6	Verifies successfull saving of a tape program.
			If OK then no message is displayed, otherwise 
			the VERIFY ERROR is displayed.

REG		F6	Points to an area of memory where parameters
			for passing values to the Z80 registers can be
			located.
			The arrangement is REG F A C B E D L H

USR		F6	Jump to machine code subroutine at address
			pointed to by TOP. On calling, AF BC, DE and
			HL of REG are transferred across to the Z80
			registers, on returning, the contents of the 
			registers are transferred to REG.
			e.g. REG 1 + CONST AREG defines the address of
			the A register argument location.
			$30 AREG !B USR puts $30 into the A register
			argument location and calls the subroutine
			starting at address $12.

APLY		F6	Treats the character in quotes as a binary
			operator on TOP and 2nd.
			e.g. 3 4 "+" APLY is equivalent to 3 4 +.

BASE		F2	Address in memory where the current base for
			mathematical calculations is stored. Only the
			lower byte of TOP is significant.
			e.g. $10 BASE ! puts the micro into base 16.

SP		F5	Address in memory where bottom address of
			return stack is located.

DS		F5	Address where bottom of the data stack
			is located.

TXT		F6	Return to editor mode.


REVERSE POLISH NOTATION.
------------------------
Forth use RPN for mathematical calculations. RPN is easy to learn.
All numbers are stored on the data stack, when a binary operator (such
as + or * ) is encountered, Forth takes both operands off the TOP of
the data stack, performs the calculation and then pushes the result
back on TOP.  Once learned, it is very easy to use and dispenses with
the need for the parenthesis that conventional infix notation requires.

In addition to the MZ-700 Forth language itself, we supply 10 programs
to demonstrate some of the features of Forth programming.

To load the programs follow these steps.

1)  Type TXT and press CR to get into editor mode.
2)  Type & and press CR key to clear the edit buffer.
3)  Type L and press CR to load the program into memory.
4)  Once loading has finished, type F and then press CR to compile the 
program. The text will list to the screen as compilation occurs. Some 
of the programs add new commands, others demonstrate Forth
capabilities. Once compiled press ! and CR to enter run mode. Programs
will start as soon as you enter the appropriate keyword and press CR.

*********************End of supplied documentation.************************
EXTRA commands

The following  are extra words

1.  clearscreen
	[ CLS "C" S. ]  the "C" used is the Sharp inverse c.

2.  Jump to monitor, same as SBASIC bye
	[ BYE $0 USR ]
	or
	M[ BYE $c3 0 0 ]M

3.  Time delay same as SBASIC wait
	[ WAIT 0 DO $996 USR LOOP ]
	This word is used as   n WAIT where n can be any integer number.

4.  The Forth word EMIT is defined as follows.
	[ EMIT REG 1 + ! $12 USR ]
	e.g. typing in 65 EMIT will give back the ASCII code of 65

5.  The Forth word SPC or spaces is defined as follows.
	[ SPC 0 DO $C USR LOOP ]
	Format used is  3 SPC, this will print 3 spaces.

6.  The Forth word NOT is as follows
	[ NOT $FFFF XOR ]

7.  To obtain greater than or equal
	[ >= < NOT ]

8.  To obtain less than or equal
	[ <= > NOT ]

9.  The word VLIST is as follows
	[ VLIST $1506 @ @ BEGIN DUP 2 + @B DUP @OVER 3 + S. "(" S.
	over + 3 + @B $. ")" S. @ DUP @ -1 = END DROP ]
10. To set the cursor to any position on screen.
	[ CUR $1172 !B $1171 !B ]
	the screen coordinates must be on the stack to work.
	e.g. 12 20 CUR.
11. If you do not like the [ and ] then change the address
	$1D65 from $5B to $3A and the address $1DfE from $5D
	to $3B. This will change the [ required to : and the
	] will then be ; which is more like standard Forth.





