[net.sources] Princeton FORTH v2.0 for the VAX, part 3 of 8

wls@astrovax.UUCP (William L. Sebok) (06/26/84)

Part 3 of 8
---------Cut here and extract with sh not csh---------------
mkdir ./doc
/bin/echo 'Extracting ./doc/forth2'
sed 's/^X//' <<'//go.sysin dd *' >./doc/forth2
<#								169
	Initialize pictured numeric output.  The words:

		<#  #  #S  HOLD  SIGN  #>

	can be used to specify the conversion of a double integer into an
	ASCII character string stored in right-to-left order.  pronounced
	"sharp-less".

<:								Local
	Switches from compiling a CODE definition to compiling a higher lever
	Forth.  Sets the CONTEXT to the CURRENT vocabulary, sets compile
	mode, and, if necessary, compiles the code to do the context switch
	(unnecessary on the Vax). The definition can be ended normally with
	; .  If  <: and :> are used to execute a word inside a CODE definition
	saving needed registers (other than stack pointers) is the caller's
	responsibility.   See :>

<=		n1 n2  ---  flag				Local
	True if `n1' is less than or equal to `n2'.

<>		n1 n2  ---  flag				Local
	True if `n1' is not equal to `n2'.

<ASK		---  str_s					strings
	Read the input stream and return the contents of the next line (i.e.
	up to the next carriage return or line feed) on the string stack.
	The trailing delimiter is not included and initial spaces and tabs are
	removed.
	<ASK is intended for use in the construction of words that read the
	input stream and return the number.  It is intended to be followed
	by a word which converts the returned string into a number.

<C@		addr  ---   n					local
	Access the character contained at address `addr' sign-extending it
	to fill a stack cell.
	
<KEY								Local
	Set terminal into raw mode no-echo in which each character typed
	from the keyboard is passed immediately to the user's program.

<SCAN		offset_l descr  ---				unix-interface
	Cause the standard input to be taken from the file pointed to by file
	descriptor `descr'.  Reading of this file starts at offset `offset_l'.
	This input diversion is ended by the word  SCAN> . <SCAN  ...  SCAN>
	pairs can be nested.

<W@		addr  ---  n					local
	Access the 16-bit integer contained at address `addr' sign-extending
	it (if necessary to fill a stack cell.

=		n1 n2  ---  flag				173
	True if `n1' is equal to `n2'.  "equals"

>		n1 n2  ---  flag				102
	True if `n1' is greater than `n2'.  "greater-than"

>#		---
	Close diverted standard output and resume sending of standard output
	to the terminal.

>=		n1 n2  --- flag					Local
	True if `n1' is greater than or equal to `n2'.

>>FILE		file_s  ---
	Append forth's standard output to the end of file `file_s' (creating it
	if it does not already exist).

>DESC		desc ---
	Divert forth's standard output to file descriptor `desc'.

>FILE		file_s  ---
	Create or truncate to zero length file `file_s' and divert forth's
	standard output to that file.

>IN		---  addr				U,201
	Leave the address of a variable which contains the present character
	offset within the input stream {{0..1023}} "to-in"

	In this implementation >IN contains the byte offset within the
	buffer which holds the current piece of the input stream. Pointer >LOC
	holds the current offset of the beginning of that buffer within the
	input stream.

>LOC		---  loc					U,local
	Returns a variable containing the offset into a the text-type file
	currently being interpreted.  This offset is an L-type (32-bit) integer
	(requiring 2 cells of storage on a 16 bit machine, 1 cell on a 32 bit
	machine).

	In a call to BLOCK in this implementation:

		block numbers >= (unsigned) CHANBOT are channel numbers of open
		(not necessarily block or screen format) text files.  A call to
		BLOCK on one of these block numbers returns a buffer containing
		1024 bytes read from the file whose file descriptor is
		n - CHANBOT from a position in the file whose byte offset from
		the beginning of the file is contained in the L-type (32-bit)
		user variable >LOC .

>R		n  ---						C,200
	Transfer  `n'  to the return stack.  Every >R must be balanced by
	a R> in the same "DO-LOOP" nesting level of a colon definition.

>WRD<		n1_l  ---  n2_l					local
	Interchange the two 16 bit components of the 32-bit integer on the
	stack.  The 32-bit integer consists of as many stack cells as needed
	to hold a 4-byte number (2 on a 16-bit machine, 1 on a 32-bit machine).
	This operation is identical to a SWAP on a 16-bit machine.

?		addr  ---					194
	Display the (integer) number at address `addr', using the format of "."
	"question-mark".

?;S		---						Local
	Used in expressions of the form:

		?;S name

	If `name' is present interpretion of the current input screen or file
	is terminated, resuming interpretation of previous input stream.
	Otherwise interpretation of the present input screen or file continues.

	Typically ?;S will be used at the beginning of a file containing a
	software package.  `name' will be the name of one of the words defined
	in that package.  Thus the presence of ?;S will guarantee that one
	can request the Loading of this package whenever it is needed, without
	the worry that multiple copies of this package will be loaded.  This
	effect can also be achieved by loading files with ?FLOAD or ?LOADF.
	
?>WRD<		n1_l  ---  n2_l					local
	Interchange the two 16 bit components of the 32-bit integer on the
	stack if the machine does not store them in the canonical order of
	high order part at the lower address.  This word is a no-operation
	otherwise.  The 32-bit integer consists of as many stack cells as needed
	to hold a 4-byte number (2 on a 16-bit machine, 1 on a 32-bit machine).
	An example of a machine for which this word is not a no-operation is
	the VAX.

?CON		 ---						local
	A defining word used in the form:

		n ?CON <name>

	If <name> has not already been defined ?CON behaves like CONSTANT,
	creating a dictionary entry for <name>,  leaving  `n' in its parameter
	field.  When <name> is later executed,  `n' will be left on the stack.

	If <name> has already been define `n' is simply popped and no
	definition is created.

	Thus ?CON can be used to create compile time adjustable parameters.
	The parameter `n' to ?CON behaves like a default that can be overridden
	by previously defining a CONSTANT with that name but some other value.

?DUP		n  ---  n  ( n )				184
	Duplicate  `n'  if it is non-zero  "query-dup"

?FLOAD		---						unix-interface
	Conditionally load the contents of a file.  Used in a command of the
	form:

	?FLOAD wordname filename

	A check is made to see if `wordname' is present in the forth dictionary
	(starting the search at the usual CONTEXT vocabulary).  If `wordname'
	is not present the contents of file `filename' is LOADed.

	  The forth interpreter will start to interpret the contents of file
	`name'.  This file can either be a regular text file (i.e. lines
	separated by newlines), or a forth screen-format file (constant width
	lines of 64 characters).  LOAD's, FLOAD's,  and LOADF's can nest to
	any level (or at least until return stack overflow).
	  Note: words that grab a string from the input stream cannot be
	guaranteed to work if the word and its string are separated by the end
	of a line.
	  It will first try to find the file in the current directory.  If that
	fails it will try the FORTH library directory (i.e. the directory
	defined by the string SDIR).  If the file name begins with a '<' (i.e.
	a less-than symbol) the '<' character is stripped off and only the
	FORTH library directory is searched.  If everything fails an abort is
	taken.
	NOTE: need to implement a search path.
	  `wordname' will typically be a word whose definition is in `filename'.
	Forth words are usually organized into sets of related packages.  One
	package may need some words a present in another package. ?LOADF allows
	a package to load words it needs without worrying whether some other
	package may have already loaded those words.

	Implementation note:  FLOAD is implemented using the CHANBOT mechanism
	of BLOCK.  The current byte offset within the file is kept in user
	variable >LOC.  Making FLOAD's able to nest was a real pain.
		
?LOADF		---						unix-interface
	Conditionally load a screen-format file.  Used in a command of the form:

	?LOADF wordname filename

	A check is made to see if `wordname' is present in the forth dictionary
	(starting the search at the usual CONTEXT vocabulary).  If `wordname'
	is not present the contents of file `filename' is LOADed.
	 The file `filename' is first opened read/only and installed at an
	automatically range of block numbers (using -INSTALL ).  Then the
	file is LOADed (using LOAD ).  Finally the file is REMOVEed from the
	block allocation table (using REMOVE ).
	  It will first try to find the file in the current directory.  If that
	fails it will try the FORTH library directory (i.e. the directory
	defined by the string SDIR).  If the file name begins with a '<' (i.e.
	a less-than symbol) the '<' character is stripped off and only the
	FORTH library directory is searched.  If everything fails an abort is
	taken.
	NOTE: need to implement a search path.
	  `wordname' will typically be a word whose definition is in `filename'.
	Forth words are usually organized into sets of related packages.  One
	package may need some words a present in another package. ?LOADF allows
	a package to load words it needs without worrying whether some other
	package may have already loaded those words.
		
?OPEN		fil_s iomode ---  fildes 			unix_interface
	Tries to open file `fil_s', searching in various places. `iomode' is
	the file mode == 0 read only, 1 write only, 2 read/write.  In each case
	if `iomode' is 2 (read/write) it will also try to open it read only if
	the initial open attempt fails.
	It will first try the current directory.  If that fails it will try
	the FORTH library directory (i.e. the directory defined by the string
	SDIR).  If the file name begins with a '<' (i.e. a less-than symbol)
	the '<' character is stripped off and only the FORTH library directory
	is searched.  If everything fails -1 is returned and the error number
	is contained in User variable ERRNO.
	NOTE: need to implement a search path.

?UERMSG		---						Unix-interface
	Check the contents of user variable ERRNO and print a message if it is
	non-zero.  ERRNO contains the status returned by the last Unix system
	call.

?UERROR		---						Unix-interface
	Check the contents of user variable ERRNO and abort with a message if
	it is non-zero.  ERRNO contains the status returned by the last Unix
	system call.

?VECT		cnt addr  ---					local

	Check the consistency and legality of an attempt to move data into
	a VECT.  No actual moving of data is done.  A check is made that
	`addr' points to a VECT and that this VECT contains sufficient space
	to accomodate `n' bytes.  If either condition is not met an error
	condition exists and an abort is taken.  

	  VECT and ?VECT can be used to create commands used by naive users
	that store data in an array specified by the user.  Then the common
	mistake of specifying an invalid array or specifying the wrong number
	of arguments to the command will not bring down Forth.
	`addr' - 1*wordsize  is set to `cnt', in effect marking the number of
	bytes currently in this VECT.

@		addr  ---  n					199
	Leave on the parameter stack the number contained at addr. "fetch"

@++		addr  ---  addr2  n				local
	Leave on the parameter stack the word-length value contained at address
	`addr' above the value of `addr' incremented by one word-length.

@EXPON		fl_f  ---  fl_f  n				floating
	Extracts the base 2 exponent from floating point number `fl_f'
	( = log2(fl_f) + 1 ) and returns it on the parameter stack without
	disturbing `fl_f'.

A+		addr1 n  ---  addr2				Local
	Multiply `n' by the integer cell size and add to address `addr1'  (i.e.
	construct the address of the `n'th integer cell beyond `addr1').

A-		a1 n  ---  a2					Local
	Subtract word offset n from address a1, i.e., multiply `n' by the word
	length in bytes and subtract from address `a1'.

A1+		a1  ---  a2					Local
	Increment address `a1' by one word-length, i.e., add the word length in
	bytes to address `a1'. 

A1-		a1  ---  a2					Local
	Decrement address `a1' by one word-length, i.e., add the word length in
	bytes to address `a1'. 

ABORT								101
	Abort what is currently being executed and do a general system reset.
		Standard Resets:
	1) Reset all stacks.
	2) Set execution mode. 
	3) Return control to the terminal (set TYPER to TYPER0).
		Additional resets in this implementation:
	4) Reset the current message buffer MSGBUF to the normal MSGBUF0
	5) If coprocess support is enabled reset the buffer lock count to 1.

ABS		n1  ---  n2					108
	Leave the absolute value of a number. "absolute"

ALIGN		---						local
	Conditionally increments the dictionary pointer to make the dictionary
	pointer conform to the machine's most stringent alignment requirements
	(aligns to the next 4 byte boundary on the VAX).

ALLOT		n  ---						154
	Add `n' bytes to the parameter field of the most recently defined word.
	In the Unix implementation the break (boundary of accessible memory)
	is adjusted to accommodate the added bytes. 0 ALLOT can be used to
	guarantee that the break is consistent with the current dictionary
	pointer.

AND		n1 n2  ---  n3					183
	Leave the bitwise logical 'and' of `n1' and `n2'.

ARRAY		n  ---						local
	Used in definitions of the form
		n ARRAY xxx
	To define an area of memory `n' words in length.  When `xxx' is
	executed it will place its address on the parameter stack.  The
	contents of this memory is cleared.

ASK		---  num_X  flag				local
	A number is read from the input stream up to the next trailing blank
	or tab and is returned on the stack as `num_X'. `flag' is false (0) if
	the number was valid and true (1) if the number was invalid.
	The identity of `num_X' is implementation dependent.  It is intended
	that num_X be the full precision used in the character to number
	conversion, and that information about the type of number intended,
	position of the decimal points, etc. be available in the implementation
	dependent variable DPL. 
	  On the VAX num_X is a double length (8 byte) integer.
	  For more information on the information contained in DPL, see
	 CONVERT.

ASK>		num_2 flag  ---  0				strings
	if flag = 0 
		num_2 flag  ---  num_2 1
	if flag != 0

	Test the value of `flag'.  If `flag' is true (flag not equal to zero)
	pop the double integer `num_2' and return 0 for false on the parameter
	stack and type "Bad Number<CR>Try again:".  If `flag' is  false (equal
	to zero) retain the double integer `num_2' on the parameter stack and
	return a 1 for true above it on th parameter stack.

	Thus the flag returned by ASK> is the logical NOT of the flag passed
	to it.

	ASK> is intended for use in the construction of words that read the
	input stream and return the number.  It will generally be followed
	directly by the UNTIL of a BEGIN ... UNTIL loop surrounding the
	conversion process.

ASSEMBLER							I,166
	Select assembler as the CONTEXT vocabulary.

ASSIGN		addr ---					old
	Used in a construction of the form:
		: xxx  ...    var ASSIGN ... ... ;
	When word `xxx' is executed the code address of the words following
	ASSIGN address is placed in variable `var' and a exit from `xxx' takes
	place.  Then these words can be later executed by the command
		var @ EXECUTE

ATOF		str_s  ---  result_f flag			strings
	Convert and pop string on string stack to single precision floating
	point number.  Result is left on the floating point stack. A flag is
	left on the parameter stack which is false for a successful conversion
	and true for a bad conversion.

ATOI		str_s  ---  result flag				strings
	Convert and pop string on string stack to word length signed integer.
	Result is left on parameter stack with a flag above which is false for
	a successful conversion and true for a bad conversion.

ATOL		str_s  ---  result_l flag			strings
	Convert and pop string on string stack to double length signed integer.
	Result is left on parameter stack with a flag above which is false for
	a successful conversion and true for a bad conversion.

B!+		addr  n  ---  addr2				local
	Store byte `n' into the memory location pointed to by address `addr',
	leaving on the parameter stack the value of `addr' incremented by one.

B.BLKTAB	--- addr					Local
	Word array which contains the block number into which is mapped the
	first block of a file in the block mapping table.

BASE		---  addr				U,115
	Leave the address of a variable containing the current input-output
	conversion base. {{2..70}}

BEGIN								I,C,147
	Used in a colon-definition in the forms:

	BEGIN  .  .  .  flag UNTIL	or
	BEGIN  .  .  .  flag WHILE .  .  .  REPEAT

	BEGIN marks the start of a word sequence for repetive execution.
	A BEGIN-UNTIL loop will be repeated until `flag' is true.  A BEGIN-
	WHILE-REPEAT loop wil be repeated until `flag' is false.  The words
	after UNTIL or REPEAT will be executed when either loop is finished.
	The `flag' is always dropped after being tested.

BELL								local
	Transmit an ASCII bell character to the current output device.

BINARY								local
	Set the input-output numeric conversion base to two.

BLFREE		len  ---   start				Unix-interface
     Finds free space in block mapping table.  If `len' blocks are required it
     finds the first unmapped set of block numbers of size at least equal to
     `len'  ( first fit algorithm ). The block number of the start of this
     extent is returned as `start' (used by INSTALL).

BLK		--- addr				U,132
	Leave the address of a variable containing the number of the mass
	storage block being interpreted as the input stream.
	If the contents is zero, the input stream is taken from the terminal.
	If the contents is greater than (unsigned) CHANBOT the then
	(contents - CHANBOT) is a unix file descriptor.

BLKTAB		---							local
	Type out the contents of the block mapping table. A typical printout
	might be

	Chan   Start     End
	   3       0      54
	   5     100     105

	Which means that two extents of block numbers are defined, those from
	0 to 54 and those from 100 to 105.  All other block numbers are
	undefined.  The extent from 0 to 54 goes through file descriptor 3 and
	the extend from 100 to 105 goes through file descriptor 5.

BLOCK		n_u --- addr					191
	Leave the address of the first byte in block `n_u'.  If the block is not
	already in memory, it is transferred from mass storage into whichever
	memory buffer has been least recently accessed.  If the block occupying
	that buffer has been UPDATEd (i.e. modified), it is rewritten onto mass
	storage before block n is read into the buffer.  `n_u' is an unsigned
	number.  If correct mass storage read or write is not possible, an
	error condition exists.

	In this implementation:

	1)	block numbers <  (unsigned) CHANBOT are mapped into files using
		the block mapping table.  With the block mapping table files are
		mapped into extents of block numbers.  Block numbers in between
		these extents are undefined and references to these block
		result in an error condition.

	2)	block numbers >= (unsigned) CHANBOT are channel numbers of open
		(not necessarily block or screen format) text files.  A call to
		BLOCK on one of these block numbers returns a buffer containing
		1024 bytes read from the file whose file descriptor is
		n - CHANBOT from a position in the file whose byte offset from
		the beginning of the file is contained in the L-type (32-bit)
		user variable >LOC .

	3)	block number = -1  is a null or empty block.

BUFFER		n --- addr					130
	Obtain the next block buffer, assigning it to block `n'.  The block is
	not read from mass storage.  If the previous contents of the buffer has
	been marked as UPDATEd, it is written to mass storage.  If correct
	writing to mass storage is not possible, an error condition exists.
	The address left is the first byte within the buffer for data storage.
	`n'  is an unsigned number.

BUFS		--- n						Local
	Returns the number of disk buffers in existence.

BYE							Local (non-stand-alone)
	FLUSH buffers and exit to the operating system.

BYTE		n1  ---  n2					Local
	Convert a word offset to a byte offset, i.e. multiply by 2 or 4,
	whichever is the word length in bytes.

C!		n  ---  addr					219
	Store the least significant 8 bits of n at addr.  "c-store"

C,		n ---						VAX
	Allot a byte in the dictionary, storing  `n'  there.

C@		addr  ---  byte					156
	Leave on the stack the contents of the byte at addr (with the higher
	bits of the word-length stack entry padded with zeroes). "c-fetch"

CA+		addr1 n  ---  addr2				Local
	Multiply `n' by the size of a character in bytes (1 on most machines)
	and add to address `addr1'  (i.e. construct the address of the `n'th
	byte beyond `addr1').

CA1+		a1  ---  a2					Local
	Increment address `a1' by the size in bytes of 1 character.  This is 1
	on most machines.

CASE		n m --- n  (if n != m ) or			local
		n m ---    (if n == m )
	Used in the construnction:

		n m CASE  ....   THEN	or
		n m CASE  ....   ELSE  ....  THEN

	`n' is compared to `m'. If the are equal, both are dropped and the true
	clause is executed.  If they are not equal `m' is dropped and the ELSE
	clause (if present) is executed.

CD		---						Unix-interface	

	Switch to a new current directory.  Used in a definition of the form:
		CD  name
	which will make the current directory be directory `name'.  The ~
	notation (standing for one's or someone else's home directory) is not
	(yet) recognized.

CDOES>		delim  ---					I,C,strings

	Used in definitions of the form:

		: <name> . . .   delim CDOES>  . . . ;  IMMEDIATE

	If <name> is executed directly by the outer interpreter, a character
	string is obtained from the input stream up to the appearance of the
	character whose ASCII value is `delim'. Then the words following
	CDOES> are executed with this string on the string stack. Or, if
	<name> appears in a definition, CDOES> obtains a character string from
	the compile-time input stream up to the delimiter, and compiles this
	string into the dictionary.  Then when the word containing the
	reference to <name> is executed, the words after CDOES> will be
	executed with the compiled string on the string stack.  CDOES> is used
	to make words which obtain strings from the input stream and have an
	identical appearance when they appear in definitions.  (Implementation
	note: at present, strings longer than 5 characters are kept in a
	temporary file on disk.)

CHANBOT								Local
	The offset added to file descriptor numbers to turn them into
	the false "block numbers" used to enable this Forth implementation
	to use a regular text format file as its input stream.

CLEAR		addr n  ---					local
	Stores 0 into the array of `n' words beginning at address `addr'.

CMOVE		addr1 addr2 n ---				153
	Move the specified quantity `n' of bytes beginning at addr1 into memory 
	t addr2.  If `n' is zero or negative nothing is moved.
	Local modification:  If addr1 > addr2 then the first byte of addr1 is
	moved first, otherwise the last byte (`n'th) of addr1 is moved first.
	Thus, moves between overlapping fields are properly handled.

CODE								111
	A defining word used in the form:

		CODE <name> ... END-CODE

	to create a dictionary entry for <name> to be defined by a following
	sequence of assembly language words.  ASSEMBLER becomes the context
	vocabulary.
	(Vax note:  When <name> is compiled a reference to <name> (essentially
	a subroutine call) is compiled into the dictionary).

COM		n2  ---  n1					local
	Return the one's complement of `n1'.

COMPILE								C,146
	COMPILE is used in a word (call it Word A) which is used in the
	construction of a dictionary entry for another word (call it Word B),
	to compile a reference to a third word (Word C).
	When a word (word A) containing COMPILE executes, a reference to the
	word (Word C) whose reference in Word A follows the reference to COMPILE
	in Word A, is compiled into the dictionary as part of the definition of
	Word B which under construction.
	i.e. COMPILE DUP will compile into the dictionary a reference to DUP.

	(Vax Implementation) COMPILE knows about the in-line bit.  For example,
	in the above example, since DUP is an in-line word, the machine language
	instruction which duplicates a stack entry is compiled directly into
	the dictionary.

CON		n ---						Local
	An synonym for CONSTANT.

CONNECT		descr  ---				input/output control
	Set the file descriptors in the input/output structure currently
	pointed to by user variable TYPER to `descr'.

	The file descriptor for standard output is placed one integer cell
	beyond the address of the structure  (at structure + 4 on the VAX).

	The file descriptor for standard input is placed two integer cells
	before the address of the structure  (at structure - 8 on the VAX).

CONSOLE		---					standard input/output
		control block for console --> TYPER
	Make Forth's "standard output" go to terminal.  The address of the
	control block for the normal unix standard output is placed in user
	variable TYPER.

CONSTANT	n ---						185
	A defining word used in the form:

		n CONSTANT <name>

	to create a dictionary entry for <name>,  leaving  `n' in its parameter
	field.  When <name> is later executed,  `n' will be left on the stack.

CONTEXT		---  addr				U,151
	Leave the address of a variable specifying the vocabulary in which
	dictionary searches are to be made, during interpretation of the input
	stream.

CONVERT		in_2 addr1  ---  out_2 addr2			195
	Convert to the equivalent stack number the text beginning at `addr1+1'
	with regard to BASE.  The new value is accumulated into the double
	integer `in_l', begin left as `out_l'.  `addr2' is the address of the
	first non-convertible character.

COPYS		in out count  ---				local
	Copy `count' forth screens from an extent of screens starting at block
	number `in' to the extent starting at block number `out'.  If in > out
	the copy occurs from first block to last block.  If in < out the copy
	occurs from last block to first block.  Thus the copy takes place
	correctly even if the input and output extents overlap.  BEWARE, THIS
	IS A VERY DANGEROUS WORD.

CORE		---  n						local
	Return the amount of free memory available.
	core = (stack bottom) - (here) - (size of PAD).
	BUGS: useful on PDP11 implementation but not terrifically useful
	on VAX.  Should be made on VAX to know about virtual memory quotas.

COUNT		addr   ---  addr+1 n				159
	Leave the address `addr+1' and the character count of text beginning at
	`addr+1.'  The first byte of addr must contain the character count `n'.
	Range of n is {0...255}.

CR								160
	Cause a carriage-return and line-feed to occur at the current output
	device. "c-r"

CREATE								239
	A defining word used in the form:

		CREATE <name>

	to create a dictionary entry for <name>, without allocating any
	parameter field memory.  When <name> is subsequently executed, the
	address of the first byte of <name>'s parameter field is left on
	the stack.

CSH		---						unix-interface
	Shell escape.  The c-shell is invoked as a subprocess.  The forth
	process sleeps until the exit of this shell.  Terminal modes are reset
	to the system default and interrupts and quits are set to ignored
	before invoking the shell.

CSTAT		--- val						unix-interface
	Puts a value on the stack equal to octal 666.  Intended to be used to
	supply a standard "mode" value for $CREATE.

CURRENT		---  addr				U,137
	Leave the address of a variable specifying the vocabulary into which new
	word definitions are to entered.

D+		n1_2 n2_2  ---  n3_2				241,dbl_int
	Leave the arithmetic sum of double integers `n1_2' plus `n2_2'. "d-plus"

D+!		n_2  addr  ---					local
	Add double integer `n_2' to the double integer value at the address.
	"d-plus-store"

D-		n1_2  n2_2  ---  n3_2				double_int
	Subtact double integer `n2_2' from double integer `n1_2' and leave the
	result in double integer `n3_2'.

D.		n_2  ---					double_int
	Display double integer `n_2' converted according to BASE in a free-field
	format, with one trailing blank.  Display the sign only if negative.
	"d-dot"

D.R		m_2  n  ---					double_int
	Display double integer `m_2' converted according to BASE, right aligned
	in an `n' character field.  Display the sign only if negative.
	"d-dot-r".

D0=		n_2  ---  flag					double_int
	Leave true if `n_2' is zero.  "d-zero-equals"

D<		d1_2 d2_2  ---  flag				244,double_int
	True if `d2_2' is less than `d2_2' (signed double integer compare)
	"d-less-than"

D=		n1_2  n2_2  ---  flag				double_int
	True if double integer `n1_2' equals `n2_2.' "d-equal"

DABS		n1_2  ---  n2_2					double_int
	Leave as a positive double integer `n2_2', the absolute value of a
	double integer `n1_2'. "d-abs"
DAREA		---  darea					U,local
	Returns a variable containing a pointer to an area of memory
	controlling the block buffers.

DBLE		n --- m_2					local
	Sign extend integer `n' to double integer `m_2'.

DECIMAL								197
	Set the input-output numeric conversion base to ten.

DEFINITIONS							155
	Set CURRENT to the CONTEXT vocabulary so that subsequent definitions
	will be created in the vocabulary previously selected as CONTEXT.

DEPTH		--- n						238
	Leave on the parameter stack the number of the words (not counting `n')
	contained on the parameter stack.

DETAB		in_s  ---  out_s				strings
	Expand tabs to spaces in string on top of string stack. Tab stops are
	set every 8 spaces.

DEVICE		n  ---					input/output control	
	used in definitions of the form:

	n DEVICE <name>

	Defines a structure to be used for forth standard input/output.
	When "name" is executed the address of this structure is placed
	in the the user variable TYPER.  It is assumed that the the word at
	this address contains a pointer to the code address of a forth routine
	that will handle output.  If this "device" is intended for input (i.e.
	if it is intended that this control block can be later placed in user
	variable READER ) then the word before the address of the structure
	must contain a code address of the forth routine that will handle
	input (i.e. this structure has at least one entry with a negative
	offset).

	The input/output routines are called with the parameters

		bufaddr count struct  ---

	Where `bufaddr' is the address from which input/output is to occur
	`count' is the number of characters to read/write and struct points
	to the structure discussed here.

	`n' is the number of words between the physical beginning of the
	structure and the given address of the structure. Thus, space for
	negative offsets can be reserved.  It is intended that 0 and positive
	offsets be used for output items and negative offsets for input items.

	No actual memory is reserved although the structure must immediately
	follow the definition.  Memory must be reserved with the , (comma) or
	ALLOT operators.

DISCONNECT	---					input/output control
	Close the output file descriptor in the input/output structure currently
	pointed to by user variable TYPER.  Set its value to the null value
	-1.  Replace the contents of TYPER with the contents of user value
	TYPER0 (i.e. reset output diversion to the default).

	The file descriptor for standard output is placed one integer cell
	beyond the address of the structure  (at structure + 4 on the VAX).

DLITERAL	num_d ---					I,local
	If compiling, then compile the double precision floating point number
	`num_d' as a double precision floating point literal, which, when later
	executed, will leave `num_d' on the floating point stack.

DMAX								double_int
	Leave the larger of the two double integers.

DMIN		n1_2  ---  n2_2					double_int
	Leave the smaller of the two double integers.

DNEGATE		d_2  ---  -d_2					245,double_int
	Leave the double integer two's complement of a double integer, i.e., the
	difference 0 less `d_2'.  "d-negate"

DO	n1 n2  ---						I,C,142
	
	Use in a colon-definition:

	DO  . . .  LOOP		or
	DO  . . . +LOOP

	Begin a loop which will terminate based on control parameters.  The
	loop index begins at `n2', and terminates based on the limit `n1'.  At
	LOOP or +LOOP, the index is modified by a positinve or negative value.
	The range of a DO-LOOP is determined by the terminating word.

DOES>								I,C,168
	Define the run-time action of a word created by a high-level
	defining word.  Used in the form:

		: <name> . . .  CREATE  . . .  DOES>  . . . ;

		and then  <name> <namex>

	Marks the termination of the defining part of the defining word <name>
	and begins the definition of the run time action for words that will
	later be defined by <name>.  On execution of <namex> the sequence of
	words between DOES> and  ;  will be executed, with the address of
	<namex>'s parameter field on the stack.
	(In both the PDP11 and VAX implementations used here, the parameter
	field of <namex> can be accessed by

		' <namex>

	) "does"

DP+!		n  ---						local
	Add  `n' to the dictionary pointer, moving the boundary of
	the dictionary and the free memory area forward by `n' bytes.
	In the Unix implementation, this differs from ALLOT in that
	an sbrk(2) system call is NOT done if the new allocation crosses
	a page boundary.  DP+! is intended for use with ALLOT in a construction
	of the form:
			n ALLOT  -n DP+!
	Which, in affect, guarantees the existence of a temporary free buffer
	starting at HERE which contains `n' accessable bytes.  This buffer will
	exist until the next ALLOT or until FORTH returns to the outer
	interpreter.  The ALLOT triggers the necessary `sbrk's while the DP+!
	frees the memory without releasing it to the operating system.

DPL		---  addr				U,reference
	Returns a variable containing information about the last number cracked
	by the output interpreter.  The low byte contains the number of digits
	to the right of the decimal point or comma.  If there was an E or D in
	the number (single or double floating point) the signed contents of the
	low byte is the number of digits to the right of the decimal point
	offset by the exponent that followed the E or D (in effect the negative
	of the exponent applied to the double integer returned by CONVERT). DPL
	also contains flags in its high bits.  These are (in hex):
		N.NEG =  100  The number is negative.  -0 can thus be detected.
		N.FLT =  200  The number is floating point.
		N.DBL =  400  The number is double precision floating point.
		N.SNG = 8000  (sign extended to the highest bits of DPL if
			       necessary).  The number is a single precision
			       integer.

DROP		n ---						233
	Drop the top number from the stack.

DU<		ud1_2 ud2_2  ---  flag				double_int
	True if `ud1_2u' is less than `ud2_2u' (unsigned double integer
	compare).  "d-u-less"

DUMP		addr count  ---	
	Dump `count' words in the current base starting at address `addr'.

DUP		n --- n n					205
	Leave a copy of the top stack number.

E.		x_f  ---					floating
	Floating point number `x_f' is typed in exponential format (for example
	-1.345678e+00).

E.BLKTAB	--- addr					Local
	Word array which contains the block number into which is mapped the
	last block of a file in the block mapping table.

EDITOR
	The name of the EDITOR vocabulary.  Execution makes  EDITOR  the
	CONTEXT vocabulary.  Words in the EDITOR vocabulary form a simple
	resident line-oriented editor for forth screens.  The more elaborate
	forth screen-oriented editor EDIT uses words from the EDITOR vocabulary.

ELSE								I,C,167
	Used in a colon-definition in the form:

		IF  . . .  ELSE  . . .  THEN

	ELSE executes after the true clause following IF.  ELSE forces
	execution to skip till just after THEN.  It has no effect on the
	stack.  (See IF)

EMIT		char  ---					145
	Transmit to the output device the single char whose ASCII value is on
	the stack.

EMPTY-BUFFERS							145
	Mark all block buffers as empty, without affecting their actual
	contents.  UPDATEd blocks are not written to mass storage.

ENCODE		addr cnt ---					local
	The forth standard output is diverted into the buffer at address `addr'
	of length `cnt' bytes.

END-CODE
	Terminate a code definition, resetting the CONTEXT vocabulary to the
	CURRENT vocabulary.  If no errors have occurred, the code definition is
	made available for use.

	Vax implementation notes:  for in-line (i.e. ICODE) definitions the
	code-length field in the dictionary header is set by END-CODE.
	Then, for either in-line or not in-line definitions, an rsb instruction
	is compiled into the dictionary.  The rsb instruction is necessary
	here to make ICODE and CODE definitions look the same and to make
	it possible to execute ICODE definitions directly from the keyboard.

ENTAB		in_s  ---  out_s				strings
	Replace all possible strings of spaces by tabs in string on top of
	string stack. Tab stops are set every 8 spaces.

ENVIR		---  addr					unix-interface
	Returns a pointer to the environment area passed to the process
	when it was invoked.  This area is a list of addresses, terminated by
	a 0 each of which points to one of the the null terminated environment
	strings.  (for a word to search this environment, see ENVIRON ).

ERRNO		---  errno					U,local
	A user area variable into which an error code is placed on the
	completion of a system call.  A error code of 0 indicates no error
	see ?UERROR and ?UERMSG ).

EXECUTE		addr ---					163
	Execute the dictionary entry whose compilation address is on the stack.

EXIT								C,117
	When Compiled within a colon-definition, terminate execution of that
	definition, at that point.  May not be used within a DO ... LOOP.

EXPECT		addr n ---					189
	Transfer characters from the terminal the address beginning at `addr',
	until a "return" or the count of n has been received.  Take no action
	for `n' less than or equal to zero.  One or two nulls are added at the
	end of text.  (Local implementation note: the device used is that whose
	control block is pointed to by the user variable READER.  See the
	section on terminal output for a description of this control block).

EXPON		---  n						local
	Recall the exponent from the last character-to-number conversion. This
	is the number of digits to the right of the decimal point (if any) minus
	any explicitely given exponent (i.e. a number following an "E" or "D" 
	character.   This quantity is currently stored in the low-order byte
	of the user variable DPL as an 8 bit signed integer.

F!		fl_f addr  ---					floating
	Store floating point number n at address addr. "f store"

F*		a_f  b_f  ---  c_f				floating
	Leaves the floating point product of `a_f' and `b_f' on the floating
	point stack.

F+		a_f  b_f  ---  c_f				floating
	Leaves the floating point sum of `a_f' and `b_f' on the floating point
	stack.

F+!		fl_f addr  ---					floating
	Adds the floating point number `fl_f' to the floating point number
	stored in `addr' leaving the result in `addr'.

F++		a1  ---  a2					floating
	Increment address a1 by the length of a floating point number, i.e.,
	add the floating point number length in bytes to address `a1'. 

F+A		n addr1  ---  addr2				floating
	Multiply `n' by the floating point cell size and add to address
	`addr1'.  Like FA+ except arguments are swapped.

F,		x_f ---						floating
	Allot a space for a floating point number in the dictionary, storing
	floating point number `x_f'  there.  "f comma"

F-		a_f  b_f  ---  c_f				floating
	Leaves the floating point difference `a_f' minus `b_f' on the floating
	point stack.

F--		a1  ---  a2					floating
	Decrement address a1 by the length of a floating point number, i.e.,
	subtract the floating point number length in bytes from address `a1'.

F-ROT		fl1_f fl2_f fl3_f  ---  fl3_f fl1_f fl2_f	floating
	Rotate the top three numbers on the floating point stack in the other
	direction than FROT, putting the top number in the deepest position.

F.		x_f n  ---					floating
	Print a floating point number in fixed format.  The floating point
	number `x_f' is printed with `n' digits to the right of the decimal
	point.  `n' may be greater than or equal to zero.

F.BLKTAB	--- addr					Local
	Byte array which contains the file descriptors of files in the
	block mapping table.

F.R		x_f n w  ---					floating
	Print a floating point number in fixed format right justified in a field
	of width `w' characters.  The floating point number `x_f' is printed
	with `n' digits to the right of the decimal point.  `n' may be greater
	or equal to zero.

F/		a_f  b_f  ---  c_f				floating
	Leaves the floating point quotient of `a_f' divided by `b_f' on the
	floating point stack.

F/MOD		x_f  y_f  ---  mantis_f  int_2			floating
	Divide floating point number `x_f' by floating point number `y_f'.
	Leave the quotient as a double integer `int_2' and the remainder as a
	floating point number `mantis_f'.

F0!		addr  ---					floating
	Store a floating point zero at address addr.

//go.sysin dd *
made=TRUE
if [ $made = TRUE ]; then
	/bin/chmod 644 ./doc/forth2
	/bin/echo -n '	'; /bin/ls -ld ./doc/forth2
fi
exit
-- 
Bill Sebok			Princeton University, Astrophysics
{allegra,akgua,burl,cbosgd,decvax,ihnp4,kpno,princeton,vax135}!astrovax!wls