~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved ~Table of Contents~ Distribution Disks . . . . . . . . . . . . . . . . . . . 1-2 General Information . . . . . . . . . . . . . . . . . . 1-2 Note on Merchantability . . . . . . . . . . . . . . . . 1-3 Program Compilation Using CED/CMD "RUN" command . . . . . . . . . . . . . 2-1 Compiler Directives . . . . . . . . . . . . . . . . . 2-5 Conditions of public distribution . . . . . . . . . . 2-8 CED/CMD Editor . . . . . . . . . . . . . . . . . . . . . 3-1 EnhComp BASIC Statements and Functions Compiler Introduction . . . . . . . . . . . . . . . . 4-1 Compiler Directives . . . . . . . . . . . . . . . . . 4-2 String Functions: An overview . . . . . . . . . . . . 4-7 ABS to XFIELD . . . . . . . . . . . . . . . . . . . . 4-3 Technical Information Variable names . . . . . . . . . . . . . . . . . . . . 5-1 Variable TYPE designations . . . . . . . . . . . . . . 5-1 Variable storage format . . . . . . . . . . . . . . . 5-1 Precision of math library . . . . . . . . . . . . . . 5-2 File buffer allocation . . . . . . . . . . . . . . . . 5-2 Support subroutine descriptions . . . . . . . . . . . 5-3 Introduction to EnhComp Z80 assembler . . . . . . . . . 6-1 Z80 source code inclusion in programs . . . . . . . . 6-1 Assembler Binary Operators . . . . . . . . . . . . . . 6-2 Allowable pseudo-ops . . . . . . . . . . . . . . . . . 6-3 Invoking the REF/CMD utility . . . . . . . . . . . . . 7-1 Appendices Alphabetical summary supported BASIC . . . . . . . . . A-1 Possible Compile Time Errors . . . . . . . . . . . . . A-9 Possible Runtime Errors . . . . . . . . . . . . . . . A-10 Reproduction of this manual in any manner, electronic, mechanical, magnetic, optical, chemical, or otherwise, without written permission, is prohibited. The MISOSYS Enhanced BASIC Compiler product is published by: MISOSYS, Inc., P. O. Box 239, Sterling, Virginia 22170-0239 [703-450-4181] LDOS is a trademark of Logical Systems, Inc. MICROSOFT is a trademark of the Microsoft Corp. TRSDOS is a trademark of Tandy Corp. ~General Information~ 1 - 1 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved Important Note Certain documentation pertaining to this package may be available after the user manual has gone to press. Consult the file entitled README/TXT for details on additional support material and errata. If you are new to LDOS, read the booklet entitled, "Running under LDOS". Distribution Disks The TRSDOS 6.x EnhComp Development System is distributed on a 40 track double density data diskette. The Model I/III EnhComp Development system works on both the Model I and Model III under LDOS 5.x, and TRSDOS 1.3. It is released on a 40 track double density Model III smalLDOS system diskette. TRSDOS 1.3 users must use the procedure outlined under TRANSFERRING ENHCOMP TO TRSDOS 1.3 and a two-drive system to transfer the files from the master disk to a working system disk. The master disk is readable by LDOS and DOSPLUS. Model I or III use under a DOS other than LDOS may require patches to one or more of the supplied programs. General Information To begin with, the EnhComp BASIC Compiler Development System comprises five files that are on the disk included with this package. These are BC/CMD, CED/CMD, REF/CMD, S/CMD, and SUPPORT/DAT. BC/CMD is the actual BASIC compiler. It normally produces a directly executable Z80 machine language /CMD file on compilation finish, from a user-supplied source program. This compiled code uses an efficient internal pseudo-code for the most part. CED/CMD is a special line-oriented editor included should you desire to use it. You can use an editor that you're familiar with if you so choose; however, EnhComp expects its input to be in either pure ASCII form, with line numbers required for every line, or in its own specially tokenized format, which is provided by CED/CMD. In addition to more efficiently storing your source code in memory and on disk because of EnhComp keyword tokenization, CED allows you to merely type 'RUN' to semi-interactively compile and execute (if 0 errors are detected) your current program, returning control to CED on program completion or compiler error abort. S/CMD is a "supervisor" program required for the interactive 'RUN'. It is a small program that automatically loads and executes CED/CMD when it is itself executed. Although CED can be used without S/CMD invocation, inter- active RUNs will be disallowed. REF/CMD is the utility for generating the reference report. SUPPORT/DAT is a relocatable library module, in a special format, which contains support subroutines needed for various BASIC instructions and util- ~General Information~ 1 - 2 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved ities. They are appended as needed to the compiled program, thus assuring that no wasted utilities are included. These files comprise the fundamental EnhComp compiler system. SUPPORT/DAT must be available on one of your disks during every compile. Compilation will automatically be aborted if SUPPORT/DAT isn't available. It is recommended that SUPPORT/DAT reside on a different drive (say, drive 1) than the compiled program destination drive (say, drive 0). This greatly reduces excessive disk drive repositioning during the compilation process. For the same reason it is a good idea to separate the source and object files on different disks. If using an interactive editor RUN, you can pre-create TEMP/BAS, which holds your source during compilation, TEMP/CMD, which holds the compiled program, and TEMP/DAT, which holds the optional reference data file, on different drives, to assure this. EnhComp acts as a translator between high level language, which most people find easiest to program in, to faster Z80 machine language (and pseudo-code), which most people find hard to program with. Sometimes this translation is simple, sometimes it's pretty complex. An experienced assembly language programmer can almost always produce more efficient code than a compiler, including the so-called optimizing compilers. Because a "core" of subroutines are included as needed, the size of relatively short EnhComp programs will be around 8-9k larger than the source file. Lacking the time and/or money required to write an assembly program from scratch to duplicate a high level program, a compiler is a good compromise, and is quicker in any case. Note on Merchantabilty Neither the author nor the Publisher of EnhComp makes any guarantee as to the fitness of EnhComp, or programs generated by EnhComp, for any parti- cular use, nor do they assume any liability whatsoever for any damages that may arise directly or indirectly through the use of EnhComp and associated material such as this manual, including through programming errors that may be found. Publisher's sole liability shall consist of replacing magnetic media found defective by the buyer upon first testing the distribution disk- ette. By using EnhComp you imply acceptance of these terms. However, the author has gone to the greatest feasible measures for testing the reliability of EnhComp and has confidence that it will work as described herein. Due to the nature of programming, certain errors will probably occur periodically, especially in a program with the complexity of EnhComp. The Publisher would appreciate receiving comments from EnhComp users about bugs found and will make every effort to correct them in future versions, which will be made available to registered purchasers of EnhComp for a nominal fee as they become available. ~General Information~ 1 - 3 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This page intentionally left blank ~General Information~ 1 - 4 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved Compilation from CED Editor The easiest way to compile a source program is to use CED to create an EnhComp program and then type RUN. For a "standard", plain vanilla compila- tion, it's as easy as an interpretive BASIC RUN, although much slower. If you have no test program handy, here's one to use. Type 'S' at DOS READY. CED will automatically be loaded. Then, using the same procedure as the TRS-80 BASIC editor (i.e., typing all lines verbatim), enter the following. 10 ' 20 ' Draws design on the screen 30 ' 40 CLS 50 FOR Y=0 TO 47 STEP 3 60 ' 70 ' Plot lines moving in opposite directions from opposing 80 ' corners 90 PLOT S,0,0 TO 127,Y:PLOT S,127,47 TO 0,47-Y 100 NEXT 110 A$=WINKEY$:END Once you've entered this simple program, simply type RUN and wait for compilation to finish; this should take around a minute and probably less if you're using hard disks or RAM disks. If TEMP/BAS already exists, the message 'Replacing existing file' will appear; otherwise, 'Creating new file' or something similar will be printed. After your source has been saved to disk (notice that the EnhComp system is usually disk I/O bound), BC/CMD will be loaded. After the initial message has been printed, the sentence 'PASS #1' will appear. EnhComp is a two pass compiler, so this is only the first run through your source program. Soon the message 'Appending support subs' will appear, along with the subroutine currently being linked. Upon completion of the first pass, 'PASS #2' informs you of the start of the last pass. When this is done, and the support routines have been linked in from SUPPORT/DAT, you'll see various information detailing the loading area in memory of the compiled program and the number of bytes required by each data table (this need not concern you at the moment.) If all went well, there will be 0 errors, and TEMP/CMD, which holds the compiled program, will be loaded and executed. After the design has been created, the 'A$=WINKEY$' instruction waits for a key to place in A$; press any key to have CED, and your source code, re-loaded for another round. Although the programming cycle is somewhat slow, as with almost all floating point, non-trivial compilers, this procedure is much less taxing and irritating than the conventional edit, save, run compiler, link, executed, etc. etc. cycle. ~Program Compilation~ 2 - 1 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved If things didn't go quite as smoothly as described; that is, if you got some error messages while compiling the program, check your program. If it was the one given, make sure you typed it in correctly. The error codes (summary given elsewhere in this manual) should help you locate the source of the problem. If the error was DOS related, an appropriate message will be given, followed by a detailed DOS error message. The supervisor will automatically give an error message if a fatal DOS error occurred (e.g., missing BC/CMD or SUPPORT/DAT). Note that, when using an interactive RUN, and barring a fatal disk error like a missing sector, your current program will be safely in TEMP/BAS should anything go drastically wrong; which can happen in such instances as bad Z80 assembly code in your source file, and so on. Simply re-boot, type 'S', and load in TEMP/BAS using 'L:TEMP/BAS'. Note that due to the external file inclusion facility of *GET or *INCLUDE, source files of any length can be compiled, up to free memory limits in the compiler data tables and loadable machine language file size. Due to the large amount of space available with CED (around 30K), this is unlikely to be a problem. *GET is usually useful for including standard library subroutines or user functions/commands. To re-iterate: If, during an interactive 'RUN', any errors are detected during compilation, control reverts back to the editor at the end of the first pass, with the original source file automatically intact. Otherwise, TEMP/CMD is loaded and executed. When the program is exited (via END or STOP or BREAK) control passes back to the editor, with source text reloaded, unless Z80 code or a compiler bug has caused a serious problem. ********************************************************* * * * ~CAUTION~ * * * * Do not attempt to invoke from DOS Ready, a program * * compiled from the supervisor mode. To generate a * * program which is to be invoked from DOS Ready, re- * * compile the source program using BC/CMD. * * * ********************************************************* Runtime Errors A program will terminate, unless an 'ON ERROR GOTO' is active, when an error condition is detected. If 'ON ERROR GOTO' is inactive, then: RUNTIME ERROR CODE ccc IN SOURCE LINE #xxxxx will appear ('xxxxx' will be invalid if the source line was unnumbered or if the line # information was suppressed in the compiled code with the 'NS' ~Program Compilation~ 2 - 2 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved directive). If compilation was invoked from an interactive RUN, control will be passed back to CED and the source reloaded. If general compilation was used (described in the following section), control will pass back to DOS READY. A complete list of runtime errors is given in an Appendix. Note that certain special DOS error codes, different than standard or unique codes, will be flagged by being in the range 32-100, with 32 added to the original code to produce the EnhComp code. The DOS error code must be between 0 and 68 to avoid confusion with other EnhComp error codes. Transferring EnhComp to TRSDOS 1.3 The following procedure is used to transfer your EnhComp system to a TRSDOS 1.3 disk. Note that the procedure requires a two-drive system. 1) Place a blank diskette in drive 1 and a working backup of EnhComp in drive 0. BOOT the EnhComp disk. 2) Type: FORMAT :1 (NAME="ENHCOMP",SDEN,CYL=35,Q=N,ABS) 3) After the disk format successfully completes, type: COPY BC/CMD:0 :1 4) Continue to copy from drive 0 to drive 1 (as you did in step 3) the files: S/CMD, CED/CMD, REF/CMD, and SUPPORT/DAT. 5) Remove the EhnComp system disk from drive 0 and BOOT your TRSDOS 1.3 system disk. Your TRSDOS 1.3 system disk should have at least 102 granules of free space. 6) Use TRSDOS 1.3's CONVERT utility to transfer the five EnhComp files from drive :1 to drive :0. 7) EnhComp should now be accessible to TRSDOS 1.3. ~Program Compilation~ 2 - 3 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved General Compilation Parameters The general format of a direct compiler invocation is: _______________________________________________________ | | | ~BC filespec,start_address,top_address,-dir-dir...~ | | | | ~filespec~ - is the source program specification. | | The extension defaults to '/BAS'. | | | | ~start_address~- is the specified program origin. | | | | ~top_address~ - is the highest address to be used | | by the compiled program. | | | | ~-dir~ - is a compiler directive. | |_______________________________________________________| As you can see, a number of variables can be changed in the invocation. The default loading address for compiled programs is 5200H (Model I/III) or 2600H (TRSDOS 6). You can change this by simply putting a comma after the filespec, followed by the desired address (in hexadecimal format). If it is necessary to limit the top memory location accessed by the compiled program, this limit can be specified as well (for example, to limit access in a 32K RAM program, BFFF would be given, the topmost valid memory location in a machine with 32K of memory). The default top_address used would be that recovered from the system's HIGH$ memory pointer at the time the compiled program was invoked. You can change compilation parameters through a device known as "direc- tives" -- so called because they are directions to the compiler, not compil- able instructions. Directives produce no code per se, although they may affect the size of the final compiled program. Directives specified in the compiler invocation input are "global" directives, so called because they affect the entire source program. You can also use directives within your source program, in which case they're called "local" directives. Some direc- tives can be used both globally and locally. The rest are restricted to either domain. Local directives are explained further on. As an example, the 'NO' global directive inhibits the generation of an object file, usually to compile a program to check for errors, without over- writing an existing object file. In the case of the TEST/BAS program, this goes as such: BC TEST/BAS,,,-NO Note the omission of the loading origin and memory limit variables. They still retain their default values. However, the commas are necessary to delimit the sentence. 'C TEST/BAS -NO' is invalid, as is 'C TEST/BAS,-NO' and 'C TEST/BAS,,-NO'. ~Program Compilation~ 2 - 4 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved Multiple directives are delimited by dashes, as in: BC TEST/BAS,8000,F000,-WD-WE In addition to the global compiler directives, which may be used, in most cases, both globally and locally, there are purely local directives, which are prefixed by an asterisk (except for Z80-MODE and HIGH-MODE). This is indicated in the directive list which follows. Note: It is important to realize that compiler directives are activated as they are encountered in the input stream in a purely linear manner from left to right; runtime program logic has no effect on their activation. Directives valid both locally and globally are prefixed with an "*-"; directives valid only within the program (locally) are prefixed with only "*". Compiler Directives BC supports the following compiler directives: GET, INCLUDE, LIST, PRT, NOLIST, NOPRT, WD, NO, Z80, NS, YS, WE, NX, YX, IF, ENDIF, INJECT, LINK, PRINT. In the following paragraphs, directives which are considered global in nature will be denoted with '(G)'; directives which are considered local in nature will be denoted with '(L)'; directives which are considered both local and global with '(B)'; and directives which are purely local with '(P)'. Remember, when you use a compiler directive within your source stream, each must be prefixed with an asterisk and dash ('*-') except for PURELY LOCAL directives which are prefixed with an asterisk only. LIST~(B) This directive will list the source program on the video screen during the second pass, with error messages. PRT~(B) This directive will print the informative and diagnostic messages as well as the source program to your line printer during the second pass, with error messages. NOLIST~(L) This local directive will turn off the source program screen listing until a subsequent LIST directive is detected. NOPRT~(L) This directive will turn off the printer listing until a subsequent PRT directive is detected. ~Program Compilation~ 2 - 5 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved WD~(B) This directs EnhComp to write the reference data file upon completion of the compilation phase. The file specification used for the reference file will be constructed with the filename of the source program and the file extension of '/DAT'. No drive extension will be appended. An informative message will be issued advising you of the file's generation. This file can be subsequently processed by the REF/CMD utility to produce a program reference report. NO~(B) This tells the compiler to refrain from writing the compiled program to a disk file. You will find it useful to speed up the compilation phase when you only want to scan for detectable source code program errors. Z80~(G) This directive causes the compiler to assume that your source program contains only Z80 assembly language. The compiler will then inhibit writing of "extraneous" high level support code. NS~(B) This directive tells the compiler to inhibit the generation of source line number information in the compiled program's object code code file. This saves 3 bytes per source code line; however, runtime diagnostics will not be able to then report the line number of a source line which causes a runtime error. The compiler default is to generate source line number information. YS~(L) This directive informs the compiler to resume the generation of source line number information (see directive NS). WE~(B) This directive will cause the compiler to wait for you to press a key when an error has been detected during compilation. This allows you to ob- serve the error diagnostic message without worrying about it scrolling off of the video screen. Any keystroke will cause a continuation of the compilation. NX~(B) The compiler normally generates code which checks for the BREAK key and handles TRON at the conclusion of each source program statement. If you do ~Program Compilation~ 2 - 6 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved not desire this BREAK key handling, the NX directive will inhibit the writing of this code. This will shorten the resulting compiled program file. Note that the local directive 'YX' can resume the generation of this handling code so that you can restrict certain segments of your program from having the BREAK handling code. YX~(L) This directive resumes the generation of the BREAK and TRON handling code. See the 'NX' directive discussion. IF exp ENDIF~(P) The IF...ENDIF directive pair provides for a conditional compilation. If the expression, 'exp', evaluates to a non-zero value, then the next lines of source up to the 'ENDIF' are compiled. Otherwise, a zero value of 'exp' re- sults in the compiler ignoring the next lines of source until the 'ENDIF' statement is reached. *INJECT filename <(offset<,lower_limit<,high_limit>>)~(P) This directive is used to insert a machine language load file into the current compilation machine code output file. If 'offset' is given, the file will be loaded into memory at a new address of 'offset+old address'. To selectively offset program loading -- say, to avoid offsetting a load to addresses in lower RAM -- a 'lower_limit' can be given (such as 4400H). Similarly, an 'upper_limit' for the offset can be given. Thus, to offset the loading of TEST/CMD between all addresses in the range 6000H-7000H by 8000H, use: *INJECT TEST/CMD(8000H,6000H,7000H) This instruction would then inject TEST/CMD into the output stream of the compiled program file. The DOS loader will then load TEST/CMD into memory along with the compiled program; any parts of TEST/CMD that would have loaded between 6000-7000 will now load into memory at E000-F000. *LINK filespec(module #, module #, ...)~(P) This directive causes the compiler to link a special link-type file into the current compiled program output. Such a file would be provided and its use documented by the publisher of EnhComp. The SUPPORT/DAT library file is an example of such a link file. In addition to great disk space efficiency, link files are "assembled" much faster than the original source. ~Program Compilation~ 2 - 7 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved *GET/*INCLUDE filespec (P) The two directives 'GET' and 'INCLUDE' are equivalent. They are used to include a secondary source program file into the input stream. This can be useful to provide a means of segregating your source program into "modules" - each module in a separate file. At the conclusion of the 'INCLUDE' file, the source stream compilation will revert back to original source program. *PRINT<#n> <"info"> <,> <;> <$(chrexp)> ~(P) This directive is used to display a compilation message on the screen or printed on a printer, depending on the current option switch settings. The '#n' specifies the pass in which to print (if omitted, the second pass only is implied). If '#n' is entered as '#0', then the message will print during both passes. A '#1' or a '#2' entry indicate that the message will print only on the first or second pass respectively. Anything in quotes is printed verbatim. The '<,>' and <;> are print delimiters as in a normal BASIC PRINT statement. For an entry of '$(chrexp)', the equivalent ASCII code is printed. The field denoted as 'exp' indicates a print expression. Compilation mode versus Interactive RUN mode The interactive RUN mode is useful for writing and debugging programs. The /CMD file produced during this time, TEMP/CMD, is not intended to be used without the S/CMD supervisor loaded and CED/CMD available on the disk. To produce a final, compiled program once development is complete, you must invoke BC/CMD directly from DOS level. The various optional parameters or directives available have been described in the last section. It might be desirable to disable the "debugging friendly" features in the compiled pro- gram (source line # printed on error, BREAK detected, TRON available) for your final copy; in addition to saving space, this will make it impossible for someone to decode your program without a lot of work. This program will be in the form of a fully independent '/CMD' file, executable as easily as an other /CMD file. BC/CMD, S/CMD, CED/CMD, and SUPPORT/DAT will no longer be needed to run the program. Independent use of compiled programs There are no restrictions (royalty payments) on compiled programs to be distributed for NON SYSTEMS SOFTWARE or UTILITIES use, such as a business program. For SYSTEMS SOFTWARE/UTILITIES (such as another compiler, or a language, and so on -- in general, anything designed to be a programming tool), public distribution is PROHIBITED without a written release from the author of EnhComp (Philip Oliver), or some kind of fee-per-copy arrangement. Without such a release or arrangement, such distribution will be considered copyright infringement of the SUPPORT/DAT subroutines. ~Program Compilation~ 2 - 8 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved CED General Information The EnhComp editor differs somewhat from the TRS80 BASIC editor. How- ever, all internal editing commands (with the 'E' command) are the same. The significant difference between the TRS-80 BASIC editor and the EnhComp editor is that the latter recognizes two types of line numbers: editing line num- bers, and BASIC line numbers. Any individual line may carry a distinctive line number, treated as a BASIC line number; for this reason, standard ASCII BASIC programs can be loaded into the EnhComp editor. Every line is numbered from 1 thru "n" in steps of one; also, where "n" is the total number of pro- gram lines. Not every line has to have a BASIC line number, but with every line is associated an edit number, representing its position relative to the beginning. This carries the advantage of never having to renumber due to line numbers too close together; the disadvantage lies in the fact that "renum- bering" occurs automatically whenever you insert or delete or copy or move lines -- so you must therefore keep track of where you are in the program. If multiple (edit) line number expressions are needed by a command, they are always separated by commas. An edit line number expression can consist of a decimal number, or the letter "T" to represent "1" (the top), or "B" to reference the bottom (last) line. Note that 'DET,B' deletes your entire pro- gram (DElete from Top to Bottom.) To recover from an unforeseen accident during a compiled program run, recall that your source text is always saved in "TEMP/BAS" if compilation was invoked from edit mode. All you have to do is reload it. NOTE: Unless otherwise mentioned or clearly implied by the context, references to line numbers are EDITOR line numbers. ? exp This command will print the integer result of the expression, 'exp'. ?F This command will print the filename of the file currently being edited. / editor_line_number, BASIC_line_number This command will add the specified BASIC line number to the line identified by the given editor line number. < BASIC line number This command will remove the specified BASIC line number from whatever editor line it is on (if it exists). ~Compiler Editor - CED~ 3 - 1 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved BLH The "BASIC Line Hide" command will suppress the display of all BASIC line numbers. BLS The "BASIC Line Show" command will restore the display of BASIC line numbers. C start_line,end_line,destination_line This command will copy a block of lines from the 'start_line' to the 'end_line' (inclusive), inserting at the 'destination_line'. DE line1 <,line2> (DL ... for BASIC line #s) The 'DE' command will delete a single line identified by 'line1'; or the multiple lines identified by 'line1' through 'line2', if 'line2' is given. Using 'DE', the line numbers entered for the deletion refer to EDITOR line numbering. If you wish to delete a line or lines according to their BASIC line number(s), specify the delete command as 'DL' in lieu of 'DE'. ELH The "Editor Line Hide" command will suppress the display of EDITOR line numbers. This is the default mode of CED. ELS The "Editor Line Show" command will restore the display of EDITOR line numbers. ERROR errcode (or ERR errcode) This command will display the full error message of the given runtime code denoted by 'errcode'. Fstring Beginning at the current line+1, this command searches through the text for the specified string. The line which contains the string is listed if a match is found, otherwise 'STRING NOT FOUND' is issued and the search stops. IMPORTANT NOTE: Do NOT include ANY SPACES after the 'F' command unless they are part of the search string. ~Compiler Editor - CED~ 3 - 2 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved GO This command causes an exit from the editor and a return to DOS. E or EDIT <'string'> (use "ED" for editor line #'s) The 'E' command is the most sophisticated of the edit commands, not surprisingly. It allows intra-line editting of a particular line or set of lines on a mostly conceptual basis (as opposed to directly perceptual screen editing.) Users of Z80 based TRS-80 computers will recognize the format of the command, since it is essentially the same as the EDIT function of the BASIC language on those computers. Note that with the 'E' (or 'EDIT') command, numbers refer to BASIC line numbers; with the 'ED' command, numbers refer to editor line numbers. Other- wise, all material in this description is precisely the same for both commands. Fundamentally, editing is done by single letters, which switch the editing mode when appropriate. Initially, only the line number is shown; the cursor is placed at the beginning of the line. This is the edit command mode. ____________________________________________________________________ | | | ~Summary of internal edit commands~ | | | | Skip over next character, displaying it | | (edit) In edit mode: Move cursor left nondestructively | | (ins) In insert mode: Move cursor left destructively | | A Leave the edit with the old line untouched | | C Change characters | | D Delete character | | H Hack line | | I Go into insert mode | | K Delete up to | | L List rest of line and restart edit on new line | | S Move cursor to occurance of after cursor | | X Move cursor to end of line, start insert mode | |____________________________________________________________________| To non-destructively move the cursor over the line and to display it one character at a time, press the space bar. The cursor won't move past the end of the line once the last character has been displayed. To non-destructively move the cursor backwards, press the backspace key. Once again, once the first character has been moved over, the cursor won't move. The space and the backspace can be seen as single letter commands. To list the entire line and then restart the edit at the beginning of a new line, type 'L'. Doing this twice will show you a "clean" version of the line you're working with. ~Compiler Editor - CED~ 3 - 3 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved To insert new characters into the line, position the cursor to the de- sired point (directly over the point of insertion) and type 'I'. Then, any characters typed will be inserted into the line at that point; what you see from the line number on will be the start of the new line. Any backspaces in insertion mode are destructive. To stop the insertion and go back to the edit command mode (the initial mode), press the key (or ). To delete characters, position the cursor directly before the character to be deleted and type 'D' (in the edit command mode.) The character just deleted will be printed between slash marks. To totally restart the edit from scratch, and call up the line as it was initially before your editing, type 'A' in edit command mode. The edit will be restarted on the next line. To "hack" the rest of the line at any given point, type 'H'. The cursor will then be placed at the end of the line and insert mode will be on. To change a character "under" the current cursor position, type ; the character will be changed to . To delete all characters from the character "under" the cursor up to and including a particular character, type . To move the cursor to the end of the line and go into insert mode, type . To move the cursor to a particular character in the line after the cur- sor position, type . If the specified character is not on the line, the cursor will be moved to the end of the line. If it is, the cursor will be placed "over" that character. In either case, edit command mode will still be active. Note that pressing the key or its equivalent will almost always abort the current command and cause a return to edit command mode. Once all editing has been completed and you're satisfied with the re- sults, hitting will enter the new line in place of the old one. If you want to leave the line alone, type in edit command mode followed by ; the line will be unchanged. Hitting will also cause an escape without changing the old line. Optionally, you can, initially, specify two parameters. If you specify a range of lines, a succession of edits will occur. In this case, after you type or to enter or escape from the edit, the next line will be edited. However, typing will cause a return to the editor command mode. You can also specify a string which will be entered just as if you had typed it in at the beginning of the edit. For example, entering: E'L'10 ~Compiler Editor - CED~ 3 - 4 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved would edit line 10, displaying it first, because of the edit command. Note that the apostrophes are actual characters to be typed, not documen- tation syntax marks. This is really only useful when a range of lines is specified. Then, you can automatically edit them without tediously typing the edit commands for each line. A left bracket, "[", in the string is taken to mean an , so entering, for example: E'I;['15,20 would insert a semi-colon at the beginning of lines 15 through 20 inclusive, editing each line automatically. This particular command would be useful to temporarily convert a range of Z80 assembler source lines to comments. Later, the semi-colons could just as easily be deleted by entering: E'D['15,20 Note that if the parameter "T,B" (without quotation marks) is specified for the line range, the entire program will be edited. As alluded to earlier, typing a number before most commands will cause that command's action to be done that number of times. For example, typing <1><2> essentially causes the space command to be done twelve times. If the end of the line isn't reached, the cursor will skip over twelve new characters. To delete 6 characters, say, type <6>. To "erase" a number just typed and essentially set it back to 1, type or its equivalent. With the and commands, the specified number of characters will be searched before the command's action is done. For example, <2> will skip the cursor over the first 'A' encountered in the line and place it over the second one found (or the end of line, whichever comes first.) And, say, <3> will delete all characters from the one "under" the cursor to the third 'I' found in the line after the cursor, inclusively -- or until the end of the line is reached. With the command, the specified number of characters will be modi- fied. If the end of the line is reached, edit command mode is enabled. H line1 <,line2> This command will print 'line1' (through 'line2' if given) on your printer. If the printer is unavailable, hit to escape. I line_number This command will begin insertion of lines at the specified line number. Hit to escape insert mode. Note that no BASIC line number is attached to these lines. ~Compiler Editor - CED~ 3 - 5 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved K:filespec This command will "Kill" (remove) a file from disk. Note the use of the mandatory colon, ':', in the command syntax. LIST linerange This command will list a range of lines to the video screen; numbers given by 'linerange' refer to BASIC line numbers. LLIST linerange This command will print a range of lines on your printer; numbers given by 'linerange' refer to BASIC line numbers. L:<(insert line)> filespec <,line1 <,line2>> This command will load source text from disk into memory. Note the use of the mandatory colon, ':', in the command's syntax. Note also that line numbers are EDITOR line numbers. The simplest form of this load command is, for example: "L:TEMP/BAS" TEMP/BAS will be either loaded into memory if there's nothing in the text buffer, or appended onto the end of the current text. If "(insert line)" is specified, the disk file will be inserted into that point in the current text. If > is/are given, only 'line1', or 'line1 through line2' inclusive, is/are loaded from the disk file (relative line numbering is used). For example: L:(10)SOURCE1/BAS Inserts "SOURCE1/BAS" starting at line 10. L:CHESS80/BAS,50,177 Loads or appends lines 50 through 177 from the "CHESS80/BAS" file. Loading stops automatically if less than 177 lines are in the file. L:(184)NWAR/BAS,15,40 This is a combination of insert/selective loading. Lines 15-40 from "NWAR/BAS" are inserted at the current line number 184. ~Compiler Editor - CED~ 3 - 6 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved M line1,line2,destination_line This command is similar to "C"opy, except that lines are moved rather than duplicated. N >>> This command renumbers the BASIC lines of a program. Four optional parameters are allowed. The first two are the current line range to renumber. The third is the new starting number. The last is the line increment. The default values are 0,65535,100,10. For example: N 100,300,10,10 would renumber all lines in the range 100-300 inclusive; the first line then being 10, the next 20, etc. N ,,100,5 would renumber the whole program, starting at 100 and advancing in increments of 5. O This command will begin appending lines without BASIC line numbers. P line1<,line2> 'P' lists 'line1' or 'line1 through line2' to the screen. If no parame- ters are given, then 15/23 lines starting with the current line are listed. Q drivenum This command will display a directory of files on the disk drive speci- fied as 'drivenum'. If 'drivenum' omitted, drive 0 is assumed. R line1<,line2> 'R' will replace 'line1' or 'line1 through line2'. The current line is printed; insert prompt allows new replacement line to be entered. Once line(s) are replaced, control passes automatically into insert mode. RUN This command starts a chain of events if the compiler editor is invoked in the supervisor mode (i.e. from "S/CMD"). First, source text is saved in ~Compiler Editor - CED~ 3 - 7 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved the file named, "TEMP/BAS". Then it's compiled into "TEMP/CMD". If the com- pilation is successful, "TEMP/CMD" is invoked; if not, control passes to the editor, with source reloaded. This also happens when the runtime program terminates in an acceptable (END/STOP/BREAK) way. Sstring This command operates the same as 'Fstring' except the search starts at the beginning of the text instead of line+1. U This command provides memory usage. It displays number of bytes used and bytes free. V:filespec > This command allows you to display lines from the specified disk source text file. W:filespec > This command writes text from memory to the specified disk file. Note the use of the mandatory colon, ':', identified in the command's syntax. If line parameters are omitted, the entire text is saved. If line parameters are given, only those lines are written to the file. X/replacement$/search$ This command will search and replace all occurances of the search$ string with the replacement$ string. The search will begin at the current line number. A stops the command. Note that only one replacement per line is done. For example: X/ent/ant replace all occurances of "ant" with "ent". Y=linespages,pagelength This command will change printer forms control parameters (for LLIST, H) to do a top_of_form, 'TOF', after 'linespages' lines. If 'pagelength' is given, this will define the number of lines total for each page of the paper you're using in your printer (usually 66). ~Compiler Editor - CED~ 3 - 8 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved Compiler Introduction EnhComp is a compiler, which differentiates it from TRS-80 BASIC inter- preters included with your DOS. The essential difference is not so much the structure of the languages themselves, but the manner in which your computer executes any given program in the languages. The resident BASIC in your machine must analyze program text every time it executes a command. Com- pilers, however, translate program text into a format that is better suited to machine interpretation than a straight BASIC program. Some compilers compile to "pseudo-code", which is space efficient but slow. EnhComp is a true compiler; it compiles directly to Z80 machine lang- uage. EnhComp does accomplish some space compression since many lengthy routines used many times thoughout compiled programs are copied just once in memory, and called as subroutines. EnhComp is unique. Not only can the programmer take advantage of a pow- erful high level language, but Z80 source code can be intermixed with the language to any extent desired. EnhComp, in fact, is not only a compiler, but a Z80 assembler that allows powerful algebraic expressions in source code statements, and takes advantage of the high level language/machine language intermix ability, with special functions that allow access to variable, line number, and label addresses. EnhComp is not guaranteed to translate your TRS-80 Model I or III interpreted BASIC programs unmodified into machine language. However, any differences are slight and easily fixed to accomodate compilation. The large repertoire of new commands and functions make it likely that you will be writing old programs over using these new features, rather than settling for the limited capabilities of the resident BASIC/Disk BASIC interpreters. EnhComp retains many of the "nice" features of interpreted BASIC that are excluded in other, inferior, compilers. For example, the key is functional during execution, if desired, and BREAKing a compiled program will result in a BREAK message along with the source code line number in which the interrupt occured. Error messages at runtime display the error code and the source code line number in which the error occured. Dynamic array allocation, up to fifteen dimensions (e.g. A(a1,a2,a3,...,a15) ), is allowed, as is dynamic string space allocation. All standard BASIC variable types are sup- ported (integer, single precision, double precision, and string.) Strings are no longer limited to 255 characters in length; 32767 is the new string length limit. "FOR-NEXT" constructs may have more than one NEXT for a single FOR, since error checking (in this case) is done at runtime, not at compile time. More than one dimension statement for the same array may occur in a program at once, but an error message will be issued at runtime if more than one of the dimensions are executed. Compiler Directives Compiler directives are not "true" commands. They simply tell the com- piler, at compile time, to do some task. The directives pertinent to the program code stream will be discussed here. All of the compiler directives ~BASIC Statements and Functions~ 4 - 1 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved are discussed in Chapter 2. HIGH-MODE This puts the compiler into High Level Compilation mode. 'HIGH-MODE' is the default compilation mode. The compiler will be looking for only "high level" commands and functions in this mode. Z80-MODE This puts the compiler into Z80 Assembler mode. High Level commands will generate expression errors in this mode. Only valid Z80 opcodes and assembler directives will be recognized. Source code line inclusion and BREAK key checking will be disabled in this mode. High Level Statements Statements are instructions that perform some specific task, and exist as independent entities; as opposed to functions, which are used inside alge- braic or string expressions, and are not used independently. Statements and functions may be used in High Level mode only (the default mode of the com- piler.) They will generate expression errors in Z80 mode. High Level Functions Functions are used with expressions. They are also used with statements; however, a function is never used alone. In general, functions can be divided into two main categories: String and Numeric. Naturally, these categories are further divided into fairly reasonable groups of related functions. String Functions: An overview Strings, as you're probably aware, are bytes which are sequentially strung together in a "string" and which can be assigned and manipulated using string variables, which can hold a string of variable length. With EnhComp, this length can be from 0 to 32767, a significant improvement over the 255 character limitation of many interpretive BASICs. EnhComp internally uses a memory-efficient string list technique to manipulate strings. This process is transparent to the user; it is worth mentioning because PRINTs or LPRINTs take up no extra string space whatever when printing a string expression -- except a small amount for generative string functions such as HEX$ and BIN$. Additionally, string assignments are fairly memory and time efficient due to the fact that string literals and STRING$ functions take up no temporary string space during the assignment; however, A$=A$+B$, say, requires that A$ and B$ take up temporary storage space due to extensive moving around of A$ and B$ during the assignment. However, the same expression, A$+B$, would take up NO temporary space if it was printed (PRINT A$+B$ or LPRINT A$+B$), regardless of the combined length of A$ and B$. In the same way, LPRINT "--> "+STRING$(128,42)+" <--" would work with 0 bytes cleared for string space. ~BASIC Statements and Functions~ 4 - 2 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This function returns the absolute value of its argument. _________________________________________________________ | | | ~ABS(exp)~ FUNCTION | | | | ~exp~ - is a numeric expression. | |_________________________________________________________| ABS returns the absolute value of an expression. If the expression evaluates to a non-negative value, that result is returned; otherwise -expression. For example: ABS(-4) = 4; ABS(0) = 0; ABS(1.414) = 1.414. ~BASIC Function: ABS~ 4 - 3 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This function obtains the absolute memory address of its argument. _________________________________________________________ | | | ~ADDRA(addr)~ FUNCTION | | | | ~addr~ - is a line number or a label. | |_________________________________________________________| ADDRA returns the absolute memory address of a specified line number or label. For example: 10 L=ADDRA(100) 20 A=PEEK(L):L=L+1:IF A=0 THEN END 30 PRINT CHR$(A);:GOTO 20 50 Z80-MODE 100 "STRING":DB 'ASCII TEXT STRING',13,0 This prints a string defined in memory, accessable as the address of line numbered 100. Alternatively, line 10 could be: L=ADDRA("STRING"), as the value of the label '"STRING"' equates to ADDRA(100). ~BASIC Function: ADDRA~ 4 - 4 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This is used to allocate the quantity of disk file control blocks. _________________________________________________________ | | | ~ALLOCATE exp~ STATEMENT | | | | ~exp~ - is the number of file control blocks to | | allocate in the range <1-15>. | |_________________________________________________________| Before any disk files can be OPENed, file control blocks must be allo- cated. 'ALLOCATE' creates up to 15 control blocks. Note that the blocks are allocated sequentially -- blocks allocated equal the highest file buffer accessable by OPEN. For example, if a maximum of 3 files will be open at once in a program, 'ALLOCATE 3' is executed before any OPENs are done. File control blocks can be specified by a variable expression -- the number of blocks to be allocated need not be a constant defined at compile time. For instance, ALLOCATE F+1 is valid. More than one ALLOCATE can exist in a program -- but only one of them may be executed (or an error will be generated.) ~BASIC Statement: ALLOCATE~ 4 - 5 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved These functions indicate their arguments as being other than decimal format numbers. _________________________________________________________ | | | ~&Bd0...d15~ - Binary number FUNCTION | | ~&Hd0...d4~ - Hexadecimal number FUNCTION | | ~&Od0...d5~ - Octal number FUNCTION | |_________________________________________________________| '&B' signals a binary number in ASCII format. For example, the assign- ments: A = B AND &B11110101 and A = B AND 245 are functionally equivalent. '&H' flags a hexadecimal ASCII format number: &H100 = 256 decimal. And, '&O' flags an octal ASCII format number: &O70 = 56 decimal. ~BASIC Functions: &B, &H, &O~ 4 - 6 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This function returns the first byte of its string argument as an integer. _________________________________________________________ | | | ~ASC(exp$)~ FUNCTION | | | | ~exp$~ - is any string expression. | |_________________________________________________________| 'ASC' takes the first byte of the specified string expression and con- verts it into numeric format. For example: 10 A$="ABC" 20 PRINT ASC(A$) prints 65, the ASCII code of the letter 'A', which is the first character in the argument, A$. ~BASIC Function: ASC~ 4 - 7 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This function obtains the arc-tangent of its argument. _________________________________________________________ | | | ~ATN(exp)~ FUNCTION | | | | ~exp~ - is a numeric expression in radian measure | |_________________________________________________________| ATN returns the arctangent of an angle assumed to be in radian degrees measure. It can receive, and return, either a single or double precision value, of full precision. Thus, if the argument is double precision, the result will be a double precision value. ~BASIC Function: ATN~ 4 - 8 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This function converts numeric expressions to a string of binary digits. _________________________________________________________ | | | ~BIN$(exp16)~ FUNCTION | | | | ~exp16~ - is in the range <-32768 to 32767> | |_________________________________________________________| BIN$ returns a 16 character ASCII binary representation of a selected integer expression. For example, BIN$(4095) is equal to "0000111111111111". ~BASIC Function: BIN$~ 4 - 9 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved These statements are used to provide key control of your program. _________________________________________________________ | | | ~BKON~ STATEMENT | | | | ~BKOFF~ STATEMENT | |_________________________________________________________| 'BKON' and 'BKOFF' can be used to effectively turn the BREAK key on or off, respectively. They affect only the BREAK scan flag. BKON will have no apparent effect if the "-NX" directive flag has been specified, since the BREAK scan code calls will be left out of the compiled program. An 'ON BREAK GOTO addr' causes a jump to the specified line number or label if the key is hit and the BREAK scan is activated. 'ON BREAK GOTO 0' disables key branching, parallel to 'ON ERROR GOTO 0'. Causing an 'ON BREAK GOTO addr' jump also automatically disables key branching. Example Program 5 ON BREAK GOTO 100 10 PRINT"HO HUM ..." 20 FOR X=0 TO 1E12: NEXT 30 PRINT"OH BOY, LET'S COUNT TO A QUADRILLION NOW!" 40 END 100 PRINT"THANKS! SAVED FROM A FATE WORSE THAN SCARFMAN...." ~BASIC Statements: BKOFF, BKON~ 4 - 10 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This function is used to convert its argument to double precision. _________________________________________________________ | | | ~CDBL(exp)~ FUNCTION | | | | ~exp~ - is a numeric expression. | |_________________________________________________________| CDBL converts a numeric expression to double precision floating point format. ~BASIC Function: CDBL~ 4 - 11 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This function converts a byte value to a one-character string. _________________________________________________________ | | | ~CHR$(exp8)~ FUNCTION | | | | ~exp8~ - is in the range <0-255>. | |_________________________________________________________| CHR$ is used to convert a number between 0 and 255 into a string character. CHR$(65) = "A" for example. ~BASIC Function: CHR$~ 4 - 12 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This function converts a numeric expression to integer format. _________________________________________________________ | | | ~CINT(exp)~ FUNCTION | | | | ~exp~ - is a numeric expression. | |_________________________________________________________| CINT converts a numeric expression to integer type. Expression must be in the range (-32768 to 32767). ~BASIC Function: CINT~ 4 - 13 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved The 'CLEAR' statement is used to clear variables and allocate string space. _________________________________________________________ | | | ~CLEAR ~ STATEMENT | | | | ~exp~ - is used to designate the amount of string | | space to reserve. | |_________________________________________________________| 'CLEAR' without expression simply zeroes all numeric variables, clears all strings, and undimensions all arrays. With expression given, 'CLEAR' does all of the previous and also redefines the amount of memory devoted to string storage, which is 100 bytes by default. If, for example, you had a program that stored a maximum of 500 strings each with a maximum length of 8 bytes, then you would need to at least CLEAR 4000 (bytes). In reality, string related functions and commands temporarily use some of the currently free string storage area as a "scratchpad", so a buffer of 600 bytes is not unreasonable -- make it: 'CLEAR 4600'. ~BASIC Statement: CLEAR~ 4 - 14 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This statement is used to close a file or files. _________________________________________________________ | | | ~CLOSE >~ STATEMENT | | | | ~blknum~ - designates a specific file to close. If no | | blknum is given, all open files are closed. | |_________________________________________________________| All open files must come to a close. 'CLOSE' assures that all important information vulnerably sitting in RAM is written safely to disk. (Disk data is usually unaffected during "I" type file access so ACCIDENTALLY not closing an "I" type file is usually harmless. CLOSE them anyway.) With a list of file control blocks given, only those blocks will be affected. CLOSEd control blocks are unaffected by CLOSE. With no specific File Control Blocks listed, ALL open files are closed. ~BASIC Statement: CLOSE~ 4 - 15 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This statement is used to clear the video display screen. _________________________________________________________ | | | ~CLS~ STATEMENT | |_________________________________________________________| This statement simply clears the screen with blanks (ASCII 32) and homes the cursor. Only a portion of the screen will be cleared if scroll protection is enabled. ~BASIC Statement: CLS~ 4 - 16 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved The COMMAND-ENDCOM construct permits you to define new BASIC commands. _________________________________________________________ | | | ~COMMAND name(input variable list)~ STATEMENT | | ~ program statements~ | | ~ENDCOM~ STATEMENT | | | | ~name~ - is a string of characters in the set | | ("A"-"Z", "0"-"9"), starting with ("A"-"Z") | | | | ~input variable list~ - is a list of (local) input | | variables. | | | | ~Note: user commands are invoked by preceding the name~ | | ~with a percent as in, '%name(operand list).~ | |_________________________________________________________| COMMAND is a powerful statement that allows you to define new commands. A user-command definition consists of the 'COMMAND' statement header, a definition body, and an 'ENDCOM' statement. Once defined, the user-command is easily and clearly referenced by the technique of "%name(operand list)". The percent sign acts as a user-command invocation symbol. Any combination of numeric and string expressions can be specified as user-command operands. For each operand specified in a user-command invoca- tion there must be a corresponding local variable in the user-command defi- nition -- "local" because the existing values of the variables listed in the definition are pushed onto the stack before they are assigned to the operands given in the user-command invocation. NOTE: input variables are restricted to simple variables and exclude array elements. So ALPH$ is a valid local input variable, but NAME$(4) is NOT. The RETURN command (inside a user-command definition), re-assigns original values to local variables and exits from the user-command. COMMAND definitions may not be nested. Also note that definitions are "defined" at compile-time, so they may exist anywhere in the program; they need not be executed. In fact, when encountered, a definition is skipped over. ~BASIC Statement: COMMAND~ 4 - 17 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved Example Program #1: 10 PRINT"FACTORIAL PROGRAM":PRINT 20 INPUT"# TO TAKE FACTORIAL OF";X 30 IF X<>INT(X) OR X<0 THEN PRINT"INVALID #.":GOTO 20 40 %FACTORIAL(X):PRINT X;"! = ";F 50 END 60 COMMAND FACTORIAL(Y) 70 IF Y<2 THEN F=1:RETURN 80 %FACTORIAL(Y-1):F=Y*F:RETURN 90 ENDCOM The preceding program needs a little explaining. The command definition body, lines 70-80, is the heart of the program. Line 70 sets 'F', the output vari- able by choice, to 1 if 'Y', the local input variable is less than 2; as it should, as 1! = 0! = 1. Line 80 is the clincher. %FACTORIAL(Y-1) is a recur- sive invocation, so called because the user-command definition is referencing itself! The opinion of poor math teachers aside, definitions that refer to themselves can be perfectly valid (with the important proviso that at some point something specific must happen and the recursion, or self-referencing, terminates); in this case %FACTORIAL(Y-1) is allowable because of the fact that 'Y' is a local variable. Intermediate values in the factorial calcula- tion are preserved. F=Y*F is a perfectly proper way to calculate the factorial, because Y! = Y * (Y-1)!, and F (before the assignment F=Y*F) is (Y-1)! because of %FACTORIAL(Y-1). Naturally, a recursive invocation has to stop sometime for it to be useful, and the "stopper" is line 70, which returns a "hard" number (1) when Y is finally decremented to 1. From then on, a sort of backlash occurs until the factorial is finally calculated. Details are left "... as an exercise for the reader." The potential power of mixing Z80 assembly language with BASIC should be evident in the next program. Example Program #2 for TRS-80 Model I/III: 10 FOR X=0 TO 255 20 %FILL(X) 30 NEXT 40 END 45 ' 50 COMMAND FILL(X%) 60 Z80-MODE 70 LD A,(&(X%)):LD HL,3C00H:LD (HL),A 80 LD DE,3C01H:LD BC,03FFH:LDIR 90 HIGH-MODE 100 ENDCOM Screen memory is filled with all possible characters, making a rapidly changing display. You Z80 programmers can figure this program out. The rest of you -- what can I say? ('learn Z80 assembly language ...'). ~BASIC Statement: COMMAND~ 4 - 18 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This statement is used to complement a pixel. _________________________________________________________ | | | ~COMPL(x,y)~ STATEMENT | | | | ~x~ - is a numeric expression which evaluates to | | the range <0 - 127> for 64-column screens | | and <0 - 159> for 80-column screens. | | | | ~y~ - is a numeric expression which evaluates to | | the range <0 - 47> for 16-row screens and | | <0 - 71> for 24-row screens. | |_________________________________________________________| SET, RESET, and COMPL form the set of the single-pixel-affecting graph- ics commands. Note that screens that display 16 rows of 64 characters will display 72 rows by 160 columns of graphics pixels; screens that display 24 rows of 80 characters will display 72 rows by 160 columns of graphics pixels. The COMPL command complements a selected graphics pixel, turning it ON if it is OFF and vice versa. The following illustrates a brief example of these graphics commands: 5 Y=23:RANDOM:CLS 10 FOR X=0 TO 127 20 SET(X,Y) 30 Y=Y+SGN(RND(3)-2) 40 IF Y<0 THEN Y=0 ELSE IF Y>47 THEN Y=47 50 NEXT 60 FOR X=0 TO 127 70 COMPL(X,23):NEXT 80 FOR X=0 TO 127 90 RESET(X,23):NEXT The program first plots a pseudo-"mountainous" profile on the screen, pro- ceeds to "complement" all graphics dots down the middle of the screen, and finally resets all pixels through the middle of the screen. ~BASIC Statement: COMPL~ 4 - 19 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This function obtains the trigonometric cosine of its argument. _________________________________________________________ | | | ~COS(exp)~ FUNCTION | | | | ~exp~ - is a numeric expression in radian measure. | |_________________________________________________________| COS takes the cosine, in radians, of an expression. It returns, in full precision, a value of the same type as exp. Thus, if the argument is a double precision type, the value returned is in double precision with full signifi- cance. ~BASIC Function: COS~ 4 - 20 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This function converts its argument to single precision. _________________________________________________________ | | | ~CSNG(exp)~ FUNCTION | | | | ~exp~ - is a numeric expression. | |_________________________________________________________| CSNG converts any numeric expression of any numeric type into a single precision format number. ~BASIC Function: CSNG~ 4 - 21 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This function obtains the position cursor of the video cursor. _________________________________________________________ | | | ~CURLOC~ - No operands are required! FUNCTION | |_________________________________________________________| 'CURLOC' returns the position of the video screen cursor. The position obtained is a value from 0 to n where n+1 repreents the total number of characters displayable on the video screen (0-1023 for 16x64 and 0-1919 for 24x80). 'PRINT @ CURLOC, ...' is normally equivalent to 'PRINT ...'. ~BASIC Function: CURLOC~ 4 - 22 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved The 'CVD' function unpacks the 8-byte string argument to a double precision floating point number. _________________________________________________________ | | | ~CVD(exp$)~ | | | | ~exp$~ - is an 8 byte string expression | |_________________________________________________________| CVD's primary purpose is to convert a double precision number stored in a file on disk as an 8-byte string back into double precision format. It is the converse of the MKD$(exp) string function. MKD$, described elsewhere, converts a double precision numeric expression into an eight byte string containing the double precision data. EXP = CVD(MKD$(EXP)). The 'CVI' function unpacks the 2-byte string argument to an integer number. _________________________________________________________ | | | ~CVI(exp$)~ | | | | ~exp$~ - is a 2-byte string expression. | |_________________________________________________________| The main purpose of CVI is to convert an integer stored as a 2-byte string on disk by the converse string function MKI$(exp) back into an integer. EXP = CVI(MKI$(EXP)). The 'CVS' function unpacks the 4-byte string argument to a single precision floating point number. _________________________________________________________ | | | ~CVS(exp$)~ | | | | ~exp$~ - is a 4 byte string expression. | |_________________________________________________________| The prime function of CVS is to convert a single precision number, con- verted into a 4 byte string by the MKS$ string function and stored in a disk file, back into a single precision number. EXP = CVS(MKS$(EXP)). ~BASIC Functions: CVD, CVI, CVS~ 4 - 23 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This function returns the system date as a string. _________________________________________________________ | | | ~DATE$~ There is no operand FUNCTION | |_________________________________________________________| The system date is returned as an eight-character string of the form, MM/DD/YY. ~BASIC Function: DATE$~ 4 - 24 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This statement allows you to declare a list of data items to be input with the READ statement. _________________________________________________________ | | | ~DATA datalist~ STATEMENT | | | | ~datalist~- is a list of numbers or alphanumeric | | strings, quoted or unquoted; each item is | | separated by a comma. | |_________________________________________________________| DATA provides an efficient way to store many static pieces of data in a program (such as a tax table). Executing a DATA statement does nothing as program execution jumps over the data list. READ is the mechanism used to read from DATA lists. READ has the pecul- iar attribute that it can read a DATA item as either a string or a number. An item can always be read into a string (as a string of characters). An item can SOMETIMES be read as a number -- if it's a number. READ A$ reads the next DATA item (say 1.618033) literally, character by character, into A$; in this case an 8 byte string. READ A, using the same item, stores into A the binary equivalent of the converted string 1.618033. RESTORE and RDGOTO provide ways to point at the desired data list. RDGOTO, especially, eliminates the wasteful process of reading and discarding lists of data to get to the desired list required in interpretive BASIC. Initially, the first data item read, unless the data pointer is changed by a RDGOTO/RDGTO statement, will be the first data item in the first DATA statement in the program. Example Program: 5 RDGOTO "PRIME" 10 READ TITLE$:PRINT TITLE$:PRINT:READ N 20 FOR X=1 TO N:READ A:?A,:NEXT 30 END 35 ' 40 "FIB" 50 DATA The first EIGHT Fibonacci numbers in order 60 DATA 8, 1,1,2,3,5,8,13,21 70 "PRIME" 80 DATA The first NINE prime numbers in sequential order 90 DATA 9, 2,3,5,7,11,13,17,19,23 ~BASIC Statement: DATA~ 4 - 25 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved 'DEC' is used to decrement an integer variable. _________________________________________________________ | | | ~DEC intvar~ STATEMENT | | | | ~intvar~ - is either an integer variable or an integer | | array element. | |_________________________________________________________| 'INC' and 'DEC' provide a very quick way to increment or decrement a specified integer variable, respectively. Examples: INC A%: 'A% = A% + 1 DEC B%(10): 'B%(10) = B%(10) - 1 ~BASIC Statement: DEC~ 4 - 26 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved These 'DEFxxx' commands are used to declare a group of variables to be of a specific type: integer, single precision, double precision, or string. _________________________________________________________ | | | ~DEFDBL letters~ STATEMENT | | | | ~DEFINT letters~ STATEMENT | | | | ~DEFSNG letters~ STATEMENT | | | | ~DEFSTR letters~ STATEMENT | | | | ~letters~ - is a list of letters (A-Z) flagging all | | variables beginning with specified letter. | | Multiple letters are separated by a comma | | in the list. Two letters separated by a | | dash indicates both letters and all letters | | alphabetically between them (e.g. B-E | | specifies B,C,D, and E). | |_________________________________________________________| The standard default type for variables, when no type declaration character suffix follows a variable (% = integer with 2 bytes of storage needed, ! = single precision with 4 bytes of storage needed, $ = string with 4 bytes of storage needed, # = double precision with 8 bytes of storage needed), is single precision. However, the above listed commands alter the default types for selected variables -- all variables beginning with the specified letter(s) in the list. For example, 'DEFINT A-K' instructs the compiler to assume that all following untyped variables starting with one of the letters A,B,C,D,E,F,G,H or K are integers (integer type). *********************************************************** * * * IMPORTANT INCOMPATIBILITY NOTE: All above statements * * are, in reality, COMPILER PSEUDO-OPs! They affect * * compiled output as they are LINEARLY encountered * * sequentially in a source line, not as they are * * LOGICALLY encountered. For example: * * * * IF A=3 THEN DEFSTR A-Z ELSE DEFINT A-Z * * * * sets all following untyped variables to be strings, * * and then immediately assumes them to be integers. * * In other words, RUNTIME LOGIC has ABSOLUTELY NOTHING * * TO DO with setting untyped variable type defaults, * * unlike interpretive BASIC. In fact, the compiler * * generates no code for DEFINT,DEFSTR,DEFDBL or DEFSNG. * * * *********************************************************** ~BASIC Statements: DEFDBL, DEFINT, DEFSNG, DEFSTR~ 4 - 27 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This statement is used to define single-line user-defined functions. _________________________________________________________ | | | ~DEFFN name(input variable list) = exp~ STATEMENT | | | | ~input variable~ - is any simple string or numeric | | variable. Arrays are not allowed. | |_________________________________________________________| DEFFN is used to define a function capable of being evaluated from a single expression. It operates similarly to Interpretive BASIC. EnhComp uses FUNCTION as a powerful statement that allows new multi-lined functions to be defined. DEFFN is an interpretive Disk BASIC feature. The statement| DEFFN name(input variable list) = exp is functionally equivalent to: FUNCTION name(input variable list): RETURN exp: ENDFUNC ~BASIC Statement: DEFFN~ 4 - 28 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved The 'DIM' statement is used to allocate space for one or more arrays while specifying the array dimensions. _________________________________________________________ | | | ~DIM array(explist) <,array2(exp)...>~ STATEMENT | | | | ~array~ - is an array name. | | | | ~explist~ - is an expression or list of expressions, | | specifying the index limits of the array. | |_________________________________________________________| Until an array is DIMensioned, it cannot be accessed. DIMensioning sets up the index limits (defining the acceptable range of index values) and allocates memory for array data. For example: 10 DIM A(10) 20 FOR X=0 TO 11:A(X)=X*X:NEXT will cause an error when X=11, which exceeds the dimensioned limit of 10. Multiple dimensions can be done with one 'DIM' statement by separating the arrays by commas -- i.e. DIM X(60),Y(75). EnhComp allows the actual index limits in the 'DIM' statement to be undefined at compile time (in other words, specified by variables and resolvable only at run-time) -- unlike many other BASIC compilers. For example, the statement: DIM TAX(A,B) is allowed by EnhComp, because the dimension will occur dynamically when the compiled program is run, but disallowed by BASIC compilers that need con- stants as index limits to precompute the amount of space needed for all array elements. ~BASIC Statement: DIM~ 4 - 29 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This statement is used to scroll the video screen down one line. _________________________________________________________ | | | ~DOWN~ STATEMENT | |_________________________________________________________| 'DOWN' scrolls the entire screen down by one line, clearing the top line. ~BASIC Statement: DOWN~ 4 - 30 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This statement is used to draw a "turtle graphics" figure. _________________________________________________________ | | | ~DRAW 'flag' @ x,y USING array%(exp)~ STATEMENT | | | | ~'flag'~ - designates the type of pixel action: | | 'S' signifies unconditional SET; | | 'R' signifies unconditional RESET; | | 'C' signifies pixel COMPLement. | | ~x,y~ - is the coordinate of the starting point. | | x is in the range (0-127|0-179); y is in | | the range (0-47|0-71). | | | | ~array%(exp)~ - is an integer array element. | |_________________________________________________________| Essentially, DRAW takes a list of line segment lengths combined with rotations, specified in any specified integer array at any point in the array (such as A%(10) or B%(18)), and plots a figure on the screen based on the list. The concept is very similar to turtle graphics in the LOGO language. EnhComp DRAW allows 256 degrees of rotation and is properly scaled to assure minimal distortion of rotated figures. That is, a box will still look much like a box when it is rotated say 60/256s of a circle (60 DRAW degrees) and redrawn. Furthermore, the lengths of its sides will be close to that of the unrotated figure. In addition to allowing 256 degrees, DRAW allows non- integer line lengths and scaling: line lengths are specified in 1/256 graphics pixel width units. To set up a turtle graphics figure, dimension an integer array to at least 4*L-1, where 'L' is the required number of line segments needed to draw your figure. Each entry requires 4 bytes, encoded into a specified integer array (A in this example) in the following manner: A%(x) = (Byte_1) + 256 * (Byte_2) where Byte_1 is n/256 fraction of line length and Byte_2 is the integer part of the line length. Bytes 1 and 2 con- tain the line length information: (BYTE 2) + (BYTE 1)/256 is the line length. A%(x+1) = (Byte_3) + 256 * (Byte_4) where Byte_3 specifies the rotation num- ber in DRAW degrees (0-255) and Byte_4 is the ENTRY code. Byte_3 contains the number of degrees relative to the current orientation to draw the next line. The ENTRY code specified by Byte_4 is determined from the following table: ~BASIC Statement: DRAW~ 4 - 31 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved ____________________________________________________ | | | Code Number Signifying | | ----------- -------------------------------- | | 0 List end; terminate DRAW | | 1 Draw line according to DRAW flag | | 2 Unconditionally SET line | | 3 Unconditionally RESET line | | 4 Unconditionally COMPL line | | 5 - 255 Ignore entry | |____________________________________________________| Example Program: 10 DEFINT F 15 CLS 20 DIM FIGURE1(110) 25 Y=0 30 FOR X=0 TO 250 STEP 10 40 FIGURE1(Y)=X*6:' Set line length = 6*X/256 units 50 FIGURE1(Y+1)=X+256:' Rotation = X, entry code = 1 55 Y=Y+2 60 NEXT:' Continue until figure completed 70 FIGURE1(Y+1)=0:' Set 0 entry code to terminate list 75 ' 77 ' Draw it! 79 ' 80 DRAW SET@ 64,23 USING FIGURE1(0) Notice that 'FIGURE1(0)' in line 80 above specifies the DRAW to begin inter- preting entries at the first array entry. DRAW SET@ 64,23 USING FIGURE1(2) would skip drawing the first line in the figure specified by FIGURE1(0). Drawing begins at location (64,23) and the object is SET on the screen as per the DRAW flag 'SET'. DRAW RESET@ 64,23 USING FIGURE1(0) executed just after line 80 would immediately clear the figure off the screen. ~BASIC Statement: DRAW~ 4 - 32 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This statement is used to terminate your program and return to DOS. _________________________________________________________ | | | ~END~ STATEMENT | |_________________________________________________________| END causes a transfer back to DOS via the @EXIT address. ~BASIC Statement: END~ 4 - 33 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This function obtains the line number of the line containing an error. _________________________________________________________ | | | ~ERL~ - No operands are required! FUNCTION | |_________________________________________________________| 'ERL' is usually used inside an error-trapping routine that was invoked by an error that occured with an active 'ON ERROR GOTO'. If the line number is available, ERL returns the source line # in which the error happened. ~BASIC Function: ERL~ 4 - 34 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This function obtains the error code of the last error generated. _________________________________________________________ | | | ~ERR~ - No operands are required! FUNCTION | |_________________________________________________________| 'ERR' holds the code of the last error generated. As a consequence, it holds useful information only after an error occurs, which implies that an 'ON ERROR GOTO addr' must be active to override the standard error message and exit. ~BASIC Function: ERR~ 4 - 35 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This statement is used for runtime program error control. _________________________________________________________ | | | ~ERROR exp8~ STATEMENT | | | | ~exp8~ - is a numeric expression which evaluates to | | the range (0-255). | |_________________________________________________________| The ERROR command forces a runtime error to occur. Normally, an error message 'RUNTIME ERROR CODE ccc IN SOURCE LINE #lllll' is printed and pro- gram execution is stopped. If an 'ON ERROR GOTO addr' is active, program execution branches to the address specified by the ON ERROR GOTO statement on occurance of a runtime error. 'ON ERROR GOTO 0' disables this feature and causes the visual error message previously mentioned. ~BASIC Statement: ERROR~ 4 - 36 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved 'EXISTS' will check for the availability of the designated filespec. _________________________________________________________ | | | ~EXISTS(filespec$) FUNCTION | | | | ~filespec$~ - specifies which file to look for. | |_________________________________________________________| 'EXISTS' will check if the specified file is available for use. It returns a logic TRUE (-1) if the file is accessible. ~BASIC Function: EXISTS~ 4 - 37 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This function obtains the exponential of its argument. _________________________________________________________ | | | ~EXP(exp)~ FUNCTION | | | | ~exp~ - is a numeric expression. | |_________________________________________________________| EXP(exp) is equivalent to 2.7182818 ... raised to the 'exp'th power. If you're not familiar with this random-looking number, it pops up all over the place in engineering, scientific, and business problems. It returns, with full precision, a value of the same type given. ~BASIC Function: EXP~ 4 - 38 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved The 'FIELD' statement is used to assign the segments of a type "R" file record buffer to strings. _________________________________________________________ | | | ~FIELD blknum,exp as var$<,exp2 as var2$>~ STATEMENT | | | | ~blknum~ - is file control block number, 1-15. | | | | ~exp~ - is the string length. | | | | ~var$~ - is any string variable. | |_________________________________________________________| FIELD is used with "R" type files. It fields the record buffer into segments accessable by string variables, providing a means to read and write information in an orderly manner from or to any record in the file. For writing to a file, information is placed into the FIELDed variables by means of the 'LSET' and 'RSET' commands. For obtaining non-string data read from fielded string variables, the 'CVI(var$)', 'CVS(var$)', and 'CVD(var$)' functions are used. Example Program: 5 CLEAR 1000 10 ALLOCATE 1 20 OPEN "R",1,"TEST/DAT" 30 FIELD 1,256 AS A$ 40 LSET A$=STRING$(256,".") 50 PUT 1,1 60 CLOSE Line 5 gives enough room for strings to breathe. Line 10 allocates a single file block. Line 20 opens the file for use; line 30 fields A$ as entire record buffer (recall that EnhComp allows 32Kbyte length strings). Line 40 fills the record buffer with dots, and line 50 writes the record buffer to the first record in the file 'TEST/DAT', followed by the necessary CLOSE statement to neatly close the file and keep the disk directory running smoothly. ~BASIC Statement: FIELD~ 4 - 39 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved This function truncates the non-integer portion of its argument. _________________________________________________________ | | | ~FIX(exp) FUNCTION | | | | ~exp~ - is a numeric expression. | |_________________________________________________________| FIX returns the expression with the non-integer part stripped away. For example: FIX(-1.6) = -1. ~BASIC Function: FIX~ 4 - 40 ~MISOSYS Enhanced BASIC Compiler Development System~ Copyright 1986 Philip A. Oliver, All rights reserved These statements implement the typical FOR-NEXT loop construct. _________________________________________________________ | | | ~FOR indexvar = start TO end ~ STATEMENT | | | | ~NEXT >~ STATEMENT | | | | ~indexvar~- is a loop index variable. | | | | ~start~ - is any numeric expression; the initial | | value of the loop index variable | | | | ~end~ - is any numeric expression; the terminating | | top or bottom limit value of the loop. | | | | ~step~ - is any numeric expression; added to the | | loop variable in each iteration. May be | | negative, in which case 'end' is bottom and | | not top limit. | |_________________________________________________________| 'FOR' and 'NEXT' are the standard, eternal, BASIC looping construct statements. The 'FOR-NEXT' construct works by setting an index variable, specified in the initial 'FOR ...' statement, to an initial value, uncon- ditionally executing the loop code once (unless programming "tricks" are used) until a 'NEXT' is reached; then, unless the step was specified with 'STEP' in the 'FOR ...' setup, the step size is one, and this is added to the index variable. If the step is positive, 'NEXT' checks for 'indexvar' > 'toplimit'. If this is so, the statement following 'NEXT' is executed (the loop falls through). If 'indexvar' =< 'toplimit', 'NEXT' branches to the