o;?		FORTH PROGRAMMING SYSTEM
		DECSYSTEM-10 DOCUMENTATION FILE
		28 NOVEMBER 1978
		M. S. EWING, CALTECH

	This File describes the second DECsystem-10 version of Forth
that has been submitted to DECUS.  This document should be read 
after the principle report:  "The Caltech Forth Manual", Second 
Edition, June, 1978, A Technical Report of the Owens VAlley Radio
Observatory, California Institute of Technology.  (The 139-page
Manual is available from Bookstore, Caltech, Pasadena,
California 91125.  The price is $6.00 including postage, handling,
and applicable taxes.)

	This version is a substantial update of the original DECUS distri-
bution.  The Forth address interpreter has been improved so that NEXT
consists of only a single machine instruction.  There are also
only 2 words required in each word header since the code address field
has been eliminated.  These improvements correspond to the changes
made in PDP-11 Forth, which also has been resubmitted to DECUS.

DISTRIBUTED FILES.

	The following files are included in the new distribution:

	FORTH.MAC	MACRO-10 Source File
	FORSYS.DAT	Forth "system" file  (block i/o)
	FORTH.DOC	This document
	FDUM.MAC	A dummy Macro program to help link in Fortran
			routines
	FORTH.COM	A sample command file to assemble, link,
			and run Forth


ASSEMBLY OPTIONS.

	You may choose between several assembly options:

	..FORT	Causes certain externals to be defined which correspond
		to routines in the DEC-10 Fortran library.  These are
		SIN., COS., SQRT., ATAN., ATAN2., EXP., IFX.2, ASIN.,
		CEXP., FLT.2, ALG10., and ALOG.  You may add others as
		needed.

	TWSEG	Causes a two-segment program to be assembled, with
		sharable and reentrant code in the high segment.  If not
		defined a standard one-segment program results.
		The one-segment version generally uses a bit less total
		memory.

	KORE	Selects the number of kilowords of initial dictionary
		space to be reserved.  The Forth word CORE may be used
		to alter the allocation at run time.


SPECIAL COMMENTS.

	This section deals with peculiarities of the DEC-10 Forth
particularly as compared with the "standard" vocabulary of the
Manual.

FPMATH	Say FPMATH LOAD to obtain the assembler for
	the KA-10 model of the DECsystem-10.  (Single precision only). 
	Also loaded are the following words which call the indicated Fortran
	routines.  (Note that the ..FORT option must have been specified
	in the assembly.)

	Forth	function		"Fortran" expression
	word
	-----	--------		--------------------
	SQRT	Square root.	 	X --> SQRT(X)
	FIX	Fix a floating number.	X --> IFIX(X)
	FLOAT	Float an integer.	I --> FLOAT(I)
	LOG10	Log base 10.		X --> ALOG10(X)
	LOG	Log base e.		X --> ALOG(X)
	EXP	Exponential		X --> EXP(X)
	SIN	Sine			X --> SIN(X)
	COS	Cosine			X --> COS(X)
	ATAN	Arctangent		X --> ATAN(X)
	ATAN2	Arctangent of quotient	X Y --> ATAN2(X,Y)
	CEXP	Complex exponential	X Y --> CEXP( X + iY)

	These functions are implemented as machine language calls to
	the Fortran library routines.  They are vectored through the
	FORTRAN table in the kernel which is loaded with the run time
	addresses of the routines.

SLEEP	Puts the program to sleep for the number of seconds specified
	via the stack.

ILDB	Given the address of a byte pointer on the stack, ILDB increments
	the byte pointer, fetches that byte, and returns the byte on
	the stack.  (Mimics the ILDB machine instruction.)

IBP	Given a byte pointer address on stack, increment byte pointer by
	one byte.

VIBP	Variable IBP.  Say <byte pointer address> <byte increment> VIBP.
	This adjusts the byte pointer by the increment.  The increment
	may have any reasonable integer value.

<R	Equivalent to >R in standard vocabulary.

<:	Equivalent to >: in standard vocabulary.

BYTE-POINTER	Like CONSTANT but defines a DEC-10 byte pointer.
	Say i j k BYTE-POINTER <name> to define <name> as a pointer with
	address i, j bits per byte, and bit offset k.  If k=36(10),
	the pointer is the first (leftmost) byte in the
	word.

FBYTE	A constant which when added to an address gives a byte pointer to
	the first 7-bit byte at that address.

SIXBIT	Say SIXBIT <name> to get the sixbit equivalent of <name> on the
	stack.  Up to 6 characters in <name> are converted into a 
	36 bit integer.

XWD	Combines two stack values into 18-bit fields of a single
	36-bit integer.  Say <left half> <right half> XWD.

FFTPACKAGE	This is a sample application vocabulary.  It is a set of
	routines that computes the fast Fourier transform of DIM =
	2 ** LOGDIM complex floating point data points.  Load data into
	DATA array (using !C) and say FORWARD FFT to compute the FFT.
	REVERSE FFT should restore the original data.  Each operation
	results in a scaling upward by a factor DIM, no normalization
	is done.



NOTE

	The entire Forth vocabulary is defined in upper case characters.
Lower case characters are understood, but are distinguished
from upper case.  We suggest you use .SET TTY NO LC.