TaylorModula-2 for MS-DOS: Demo Kit         Document Nr. MD2-DK-003-1988
------------------------------------------------------------------------


This document describes the contents and possibilities of the
TaylorModula-2 Demo Kit.


1. DEMO KIT INSTALLATION

The demo diskette contains the following files:

  DC.BAT       - Explains, compiles and executes Dhrystone 1.0 Benchmark.
  DHRY.MOD     - Main module of Dhrystone 1.0 Benchmark.
  DHRY1.DEF    - Definition module 1 of Dhrystone 1.0 Benchmark.
  DHRY1.MOD    - Implementation module 1 of Dhrystone 1.0 Benchmark.
  DHRY2.DEF    - Definition module 2 of Dhrystone 1.0 Benchmark.
  DHRY2.MOD    - Implementation module 2 of Dhrystone 1.0 Benchmark.
  DHRY3.DEF    - Definition module 3 of Dhrystone 1.0 Benchmark.
  DHRY3.MOD    - Implementation module 3 of Dhrystone 1.0 Benchmark.
  HELLO.MOD    - Very simple program example.
  MOD.BAT      - Batch procedure compiling, linking, and executing a
                 Modula-2 main module or compiling and storing a
                 Modula-2 implementation module into a library.
  README.TXT   - This text.
  RUNTIME.DLB  - Definition library of runtime system modules,
                 small memory model.
  RUNTIME.ILB  - Implementation library of runtime system modules,
                 small memory model.
  RUNLARGE.DLB - Definition library of runtime system modules,
                 large memory model.
  RUNLARGE.ILB - Implementation library of runtime system modules,
                 large memory model.
  SIEVE.MOD    - Sieve of Eratosthenes Benchmark.
  STANDARD.DLB - Definition library of standard library modules,
                 small memory model.
                 (limited).
  STANDARD.ILB - Implementation library of standard library modules,
                 small memory model.
                 (limited).
  STDLARGE.DLB - Definition library of standard library modules,
                 large memory model.
                 (limited).
  STDLARGE.ILB - Implementation library of standard library modules,
                 large memory model.
                 (limited).
  TLIB.EXE     - Librarian.
  TLINK.EXE    - Linker.
  TMODULA.EXE  - Compiler (limited).
  TREE.MOD     - Binary Tree Benchmark.

To install the TaylorModula-2 demo kit, simply copy all files from the
demo diskette into a subdirectory of your disk or onto a work diskette.

IMPORTANT: Your CONFIG.SYS file should allow DOS for at least 20 file
           handles held open simultaneously. If necessary, insert the
           line

             FILES=20

           into your CONFIG.SYS file.
           If the number of files is too small, TaylorModula will
           respond with "Cannot open file ..." error messages.


To quickly compile and run your first TaylorModula-2 program, enter

  MOD HELLO

at the DOS prompt.


2. FILES AND LIBRARIES

TaylorModula-2 deals with the following file types:

  - Modula-2 sources of definition, implementation, and main modules.
    They are standard ASCII text files.

  - Modula-2 objects of implementation and main modules as created by
    the compiler.

  - Modula-2 definition libraries contain the 'objects' of definition
    modules as created by the compiler. The compiler imports modules
    from definition libraries and stores compiled definitions in them.
    Definition libraries are created and managed by the librarian TLIB.

  - Modula-2 implementation libraries are a collection of implementation
    or main module objects. The linker imports modules from
    implementation libraries. Implementation libraries are created and
    managed by the librarian TLIB.

  - Executable programs as created by the linker. They conform to the
    MS-DOS .EXE-Format.

NOTE:

If you want to import from other libraries than STANDARD and RUNTIME
(STDLARGE and RUNLARGE in the large memory model) or libraries not
contained in the default drive and directory, you must set up a DOS
environment variable TLIBS (small memory model) or TLIBL (large memory
model) which contains the path names of all libraries from which you
want to import in compiler and linker.
If you do not end the list of libraries by a semicolon, you will be
prompted for additional libraries by compiler and linker.

Example:

You have created your own libraries, MYLIB1 and MYLIB2 from which you
want to import in the compiler (MYLIB1.DLB and MYLIB2.DLB) or the linker
(MYLIB1.ILB and MYLIB2.ILB). All your libraries are stored in the \LIB
directory. To set them up, enter:

  SET TLIBS=\LIB\MYLIB1 \LIB\MYLIB2 \LIB\STANDARD \LIB\RUNTIME;


3. OPERATING

The two steps necessary to convert Modula-2 sources to an executable
.EXE file are:

  - First compile the necessary definition, implementation and main
    modules.

  - Then link the necessary modules in order to get an executable
    .EXE-file.


   3.1  COMPILER

The compiler performs two different tasks:

  - It compiles definition modules and stores the compiled form in a
    definition library.

  - It compiles main and implementation modules and stores the object in
    a file.

The evocation format of the compiler is:

For code generating modules (main and implementation, not definition
modules):

  TMODULA source object listing

For definition modules:

  TMODULA source library listing

source is the name of the source file to be compiled.

object is the name of the object file to be created.

library is the name of the definition library to store the compiled
        definition module.

listing is the name of the listing file to be created. If you do not
        want a listing to be created (which reduces compilation time),
        specify NUL as listing file name.

Any missing or wrong (e.g. files not found) parameters must be entered
via standard input.

Examples:

To compile the source SIEVE.MOD into an object code file SIEVE.COD
and a listing SIEVE.LST, simply enter

  TMODULA SIEVE;

To compile the definition module DHRY1.DEF with the compiled definition
stored in \LIB\MYLIB1.DLB and the listing sent directly to the printer,
enter

  TMODULA DHRY1.DEF \LIB\MYLIB1 PRN


   3.2  LINKER

The linker collects all code modules required to create an executable
program. You can explicitly specify the modules to be linked or let the
linker search them among the implementation libraries (STANDARD.ILB and
RUNTIME.ILB or the ones specified in the TLIBS environment variable).

The evocation format of the linker is:

  TLINK mod1{+modi} exefile listing

mod1 and the (optional and repeatable) modi are the object code
     modules to be linked explicitly. They must be separated by plus
     signs.

exefile is the name of the .EXE file to be created.

listing is the name of the listing file to be created. If you do not
        want a listing to be created (which reduces linkage time),
        specify NUL as listing file name.

Any missing or wrong (e.g. files not found) parameters must be entered
via standard input.

Examples:

To link the main module SIEVE.COD creating the program SIEVE.EXE and
a listing SIEVE.LST, simply enter

  TLINK SIEVE;

To link the modules DHRY.COD, DHRY2.COD and DHRY3.COD without a listing
and creating the program DHRY.EXE, enter

  TLINK DHRY+DHRY2+DHRY3,,NUL


   3.3  LIBRARIAN

The librarian manages definition and implementation libraries. You can
create, list and reorganize libraries and delete members. In
implementation libraries, you can add and extract object code files. The
librarian creates an optional library listing file containing the
alphabetic list of modules contained in the library with their version
and size, and how many percents of the library file size are actually
occupied by its members. Although you add an object code file by its
file name, all members in a library are identified by their module name.
Remember that module names (like other identifiers) are case sensitive
in Modula-2!

The evocation format of the librarian is:

  TLIB library[/C|/R] listing {op};

library is the definition or implementation library to be operated on.
        Its default extension is .ILB for implementation libraries.
        Specify .DLB for definition libraries.

listing is the name of the listing file to be created. If you do not
        want a listing to be created (which reduces library management
        time), specify NUL as listing file name.

op is a list of operations terminated by a semicolon. Operations
   supported are:

    +file   - append the object file to the library or replace it (for
              implementation libraries only). file is a DOS file name.

    -module - delete the module from the library. module is the module
              name (an identifier).

    *module - extract the module from the library and create an object
              file (for implementation libraries only). module is the
              module name (an identifier).

  /C specifies that a new empty library be created. The library type
  (definition or implementation library) is derived from the library
  name extension.

  /R specifies that the library be reorganized. Reorganize your
  libraries before the used space is less than 50 % (the listing will
  show the percentage used).

Any missing or wrong (e.g. files not found) parameters must be entered
via standard input.

Examples:

To create a new implementation library MYLIB1.ILB and add the object
files DHRY2.COD and DHRY3.COD to it without creating a listing, enter

  TLIB MYLIB1/C NUL +DHRY2 +DHRY3;

To list the contents of the library STANDARD.DLB to the printer, enter

  TLIB STANDARD.DLB PRN;


    3.4  BATCH PROCEDURE MOD

MOD is a simple batch procedure performing two different tasks:

  - It compiles, links and executes main modules. The modules required
    for linkage are expected to reside in the libraries specified in the
    environment variable TLIBS (or in STANDARD and RUNTIME).

  - It compiles implementation modules and stores the object in a
    library.

The evocation format of the MOD procedure is:

  For main modules:

  MOD source

  For implementation modules:

  MOD source library

  source is the name of the source file to be compiled (the extension is
         .MOD, you MUST NOT specify it).

  library is the name of the implementation library to store the
          compiled implementation module.

Compiling modules with the MOD procedure does not create any listing at
all.

Examples:

To compile, link and execute the source TREE.MOD, enter

  MOD TREE

To compile the implementation module DHRY2.MOD and store its
implementation in library \LIB\MYLIB1.ILB, enter

  MOD DHRY2 \LIB\MYLIB1


4. METACOMMANDS

The compiler recognizes the following metacommands (embedded into source
comments):

  $CaseCheck+/-       Enables or disables CASE range checking.
  $Checks+/-          Enables or disables all runtime checks.
  $LineNumbers+/-     Enables or disables error location saving.
  $NilCheck+/-        Enables or disables NIL pointer checking.
  $OverflowCheck+/-   Enables or disables integer overflow checking.
  $RangeCheck+/-      Enables or disables range checking.
  $StackCheck+/-      Enables or disables stack overflow checking.

  $LineSize:n         Sets listing line size to n.
  $Page               Skips to a new listing page.
  $PageSize:n         Sets listing page size to n.
  $Title:"Title"      Sets listing title.

  $8087+/-            Enables or disables 80(2)87 code generation.
  $Chip:iAPXNr        Selets instruction set (iAPXNr must be 86, 186 or
                      286).
  $Large+/-           Selects small or large memory model.
  $LongReal+/-        Makes REAL a synonym of LONGREAL.
  $OpenArrayCopy+/-   Enables or disables open array parameter copying.

  $EliminateCSE+/- ,
  $KeepRegs+/- ,
  $MergeTails1+/- ,
  $MergeTails2+/- ,
  $OptimizeJumps+/- ,
  $RegVars+/- ,
  $ReorderExpr+/- ,
  $SimplifyExpr+/-    Enables or disables various optimizations.

  $Optimize+/-        Enables (default) or disables all optimizations.


5. LANGUAGE EXTENSIONS

- Standard types LONGINT (32 bit) and LONGREAL (64 bit).

- Multidimensional open array parameters (e.g. ARRAY OF ARRAY OF REAL)

- FORWARD declaration of procedures.

- Unsegmented (16-bit) and segmented (32-bit) addresses in the small
  memory model:

    Unsegmented       Segmented
    ------------      ----------------
    POINTER TO t      LONGPOINTER TO t
    NIL               LNIL
    VAR               LVAR
    ADDRESS           LONGADDRESS
    ADR               LADR

- FAR declaration of procedures (for procedure variables and parameters):

  VAR    p: PROC;

  FAR PROCEDURE FarProc;
  BEGIN
  END FarProc;

  BEGIN
    p := FarProc;
    ...

- Fixed record offsets:

  TYPE   Both = RECORD
                  i   [00]:  LONGINT;
                  low [00],
                  high [02]: CARDINAL
                END;


6. MODULE SYSTEM

The module SYSTEM could be defined as follows:

DEFINITION MODULE SYSTEM;

TYPE  BYTE, WORD, ADDRESS, LONGADDRESS;

PROCEDURE ADR (x: AnyType): ADDRESS;
PROCEDURE LADR (x: AnyType): LONGADDRESS;
PROCEDURE TSIZE (x: AnyType): CARDINAL;
PROCEDURE NEWPROCESS (P: PROC; A: ADDRESS; n: CARDINAL;
                      VAR new: ADDRESS);
PROCEDURE TRANSFER (VAR source: ADDRESS; destination: ADDRESS);

END SYSTEM.


7. STANDARD LIBRARY

The Demo Kit standard library provides the following modules:

------------------------------------------------------------------------

DEFINITION MODULE FileSystem;

(* This module supports random reading and writing from and to files. *)

FROM SYSTEM IMPORT BYTE, LONGADDRESS;

TYPE   StatusCode = (Ok, GeneralError, FileNotFound, PathNotFound,
                     TooManyFiles, AccessDenied, UnopenedFile,
                     DeviceFull);

       AccessMode = (Reading, Writing, Modifying);

       File = RECORD
                handle: CARDINAL;
                status: StatusCode
              END;

PROCEDURE Open (VAR f: File; name: ARRAY OF CHAR; access: AccessMode);
(* Opens file f for the specified access mode. *)

PROCEDURE Create (VAR f: File; name: ARRAY OF CHAR);
(* Creates a new empty file with name "name". If such a file exists
   already, it is replaced by the new one. *)

PROCEDURE Close (VAR f: File);
(* Closes a file and updates its directory information. *)

PROCEDURE Length (VAR f: File): LONGINT;
(* Returns the length of the file in bytes. *)

PROCEDURE SetPos (VAR f: File; pos: LONGINT);
(* Sets current file position to pos. *)

PROCEDURE GetPos (VAR f: File; VAR pos: LONGINT);
(* Gets current file position. *)

PROCEDURE ReadRec (VAR f: File; LVAR rec: ARRAY OF BYTE;
                   VAR BytesRead: CARDINAL);
(* Reads SIZE (rec) bytes from file f into rec. BytesRead is the actual
   number of bytes read, i.e. if BytesRead < SIZE (rec), eof was
   reached. The file position is moved forward BytesRead bytes. *)

PROCEDURE WriteRec (VAR f: File; rec: ARRAY OF BYTE);
(* Writes SIZE (rec) bytes from rec to file f. The file position is
   moved forward SIZE (rec) bytes. *)

PROCEDURE ReadBytes (VAR f: File; bytes: CARDINAL; buffer: LONGADDRESS;
                     VAR BytesRead: CARDINAL);
(* Reads 'bytes' bytes into storage at buffer from file f. BytesRead is
   the actual number of bytes read, i.e. if BytesRead < bytes, eof was
   reached. The file position is moved forward BytesRead bytes. *)

PROCEDURE WriteBytes (VAR f: File; bytes: CARDINAL; buffer: LONGADDRESS);
(* Writes 'bytes' bytes from storage at buffer to file f. The file
   position is moved forward 'bytes' bytes. *)

PROCEDURE Delete (name: ARRAY OF CHAR; VAR status: StatusCode);
(* Deletes the file with name 'name'. If status = Ok on return, the
   operation was successful. *)

PROCEDURE Rename (oldname, newname: ARRAY OF CHAR;
                  VAR status: StatusCode);
(* Renames the file with name 'oldname' to 'newname'. Full path names
   are allowed for both names. If status = Ok on return, the operation
   was successful. *)

END FileSystem.

------------------------------------------------------------------------

DEFINITION MODULE InOut;

(* This module supports stream I/O on standard input and output. Program
   controlled I/O redirection is possible via procedures OpenInput and
   OpenOutput resp. CloseInput and CloseOutput. *)

CONST  EOL = 15C;  (* carriage return *)

VAR    Done:   BOOLEAN;
       termCH: CHAR;

PROCEDURE OpenInput (defext: ARRAY OF CHAR);
(* Prompt for a file name and open input file "in". Done := "file was
   successfully opened". If open, subsequent input is read from this
   file. If no extension is entered, defext is assumed. *)

PROCEDURE OpenOutput (defext: ARRAY OF CHAR);
(* Prompt for a file name and create output file "out". Done := "file
   was successfully created". If created, subsequent output is written
   to this file. If no extension is entered, defext is assumed. *)

PROCEDURE CloseInput;
(* Closes input file and returns input to terminal. *)

PROCEDURE CloseOutput;
(* Closes output file and returns output to terminal. *)

PROCEDURE Read (VAR ch: CHAR);
(* Reads a single character from "in". Done := NOT in.eof. *)

PROCEDURE ReadString (VAR s: ARRAY OF CHAR);
(* Reads a string from "in", i.e. a sequence not containing blanks nor
   control characters. Leading blanks are ignored. Input is terminated
   by any character <= " "; this character is assigned to termCH. BS is
   used for backspacing. Done := NOT in.eof. *)

PROCEDURE ReadLine (VAR s: ARRAY OF CHAR);
(* Reads a line from "in", i.e. a sequence of characters up to a
   terminating CR. When reading from terminal, control characters are
   interpreted, and more than HIGH (s) + 1 characters are not allowed.
   When reading from a file, control characters are not interpreted, and
   superfloous characters are ignored. A LF following the CR is ignored.
   Done := NOT in.eof. *)

PROCEDURE ReadInt (VAR x: INTEGER);
(* Reads a string and converts it to an integer. Done := "integer was
   read". *)

PROCEDURE ReadCard (VAR x: CARDINAL);
(* Reads a string and converts it to a cardinal. Done := "cardinal was
   read". *)

PROCEDURE Write (ch: CHAR);
(* Writes a single character to "out". On terminal, control characters
   are interpreted. Done := "device was not full"  *)

PROCEDURE WriteLn;
(* Writes an EOL character, i.e. CR/LF. Done := "device was not full"
*)

PROCEDURE WriteString (s: ARRAY OF CHAR);
(* Writes a character string. On terminal, control characters are
   interpreted. Done := "device was not full"  *)

PROCEDURE WriteInt (x: INTEGER; n: CARDINAL);
(* Writes integer x with (at least) n characters to "out". If n is
   greater than the number of digits needed, blanks are added preceding
   the number. Done := "device was not full"  *)

PROCEDURE WriteCard (x, n: CARDINAL);
(* Writes cardinal x with (at least) n characters to "out". If n is
   greater than the number of digits needed, blanks are added preceding
   the number. Done := "device was not full"  *)

PROCEDURE WriteHex (x, n: CARDINAL);
(* Writes cardinal x encoded as hexadecimal number with (at least) n
   characters to "out". If n is greater than the number of digits
   needed, blanks resp. zeroes are added preceding the number. Done :=
   "device was not full"  *)

END InOut.

------------------------------------------------------------------------

DEFINITION MODULE LongInOut;

(* This module supports reading and writing of longint numbers via
   InOut. *)

VAR    Done: BOOLEAN;

PROCEDURE ReadLong (VAR x: LONGINT);
(* Reads a string and converts it to longint. Done := "longint was
   read". *)

PROCEDURE WriteLong (x: LONGINT; n: CARDINAL);
(* Writes x using n characters. If fewer than n characters are needed,
   leading blanks are inserted. *)

END LongInOut.

------------------------------------------------------------------------

DEFINITION MODULE RealInOut;

(* This module supports reading and writing of real numbers via InOut.
*)

VAR    Done: BOOLEAN;

PROCEDURE ReadReal (VAR x: LONGREAL);
(* Reads a string and converts it to longreal. Done := "longreal was
   read". *)

PROCEDURE WriteReal (x: LONGREAL; n: CARDINAL);
(* Writes x using n characters. If fewer than n characters are needed,
   leading blanks are inserted. *)

END RealInOut.

------------------------------------------------------------------------

DEFINITION MODULE Storage;

(* This module supports dynamic memory allocation in nonsegmented space.
*)

FROM SYSTEM IMPORT ADDRESS;

PROCEDURE ALLOCATE (VAR a: ADDRESS; size: CARDINAL);
(* Allocates an area of the given size (in bytes) and returns its
   address in a. If no space is available, a runtime error occurs. *)

PROCEDURE DEALLOCATE (VAR a: ADDRESS; size: CARDINAL);
(* Frees the area at address a of the given size (in bytes). Size must
   be the same as on the call to ALLOCATE. NIL is assigned to a. *)

PROCEDURE Available (size: CARDINAL): BOOLEAN;
(* Returns TRUE if size bytes could be allocated. *)

PROCEDURE GetHeap (VAR HeapEnd: ADDRESS);
(* Gets the current heap end pointer to save the current heap state. *)

PROCEDURE SetHeap (HeapEnd: ADDRESS);
(* Resets the heap to the state it had when GetHeap was called.
   Allocations above HeapEnd will be lost. *)

END Storage.

------------------------------------------------------------------------

DEFINITION MODULE Strings;

(* This module supports operations on strings. A string is an ARRAY OF
   CHAR terminated by its upper bound or by 0C. *)

PROCEDURE Assign (source: ARRAY OF CHAR;
                  LVAR destination: ARRAY OF CHAR);
(* Copies the string source to the string destination. If Length
   (source) > HIGH (destination) + 1, source is truncated to fit into
   destination. *)

PROCEDURE Insert (source: ARRAY OF CHAR;
                  LVAR destination: ARRAY OF CHAR; before: CARDINAL);
(* Inserts the source into destination before destination[before]. If
   before >= Length (destination), source is appended to destination. *)

PROCEDURE Delete (LVAR destination: ARRAY OF CHAR;
                  start, length: CARDINAL);
(* Deletes length characters of destination, starting with
   destination[start]. If start >= Length (destination), no operation is
   performed. If start + length > Length (destination), destination is
   truncated to length start - 1. *)

PROCEDURE Pos (pattern, source: ARRAY OF CHAR): CARDINAL;
(* Returns the index into source of the first occurence of pattern. If
   pattern does not occur, HIGH (source) + 1 is returned. If Length
   (pattern) = 0, 0 is returned. *)

PROCEDURE Copy (source: ARRAY OF CHAR; start, length: CARDINAL;
                LVAR destination: ARRAY OF CHAR);
(* Copies length characters from source into destination, starting at
   source[start]. If start + length > Length (source), or length > HIGH
   (destination) + 1, the substring is truncated. *)

PROCEDURE Concat (left, right: ARRAY OF CHAR;
                  LVAR destination: ARRAY OF CHAR);
(* Concatenates the two strings left and right into destination. If
   necessary, the resulting string is truncated. *)

PROCEDURE Length (source: ARRAY OF CHAR): CARDINAL;
(* Returns the actual length of source, i.e. the position of the
   terminating 0C or HIGH (source) + 1, if no 0C is found. *)

PROCEDURE CompareStr (left, right: ARRAY OF CHAR): INTEGER;
(* Compares the two strings left and right. Returns the following
   values:
     -1 if left < right
      0 if left = right
      1 if left > right. *)

PROCEDURE Expand (LVAR destination: ARRAY OF CHAR);
(* Expands destination to Length (destination) = HIGH (destination) + 1
   by appending blanks. *)

END Strings.

------------------------------------------------------------------------

DEFINITION MODULE Terminal;

(* This module supports simple terminal I/O. Under MS-DOS, I/O
   redirection is supported. *)

PROCEDURE Read (VAR ch: CHAR);
(* Reads a single character from the keyboard without echoing it. *)

PROCEDURE BusyRead (VAR ch: CHAR);
(* Like Read, but returns 0C, if no character is waiting. *)

PROCEDURE ReadAgain;
(* Causes the last character to be returned again upon the next call of
   Read. *)

PROCEDURE Write (ch: CHAR);
(* Writes a single character to the terminal. Control characters are
   interpreted. *)

PROCEDURE WriteLn;
(* Writes a CR-LF-sequence. *)

PROCEDURE WriteString (s: ARRAY OF CHAR);
(* Writes a character string to the terminal. Control characters are
   interpreted. *)

END Terminal.

------------------------------------------------------------------------

8. LIMITS OF THE DEMO KIT

The Demo Kit is limited by

  - The compiler allowing a maximum of about 600 symbols (identifiers,
    numbers, keywords, delimiters) per source. If this limit is
    exceeded, the message "Fatal Error F7: Internal limit exceeded" is
    displayed.

  - The standard library providing only the modules listed in
    paragraph 6. Other modules are:
      Clock
      Directory
      Environment
      Interrupts
      LongStorage
      LowTerminalIO  (with installable hardware dependent drivers)
      LStrings
      MathLib0  (8087/287 and software emulation version)
      Memory
      NumberConversion
      Parameters
      Processes
      Programs
      RealConversion
      RS232  (two hardware dependent versions)
      SystemCalls
      TextFiles
      TextNumbers

  - The missing ObjectConverter (for incorporation of assembly language
    modules).

  - And of course the missing documentation.