STARTUP GUIDE ------------- Chapter 1. About This Manual Section 1. Audience This manual describes the Modula-2 Implementation of Hochstrasser Computing AG for CP/M systems using a Z80 processor. It is neither a reference manual nor a course about programming in Modula-2. From the user's part, basic CP/M familiarity is assumed. Should you be a newcomer to programming, it is indispensable for you to buy and thoroughly study a text book about Modula-2; also, the lecture of books dealing with programming in general is recommended. For Modula-2 text books, please consult the bibliography that is contained in our manual. When learning Modula-2, familiarity with Pascal is useful, although not necessary. The error messages of the Modula-2 Compiler are in most cases more to the point than the ones a Pascal Compiler generates, thus, it can be even simpler to learn Modula-2 than it is to learn Pascal. Section 2. Marking and Typography Section 3. Organization The manual is divided into different parts, each of them describing one particular topic. Each of these parts begins with an overview describing the material covered in it in catchwords. When you're just starting to use the system, it is recommended to search a specific topic by browsing through these catchwords to find the desired topic. As an example, the catchwords of all the manual's main parts are presented here in tabular form. The main parts are: Part Topics covered --------------------------------------------------------------------- Startup Guide - Manual usage (you're in it right now) - System description - licensing updates, liabilities - distribution disk contents - backup and installation procedure - sample compile and run procedure Introduction to Modula-2 - Modula-2 Description - Modula-2 for Pascal Programmers Implementation Guide - System Parts, Program description - How to compile and link - System Restrictions - Standard Library description - Utility Library description Advanced Programming Guide - Using shared data and heap - Assembler Interfacing - How to achieve better efficiency Appendices - Relocatible Format Description - Reserved Words - Standard Identifiers - ASCII Character Set (Hex/Dec/Oct) - Bibliography - Error Messages - Index It is recommended to read the Startup Guide from start to end first. WARNING - DO NOT UNSEAL THE DISKS BEFORE HAVING READ THE SYSTEM REQUIREMENTS, SYSTEM FEATURES AND THE LICENSING SECTIONS. You can return the system and get your money back only as long as the seal isn't broken. If you have never programmed in Modula-2 before, it is suggested to buy a good text book on it. A bibliography can be found in the appendices. There may be new good books around; choose one that appeals to you. In all cases, read the Introduction to Modula-2 carefully. After readying the system for use, have a look at the sample programs and at the library module sources. A must for everybody is the Implementation Guide. It contains detailed descriptions of the programs belonging to the System, as well as the included libraries. The Advanced Programming Guide concentrates on more elaborate programming techniques that make the code generator produce more efficient code, as well as assembly language interfacing, operating system service usage, processes etc. --------------------------------------------------------------------- Chapter 2. System Description Section 1. System Requirements To be able to run the Modula-2 System on your computer, it has to have the following characteristics: - Z80 or official instruction set compatible processor (i.e. NEC 780, NSC 800. Sorry,k no 8080, 8085). - At least a 56k CP/M system. We only tested it under CP/M 2.2, but there seems to be no obstacle against earlier or later versions. The larger your system, the larger the programs the compiler can translate. - The compiler itself uses about 170, Bytes of disk space; though it is desirable to have at least 2 drives holding 350k Bytes each to work comfortably with the system. Section 2. System Features The Modula-2 System for Z80 generates fast, ROM-able, reentrant Z80 native code. Assembly language integration is supported, as well as assembly language compiler output. The System also sports an auto- search mechanism in the compiler as well as the linker. However, if some minor omissions are present in this package: There are no priorities and therefore no monitors set up by the compiler. This omission was made because of the Z80's "flexible" interrupt structure: There are nearly as many different interrupt schemes as Z80 based computer brands. Version Control is currently disabled. Hardware interrupt facilities can be accomplished by writing your own assembly language "Processes" module. The information necessary to do so can be found in the Advanced Programming Guide. Please do not try to get that done as your first task; get acquainted with the system first. --------------------------------------------------------------------- Chapter 3. Licensing, Updates, Liabilities and Support --------------------------------------------------------------------- Chapter 4. Getting Started This section gives an overview of the compinents of the Modula-2 System, explains how to adapt it to your computer and features a sample compilation. Therefore, please read this section carefully. Section 1. Distribution Disks The distribution diskettes contain your Modula-2 System. WARNING - Do not use these disks as your work disks. Please make at least one backup prior to any work with the system. That's in your very best interest. The following files can be found on the distribution disks: Group File Contents ------------------------------------------------------------------ Compiler MC.COM Syntax check MCP2.COM Imports & Initialisation MCP2A.COM Declaration Analysis MCP3.COM Body Analysis; Type Check MCP3A.COM Symbol File Generation MCP4.COM Code Generation, MRL output MCP4MAC.COM " , Assembler output MCL.COM Lister Linker ML.COM Pass 1 MLP2.COM Pass 2 Ref-Lister MX.COM Reference Lister Converter MR.COM REL to MRL converter Installation MP.COM System Configuration Program Library MODLIB.MRL Runtime Library Utilities CMDLIN.* Command Line Scanner CONVERSI.* Conversions (numbers <-> strings) CONVERTR.* Conversions (REAL numbers <-> strings) INOUT.* Standard I/O REALINOU.* Standard I/O for REALs MOVES.* fast moves OPSYS.* operating system access SEQIO.* Sequential File I/O FILESYS.* Sequential File I/O FILES.* Random File I/O TERMINAL.* CRT I/O TERM1.* CRT I/O (sample programs) Test Programs ACKER.MOD Ackermann function ERATOS.MOD Sieve of Erathostenes (BYTE) QUEENS.MOD Eight Queens Problem These files will be present in any case; there might be others as well. Section 2. Making a Backup Copy Your first step is now to make a copy of the distribution disks. This copy will serve as your Copy Master thereafter. To generate a copy, follow these steps: - prepare enough diskettes to hold the system. This means about 450 kBytes of diskette storage. Each of these diskettes should be formatted, SYSGENized and hold a copy of PIP, CP, or your favourite copy program. It is desirable to have also a text editor as WordStar Mince, PolyVue or ED and SUBMIT on these disks. - Copy all files from the distribution disks to your prepared disks. Use these as your copy masters from now on, i.e. all copies of the system to generate a new work disks will be taken from these disks. - Perform a configuration. See the following section for this. - make a SUBMIT-file, which permits you, to copy automatically all necessary files to make a work disks on a new disk. Such a file might look like: PIP $1:=MC*.*[v] PIP $1:=ML*.*[v] PIP $1:=MODLIB.MRL[v] PIP $1:=MX.COM[v] PIP $1:=TERMINAL.*[v] PIP $1:=SEQIO.*[v] ERA $1:TERMINAL.MOD ERA $1:SEQIO.MOD Let's call this file "MODULA2.SUB". Now insert your master disk containing this file into drive A: and the work disk-to-be into drive B:. The correct usage of the SUBMIT file would be: A>SUBMIT MODULA2 B By executing these steps, you created your master diskettes. From these, you can create all of your work disks. The components that are necessary to create a working system are: The compiler (MC*.*), the linker (ML*.*), as well as the runtime library (MODLIB.MRL). If you want to create listings without a compilation but with numbered lines and reference tables, you need also MX.COM. All other modules mentioned in the SUBMIT file can be replaced by modules developed by yourself. WARNING - Hochstrasser Computing AG and its distributors do not provide replacements for intentionally or carelessly damaged distribution disks. Therefore, do NOT use the distribution disks as your master disks or - even worse - as your work disks. Keep them "off premises" in a safe or some other secure place. Make copies of them only if necessary, i.e. if the other masters are unusable! Section 3. System Configuration The Modula-2 System features an Auto-Search-Mechanism. This allows the computer to search for files which cannot be found on a particular drive, on other drives. The system distinguishes between two so called search paths: one for Data-Files (input files) and one for its own program parts. With the aid of MP.COM, these two paths can be installed into the system. For the installation, the following files have to be present on your disk: MP.COM - The installation program MC.COM - The compiler base ML.COM - The linker base Now invoke MP as follows: NOTE - user input is -according to the typographic conventions- underlined. A>MP MODULA-2 Patcher for Z80 CP/M Version 2.01 4-Jun-85 Processing Compiler enter data search path (Default @AB ): enter program search path (Default @AB ): Processing Linker Enter Data Search Path (Default @AB ): Enter Program Search Path (Default @AB ): Installation Complete A> DataPath indicates where the programs shall get their input files from ProgPath tells the programs where to search their parts. You can spread, for instance, the compiler's parts among seven drives, if you like to do so (the compiler consists of seven files). All of the programs make internal version controls, so any mismatching (old) versions are detected. Any operation is aborted immediately in this case. as well as both consist of one to sex letters. These letters can be either "@" (the at-sign) or "A" up to and including "P". The at-sign denotes the so called default drive, the other letters correspond to the respective drives allowed under CP/M. The default drive is the one whose letter is used in CP/M's prompt: If the prompt is A>, then the A: drive is the current default drive, if it is F>, then F: is the one. If you do not indicate where CP/M shall get a file or program from, it takes it from the default drive. This drive is often referred to as the currently logged drive. NOTE - there is no way to direct the intermediate files of the compiler to another then the default drive. On a standard dual disk drive system, assuming that your copy master disk is in drive A:, MP would receive the following answers: Compiler Data Search Path: @ Compiler Program Search Path: @AB Linker Data Search Path: @ Linker Program Search Path: @AB This directs the programs to search their input on the default drive only, and their program parts first on the default drive and then on the A: drive, and finally on the B: drive. If you have, say a NorthStar Advantage with only a 320 kBytes per disk capacity, it might be reasonable to place all of the program parts on the B: drive, including the runtime library,k while your programs would be placed on drive A:. In this case, your answers change to: Compiler Data Search Path: @BA Compiler Program Search Path: B@ Linker Data Search Path: @BA Linker Program Search Path: B@ So, the linker will search for the runtime library first on the default drive (usually A:) and then on B:. The 'A' in the DataPath is included to allow compilations on B: that require files from A: to be successful. NOTE - The installation program checks for multiple usage of the same drive and does flag it as an error. Section 4. A Sample Compile and Run Session If you aren't that much curious to see "how it runs", you can skip this section and switch to the Introduction to Modula-2. On the distribution disks, you find some example programs, which are ready to compile. One fo them is "ERATOS.MOD", a sieve of Erathostenes benchmark. By following the steps explained below, you can do a sample compilation. Please do not forget to install the compiler before using it. - On your work disk, there should be the following files: ERATOS.MOD - the sample program. TERM1.MSY - the symbol module of Term1. TERM1.MRL - the relocatable file of Term1. MODLIB.MRL - the Modula-2 runtime library. OPSYS.MRL - the relocatable file of OpSys. MC*.* - the installed compiler. ML*.* - the installed linker. - Start the compilation as follows: A>MC ERATOS Modula-2 compiler for Z80 CP/M Version 2.01 4-Jun-85 Compilation of ERATOS.MOD P1. Imported Modules: TERM1 .MSY - TERM1 P2. P3. P4. A>ML ERATOS Modula-2 linker for Z80 CP/M Version 2.01 4-Jun-85 P1..................... P2..................... A>ERATOS There were 1899 primes. NOTE - The dates in the above example do not necessarily coincide with what you get from your distribution disks. Also, the number of dots output by the linker can change. Further information about the programs, their operation and usage is covered by the Implementation Guide. ===================================================================== IMPLEMENTATION GUIDE -------------------- Catchwords of this part are: - Program Description and Operation - How to Compile and Link - System Restrictions - Standard Library Description - Utility Library Description The Introduction to Modula-2 explained the Modula-2 language by comparing it to its predecessor, Pascal. Here, you will learn to operate the programs that pertain to the Modula-2 System for Z80 CP/M. Also, covered in this section are the descriptions of the library modules that are delivered with this implementation. There are several Modula-2 conventions that are at best strange for CP/M users. For instance, a ReadString operation terminates not only upon receipt of a CR character denoting a line's end, but also upon receipt of a space. So, please read the specifications of each and every library module carefully before using it. --------------------------------------------------------------------- Chapter 1. Program Operation and Usage In this section, the programs of the Modula-2 System and their particular usage will be explained. Section 1. File Types used by the System The files used by the System can be categorized after their type. This is done in the following table. 1. Table of File Types The Modula-2 System uses the following file types: Type Usage ----------------------------------------------------------------- MOD Files of type MOD are used to store the source text of Program Modules or IMPLEMENTATION MODULEs. They are compiler input files DEF DEF-typed files serve as DEFINITION MODULE source holders. Like .MOD files, they are compiler input files. MSY From each successful compilation of a DEFINITION MODULE, a so called symbol file results. These are of type MSY. These files are generated by the compiler and are also compiler input files. MRL Upon successful compilation of a MOD file, the compiler generates an object file or relocatable file. These files are of type MRL. They are also linker input files. Why MRL, not REL: Although there exist already a whole bunch of more or less compatible derivations from the standard Microsoft REL-Format, we decided to create a new, not directly compatible variant. This was necessary to have longer names than 8 characters, among other reasons. For a more detailed discussion, please have a look at the appendix The MRL Format. MAC If you selected the assembler output commandline switch of the compiler, a Microsoft M80 compatible MAC file is created instead of the usual MRL file. NOTE - You cannot simply create all MAC files, assemble them and link them using L80, because the Modula-2 linker does some work that cannot be done by L80. Please read the assembly language interface section in the Advanced Programming Guide for more information concerning this topic. MAP Upon request, the linker creates a file of the addresses of all symbols that are known to him. "Known" are only symbols that are imported by some module. These files are of type MAP: they are not compatible with SYM files. LST The compiler lister generates a file of type LST upon unsuccessful compilations (i.e. if the compiler found errors in your source program). The compiler's error messages are interspersed with your source code. REF The reference lister generates files of type REF. COM The linker generates standard executable command files of type COM. R2M Files of this type are supposed to contain name translation tables for assembly language modules. For further informa- tion about assembly language integration, consult the Advanced Programming Guide. $$$ This file type is used by the compiler for its intermediate files. Should there rest any on your disk after an interrupted compilation, you can delete all of them without danger. 2. Modula-2 Program Files Program files (they are also referenced to as compiler input files) can be created and updated with any ASCII text editor (WordStar, Magic Wand, Mince, PolyVue,...). The compiler isn't sensible regarding the "unused" hi bit of characters; you can even edit your programs in WordStar's famous "document mode" without you having to use PIP to get a clean compilation. The compiler doesn't accept control characters in string constants. Control characters are ASCII NUL (0C, 0H) .. ASCII US (37C, 1FH) and ASCII DEL (177C, 7FH). 3. Symbol Files From a DEFINITION MODULE compilation, a so called symbol file results. It contains a compressed representation of the information contained in the definition module. It also contains extracts of all modules imported by that definition module. Section 2. Program Description All programs of the Modula-2 System for Z80 CP/M will subsequently be described. All options ans switches of each program are presented. Therefore, you can use this chapter as a reference manual for program operation. First, let us introduce the general calling conventions for all programs of the System. 1. General Calling Conventions All programs of the System use the same command line interpreter and therefore, all of them are similar to use, i.e. to invoke. How you can do this is explained in this section. There are two forms of calls: (1) A>ProgramName CommandLine (2) A>ProgramName *CommandLine 'ProgramName' denotes the actual name of the program you want to invoke. It is given later in the detailed program descriptions. The form of the 'CommandLine' is for both call forms as follows: CommandLine = ModuleFileName ("/" Switch) . ModuleFileName = ModuleName ["." ModuleType] . ModuleName = character {character | digit} . ModuleType = "DEF" | "MOD" . Switch = character [":" (HexNumber | DecNumber | String)} . String = character {character} . DecNumber = digit {digit} . HexNumber = HexDigit [HexDigit [HexDigit [HexDigit]]] . HexDigit = digit | "A" | .. | "F" . digit = "0" | .. "9" . character = "A" | .. | "Z" | "a" | .. | "z" . When you call a program using form (1), it signs on this way: MODULA-2 for Z80 CP/M Version m.ss dd-mmm-yy The program immediately starts its activity. If you call one of the programs by using the second invocation variant, it signs on as follows after you entered the programs name: MODULA-2 for Z80 CP/M Version m.ss dd-mmm-yy * The star prompt is displayed and the cursor is placed right behind it. Now, you can enter the command line, which is terminated by another hit of the RETURN, ENTER, or NEW LINE key on your terminal. NOTE - None of the programs is case sensitive in its command line. NOTE - The command line interpreter is tolerant against spaces that are entered before the program name, i.e. typing A> mc myprog/v actually compiles what you intended to compile, 'myprog' in verbose mode, and not 'mc'. You may make a mistake when entering a command line. Errors of this kind are flagged by the following messages: ---- Filename Expected ---- Illegal Command Line ---- Illegal Switch /x ('x' is what you entered) ---- Illegal Use of x-Switch ( " ) In most cases, they lead to another star-prompt. Just start over and enter the whole line again. If you have specified an unknown file name, all the programs abort with the following message ---- Cannot Open File "FILENAME.TYP" Another error message can occur when your disk is (nearly) full on program start. Then, ---- Cannot File "FILENAME.TYP" appears as error message before the program aborts, where can be any one out of 'Close', 'Write To' or 'Create'. After this general remarks about program invocation and error messages, you will find detailed descriptions of each program including an 'action summary' describing what's going on during you're waiting for the respective program to finish, together with a detailed description of the switches of each one, as well as some remarks about program input-, output- and intermediate files. 2. MC the Modula-2 Compiler a) General Description The compiler's duty is to analyze your program source text, to check it for errors, and finally to create a machine language program that is equivalent to your source program. This whole process is called a compilation of your program. The Modula-2 Compiler for Z80 CP/M accomplishes this task in four steps or four passes. Pass 1 checks the program syntax. It detects all syntax errors except for misspelled identifiers (remember, Modula-2 distinguishes upper- and lowercase in identifiers). If it finds errors, then, depending on the mode you selected for the compilation, it either writes an 'E' for the first of every ten errors, or it outputs for each error a message of the form Error eee on line llll, pos. ppp 'eee' is a 1 to 3 digit error number. 'llll' indicates the line on which the error occurred, first line of your program being line one, 'ppp' the position, the first position on each line being position one. For each error, a beep sounds. If you selected the verbose output and a serious error is detected, then the compiler stops after Pass 1; in non verbose mode, the lister is called. You can look up the error messages at the very end of the manual, just before the index. Depending on the seriousness of your error(s), Pass 1 either calls the lister or it 'remedies' your error(s) so that Pass 2 can work properly on your program. Among others, missing semicolons and Pascal-style BEGINs are 'corrected'. The correct(ed) version goes to Pass 2, which checks all declarations for correctness and suitability. This is the place where some of the misspelled identifiers are likely to be detected. The error handling is the same as in Pass 1, but Pass 2 doesn't make any corrections and assumptions whatsoever on its own. If no error is detected and depending on what you compile, it calls either the SymPass (for definition modules) or Pass 3 which does all the type checking and will flag all of the unknown identifiers resulting from misspellings. The error handling is the same as in the previous passes. Additionally, Pass 3 tests if any errors occured in Pass 1 (the corrected ones). For safety's sake, it aborts compilation if Passes 2 and 3 found no error, while Pass 1 had corrected some minor ones. If no errors occur, Pass 4 gets in command of the system. Its task is to generate code. Normally, no error occurs in it; should there be an error, it will be a fatal one which ends the compilation with a message looking like: ---- Expected Token: mm Received Token: nn ---- Compiler Error 5xx on Line llll Such errors always flag an internal compiler error. If you get one, please send us a preferably small listing that provokes it. We'll try to fix it as soon as possible. If you request a listing by a command line option, Pass 4 passes control to the lister after a successful compilation. The output of Pass 4 is called an object file or a relocatable file, if the assembly language output has been selected, it is called an assembler file. SymPass is called by Pass 2, if you compile a definition module. It generates a symbol file. The last part of the compiler is the Lister. Its task is to merge the compiler's error messages with your source program into a listing file that has numbered lines and error messages in it. The error messages look as follows: **** ^nnn The 'star bar' is between line numbers; 'nnn' represents the error number that applies to a symbol beginning just above the up arrow ('^'). Should there be any errors that apply to the beginning or end of the file, they are indicated at the beginning or end of the file as follows: / nnn,nnn,... As in the above form, 'nnn' are (different) error numbers. The error message explanations are located at the very end of the manual, just before the index. b) Technical Description ProgramName MC Input Files of type DEF or MOD. Pass 2 needs files of type MSY of all imported modules. Default file type is MOD, i.e. if you simply enter a file name without type, the type is assumed to be MOD. Intermediate Several files of type $$$ are used. They are all deleted after a successful compilation. After an interrupted one, you can delete all of these files without danger. Output Depending on the type of the compiled module and on the commandline switches, either a MSY, a MRL or a MAC file will be created. If compilation errors occur and you didn't select verbose mode (see later), a LST file is generated by the lister. Switches /A, /L, /V, /X, (*$Cn *), (*$C+/- *). The A switch selects assembly language instead of the default MRL format file to be output. The output file bears the MAC type in this case. Please read the Advanced Programming Guide if you want to use this output not just to see how well the compiler optimizes. (Default: MRL output) The L switch is used to force the compiler to generate a listing also on clean compilations. Please consider the use of MX the reference lister (see later). (Default: No listing) To make the compiler verbose, set the V switch. Several informations about usage of tables internal to the compiler is written to the screen in this case. (Default: non verbose) The X switch directs the compiler to delete the file '$$$.SUB' and thereby interrupts the execution of a submit file if an error occurs. (Default: submit continues) NOTE - The file name of a given module has to coincide with the first eight characters of the module (less if the module's name is shorter). To 'coincide' means that all characters are uppercased. No lowercase characters are allowed in file names to fulfill the CP/M conventions. NOTE - All compiler switches may also be embedded in the source code in the usual form (i.e. (*$A+ *), (*$L- *)). This comment may stay anywhere in the source code. If you specify one switch multiple times, only the last setting will be acted upon. There is also one source code-only switch that serves to generate more compact, but slower code. It replaces some space-consuming inline code with calls or restarts having the same effect. To generate restarts, set the switch (*$Cn *), where n lies in the range 0..6, at the beginning of the program file. It directs the compiler to generate code using the instructions RST n * 8 and RST (n+1) * 8. The option is only readied for use by this, it is not yet turned on. If you don't want restarts (for portability), just leave out this step. This is accomplished by setting (*$C+ *). Turning it off is done by (*$C- *). These two switches can stay anywhere in the source where a comment can be placed. If the (*$Cn *) setting at the program head is missing, calls are generated instead of restarts. NOTE - Use this option for initialization procedures, Screen-I/O procedures, etc. This will ensure smallest possible code with some speed losses. c) Examples - The definition module InOut shall be compiled. A>MC INOUT.DEF MODULA-2 Compiler for Z80 CP/M Version 17-03-1985 Compilation of INOUT.DEF P1. P2. SymPass. A> resulting from this compilation is the file 'INOUT.MSY'. - Next, the implementation module InOut is to be compiled; the generation of a listing is forced. A>MC INOUT/L MODULA-2 Compiler for Z80 CP/M Version 17-03-1985 Compilation of INOUT.MOD P1.............. Imported Modules: INOUT .MSY - InOut TERMINAL.MSY - Terminal SEQIO .MSY - SeqIO CONVERSI.MSY - Conversions STRINGS .MSY - Strings MOVES .MSY - Moves P2.............. P3.............. P4.............. Lister No Error detected A> This compilation generated 'INOUT.MRL' and 'INOUT.LST'. - Working in verbose mode, the compiler shall compile the program module MAIN. A>MC MAIN/V MODULA-2 Compiler for Z80 CP/M Version 17-03-1985 Compilation of MAIN.MOD P1...... 307 bytes and 27 names in name table Imported Modules: INOUT .MSY - InOut P2...... 485 bytes in name table P3...... 15% of expression evaluation buffer used P4...... Code Size: 1307 bytes Data Size: 54 bytes A> The resulting file is 'MAIN.MRL' 3. ML the Modula-2 Linker a) General Description The linker's duty is to join different relocatible files to form an executable program. The Modula-2 Linker is implemented as a two pass linker (no, er do not have an acute multipassitis!). Pass 1 searches all parts of the program (including all library modules that are used by it) and collects the information that Pass 2 needs to generate an executable program. This split into two passes was done for the following reasons: - You can link programs as big as 64 kBytes. - The symbol table space got bigger. - The linker automatically finds all modules necessary to construct the program in its first pass. This makes it amazingly simple to operate. - All modules that are used by your program-to-be-linked have to be initialized before the program body (the main program) executes. If one of your modules relies on a second one, it is intuitively clear that the second one has to be initialized before the first one. This is also assured by the linker. The runtime library MODLIB.MRL is necessary to get the linker doing its task. The compiled code heavily relies on little routines that are collected in MODLIB. Normally, the linker works in-memory, i.e. it links the program and then flushes its buffer to disk creating your executable program file this way. Now, if your program gets really big, the linker starts to flush its buffer as soon as no more space for a module is available. This continues until either your program is linked completely, or 64 kBytes are reached. In the second case, we recommend for instance a VAX computer. Another possibility to reach the linker's limits are to create single modules of more than 25000 bytes of code. This would equal to about 4000 source program lines, according to our experiences. In this case, the linker outputs a very concise error message: ---- Module Too Big and aborts its operation. Don't you think you can split up such an enormous module? b) Technical Description ProgramName ML Input Files of type MRL. Output A COM file, upon request (see /M) also a MAP file. Switches /C:xxxx, /D:xxxx, /H:xxxx, /J:xxxx, /L, /M, /N, /O:FileName, /S:FileName, /T:xxxx, /V, /X. The C switch serves to set the code start address and is used in ROM applications only. (Default: /C:100) The D switch is the data counterpart of /C. As the above one, it is used only in ROM applications. (Default: First data byte after last code byte) The H switch allows to set the heap start to a specific address. The heap is the area used to dynamically allocate memory by means of the NEW and DISPOSE procedures. You need to set it in either ROM appli- cations or in program systems with shared data. (See Advanced Programming Guide for more information regarding this tiopc.) (Default: First heap byte after last data byte) The J switch serves to reserve space in front of the actual program start. A jump around an area of xxxxH-3 bytes is placed in the first three code locations. You can insert a copyright message, for instance. (Default: no jump generated) The L switch directs the linker to show the order in which the module initializations (the bodies of implementation modules) are executed, along with a list of the requests of each module. For each module, the linker shows if it has an initialization or not by a (+) or (-) following the module's name plus a list of the names of all modules requested by the current one. (Default: no list of initializations) The M switch directs the linker to create a MAP file containing all visible symbols of a program. MAP files aren't SYM file compatible, i.e. you cannot read them into SID or ZSID. This is because the Modula-2 System allows for much longer names than the normal REL format. (Default: no symbol map) Normally every program initializes its heap on startup. To be able to retain the heap across several chained program parts (as for instance in the compiler), you can direct the linker to omit the code that does this initialization. This is done by specifying the N switch. Programs linked with the N switch are still stored as COM files, but when started from CP/M, they print the error message ---- Modula-2 Runtime Error: Cannot Execute Chain File Refer to the Advanced Programming Guide for more information about this topic. (Default: Heap gets initialized on program startup) The O switch allows to specify an arbitrary output file name instead of the main program file name. The COM as well as the MAP file will bear the specified name. (Default: output name is main program name) The S switch allows the user to specify a shared data module. A shared data module may not contain any code. The end address of the shared data module is defined to be the address of the first heap byte - 1. So, it is located just below the heap. This implies that that /S demands that /H is used, too. The Advanced Programming Guide contains more information about sharing data between several programs. (Default: no shared data module) The T switch is used to set the Top Of Stack. This switch is used for ROM applications only. (Default: Stack Top is indicated by address found at locations 6,7 at program start) The V switch sets the linker to the verbose mode. You will see the size of code and data of each of the nonMODLIB modules in your program, as well as a statistic about code-, data-, heap- and stack size, several start and end addresses, etc. In the normal mode, the linker just outputs a dot per module in both passes. (Default: non verbose) The X switch directs the linker to delete the '$$$.SUB' file leading to abortion of a submit operation if errors occur during the linkage process. (Default: submit continues) NOTE - The linker is able to detect circular references. These are created by so called cross-imports. These can be explained as follows: You program two library modules, say X and Y. X.MOD uses variables or procedures declared in Y.DEF. Y.MOD, on the other hand, uses variables or procedures declared in X.DEF. The whole thing is often referred to as chaotic programming style -- don't worry, this can happen to everybody. Such a (non-fatal) mishap is announced by a message of the form ---- Circular reference detected -- FILENAME1 FILENAME2 The order of the two initializations will be arbitrary. You can see how it is actually done by using the /L switch. Please note that there may be circular references among more than two modules. This is just a warning and therefore, it is non-fatal. c) Anatomy of a linked Modula-2 Program A linked program loaded into the memory looks as follows: | high memory | +--------------------+ <-- T switch value | stack grows down | | | | heap grows up | +--------------------+ <-- H switch value | shared data (/S) | +--------------------+ | | | global data | | | +--------------------+ <-- D switch value | | | program code | | | +--------------------+ |initialisation calls| +--------------------+ <-- J switch value | reserved table | +--------------------+ <-- C switch value | low memory | The default values of the switches are appropriate for CP/M .COM files. d) Examples Some examples should show you that this sounds all a lot more complicated than it actually is. - The program CopyFiles is to be linked. Let's name it simply 'COPY'. A>ML COPYFILE/O:COPY MODULA-2 Linker for Z80 CP/M Version 17-03-1985 P1.......... P2.......... A> - Next, we will link the program ERATOS. The linker works in the verbose mode; it also generates a MAP file. A>ML ERATOS/V/M MODULA-2 Linker for Z80 CP/M Version 17-03-1985 P1 A:ERATOS .MRL - ERATOS Code: 265 Data: 8201 A:TERM2 .MRL - TERM1 Code: 417 Data: 12 Initial Code Start: 100H End: 10DH Length: 14 Code Start: 10EH End: 532H Length 1061 Data Start: 533H End: 2650H Length 8477 Heap Start: 2651H Stack and Heap Space: 48037 bytes (on this System) P2................. A> This results in 'ERATOS.COM' and 'ERATOS.MAP'. 4. MP the Patcher a) General Description The patcher serves to install the search paths in the compiler and the linker. All other programs do not require installation. Normally, installation is performed once only. The system as distributed in installed as used for "normal" two drive systems, i.e. search paths "@AB" for both data and programs in compiler and linker. WARNING - do NOT install on your distribution disks! Use your master diskette for this purpose. b) Technical Description ProgramName MP Input User entered search path definition and MC.COM as well as ML.COM Output Installed versions of MC.COM and ML.COM Switches None. c) Examples Refer to the Startup Guide for sample installation dialogues. 5. MX the Reference Lister a) General Description This tool serves to create line numbered listings with or without an added reference table that lists for every identifier the numbers of each line on which it appears. Every 16 lines, MX writes a dot to the console. There are several formatting options provided, including page length, line length, direct output to the printer, and suppression of the table generation. The reference lister -as the compiler lister- automatically expands hard tabs. The reference lister sets a header at the top of each page. For each program listing page, this header takes the form Reference-Lister for MODULA-2 Version 19-03-1985 Page P-x Listing for : FILENAME.TYP On all reference table pages, the header looks like Reference-Lister for MODULA-2 Version 19-03-1985 Page X-x Listing for : FILENAME.TYP Where 'x' denotes the actual page number in both headers. Every 16 program lines, a dot is written to the console to show the program's progress. b) Technical Description ProgramName MX Input Files of type DEF or MOD. Default file type is MOD, i.e. by specifying no file type, you will get a refer- ence listing of the MOD file of the specified name. This is equal to the compiler's practice. Output Files of type REF, or direct printer output (see /P). Switches /I:ddd, /L:ddd, /P, /W The I switch serves to define how many spaces the text shall be indented from left margin in characters. (Default: 15 characters indent) The L switch allows to set the page length, i.e. the number of program lines that will be printed per page. Please note that the header is 3 lines high and cannot be changed. (Default: 60 program lines per page) Setting the P switch routes the output directly to the printer instead of creating an output file. (Default: File output) The W switch controls the generation of a reference table. Setting /W suppresses this table. (Default: table added to the listing) c) Examples - A listing of the definition module InOut is to be generated. No indent shall be made. A>MX INOUT.DEF/I:0 MODULA-2 Reference Lister for Z80 CP/M Version 19-03-1985 Writing Reference Listing of INOUT.DEF ......... A> - The implementation module InOut shall be listed without a reference table, output shall be routed to the printer directly. A>MX INOUT/P/W MODULA-2 Reference Lister for Z80 CP/M Version 19-03-1985 Printing Listing of INOUT.MOD ....................... A> 6. MR the REL-MRL Converter a) General Description This program is used only if you want to integrate assembler modules into your program. If you don't intend to use assembly language modules, you can skip this section. To be able to integrate assembler modules into a Modula-2 program, you have to read the assembly language interfacing section in the Advanced Programming Guide. The duty of MR is to convert machine code that is stored as a subset of the Microsoft REL format to the Modula-2 MRL format. To accomplish this task, you have to provide - the REL file of the module - Eventually a name translation table stored in a R2M typed file. The format of the name translation table is described in the above- cited assembly language interfacing section of the Advanced Programming Guide. b) Technical Description ProgramName MR Input Files of type REL, eventually a translate table in a file of type R2M. Output A MRL typed file. Switches /C, /C:FileName, /O:FileName, /V The C switch serves to specify a translation table file. Its name defaults to the name of the input file. If you want to use this R2M file, use /C only. By specifying a file name, the file FILENAME.R2M is used as a translation table. This is useful to build a 'library' of names to be translated and their translations. (Default: no translation table) The O switch allows you to specify the output file name. This file name also serves as the fefault module base name, if no translation is done. An example: An assembled module containing the entry points GET and PUT is translated by A>MR IODRV/O:PORTIO This results in an MRL module containing the entry points PORTIO.GET and PORTIO.PUT. The V switch serves to switch MR into the verbose mode. Has only an effect if a translation table is used. In that case, all the translations are listed on the screen. c) Examples - Let us convert MOVES.REL to MOVES.MRL using MOVES.R2M as transla- tion table. A>MR MOVES/C/V Modula-2 REL to MRL converter for Z80 CP/M Version 27-12-1984 MOVES --> Moves MVL --> Moves.MoveLeft MVR --> Moves.MoveRight FILL --> Moves.Fill A> --------------------------------------------------------------------- Chapter 2. System Restrictions There are several restrictions you have to watch for. These are: ------------------------------------------------------------------- - string constants may not exceed 128 characters. They have to be on a single source line. - structures may have a maximum size of 32767 bytes. This applies to records and arrays. - Standard procedure and function procedure names may not be redefined nor assigned to procedure variables. - Type transfers by means of Type Identifiers are restricted to either both argument and result having array or record structure (structured) or being scalars (unstructured), even if the sizes are the same. - CASE labels may be in the INTEGER range only (-32768 .. 32767). The compiler allows for 256 labels (where each element of a range counts as one label) per CASE statement. - FOR statements may have upper bound values up to MAX(INTEGER) - StepWidth, or MAX(CARDINAL) - StepWidth, for FOR loops over the INTEGER or CARDINAL range, respectively. An attempt to use higher values generates an eternal loop because of the way bound conditions are checked in the generated code. The same phenome- non allows downcounting but to MIN(INTEGER) - StepWideh resp. StepWidth for INTEGER and CARDINAL FOR loops. The lower bound rule applies to enumerations, too. - No runtime error checking for INTEGER/CARDINAL overflow and underflow, use of uninitialized variables or NIL pointer refer- ences is done. The only error that gets detected is a stack - heap collision. - The maximum length of names which can be handled by the linker are 24 characters. All of these identifiers have the form "ModuleName.ObjectName". The compiler issues a warning, if two identifiers are differing only after the 14th character. - There may be 16 loops nested into each other, maximum. - The compiler allows for 16 nesting levels, at most. This means that you cannot nest more than 16 modules, procedures and/or WITH statements. LOOP statements don't affect this nesting. - No variable expressions may be passed to an ARRAY OF WORD. Constants and constant expressions as well as variables may be passed freely, however. - The index of a ARRAY OF WORD is equal to the size (-1) of the object passed to it in bytes. It is suggested to access ARRAY OF WORD parameters bytewise by using a POINTER TO CHAR. All this results from TSIZE(WORD) = 2. --------------------------------------------------------------------- Chapter 3. The Standard Library Section 1. Introduction Modula-2's great advantage is that you can build toolboxes for specific purposes using library modules. So, an important part of each imple- mentation of Modula-2 is a library that provides some basic tools as well as some more advanced ones. To have some portability ensured, a standard library has been defined by Prof. Wirth. Meanwhile, MODUS, the Modula-2 User's Society, works on an extended standard library. Some of these proposed modules are present in the utility library of this implementation (i.e. Strings, MathLib, Conversions and ConvertReal). As soon as the standard is fixed, we will adopt it. Up to that time, the Volition Systems approach will be adopted as far as possible.