3$ United Controls Corporation Forth. Translated for IBM PC with EGA graphics. Version 2.00 May 1988 by M.F.Buchan Electrical Engineering Department Hong Kong Polytechnic Kowloon, Hong Kong. Translation Copyright (c) 1988 M.F.Buchan Original Copyright (c) 1982 United Controls Corporation, Huntsville, Alabama. GETTING STARTED 2 úúúúDescription 2 úúúúDemonstrations 3 úúúúDo it yourself 3 úúúúúúúúFor beginners 4 úúúúúúúúDisassembler 4 úúúúúúúúEntering Numeric values 4 úúúúúúúúNumerics in strings 5 úúúúúúúúPrinting Numeric values 5 úúúúúúúúPrinting strings 6 úúúúúúúúDumping memory and stack 6 úúúúúúúúDump Dictionary 6 úúúúúúúúDefining new words 7 úúúúúúúúLINK 7 úúúúúúúúDEBUG, TRACEON, and TAG 8 úúúúúúúúTRACEL 8 úúúúúúúúTM, TD, and SYNONYM 9 úúúúúúúúMAP and EXTRN 9 úúúúúúúúdifferences from normal 10 EDITOR 11 úúúúDescription 11 úúúúConfiguring 4th/86 12 úúúúUsing the editor 13 CONSTANTS AND VARIABLES 14 FILES PROVIDED 16 úúúú4th/86 run files 16 úúúúprimary source files 17 úúúúsecondary source files 17 úúúúextension source files 18 úúúúbonus source files 18 SYSTEM LAYOUT 19 úúúúHEAD, LAST, and LUM 19 úúúúDictionary Flag Byte 20 úúúúDictionary Entry Format 20 úúúúFormat of Linked Dictionaries 20 COMPILING 21 úúúúHow to compile demonstrations 21 úúúúCROSS-COMPILE & UNCROSS 22 úúúúFLOAD 23 úúúúON REDEFINE 23 úúúúOFF PRINTLOAD 23 úúúúCLOAD 23 úúúúCTLOAD 24 úúúú:EXIT and :ENTER 24 úúúúATTACH 25 úúúúMAKECOM 25 úúúúOMIT 25 úúúúISAVE & PIMAGE 25 úúúúILOAD & GIMAGE 26 úúúúSYSTEM 26 úúúúMAP 26 =========== Description =========== UCC stands for United Controls Corporation. This version of Forth is based on their original 8-bit version as described in detail in the next chapter. It is Direct Threaded; uses Sequential file structures (loaded with FLOAD xxx) rather than 1024 byte screens; has substantial built-in debugging and trace facilities; can shell through the DOS 3.3 to utilize your normal word processor/editor; and can CLOAD binary COM files produced by MASM. EGA graphics are also included, with several demonstration files. Although the routines will examine the DOS equipment byte to detect the presence of a CGA or an EGA board, and act accordingly, the graphics demonstration programs will NOT work properly ( if at all) if you do not have an EGA board. You can however write your own CGA demonstrations -- modify those supplied -- or modify and re-load the EGAM.ASM file. In addition you can create stand-alone COM files for your application (with all dictionary entries omitted), as well as re-building your own minimal or extended 4th/86 system based on the KERNEL.IMG image kernel provided. Because it is predicated on the original 4th 8-bit system, it is intentionally a hybrid beast. You can either use MASM and LINK to produce COM binary files which can then be CLOADed into the system -- or you can write "in-line" assembly code, but ** ONLY ** using 8080 assembly mnemonics. This is intentional in order that the original UCC 4th source code can be loaded (almost) as-is. In line 8086 assembly will come later -- but with CLOAD available, it's present omission is only a minor hardship. 4th/86 is not case sensitive. You can type in either lower or upper case and the input will be interpreted identically. (There are a couple of exceptions which will be mentioned later where lower case is not recognized). The following notes are only an outline. For a full description, United Controls Corporation, Alabama, should be contacted for a copy of the original manual. All the extensions are described here, but there is a great deal of the original which is only briefly mentioned, or omitted. UCC 4th/86 GETTING STARTED page 3 ============== Demonstrations ============== The purpose of most of these demonstrations is really to show the way in which stand-alone COM files can be produced. You will re-build them yourself later from the source code provided. You can type SINE to run the demonstration SINE.COM whether you have an EGA or a CGA card. The other demonstrations require an EGA card however. SQUARE.COM uses the word DLINE to draw a square. The display pauses for a few seconds, then returns to DOS. SMITH.COM draws three sets of circles in the form of a Smith Chart (as used for wave propagation calculations). HILBERT.COM will draw a four level Hilbert curve; wait a few seconds (probably quite a long time if you have a slow XT) and then draw a four level Sierpin curve; again wait for you to examine it; and then exit back to DOS. KALEI2.COM takes you through an extensive set of graphics demonstrations, controlled by pressing any key to progress from one to the next. (This has an irritating bug which has not yet been traced. If you wait too long on any of the continuous-running kaleidoscope demonstrations, a PC clock-interrupt is liable to hit the program at the wrong moment, the display freezes, and everything dies. ) NORM.COM is simply a utility to restore a multi-function graphics card to the normal text mode should you accidentally crash out of a running EGA program into DOS. It should not be needed, as the graphics demonstrations all execute the Forth word NORM before exiting. MANTST.COM draws a Mandelbrot set, whilst JULTST.COM draws a Julia set (see Peitgen & Richter - the Beauty of Fractals - Springer-Verlag 1986). These are based on an implementation by Larry Fogg from MicroCornucopia magazine. *** BE WARNED *** Once you start these, they can not be stopped mid-stream other than by re-booting. To complete a Mandelbrot or Julia set takes at least 12 hours on a 10 MHz AT. MANTST.COM and JULTST.COM draw the "first pass" within a couple of minutes, so that you can see what the picture looks like. Successive passes fill in the vertical resolution to full EGA definition -- and then successive passes convert the horizontal 4-bit nybble resolution into individual pixels. The result is well worth waiting for if you have the patience -- or can sleep while your PC is grinding away. ============== Do it yourself ============== From the DOS prompt, type UCC2 and you will be in UCC 4th/86. If you want to get back to DOS you can either type QUIT or BYE. BYE is preferable because it re-initializes your EGA graphics board back to text mode. QUIT simply closes files and exits to DOS. You can also type SYS to shell out to dos, and EXIT to return. You can also shell to your editor -- this is described later. The system words DIR and TYPE can be used from within 4th/86 - but paths are not implemented. Drive letters from A: through D: are implemented and can be used alone to change default drive, or as prefix with DIR and TYPE. UCC 4th/86 DO IT YOURSELF page 4 ============= For beginners ============= If you are not familiar at all with FORTH as a language, then you should get FORTH: A text and Reference by Mahlon G. Kelly and Nicholas Spies -- Prentice Hall -- 1986. The following guide is not dificult to follow however, and you should try it. The purpose is to show the special features of 4th/86 -- rather than teaching a beginner the nature of Forth. ============ Disassembler ============ To show the difference between BYE and QUIT, type DD BYE and you will get a disassembly of the word BYE -- which shows that it threads into the words NORM and QUIT. It starts -- as all Forth words do -- by calling the assembly language routine COLON and ending by executing SRET -- which in turn jumps to THREAD after restoring the Forth program counter. NORM restores the EGA card to normal text mode. Try DD QUIT. Note that this includes both Forth and Assembly code. Perhaps a better word to demonstrate how Forth and Assembly can be mixed is the word GC. Type DD GC and then use ctrl-S to pause and start the display The display can be stopped at any time by pressing the space bar. Do NOT use ctrl-C or you will be dumped out of Forth. Try DD NORM and you will see some of the limitations of the disassembly. The correct source for NORM is in the file EGAM.ASM where you will see that MVI -,00 is really MOV AH,0 and MVI A,03 is MOV AL,3 When you did DD GC you will also have seen many NOTIMP meaning that these op-codes were not implemented in the disassembler. You can also disassemble code at a specific address by using DDL for low level code or DDH for high level code. Try 5FAAH DDH and 5823H DDL as a matter of curiosity, try 5FAAH DDL and 5823H DDH ======================= Entering Numeric Values ======================= Here is one place that 4th/86 differs from all other Forths. Numbers can be input in Hex, Binary, Decimal or Octal. In 4th/86 considerable flexibility is introduced by using the same notation as when writing ASM code -- a suffix after the number -- 123H -- 123Q ( or 123O) -- 1234B for Hex, Octal, Binary respectively. Decimal is the default, so for 123 decimal just type in 123. ASCII values can be inserted as "C" rather than 43H UCC 4th/86 DO IT YOURSELF page 5 =================== Numerics in Strings =================== String values are entered between quotes " this is a test" (note that the leading " is a Forth word and must be followed by a space) If it is required to enter specific numeric bytes as part of the string -- for example 0D Hex and 0A Hex -- this is done by using the back-slash \ " \0dh\\0ah\this is a test" or " \13\\10\this is a test" The result of course is the same as crlf " this is a test" ======================= Printing Numeric Values ======================= To print out the value on the TOS (top of stack) the operators .H .L .HB .C and . .H prints a word in Hex with a leading space. .HB prints a byte in Hex with leading space. A single period . prints the TOS in decimal with a leading space. .C prints the ASCII character if one exists -- but with no leading space. .L is the same as . but without a leading space. It's main purpose is for sending ANSI control codes requiring numeric parameters. A leading space would invalidate the ANSI sequence. Try the following at the ? prompt 20H 16 "C" + + dup .H crlf dup . crlf 30H - .C Try also the following 20H 16 "C" + + dup .h 3 spcs dup . 3 spcs 30h - .c In normal Forths different number bases can not be mixed. It is necessary to define a variable BASE as either HEX DECIMAL etc. 4th/86 does not have this clumsy restriction. Whilst there is a variable called BASE in 4th/86 it has nothing to do with number bases, and is never used in normal events. It is in fact the relocation offset used when cross-compiling stand-alone COM programs. The user need not know it exists, as it is a system variable. UCC 4th/86 DO IT YOURSELF page 6 ================ Printing Strings ================ Unlike standard Forths, the dot-quote word ( ." ) does not double as part of the initial string quote. It is a separate word. 4th/86 => " this is a test" ." Other Forths => ."this is a test" ======================== Dumping memory and stack ======================== DM 8DM and 16DM are memory dumps -- try them 2000H 8DM etc. DS and DDS are stack dumps try 2 3 4 5 DS DS DS DDS DS DS prints out the stack values, and leaves them unchanged DDS (destructive dump stack) prints the values and removes them NOTE that as well as the number 2 3 4 5 on the stack, there was also the hex value 2080. This was left by 8DM so that successive 8DM would carry on where the previous 8DM finished. try 2 3 4 5 DS abcd DS this is a convenient way to clear and reset the stack -- type in any meaningless phrase (i.e. - abcd), press return, and the error message clears the stack. =============== Dump Dictionary =============== Type DDICT and you will be presented with a display (use ctrl-S to pause --- space bar to abort) of the words in the dictionary, together with the address of the dictionary entry and flag byte (high memory) and the start address of the code area. Check them with xxxx 8DM and with the disassembly word DD. Type PDICT DUP and instead of returning all the words in the dictionary, you will just get the addresses for the word DUP. UCC 4th/86 DO IT YOURSELF page 7 ================== Defining new words ================== Type : Fred 3 . ; This defines a word Fred -- which simply prints the value 3 Type FRED (or fred FrEd fREd) and you will see 3 printed (out of curiosity, disassemble with DD FRED ) Type : Fred 4 ; You will be asked if you want to redefine Fred -- answer Y Type FRED and -- apparently -- nothing will happen type DDS and you will see that in fact 4 was pushed on the stack Now type : Larry Fred 2 * . ; and then type LARRY You should get an 8 printed -- Fred -- which is 4 -- has been multiplied by 2 Let's redefine FRED once more : Fred 6 ; ( and of course answer Y ) Now try LARRY --- and you will again get the same answer -- 8 The redefinition of FRED has not affected the prior definition of Larry. This is the normal way with Forth. Now let's see how we can actually replace the old definition with a new one. ==== LINK ==== Type DD FRED and you will see the constant 6 type FORGET FRED and then DD FRED and you will see that we are now back to our second definition of FRED as the value 4 type : KEN 6 ; LINK FRED KEN LARRY you should get the value 12 printed. All calls to the last FRED are now diverted to KEN instead The last word linked can be restored with UNLINK Type UNLINK which unlinks FRED from KEN type LARRY and you should get 8 type DD FRED DD KEN and DD LARRY to confirm UCC 4th/86 DO IT YOURSELF page 8 =================== DEBUG; TRACEON; TAG =================== We already have LARRY defined Type TRACEON LARRY and then LARRY the word is traced, and stack values are displayed TRACEOFF removes the trace, and TAG (trace-again) restores it applying TRACEON to another word automatically removes it from the old one any errors -- as well as clearing the stack -- also remove TRACEON DEBUG is an on/off toggle. type TRACEOFF to be sure -- and then type DEBUG ( to toggle debug on) now type 3 4 5 6 . . DDS (return> DEBUG ( to toggle it off) this display of stack contents is useful. ====== TRACEL ====== This is Trace-level and is used for tracing DO...LOOP structures Type : SLOOPY 5 0 do I . loop ; then run it by typing SLOOPY you should get 0 1 2 3 4 5 displayed on the screen now TRACEON SLOOPY SLOOPY -------- not very impressive 3 TRACEL SLOOPY ---- somewhat better ??? UCC 4th/86 DO IT YOURSELF page 9 =============== TM; TD; SYNONYM =============== Type TM and the time will be shown Type TD and then TD again. the elapsed time between the two events is shown Try : dly1 1000 0 do loop ; : dly td 10 0 do dly1 loop crlf td crlf ; then run by typing DLY. The SECOND line shows the elapsed time to complete the word DLY -- measured between the first TD and the second TD. No -- indeed this system is not as fast as many others -- but at the moment speed is not the objective. The objective is a user- friendly interface which will allow ease of code writing and learning for beginners. So you think TM is too terse and non-standard? well try SYNONYM TIMEELAPSED TD and type TIMEELAPSED -- purists can build synonyms for any word they think "non-standard" (or modify the source) and ATTACH to a new system file. ========== MAP; EXTRN ========== For each of the UCCx.COM on disk there is an EXTRNx file which has been created by the command " EXTRNx" MAP. (see UCC1.BLD for example). These EXTRNx files contain a list of all the words compiled into that version, to avoid the need for using DDICT. EXTRN2 is very much smaller than EXTRN1 because UCC2 is not in fact a system compiled from scratch (as is UCC1 and UCC0) -- it is simply UCC1 with the extra floating point etc. functions ATTACHed. The complete list of words for UCC2 is contained in EXTRN1 and EXTRN2 together. These files also show whether the word is a colon definition, a code definition, or a variable/constant. UCC 4th/86 DO IT YOURSELF page 10 ======================= differences from normal ======================= 4th/86 is different from other implementations of FORTH in several ways. Some of the differences are because of the targeted applications of FORTH such as the fact that the dictionary is stored separately from the code so compact stand-alone code can be generated. OPther differences arise because of adding features not commonly found in other FORTHs, different naming conventions, and different philosophies in the implementation. Listed below are some of the minor differences that may "disturb" the user of a more conventional FORTH. SYNONYMS or shorty words can be used to define the more familiar names. For example: SYNONYM EMIT .C or : KEY 0 BEGIN DROP 255 6 MON2 DUP END ; After the table below is a discussion of several more significant differences. Many FORTHs 4th/86 exact replacement Equivalent C@ B@ C! B! EMIT .C KEY 0 BEGIN DROP 255 6 MON2 DUP GETCHR END TYPE 1 DO DUPB@ .C 1+ LOOP DROP ." VARIABLE DATA[ ...] CONSTANT CONST CR CRLF ."string" " string" ." ABORT" string" " string" 1 ERMSG LEAVE EXIT QUIT CLI BEGIN..UNTIL BEGIN...END BEGIN..WHILE..REPEAT REPEAT..WHILE..ENDWHILE D+ D= etc. ,+ ,= etc. In 4th/86, DO..LOOPs terminate when the loop count is exceeded, not equaled. Also in most FORTHs, the loop is always executed at least once, while in 4th/86 the loop index is checked against the limit before the loop is executed (loop skipped if limit exceeds maximum). In 4th/86, loops cannot use negative increments, When the word EXIT (corresponds to LEAVE) is executed, the loop is exited immediately (most FORTHS set the loop limit equal to the current loop index). UCC 4th/86 DO IT YOURSELF page 11 Some of the words that are considered part of the "core" of many FORTHs are kept in files in source form. These include the popular words R> and >R which, for convenience, are defined below CODE >R E C MOV, D B MOV, B POP, ' PSHBC# CALL, C E MOV, B D MOV, ; CODE R> E C MOV, D B MOV, ' POPBC# CALL, C E MOV, B D MOV, ; The file SHARPS.4th contains source for double precision formatted output routines, and DEMO#S.4th is a demonstration of these. CREATE...DOES is not included as such, but the file ARRAY.4th shows how defining words can be created. EVAL.4th shows how to convert strings to numbers. =========== Description =========== Whilst there is a file on disc called EDITOR.4TH, this is provided only as a matter of interest -- and because it was a part of the original 8-bit UCC package. It will load and run however should you choose to use it. When loaded, it will redefine EDIT and REDIT. This MSDOS version has facilities to shell to your normal DOS editor or word processor -- or to DOS itself. The word SYS will take you into DOS -- and typing EXIT will take you back into 4th/86 again. There is another word EDIT which will take you direct from 4th/86 into your normal DOS editor or word processor -- but you must set up 4th/86 so that it knows the name of your editor -- which it will assume to exist in the root directory of the currently logged-on disk. At the moment, by default, 4th/86 is set up to look in the root directory for a file called VED.COM. (This is Compuview's VEDIT PLUS, which I have used happily for many years). UCC 4th/86 EDITOR page 12 ================== Configuring 4th/86 ================== If your editor is a COM file (as opposed to EXE), then the simplest way to make it functional from 4th/86 is to copy your editor to the root directory and rename it VED.COM. It is *** NOT *** guaranteed that ALL editors will work satisfactorily however -- you will have to experiment first to make sure that yours is compatible. Just in case you are unfortunate, a public domain editor OMNI.COM has been included, which is quite neat, and does work. Just re-name it to VED.COM and put it in the root directory. One editor which does NOT work is Wordstar (but then you don't use blunt axes to sharpen pencils -- do you???). Wordstar insists on looking for ??????.??? and ends up by editing COMMAND.COM itself. If you find yourself looking at a screenful of non-ASCII characters, reboot, check that the date of COMMAND.COM has not changed, and use a different editor. PCWRITE (which is an EXE file) works happily (when renamed to VED.EXE), but you will have to patch 4th/86 to change COM to EXE. To find the address, fire up 4th/86 -- type DD EDIT -- and look for the address of the line LDIS VED.COM (it should be at 5BFB ). Now leave 4th/86 and go back to DOS. Type DEBUG UCC2.COM and then type D 5BFB (or whatever the address was). Give the file a new name (UCCX) by typing N UCCX.COM. Then change the string "COM" to "EXE" using the debug E command -- and save by typing W . When you become more familiar with 4th/86 you can alter the file DOSXTRA and re-compile the whole system instead of just patching the original run file. UCC 4th/86 EDITOR page 13 ================ Using the editor ================ You must first tell 4th/86 the name of the file you want to edit. The default name built into 4th/86 is EDHELP.TXT -- so if you type EDIT you should get this help message displayed by your editor. The word USING allows you to change the default file name to another one. To edit a different file -- say SQ -- first type USING SQ -- then all future uses of the word EDIT (and the words REDIT and RELOAD) will call up the file SQ. The editor is designed to be much more flexible than this however. After editing a Forth source file, the normal procedure would be to re-load it for testing and debugging. For this purpose, the words RELOAD and REDIT exist. RELOAD behaves the same as FLOAD except that it uses the name already specified by USING. Therefore FLOAD SQ is the same as having executed USING SQ and then executing RELOAD REDIT also uses the name specified by the previous USING and is equivalent to EDIT followed by RELOAD. The normal edit => fload => test => re-edit cycle is simplified Try USING SQ FLOAD SQ DD OSQUARE REDIT <==> DD OSQUARE REDIT <==> DD OSQUARE where <==> are the steps to exit from the editor you are using. You will see by the addresses attached to the DD disassembly that each REDIT redefines a new OSQUARE, getting higher and higher in memory. This can be avoided by defining a dummy word -- say EDSTART -- and starting your source file with FORGET EDSTART UCC 4th/86 EDITOR page 14 Try USING EDTEST : EDSTART ; FLOAD EDTEST DD OSQUARE REDIT <==> DD OSQUARE now the re-load of the newly edited file EDTEST causes deletion of the previously edited file. The following notes should now be much easier to try. Instead of trying to key into 4th/86 lengthy definitions directly from the keyboard, they can be edited into a test file, and the file loaded. Generally speaking, lower and upper case are equivalent, whether entered from the keyboard or floaded from a file. Of course, case in quoted strings is preserved " Hey There" ." will be printed Hey There - not capitalized nor all lower case. ======================= Variables and Constants ======================= (this section is extracted from the UCC 4th Manual available from UCC) BLOCK Purpose: Reserves a block of contiguous memory where the size of the block is on the TOS and the name of the block is the next word. When the name is executed, the address of the block of memory associated with it is placed on the stack. ?? block_size --- ?? ( when BLOCK is executed ) ?? --- ?? address ( when the name of the block is executed ) Example: Reserve 25 bytes of memory and name it BUFFER. 25 BLOCK BUFFER ( A buffer which is 25 bytes long ) Example: Assume that the address of BUFFER is 453EH. Using the word .H print the address of BUFFER. BUFFER .H 453E ( this is printed on the console ) UCC 4th/86 CONSTANTS AND VARIABLES page 15 CONST Purpose: Defines a constant whose value is on TOS and name follows CONST. When the name is executed, the value associated with that name is placed on TOS. Only single precision integers may be used as the value of a constant. ?? value -- ?? ( when CONST is executed ) ?? -- ?? value ( when name of constant is executed ) Example: Define the constant B_SIZE whose value is 1100. Also, using the word . print the value of SIZE. 1100 CONST B_SIZE B_SIZE . 1100 ( this is printed on console ) ,CONST ( comma const) Purpose: ,CONST is similar to CONST except a double precision constant is defined. ?? --- ?? Format: value ,CONST name DATA[ ( data left bracket) Purpose: Defines a block of memory with the values between DATA[ and ] with the name of the block following ]. The values may be: 1. one byte integers 2. two byte integers 3. strings with a length byte 4. strings without a length byte When the name of the block is executed, the address of the block associated with the name is placed on the TOS There are special words which allow the data type to vary as mentioned above. The words are: BYTE WORD LENGTH NOLENGTH ( ** Note ** DATA[ can be in lower ( case -- but these special words ( MUST be in upper case ) and are respective to the meanings 1 through 4 above. The defaults are WORD and LENGTH. When these words are detected, all remaining values have the same data type until either a new defining data type is encountered or a ] is found, which ever comes first. Note that ' and " can be used in DATA[ ?? --- ?? UCC 4th/86 CONSTANTS AND VARIABLES page 16 Example: Define TABLE whose values and format are: 145 ( one byte) 5394 ( one byte) 13 ( two bytes) " HI" ( with length byte) 423EH ( two bytes) " HELLO" ( no length byte) and write a word, TEST, which prints each value one per line. DATA[ BYTE 145 5394 WORD 13 LENGTH " HI" WORD 423EH NOLENGTH " HELLO" ] TABLE : TEST TABLE DUPB@ . CRLF 1+ DUPB@ . CRLF 1+ DUP@ . CRLF 2+ DUP PUTLIN CRLF DUPB@ + 1+ DUP@ .H CRLF 2+ DUP 4 + SWAP DO I B@ PUTCHR LOOP ; ? TEST 145 18 13 HI 423EH HELLO ================ 4th/86 Run Files ================ There are three versions of Forth provided -- UCC0.COM, UCC1.COM and UCC2.COM UCC0 is a bare minimum version designed to leave a lot of room for compiling larger versions. UCC1 is the same as UCC0 with debug, dos extensions, and EGA facilities added. UCC2 is the same as UCC1 with double precision; floating point; and transcendental functions added. UCC 4th/86 FILES PROVIDED page 17 ==================== primary source files ==================== The source code for the compiler and interpreter are NOT provided. This involves the code for the in-line assembler; command line interpreter; forth compiler; and cross compiler. If you are building your own turnkey COM file, you would not want any of the above compiler/interpreter words anyway. To enable you to create turnkey applications, the files 7BASIC2 ( basic functions) 7OSI2 ( operating system interface) 7DISP2 ( display and I/O words) provide the necessary turnkey kernel on which to build. The file UCC0.COM consists of the above three files, plus the compiler/interpreter files, plus the files XTRA2 and LOGO. To help you build your own 4th/86 system from scratch (without the source code) a memory image of KERNEL0.IMG is provided, which can be ILOADed into UCC0.COM, and either saved as-is --- or extended with other files before saving. UCC1.COM is in fact KERNEL0.IMG plus the debug and edit files etc. Note that KERNEL0.IMG is only phase-compatible with UCC0.COM. If you try to ILOAD it into UCC1.COM or UCC2.COM you will get a phase error. To save time creating turnkey systems, the files 7BASIC2, 7OSI2, and 7DISP2 are provided as an image KERNEL2.IMG -- which is phase- compatible ONLY with UCC2.COM. ====================== secondary source files ====================== UCC1.COM has been created from KERNEL0.IMG by adding the following files D62.4TH ( Forth debug and disassembly source) DOS.ASM ( ASM code to shell to DOS and editor) T.ASM ( ASM code to get time from DOS) DOSXTRA ( Forth source to deal with shelling to DOS etc.) TM ( Forth source to deal with time words) EGAM.ASM ( ASM source for EGA graphics) Of course it is necessary first to convert the ASM files into COM files by using MASM and LINK. == and then CLOAD (or CTLOAD) them. Although DOS EGAM and T are in fact COM files, they will not run by themselves, and no ( COM ) suffix has been given to them to avoid attempts to run them stand-alone. See later for detailed description of the BUILD process via .BLD files. UCC 4th/86 FILES PROVIDED page 18 ====================== extension source files ====================== UCC2.COM has been created from UCC1.COM by ATTACHING the files DOUBLE2 ( Forth source for double precision) FPOINT2 ( Forth source for Floating Point) TRANSC2 ( Transcendental functions) ATTACH2 ( Utility to create COM file of 4th/86 system after loading extra files) ================== bonus source files ================== These include games and demonstrations. They also include however source for words which are a core part of many other Forths -- but which are regarded in 4th/86 as not frequently enough used to justify bloating the system with. They can be added (and of course ATTACHed) should you feel they are indispensable. Demonstrations ============== SQ SIN SMITH HILSIER HILSIER2 WORM.4TH RANDOM.4TH Extensions ========== LOGO.ASM SHARPS.4TH DEMO#S.4TH EVAL.4TH ARRAY.4TH EDIT.4TH COMPRESS.4TH OMIT.4TH MAKECOM.4TH QUICKCOM.4TH SYSOMIT.4TH UCC 4th/86 FILES PROVIDED page 19 =============== HEAD; LAST; LUM =============== These are system variables pointing respectively to the code area; the dictionary; and the data storage area. The values can be obtained at any time from HEAD @ .H etc. The dictionary (pointed to by LAST) grows downwards, whilst the code area (pointed to by HEAD) grows upwards -\/\/\/\/\/\/\/\/\/\ CSP-> | Misc variables | <- Control Stack Pointer --------------------- TOPDICT-> | 0, SYSLAST | <- User dictionary terminator --------------------- | Dictionary for | | User's | LAST -> | Definitions | <- LAST --------------------- | | Remaining | | grows downwards | Space for | V | User's | | dictionary | DICTION-> | | --------------------- INITLUM-> | Misc variables | --------------------- | Memory reserved | LUM-> | by user's defs | <- LUM --------------------- | | Remaining | | Variable storage | Space for | | grows downwards | User | V | Variables | | and | | | ^ | | | Definitions | | | grow upwards | | | HEAD-> | | <- HEAD --------------------- | Definitions | INITHEAD-> | Created by User | --------------------- | 0,0 | <- System dictionary --------------------- terminator | Dictionary for | | Built-in | SYSLAST-> | Definitions | --------------------- | | | Built-in | | Definitions | CS:100H-> | | --------------------- UCC 4th/86 SYSTEM LAYOUT page 20 ==================== Dictionary Flag Byte ==================== Bit HEX Meaning --- --- ------- 0 01 Immediate 1 02 Don't Find 2 04 Asm 3 08 Module Name Word 4 10 Variable/Constant 5 20 6 40 7 80 Referenced in definition ======================= Dictionary Entry Format ======================= ------------------------ | | } | defadr | } 2 bytes ------------------------ | flag | } 1 byte ------------------------ | . | } | . | } | . | } # bytes equal to length | . | | word in ASCII | ------------------------ | length | } 1 byte ------------------------ Minimum dictionary entry length is 5 bytes ============================= Format of Linked Dictionaries ============================= ------------------ -------------------- | link |-->. . . --- | 0 | ------------------ | -------------------- | 0 | | | 0 | ------------------ | -------------------- | | | | | | | | | | | | | | | | dictionary | | | dictionary | | | | | | | | | | | | | | | | | | |--> | | ------------------ -------------------- UCC 4th/86 SYSTEM LAYOUT page 21 ============================= How to compile demonstrations ============================= The Forth source for all except the Kaleidoscope demonstrations is provided. To create SINE.COM simply bring up UCC2.COM and then type FLOAD SINCOM.DEM The process will end by exiting to DOS. Look at the file SINCOM.DEM which automates the building process, and the file SINE which is the source for the demonstration, to see what is happening. Similrly you can FLOAD SMITH.DEM to produce SMITH.COM -- and of course FLOAD HILCOM.DEM will produce HILBERT.COM. Note that HILSIER2 is not the same as HILSIER. HILSIER2 is used exclusively by HILCOM.DEM to produce HILBERT.COM -- and omits the facility for defining levels and magnification. On the other hand, HILSIER is available for FLOADing into UCC2.COM, and allows levels and magnification to be specified. These are in effect "batch" files which automate the compilation of turnkey programs. The details are explained below. UCC 4th/86 COMPILING page 22 ======================= CROSS-COMPILE & UNCROSS ======================= The 4th/86 system provides the user with a means of compiling a system which will reside at memory addresses other than those generated by the compiler. This means that a system may be relocated to any contiguous area of memory starting at any location in memory, This feature allows for the generation of code which will reside in ROM. As a matter of fact the 4th/86 system itself is generated using the cross- compiler. The cross-compiler is not a separate compiler, instead it is a mode in which the compiler executes. The compiler runs in one of two modes: cross-compile or noncross-compile. Until specified, the compiler will operate in noncross-compile mode. Executing the word CROSS-COMPILE switches to the cross-compile mode. Normally cross-compile will be initiated with 100H FF00H CROSS-COMPILE and 103H ORG to leave space for the startup jump. Look at any of the xxx.BLD files to see the exact method. several points need to be noted a) code generated in cross-compile mode can ** NOT ** be run during the process of cross compiling. b) all code forming part of the "mother system" can be run in cross- compile just as in noncross mode. c) cross-compiled definitions can not reference a word which has not already been loaded in cross-compile. d) Cross-compile creates its own dictionary, and FIND will reference this dictionary to determine code addresses ** NOT ** the system dictionary. The system dictionary is only used for words in immediate mode. UCC 4th/86 COMPILING page 23 ===== FLOAD ===== This has already been described. An alternative to FLOAD FILE.ABC would be " FILE.ABC" LOAD. The use of the word FLOAD avoids the need for quotes. ============ ON REDEFINE ============ REDEFINE is a flag which determines whether the compiler will give a warning or not when a re-definition is encountered. ON REDEFINE allows words to be redefined without warning. OFF REDEFINE causes warning messages. ============= OFF PRINTLOAD ============= PRINTLOAD is a flag which determines whether the file will be listed on the screen as it is loaded. OFF PRINTLOAD allows the file to load without being displayed on the screen. ON and OFF PRINTLOAD can be scattered throughout a file if parts are to be observed during loading -- as indeed can ON and OFF REDEFINE. ===== CLOAD ===== CLOAD is used for COM files created by MASM. It does ** NOT ** check for re-definition so care is needed not to duplicate words. As well as loading the code at HEAD, the word CLOAD will also put the dictionary entries at LAST. It is necessary to embed the dictionary entries in the ASM code therefore, and the best way to understand this is to look at the ASM examples provided. There might be more elegant ways to do this, but the object was to keep life simple, and in true FORTH style -- put the responsibility in the hands of the programmer rather than the compiler. For better or worse, two "unique" strings are used to delineate code from dictionary from garbage. These strings are db 'endproc ' and db 'endfile' These lower case strings have been chosen on the basis that the ASCII characters do not represent any 8086 op-codes -- and of course the sequence of ASCII bytes is also reasonably "unique" When CLOAD finds 65 Hex (lower case e ) it examines the next six bytes to see if they match either of the strings. If not, they are treated as code/data and loading continues. UCC 4th/86 COMPILING page 24 If a match with 'endproc ' is found, then the word following the space is inserted into the dictionary, and the first three bytes of 'endproc' are overwritten with JMP THREAD. The end of the dictionary word is delineated by a space, and all bytes following this are again treated as code/data to be loaded. If a match with 'endfile' is detected, then loading stops -- even though the file may contain garbage in the form of nulls, rounding up bytes, or whatever. There is a catch to all this of course --. The 8086 code itself is relocatable and will run anywhere -- but the data references are absolute with respect to DS. It is therefore necessary to add an offset HEAD to all absolute references -- where HEAD is the value at which CLOAD starts loading that particular file. CLOADing is therefore a two stage process. a) assemble, link, and CLOAD the file with any value of HEAD -- and note the addresses which are printed out b) Put the printed start address into the ASM file as the value of HEAD, reassemble, link, and CLOAD. This is not the hassle it seems. It is not very often that the same ASM code has to be loaded at a wide range of locations. EGAM.ASM is one exception -- where it may be loaded either via UCC1.BLD or from some standalone demonstration such as HILCOM.DEM ====== CTLOAD ====== The files DOS.ASM and T.ASM have been CTLOADed in the build file UCC1.BLD. There is, on reflection, really very little point in this refinement. Because the dictionary words are embedded in the ASM code, they get treated as data during assembly, and cause the program counter to increment. For simplicity, CLOAD also loads the dictionary word into the code area to maintain correct location of the code segments. It was felt that this was clumsy and wasteful of code space, so CTLOAD was written to avoid dictionary words appearing in the code area. In fact the complexity of working out offsets before assembly negates any benefit -- especially where there are many data references. Look at the files T.ASM and DOS.ASM to see what is involved. ================ :EXIT and :ENTER ================ These allow changes from assembly to colon ( :ENTER) and from colon to assembly ( :EXIT) within the same word definition. Several examples will be found in 7OSI2 and EDIT.4TH. UCC 4th/86 COMPILING page 25 ====== ATTACH ====== This is used only in noncross mode. When some definitions have been loaded, the file ATTACH2 can be FLOADed, and will create an "expanded" version of the "mother" 4th/86 which can be saved as a COM file. You will be prompted for the file name. Note -- this is NOT the same as creating a turnkey application. With ATTACH you still have the full original system - but with the new words attached. ======= MAKECOM ======= The xxx.BLD files are essentially MAKECOM files. To create a standalone COM file, FLOAD MAKECOM into UCC2.COM and then answer the requests for file names. It is assumed that all the words your application needs are contained in KERNEL2.IMG. If this is not the case, then you will have to specify in your application that it first FLOAD the additional files needed. ==== OMIT ==== This is of questionable use now. It was included with the original system to cater for situations where memory was very scarce -- 48K or less -- and it was worth while removing little used entries from the dictionary. It could be of use if there are specific entries you don't want people to have access to. To see how to use it, look at the file UCC1.BLD. The sections of OMIT have been commented out, but they can be re-instated. ============== ISAVE & PIMAGE ============== This is only used during cross-compile. At any stage of partial completion of the cross-compile, the memory image can be saved either by using ISAVE FNAME.IMG or " FNAME.IMG" PIMAGE The file ICR2 should be looked at to see this in detail. UCC 4th/86 COMPILING page 26 ============== ILOAD & GIMAGE ============== This allows a previously saved xxx.IMG file to be re-loaded in the cross-compile mode. To see how it is done, look at UCC1.BLD It is ONLY possible to ILOAD the xxx.IMG fiole back into the SAME system that it was ISAVEd from -- otherwise a phase error results. It must also be the FIRST file loaded otherwise it will not run. This is why some of the xxx.DEM files do not use ILOAD. ====== SYSTEM ====== SYSTEM is a word which prints out the dictionary and code space available at any stage. In cross-compile mode it prints additional information. === MAP === " xxxx.yyy" MAP will create a file xxxx.yyy showing all the words loaded into a system either in cross-compile or noncross mode. It will not list the words already embedded in the "mother" system. EXTRN1 and EXTRN2 are two such files -- produced by UCC1.BLD and UCC2.BLD. Addresses are included, as well as indications of Colon; Code; and Data words. Larry Buchan Electrical Engineering Dept. Hong Kong Polytechnic, Kowloon, Hong Kong. 8th July 1988 Index ----- FLOAD 2 SINE 3 SQUARE 3 SMITH 3 HILBERT 3 KALEI2 3 NORM 3 MANTST 3 SYS 3 DIR 3 TYPE 3 BYE 4 QUIT 4 DD 4 ctrl-C 4 DDL 4 DDH 4 ." 5 \ 5 .H 5 .L 5 .HB 5 .C 5 . 5 BASE 5 ." 6 DM 6 8DM 6 16DM 6 DDICT 6 PDICT 6 Colon Definitions 7 LINK 7 FORGET 7 UNLINK 7 TRACEON 8 TRACEOFF 8 TAG 8 DEBUG 8 TRACEL 8 DO..LOOP 8 TD 9 TM 9 SYNONYM 9 MAP 9 EXTRN1 9 EXTRN2 9 EMIT 10 KEY 10 TYPE 10 EDIT 11 USING 13 REDIT 13 RELOAD 13 BLOCK 14 CONST 15 ,CONST 15 DATA[ 15 UCC0.COM 16 UCC1.COM 16 UCC2.COM 16 KERNEL0.IMG 17 KERNEL2.IMG 17 EGAM.ASM 17 HILSIER 21 HILSIER2 21 batch files 21 FLOAD 23 REDEFINE 23 PRINTLOAD 23 CLOAD 23 HEAD 23 LAST 23 endproc 23 endfile 23 HEAD 24 CTLOAD 24 COLONEXIT 24 COLONENTER 24 ATTACH 25 MAKECOM 25 OMIT 25 ISAVE 25 PIMAGE 25 ILOAD 26 GIMAGE 26 SYSTEM 26 MAP 26