FORTH PROGRAMMING SYSTEM RT11 DECUS Distribution Documentation File M. S. Ewing 18 October 1978 This distribution of Forth is a major revision of the previous DECUS library program for PDP-11s. It incorporates numerous improvements. The word header is shortened to two words, even though the first 4 name characters and length are still stored. The address interpreter (NEXT) has been speeded up substantially by using one instead of two levels of indirection. Notation has been improved such that the system is more comparable to the new proposed "standard" FORTH-77. All users of this distribution should refer to the docu- ment, THE CALTECH FORTH MANUAL (SECOND EDITION), by Martin S. Ewing, June, 1978. This is a Technical Report of the Owens Valley Radio Observatory, and is available from the Bookstore, California Insti- tute of Technology, Pasadena, California 91125. The current price is $5.00 plus $1.00 tax, handling, and shipping. A companion Forth system for the DECsystem-10 is also being revised for submission to the DECUS library. Systems for RSX-11 and standalone PDP-11s have been developed and may become available through DECUS at a later time. The files distributed are geared toward RT11 V03B, although they should work with V02C. A minimum system would be the PDP11/03 with 8K and floppy disks. Three types of arithmetic hardware are supported: none (i.e. a universal PDP11 version), PDP-11/40 EIS (includes LSI-11 + KEV11), and Extended Arithmetic Element (EAE). PDP-11/40 FIS is also optionally supported. The following files are included: FORTH.DOC This file. FORTH.MAC Forth Macro source for the Forth "kernel" FORSYS.DAT Standard Forth text file XED.DAT Extended editor text BFP.DAT Basic floating point package EFP.DAT An extended floating point package MSG.DAT A minimal message file. The following options are available in FORTH.MAC: AUTOLD If defined, Forth does an automatic FORTH LOAD when run. LPDEV If defined, code is generated to support an LP-11 type line printer via the RT11 device handler. (E.g. PRINT and TERMINAL) FPNC If defined, the input number converter will handle floating point numbers. E.g. 1., 1.0, 1E0, 1.E0 will all produce a 32-bit floating point "one" on the stack. EIS If defined, EIS arithmetic is used. EAE If defined, EAE arithmetic is used. (EIS and EAE are mutually exclusive.) LDBLK A variable. Set to 0 (EIS system), 1 (universal system), or 2 (EAE system). This determines the value of the constant FORTH, and the system block which is first loaded when Forth is run. SCCA If defined, provides CTRL-C interception under V03 RT11 (or higher). Must not be defined for V02C (or lower). Restrictions & Bugs 1. Do not execute DISK from a block; the text interpreter data source becomes confused. It is acceptable to use DISK inside a :-definition, however, as long as the originial disk context is restored when the word terminates. (C.f. definition of MESSAGE.) 2. Typing CTRL-C will not terminate all loops if SCCA is specified. CTRL-Cs will stop DO - LOOPs and BEGIN - ENDS and LOADING from blocks. Loops in CODE words, however, are unaffected. Normal RT11 CTRL-C handling will occur if SCCA is not specified. 3. In SCCA mode, the only way to get back to the Monitor is with the word GOODBY. 4. Do not try to open non-existant files with DISK. 5. With FPNC specified, the numbers 1. and 1E are equivalent. You can get a double precision fixed point number by typing 1,0 -- or, equivalently, 10, . If FPNC is not defined, the "normal" Forth convention applies -- namely, 1.0 makes a double precision fixed point number equivalent to 10. 6. There is no floating point support without the EIS/FIS options. 7. The output number converter will understand BASE=16 (hexadecimal), but the input converter will not. 8. The error messages called for from the floating point packages are not present in MSG.DAT. 9. DISK (and MESSAGE, /LOAD, etc.) use the RT11 USR routine. If you are using a slow system device, such as a floppy disk, you may want to SET USR NOSWAP before running Forth. You trade memory for speed. 10. If you use ;CODE the assembly code must terminate with SEMI, -- not NEXT, . (This is explained in Section 4.2 of the Manual.) Nonstandard Features 1. A new file system is implemented using the RT11 file system. It corresponds largely to the description of Section 4.4.6 of the Manual. The principal vocabulary follows: FILE nnnn This defines a Forth word nnnn which is equivalent to the specified RT11 file- spec. is in the usual form dev:name.ext. Example: FILE XYZ DK:XYZFIL.DAT. The word nnnn will push a number on the stack which serves to identify the file. nnnn DISK This word takes a file identifier on the stack and makes that file the current Forth block file. Forth actually closes the previous file and opens the new file; for this reason floppy disk users may wish to SET USR NOSWAP to get better speed. nnnn /LOAD Equivalent to nnnn DISK 0 LOAD, except that at the conclusion of loading, the pre-existing disk file is restored. Useful for loading a "package" like XED. i nnnn j mmmm /COPY This copies block i of file nnnn into block j of file mmmm and flushes. Note this definition differs slightly from the Manual. i nnnn CREATE Creates an RT11 file with the file identifier nnnn. The number of Forth blocks reserved is i; the number of RT11 blocks is twice this number. 2. The more common double-word stack operations and double pre- cision integer operations have been included in the standard system. 3. The Extended Editor (XED) has been included as the file XED.DAT. It includes the string-handling package in its first few blocks. 4. A floating-point package (BFP - basic version, EFP - extended version) has also been included. These routines all use the single- precision FIS hardware. Extensions to PDP-11/45 and up should be straight forward. A cursory vocabulary: (The following take one floating number as input, and leave one as output.) 1/X Reciprocal SQRT Square Root FCHS Change sign (should be called FMINUS) FABS Absolute value SIN Sine (argument in radians) COS Cosine TAN Tangent ASIN Arc sine ACOS Arc cosine ATAN Arc tangent * EXP Exponential * 10**X Ten-to-the-X power * LN Natural logarithm * LOG10 Base 10 logarithm * LOG2 Base 2 logarithm * ASINH Arc-hyperbolic-sine * ACOSH Arc-hyperbolic-cosine * ATANH Arc-hyperbolic-tangent (The following have two floating inputs.) *Y X F/MOD Take Y/X and split into integer part I and remainder R. I is left on the top of the stack as an integer (N.B.), while R is left as the next-to-top floating quantity. *Y X Y**X Raise Y to the X-power. Y X F> Leave single-precision integer 1 if Y > X, 0 otherwise. Y X F< Leave single-precision integer 1 if Y < X, 0 otherwise. (The following have no inputs.) 1E0 Constant 1.0 -1E0 -1.0 2E0 2.0 PI 3.14159264 PI/2 3.14159264/2.0 *These words reside in the "extended" floating point file EFP.DAT. 5. The MESSAGE word will cause a line to be typed from the file MSG.DAT. If you specify 18 MESSAGE, you will get line 3 from block 1 of the file. (Message lines are numbered starting with line 0 equivalent to the first line of block 0 of MSG -- a little different from the editor conventions.) The message line is compressed using SPACES? before typing. 6. Number output has been extended: Single-precision decimal or octal depending on BASE: i . Type the value i, taking as many columns as needed. i j .R Type i in a field of j columns (right-justified) if possible. Otherwise type i in as few columns as possible. i ? Equivalent to i @ ?. Single-precision octal: i O. Type i, taking as many columns as needed. i O? Equivalent to i @ O. Double-precision integer: i D. Type i (a double-precision integer) in as many columns as needed. i j D.R Type i in j columns if possible. i D? Equivalent to i 2@ D. Floating-point: x i F. Type x with i digits to the right of the decimal point. (Like Fortran F format.) Use as many columns as needed.* x i j F.R Type x with i digits to the right of the decimal point. Right justify in a field of width j if possible.* i j 5F12.3 Dump j floating numbers from the array at address i in "5F12.3" format (5 numbers to a line).* *Since the floating output conversion is done using the usual floating point arithmetic, it is possible to get garbage if you ask for output with more than about 7 apparent significant digits. Bringing Up Forth under RT11 There are no special requirements for setting up the system. You first must edit FORTH.MAC to specify the assembler conditionals suitable for your system. Then assemble and link FORTH.MAC using MACRO-11. (The minimum memory required for assembly is not known, but probably is greater than 16K.) Note that the file specifications for FORSYS.DAT (in the assem- bler program) and for the other xxx.DAT files (in the FORSYS.DAT file) all specify the device DK1:. If this device is not appropriate to your system, you must use an ASSIGN command to redirect i/o to a different device. Acknowledgements Wayne Hammond has made many of the improvements to RT11 Forth, particularly the file system. With David Rogstad, he developed the new header format and address interpreter. Robert Leighton developed the floating point package.