Programmer 7500

home *** CD-ROM | disk | FTP | other *** search

/ Programmer 7500 / MAX_PROGRAMMERS.iso / INFO / FORTH / F83HELP2.ZIP / F83HELP2.DOC

Wrap

Text File | 1987-11-08 | 27.5 KB | 635 lines

UPDATED: 3/9/85 D.C.Oshel (See apology to Laxen and Perry below.) ============================================================================== CONTENTS: Preliminary notes on F83-8080.LBR release, Forth 83 Standard Topics: Use your editor's search command to locate the roman numeral of interest. 0. Introduction, Apology, and Duck I. Notes on Disk IO using F83.COM (Major file interface words) II. Terminal and printer installation III. How to use F83's self-documenting features: VIEW and SHADOW IV. Notes on "meta-compiling", or system regeneration (not required) V. General or miscellaneous observations ============================================================================== 0. Introduction, Apology, and Duck: ----------------------------------- F83-8080.LBR contains SIG/M Vol. #154, a public domain FORTH system written by Henry Laxen and Mike Perry of Berkeley, Ca. This particular version of FORTH follows Leo Brodie's book, "Starting Forth," so far as the book goes. Brodie notes the FORTH-79 variations from his (FORTH, Inc.) subject, but is not up-to-date on the Forth 83 Standard. See August 1984 Byte for that. The 8080 Forth 83 Model 1.0.0 distributed as F83-8080.LBR is philosophically linked to, and apparently shares roots with, FIG-Forth. What is NOT included in F83-8080.LBR, at least for the beginner, is a discussion of how Forth 83 Model 1.0.0's CP/M file interface works. This notes file, F83HELP2.DOC, contains some preliminary findings about the CP/M file interface, and some general observations that may be of interest to others who are new to FORTH, or to this implementation in particular. ============================================================================== ===== DUCK! There's more than one "public domain Forth 83." ===== In the original, tentative version of this help file, I concluded with a few sarcastic remarks about the difficulty of telling the difference between "pilot error" and "designer oversight". After some reconsideration, I have decided that F83 is an extremely impressive program. F83's ability to compile itself (a feature that need only have been asserted, not actually INCLUDED, by Mssrs. Laxen and Perry) speaks volumes about the level of expertise that has gone into this program. I have since seen another "Public Domain Forth 83". Let me just say that THERE IS NOT A SINGLE EXAMPLE ANYWHERE in Laxen and Perry's fully-commented Forth 83 Standard code of such idiom as this (and I quote): DROP DROP DROP DROP DROP DROP Laxen and Perry's code is clean, commented, tight and nice; by contrast, this other dog is stacked like the proverbial brick outhouse. ============================================================================== "Not everything which looks like a duck and quacks like a duck actually IS a duck." -- Anon., apocryphally attributed to Groucho Marx ============================================================================== I. Notes on Disk IO using F83.COM: ----------------------------------- 1. Summary of common file-handling commands. These are mostly documented in the EXTEND80.BLK shadow screens (see below for definition of shadow screens.) High-level file commands: DIR display directory of current disk DEFAULT make the file which was given on the CP/M command line the CURRENT file; this appears to be the only safe file to LOAD, OK or START OPEN B:FOOBAR.BLK open file on the drive specified and make it the current file; files opened this way can be edited, but there appears to be a "feature" that prevents LOADing screens from an OPENed file: Typical result is "BDOS Err on V: Select". Use caution for now, and only LOAD the DEFAULT file. This problem was seen on a Kaypro 10. DEFINE WOLFGANG.MZT just adds filename to dictionary FOOBAR.BLK make FOOBAR.BLK the current file, if previously DEFINEd FILE? show name of the current file, if any 128 CREATE-FILE FOURIER.TFM create a new file of 128 blank screens, CP/M file length is therefore 128k. Lower case in name ok if CAPS is false, translated to uppercase otherwise. Initializes file contents, but does not OPEN it or otherwise disturb the current file. Low-level drive selection, use high-level with drive spec instead: 0 SET-DRIVE look on drive A (you thought it was 1?) 1 SET-DRIVE look on drive B (you thought it was 2?) 2 SET-DRIVE (don't do it!) >CRASH!< display garbage if DIR is next F83 doesn't know about drive C, seems to do no error-checking, and gets subtly confused after a bad SET-DRIVE High-level buffer commands: 0 LIST list screen 0 of the current file L list current screen of the current file A L toggle original/shadow screen of the current file and list it B L go back one screen and list it N L go forward one screen and list it 0 EDIT edit screen 0 of the current file ED edit current screen of the current file W editor command, W(rite block to disk DONE editor command, save changes and quit FLUSH allows you to switch a disk; Hi Level word, as compared to: CP/M RESET (low level) vocabulary command to allow command to reset disk operating system, after switching a floppy disk. (Does not resolve system crash on bad SET-DRIVE, try COLD or else reboot.) 0 BLOCK OTHER LOW LEVEL COMMANDS, these look ESTABLISH interesting but I haven't explored them yet, except that the BUZZPHRASE generator in Brodie's book works as advertised (use UM* instead of U* tho) provided you LOAD it from the DEFAULT file. =o=o=o=o=o= 2. SCREENS. Read Brodie's discussion of FORTH screens to get a general idea of how and why. In general, FORTH places 1024 bytes in a single screen, and F83 (a special case of FORTH) uses CP/M BDOS primitives to manage files of screens. Usually, a screen can be edited, but there is no restriction against putting binary data or machine code in a screen provided you don't try to LOAD it or use the editor on it. Brodie documents how to move the contents of a screen into or out of the FORTH buffers, or into and out of the editor, and how to ensure that a file with changes in its buffer is actually updated on disk. =o=o=o=o=o= 3. CP/M FILES OF SCREENS. The authors of F83 use the .BLK extension to indicate that a CP/M file contains FORTH screens. Files do not have to occupy the entire space on a disk. The .BLK extension is merely a naming convention, except that VIEW expects it. There are the same number of screens in such a file as the file's size in k, as shown by STAT or D or SD (since 1k equals 1,024 bytes equals 1 screen). The contents of the file are not determined, as mentioned above. However, when the screens contain editable programs, they are regarded as 1,024 contiguous bytes of ASCII characters, divided into 16 lines of 64 characters each. Newline characters are NOT stored; on the contrary, the lines are seen as well-defined fields by the editor. Regardless of context, a screen is 1,024 bytes. Lines are numbered from 0 to 15, and the 15th line has unusual properties in some commands (since it is the last and since the end of buffer condition is not error-trapped in most commands). Some Forths store an ASCII null in the first byte of an empty screen, to prevent it from being LOADed. Forth 83 does not appear to support this interpretation of null in the input stream (an advantage in other ways.) =o=o=o=o=o= 4. FILE ACCESS. There are AT LEAST THREE ways to specify a screen file for editing, loading, etc. The first is to specify its name on the CP/M command line when you invoke F83. This file becomes the DEFAULT file. A0>F83 FOOBAR.SCR (This method is strongly recommended.) SECONDLY: If a screen file already exists, you can also gain access to it by the OPEN word: OPEN B:FOOBAR.SCR 1 LIST 180 ED ... etc. Some of the distribution files, like META80.BLK and UTILITY.BLK, have already been DEFINEd during the system generation step. (Unless you intend to regenerate the system, or you intend to make use of the VIEW feature, there's no real need to keep the other distribution files on-line.) THIRDLY: You switch to another file by typing the name of any other DEFINEd file, and you switch back the same way. Once defined, the filename is a WORD in the FORTH dictionary, and you can use SEE to decompile its definition. However, what SEE shows you, and what you did to set up the word, are two entirely different things. THE DICTIONARY WORD CONTAINS AN FCB, as you can satisfy yourself with the command (Note: tick') ' META80.BLK >BODY 128 DUMP CAUTION: Forth requires you to pay more than usual attention to the state of your buffers. Ask yourself whether changed data has actually been written to the disk before you idly switch files. WARNING: Attempting to LOAD a file which is not the DEFAULT file will cause a system crash on a Kaypro 10 (BDOS ERR on Irrational Drive: Select), and maybe on all systems. Proceed with caution. =o=o=o=o=o= 5. CREATING A NEW FILE OF SCREENS. Use CREATE-FILE, as follows: 37 CREATE-FILE B:SILLY.BLK This command creates a new CP/M file on drive B called SILLY.BLK, which contains 37 screens. I do not know what would happen if the file was already there, but I suspect the existing version would be destroyed (no different from the CP/M bdos function that does the same thing.) The screens are initialized; that is, each one contains 1,024 blanks, ASCII 32. Documentation on this command is wholly contained in EXTEND80.BLK, where words are also defined that write a core image to disk, create FCBs, etc. You'll have to read the definitions (and between the lines) to figure some of these out, but it's not too difficult. The first shadow screen in SILLY.BLK would be located at Screen 37 2 / (i.e., 18). =o=o=o=o=o= II. Terminal and Printer Installation: --------------------------------------- F83 knows about several different kinds of terminal, include FALCO, TELEVIDEO, QUME, PERKIN ELMER, ANSI and DUMB. The default terminal is DUMB. That means that the editor behaves like a simple line editor instead of using its full-screen capability. If your computer terminal emulates, for example, the Televideo functions which do these four things as defined in F83, a) Direct cursor addressing b) Home cursor and clear screen c) Clear to end of line d) Delete current line ...then all you need to do (to define your terminal and take advantage of the editor) is to issue the command TELEVIDEO. To switch back to line editing, use the DUMB command. Unfortunately, KAYPRO is not a pre-defined terminal in F83. If you have the older model Kaypro II or 4 which simply emulated the Lear Siegler ADM-3A screen, then you must use DUMB. However, if you have the Kaypro 4'84, 4+88, "new" 2, NEW 2, 2X or either of the Kaypro 10's, then you have extended terminal characteristics defined as follows in F83: : KP-AT (S x y -- ) 27 EMIT 61 EMIT 32 + EMIT 32 + EMIT ; : KP-BLOT (S x -- ) DROP 24 EMIT ; ( DROP is required ) : KP-DARK (S -- ) 26 EMIT ; : KP--LINE (S -- ) 27 EMIT 69 EMIT ; : KAYPRO (S -- ) ['] .ALL IS .SCREEN ( NOTE: "dot-all", "dot-screen" ) ['] KP-AT IS AT ['] KP-DARK IS DARK ['] KP-BLOT IS BLOT ['] KP--LINE IS -LINE ; With this definition, you may now invoke full-screen editing with KAYPRO and switch back to line editing (if you want to) with DUMB. There are two ways to permanently install your terminal definition: 1) Hard way. Edit screen 15 of UTILITY.BLK to change the default terminal definition from DUMB to, e.g., KAYPRO. Edit one of the pre-defined but unused terminal definitions located around screen 30, using the WIPE and 0 NEW editor commands. FOLLOWING THE EXAMPLE FOR KAYPRO, define the four terminal control functions, and a command that redirects the definition of AT, DARK, BLOT, -LINE and .SCREEN, as shown above, and call that, e.g., KAYPRO (same name you used on screen 15.) You may wish to edit line 0 on the other terminal definition screens so that the first word loaded on each screen is the word EXIT (prevents unnecessary terminal defs from becoming a permanent part of F83.) With the changes made (and typos eliminated!!), do the SECOND step involved in regenerating the system. That is, LOAD KERNEL.HEX <CR> (if necessary) KERNEL EXTEND80.BLK <CR> START <CR> ... after many redefinitions you will hopefully ... get a message that you should now save the ... image of your new system with BYE and SAVE BYE <CR> 93 Pages (or 94 or 95 or whatever, depending) Warm Boot (Kaypro message) SAVE 9x MIGHTBE.COM (however many F83 showed) 2) Easy way. Enter the : definitions directly at the console, following the example given for KAYPRO. Issue the command, KAYPRO for example, then test full-screen editing. If all is satisfactory, do this: MARK EMPTY HERE FENCE ! <CR> EMPTY isn't unique BYE <CR> 93 Pages (or whatever the F83 image size really is) Warm Boot (Kaypro message) SAVE 9x MIGHTBE.COM If all is ok, rename FORTH83.COM=MIGHTBE.COM, or whatever shorthand name suits your fancy. I would suggest that you DO NOT lose your original copy of F83.COM, however, under any circumstances. CAUTION: There is a significant difference in these two methods. If you use the "Hard way", you force F83 to permanently recognize a change in the terminal definition. On the other hand, if you simply save a system image that has the new definition installed in the dictionary, your new command can be wiped out using the EMPTY word if you do not adjust the FENCE. The "Hard way" has the advantage that you can eliminate unwanted terminal definitions from deep inside the dictionary. >>> PRINTER INITIALIZATION <<< F83.COM has a pre-defined word to initialize the printer for 132 columns. The word is INIT-PR, and it is DEFERred. As distributed, INIT-PR is a simple NOOP. However, F83 also has a pre-defined word EPSON which simply does a 15 EMIT (send out Control-O, Epson condensed print command). If you put EPSON in the INIT-PR "hook", then INIT-PR jumps to EPSON and sends the Control-O to the printer instead of just to the screen. The relevant commands are: (Immediate, note tick) ' EPSON IS INIT-PR (In colon definition) ['] EPSON IS INIT-PR Obviously, DEFERred execution is powerful enough to define any kind of printer or terminal whatever, if you make the appropriate definitions. =o=o=o=o=o= III. VIEW and SHADOW, How to use F83's self-documenting features: ------------------------------------------------------------------ The .LBR file which contains F83 also contains a number of other files, the most important of which are squeezed .BLK files containing FORTH screens. At first glance, these files (META80.BLK, EXTEND80.BLK, CPU8080.BLK, UTILITY.BLK and DIRECT.BLK) are for use in "meta-compiling" a new Forth system. Surprisingly, however, they are the DOCUMENTATION for F83. The bit of magic which converts a huge program source file, incoherently organized by human standards (but just fine for computers), into a useful tool for learners is the VIEW command. F83 includes a field in all Forth words which is NOT in the Forth 83 standard -- the "View Field." (Advanced note: The view field is accessible via the >VIEW command, which converts CFA to "VFA".) All words in the Forth dictionary have a view field, and those words WHICH ARE COMPILED USING THE META-COMPILER have non-zero view fields. Words which you add have a view field, but the field is set to a "do-nothing" type of action. If you enter the VIEW command, for example VIEW FORTH-83, the interpreter looks up the view field information stored in the body of the FORTH-83 word (following the example), and uses this information to decide which of the distribution contains the SOURCE CODE DEFINITION of the FORTH-83, then LISTS the appropriate screen! All F83 source screens have a parallel SHADOW screen which contains the programmer's notes for the source (assuming the notes were written, and all those notes which are REQUIRED by the Forth 83 Standard are actually there). The SHADOW screens occupy the second half of the .BLK file. Therefore, if you VIEW FORTH-83, and if META80.BLK is on-line (mounted in a disk drive), the screen which contains the FORTH-83 definition is LISTed, and you may then examine the program notes on the SHADOW screen by typing A L. The A L command is a "toggle" which switches you back and forth between the screen and its shadow. There is always a one-to-one correspondence between source screen and shadow (documentation) screen. This relationship is purely arithmetical (the shadow is in exactly the same position in the last half of the file as the original is in the first). The feature is deliberately intended to make it easy for program source files to be heavily commented "on the fly", and thereby removes at least one excuse which keeps programmers from writing documentation until last (if at all). There are two other helpful commands along these lines: SHOW and LISTING. Both require that the line printer be set up for 132 column printing. The LISTING command will print out the ENTIRE CONTENTS of the "current" file, in two parallel columns -- source screens down the left and shadow screens down the right, three per page. The 0 15 SHOW command takes two parameters ( first last -- ) and displays the screens requested two-up and three per page. If you use the form 0 15 SHADOW SHOW, you get screens 0 through 15 down the left and the corresponding shadow screens (e.g., 89 through 104) down the right, also three per page. To get a LISTING of CPU8080.BLK, for example, you would issue the commands: INIT-PR <CR> <-- assumes you've done printer installation CPU8080.BLK <CR> <-- sets "current" file to CPU8080.BLK LISTING <CR> <-- source/shadow printout of entire file ... and then go downstairs for a cup of coffee while the pup prints out. However: VIEW, SHOW and LISTING are very powerful tools to have laying around if you know what you're looking for! The COMPLEAT BEGINNER will have a chore figuring out what the right question is, and especially learning what the full list of Forth 83 command words is. You should first read Brodie, then resign yourself to the fact that Brodie is NOT talking about Forth 83. The Byte article in August of '84 is useful, but not especially helpful to the novice. Unless you know where to get a Forth 83 glossary, you will have to alphabetize your own list -- from the WORDS command! -- and then spend a lot of time browsing around with VIEW WHATEVER and A L to get your bearings. Vocabulary-Related Commands: WORDS, VOCS, ORDER, DEFINITIONS The WORDS command can be quite helpful in this regard. It is affected by various vocabularies, and the list of words shown will be different if you are in the EDITOR vocabulary, say, instead of the FORTH vocabulary. The VOCS command will display the various vocabularies: The most important are FORTH, EDITOR, CP/M, and SHADOW. The ORDER command will display "context" -- the list of vocabularies that are searched (during execution of VIEW, for example.) It will also show "content" -- the vocabulary to which your new definitions will be added. The DEFINITIONS command will set the "content" vocabulary. An example usage is FORTH DEFINITIONS. New definitions are thereafter added to the FORTH vocabulary. >>> Subtle Note: If you VIEW QUIT you will probably get a listing of the Forth interpreter's version of the QUIT command. However, if you first specify the EDITOR vocabulary, VIEW QUIT will show you the editor's vastly different version. You switch back and forth between the vocabularies by using the commands FORTH or EDITOR. Generalize on this, there are many other possibilities! >>> The subject of vocabularies is briefly touched on in Brodie. The best general discussion I've seen is in the KAMAS User's Manual, which also uses a threaded interpretive language similar to Forth. (Details of implementation are different, but the philosophy and general outlook is the same.) =o=o=o=o=o= IV. Miscellaneous Notes and Observations: ------------------------------------------ NEAT STUFF IN F83. Here are a few WORDS I've discovered that seem to do nice things, presented in example form (no stack diagrams): .S displays the current stack non-destructively 0 200 DUMP dumps 200 bytes from memory location 0 in hex/ascii (the starting byte is shown as \/ in a ruler line!) LISTING Prints (on the printer) the contents of all current screens and their shadows (see below). Requires the printer to be initialized for 132 columns. To list some other file, you need to DEFINE it or invoke it if it's already DEFINEd. LISTING prints the DEFAULT unless otherwise specified. DEFAULT appears to be undefined unless the filename was present on the CP/M command line when you started F83. EPSON EMITs Control-O for compressed print. Nothing happens at the printer unless you first type Control-P to toggle the printer on. INIT-PR Initializes the printer for 132 col. Same as EPSON because it is a DEFERred word that has been redirected to EPSON using the ['] ... IS ... commands (or not, as the case may be. It CAN be redirected, but doesn't appear to be.) Shadow screen This is an ingenious concept which gently overcomes every programmer's instinct to write the documentation last, if at all. The shadow screen is full of comments (hopefully) about a screen meant to be LOADed. If the load screens are from 1 to N, the shadows follow at N + 1; i.e., the shadows occupy the second half of the screen file. Screen 0 and its shadow are the LOGO, as seen by the LISTING word, which fills the last page with the LOGO screen if possible. A load screen may contain any amount of text following the word EXIT. You may jump back and forth between a screen and its shadow by using the A L words. Obviously, you should create screen files twice as large, to include both load screens AND their shadow documentation. SHADOW This is a warning that shadows are a more complex subject than it might appear. SHADOW is a word that selects the shadow VOCABULARY. Its contrary command appears to be FORTH. The subject is NOT in Brodie; maybe the Forth Interest Group knows, but nobody else. NOT-SO-NEAT STUFF. Most (all?) screen displays can only be interrupted, they cannot be stop-listed using control-S. Other General Observations, Gripes, Etc.: Observation #1: The F83.COM program runs "out of the box." The steps which the authors outline to regenerate the system do not really seem to be required. You might do the "meta-compilation" steps in order to: 1) Install the full-screen editor. (Why bother?) 2) Change the user version number in the HELLO word. (Vanity?) 3) Redefine FORTH to suit your own tastes. (Good luck!?) The full-screen editor is some improvement over the line editor, but WordStar users will find it awkward and primitive. The commands are fully documented in UTILITY.BLK, Screens 15 to 32. The main commands are EXPLAINED in Brodie, but there are some enhancements which make this editor more usable than Brodie's description, especially 0 NEW, TOP, K and KEEP. Observation #2: F83 sets appropriate limits for itself when running under the slightly more restricted, 60K CP/M used by the Kaypro 10. The highest RAM occupied by F83 is all under LIMIT, which is dynamically set by the cold start routine to lie on the page boundary just below the BDOS entry vector. In other words, they did it right, and F83 should probably run correctly on most CP/M machines. Observation #3: META-COMPILATION is the process of asking FORTH to recompile itself according to the information found in those distribution files which have the .BLK extension: META80.BLK, UTILITY.BLK, etc. When you regenerate the system following the authors' instructions, you will receive MANY, MANY messages of the form "XXX isn't unique". This is apparently normal behavior, but I have no idea what effect all these redefinitions have on the way space is allocated in the dictionary, and the authors aren't saying. Beginners Note 1: When you "unsqueeze" the META80.BQK file it expands to 240k! Beginners Note 2: The first step shown by the authors is B>F83 META80.BLK OK BYE Note that the OK is a COMMAND-TYPED-BY-YOU and not a status message returned by FORTH. Observation #4: DOCUMENTATION. The beginner's reference book is Leo Brodie's "Starting Forth." However, Brodie's book discusses the FORTH, Inc. system and its variations from FORTH-79. The variations from the FORTH-83 standard are not even conceived of; there was an article in Byte about the FORTH-83 standard in August '84, but that may a burden for many people to track down. Brodie's book remains the SINE QUA NON, however, and if you are beginning at FORTH, you MUST read Brodie. It discusses the 99% of the commands that have nothing to do with the way FORTH is forced to run under the CP/M operating system. BE ADVISED that if F83.COM really is a FORTH-83 implementation, then there ARE some small variations that have a major impact, especially in the definition of boolean flags. See the Byte article (sorry). Observation #5: BUGS. There appear to be some minor bugs in F83.COM, or at least some ways of abusing the system and causing it to crash that are mostly obscure to the novice. Beginners should especially note: 1. Use UPPER case for commands. Or else execute the command: 1 CAPS ! ( ignores case except in editor ) 2. Be aware that changing the base to HEX will have effects that you may not have anticipated. For example: Executing .VERSION while the base is HEX will produce the surprising notice that your version is 0.6.4 instead of 1.0.0 -- this looks like a bug at first, but it is actually an unannounced side effect of changing the number base to HEX. Brodie spends a couple of paragraphs on this issue, so it is probably the beginner's most likely mistake. 3. Be aware that most words expect to find one, none or some parameters on the stack, and you have to put them there. 4. Be aware that VARIABLES are also WORDS. They execute by placing their address on the stack, but all you see is an "ok" out of FORTH. Randomly trying out the various words given by the WORDS command is no substitute for Brodie's book. ############ EOF: F83HELP2.DOC by David C. Oshel, Ames, Iowa, 9 March 1985