Topspeed_JPI/TS/DOC/DOS_M2.DOC

DOS TopSpeed Modula-2 with Objects    Release notes version 3.10
==================================    ==========================


This document contains information on the following:


        1.  DIFFERENCES FROM TOPSPEED VERSION 2.00
        2.  ERRATA
        3.  OBJECT-ORIENTED GRAPHICS INTERFACE
        4.  TOPSPEED EXTENSIONS
        5.  COMMON QUESTIONS AND ANSWERS


ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


1.  DIFFERENCES FROM TOPSPEED VERSION 2.00
==========================================

Major improvements and alterations to the TopSpeed Modula-2
compiler and code generator since the previous version include
the following:

þ   More memory models are available, including an automatic code
    and data overlaying model.

þ   TopSpeed Modula-2 now supports Microsoft Windows version 3.

þ   Support for third-party libraries has been improved,
    particularly in the area of floating-point code generation
    (via the standard_float pragma). A large model stack-frame
    library is now supplied with TopSpeed Modula-2, which is
    likely to be of use when linking to third party libraries
    compiled for use with other vendors' C compilers.

þ   TopSpeed Modula-2's object-oriented features have been
    enhanced, to support multiple inheritance and linking to C++
    classes. The syntax of class declarations have been changed;
    the supplied utility program NEWCLASS may be used to translate
    object-oriented source code designed for the previous release
    of TopSpeed Modula-2.



2.  ERRATA
==========

Reference manual p 17:

    The FIXREAL Real type should have the following numeric range:

        -2^63 to 2^63 -1

Reference manual p 18  paragraph 1:

    This paragraph should read as follows:

        Modula-2 has one predefined enumeration type defining
        truth values:

           TYPE
               BOOLEAN = (FALSE, TRUE);

Reference manual p 43:

    A type transfer function is considered well-behaved if the sizes
    of the transfer type and the value type are the same, or if a
    proper VAL conversion is performed. If the value type size is more
    than the transfer type size then the remaining last bytes of the
    value are ignored. If it is shorter, the last bytes of the resulting
    value are undefined.

Reference manual p 72:

    Line 18 of Example 1 should read as follows:

        RETURN(c1 IS classTwo)

Reference manual p 109:

    The default value of separators should read as follows:

        Str.CHARSET {
                     CHR(9),
                     CHR(10),
                     CHR(13),
                     CHR(26),
                     CHR(32),
                     }

Reference manual p 126:

    The values returned by the GetDrive procedure are
    1 for Drive A, 2 for Drive B, etc.

Reference manual p 136 line 29:

    This line should read:

        Name : PathTail;

Reference manual p 137:

    The example should read as follows:

        (*
          This example also illustrates the use
          of ReadNextEntry
        *)

        IMPORT FIO, IO;

        VAR
          Ent : FIO.DirEntry;
          FOUND : BOOLEAN;

        BEGIN
          ...
          Found := FIO.ReadFirstEntry( "C:\COM\*.EXE",
                                       FIO.FileAttr{FIO.system,FIO.hidden},
                                       Ent);

          WHILE Found DO
             IO.WrStr(Ent.Name);
             IO.WrLn;
             Found := FIO.ReadNextEntry(Ent);
          END;
        ...

Reference manual p 139:

    The drive values for the SetDrive procedure are
    1 for Drive A, 2 for Drive B, etc.

Reference manual p 155:

    The syntax for the FindNewPath and FindPath procedures should
    read as follows:

        PROCEDURE FindNewPath(
                     name : ARRAY OF CHAR;
                     VAR fullname : ARRAY OF CHAR) : BOOLEAN;

        PROCEDURE FindPath(
                   name : ARRAY OF CHAR;
                   VAR fullname : ARRAY OF CHAR) : BOOLEAN;


    The description of these procedures omits the following information:

        FindNewPath always returns TRUE.

        FindPath returns TRUE if the requested file was found.

Reference manual p 157:

    The description of the Open procedure should read as follows:

        ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ
        Open               Open file for reading using redirection
        ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ

                PROCEDURE Open( name : ARRAY OF CHAR ) : File;

        The Open procedure is used to open a file for reading. In
        this way it is identical to the OpenRead procedure in the
        FIO module. This version of Open, however, uses the
        redirection file to determine the full path string of the
        file. The FIO version of OpenRead only looks in the current
        directory.

Reference manual p 157:

    The OpenRW procedure is not documented in the manual. The syntax
    and description are as follows:

        ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ
        OpenRW                         Open file using redirection
        ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ

                PROCEDURE OpenRW( name : ARRAY OF CHAR ) : File;

        The OpenRW procedure is used to open a file for processing.
        In this way it is identical to the Open procedure in the FIO
        module. This version of Open, however, uses the redirection
        file to determine the full path string of the file. The FIO
        version of Open only looks in the current directory.

Reference manual p171:

    The third paragraph should read as follows:

        Thus to draw a rectangle in Red, on a CGA adapter:

           x:= Graph.SetVideoMode(MRES4COLOR);
           y:= Graph.SelectPalette(0);
           (* Palette 0 *)
           Graph.Rectangle(10,10,100,2,FALSE);
           (* The color is 2 (Red) *)

Reference manual, page 173:

   The description of Arc should be replaced by the following:

     PROCEDURE Arc( x0, y0, a0, b0, x1, y1, x2, y2 : CARDINAL;
                                             Color : CARDINAL );

     Draws an arc in the color number specified by the Color
     parameter. The arc drawn is a fragment of an ellipse. The
     arc is specified using the parameters (x0,y0), a0, b0,
     (x1,y1) and (x2,y2) in the following manner:

       (x0,y0)     Specifies the center of the ellipse that
                   contains the arc.

       a0          Specifies the length of the semi-major axis
                   of the ellipse that contains the arc.

       b0          Specifies the length of the semi-minor axis
                   of the ellipse that contains the arc.

       (x1,y1)     Specifies the co-ordinates for the starting
                   point of the arc

       (x2,y2)     Specifies the co-ordinates for the ending
                   point of the arc

     The arc is drawn from (x1,y1) counterclockwise to (x2,y2).

Reference manual, page 177:

  The description of Ellipse should be replaced by the following:

    PROCEDURE Ellipse( x0, y0 : CARDINAL; a0, b0 : CARDINAL;
                       Color  : CARDINAL;   Fill : BOOLEAN );

    Draws an ellipse in the color number specified by the Color
    parameter. The ellipse is specified using the parameters
    (x0,y0), a0 and b0 in the following manner:

      (x0,y0)     Specifies the center of the ellipse.

      a0          Specifies the length of the semi-major axis of
                  the ellipse.

      b0          Specifies the length of the semi-minor axis.

      Color       Specifies the color number used to draw the
                  ellipse

      Fill        If TRUE the ellipse is filled with the current
                  fill mask (see Graph.SetFillMask).

Reference manual, page 185:

  The description of Pie should be replaced by the following:

     PROCEDURE Pie( x0, y0, a0, b0, x1, y1, x2, y2 : CARDINAL;
                    Color : CARDINAL; Fill : BOOLEAN );

    This procedure draws a pie slice. The parameters have the
    following meaning:

    Draws an arc in the color number specified by the Color
    parameter. The arc drawn is a fragment of an ellipse. The
    arc is specified using the parameters (x0,y0), a0, b0,
    (x1,y1) and (x2,y2) in the following manner:

    (x1,y1)     Specifies the center of the ellipse that
                contains pie slice.

    a0          Specifies the length of the semi-major axis of
                the ellipse that contains the pie slice.

    b0          Specifies the length of the semi-minor axis of
                the ellipse that contains the pie slice.

    (x1,y1)     Specifies the co-ordinates for the starting
                point of the pie slice (curved) edge.

    (x2,y2)     Specifies the co-ordinates for the ending
                point of the pie slice (curved) edge.

                The pie slice arc is drawn from (x1,y1)
                counterclockwise to (x2,y2).

    Color       Specifies the color number used to draw the
                slice.

    Fill        If TRUE the pie slice is filled, otherwise
                only the outline is drawn.

Reference manual p 199:

    The SetVideoMode procedure returns FALSE if the mode selected
    is not supported by the hardware.

Reference manual p 220:

    The example should read as follows:


        For example:

           IMPORT Lib, IO;
           ...
           VAR
             CPU : Lib.CpuRec;
           ...
           Lib.CpuId(CPU);
           IF (CPU.cpu <> Lib.cpu_80386)
              OR (CPU.fpu <> Lib.fpu_80387) THEN
             IO.WrStr(
               "Won't run without a 80386 & 80387");
             HALT;
           END;
           ...

Reference manual p 229:

    The declarations of the SetDate and SetTime Procedures should
    read as follows:

           PROCEDURE SetDate(
                          VAR Year, Month,
                          Day : CARDINAL) : BOOLEAN;

           PROCEDURE SetTime(
                          Hrs, Mins,
                          Secs, Hsecs : CARDINAL) : BOOLEAN;

    The return value indicates whether the date or time specified
    was valid.

Reference manual, page 257:

  PROCEDURE ATan2 should read:

    ATan2 returns the arc tangent of ( Y / X ) and the result is
    in the range -ã to ã.


Reference manual p 261   line 24:

    This line should read as follows:

        These are in graphics coordinates irrespective of the mouse
        state.

Reference manual p 261   line 30:

    This line should read as follows:

        These are in graphics coordinates irrespective of the mouse
        state.

Reference manual p 275   lines 11 and 15:

    The value in both cases should be 1 and not 0.

Reference manual p 286:

    The spelling of the NearAllocate and FarAllocate procedures
    is incorrect and should read as spelt in this sentence.

Reference manual p 288:

    The spelling of the NearDeallocate and FarDeallocate procedures
    is incorrect and should read as spelt in this sentence.

Reference manual, page 312:

  Str.Match matches insensitive to the case of the characters.
  Thus the second example returns TRUE.


3.  OBJECT-ORIENTED GRAPHICS INTERFACE
======================================

Within the multi-language example programs is an object
orientated interface to the M2 graphics module.


4.  TOPSPEED EXTENSIONS
=======================

The following is a list of TopSpeed extensions to Modula-2 as
described in Niklaus Wirth's Programming in Modula-2, 3rd
edition.

Address constructor                     A := [S:O PT]

Based pointers                          SP : POINTER S TO T

Structured constants                    SC = A(C1,C2)

Concatenation of string constants       S = 'ST'+'RING'+CHR(13)

Type conversion of numeric types        I := INTEGER(CARD)

Standard types BYTE, SHORTINT, SHORTCARD, LONGCARD,
               LONGWORD, SHORTADDR

Standard constant NULLPROC

Object extensions, with CLASS, IS, VIRTUAL and SELF keywords.

Alias notation                             A ::= P

Compiler pragmas                           (*# ... *)

Conditional compilation                    (*% ... *)

Compiler directives (old style)            (*$ ... *)

SIZE and some other SYSTEM functions do not
have to be imported from SYSTEM

Function procedures may return any data type

Shift operators                             >> and <<

GOTO/LABEL                                  GOTO fail

SIZE may be applied to any expression or designated variable.

Identifiers imported in a definition module do not have to
be re-imported in the corresponding implementation module.

A module may refer to its own objects using qualified
reference.

Keyword INLINE allows specification of a procedure body
in a definition file.

Binary procedures can be defined to be a constant agregate.

VSIZE can find the size of a record (or object) type or
variable upto and including the specified field.

FieldOfs returns the offset of a field relative to the
start of a record (or object) variable or type.

A New function FieldOfs can be used to get the offsets of record
fields of record and objects, it works on variables and types.

Function procedure results may be dereferenced,
indexed or fields selected.

Procedures may be declared using a FORWARD declaration.

Procedure may be declared externally in another module
   PROCEDURE P; IN file;

Multiple-models mean that ADDRESSes and POINTERS can be 16 or
32 bits. FarADDRESS, NearADDRESS, FarADR and NearADR can
be used to specify these explicitly.

Procedure variables may be compared for equality.

Pragmas may specify various calling conventions/parameter
passing techniques.

Record fields may be packed by using a pragma.


5.  COMMON QUESTIONS AND ANSWERS
================================

Q: How do I link to my own and other peoples C libraries?
A: If you want to interface to third party libraries you will
   have to use pragmas within the definition module to set C
   calling and naming conventions, and if necessary, to turn
   off register parameter passing. Of course if you use TopSpeed
   C to build your C library you can continue to take advantage
   of register parameter passing.

Q: How do I output to the printer using the library?
A: You can use the standard handle PrinterDevice defined in
   FIO.DEF which is pre-opened when your program starts. Then
   you can use all the FIO routines available, passing the
   handle as the first parameter  e.g:

   FIO.WrStr(FIO.PrinterDevice,'Hello'+CHR(13)+CHR(10)+CHR(12));

   An alternative is to use FIO.Open to open the printer device
   'LPT1' and use the handle returned in the same way.

Q: When using the C function printf from Modula-2, why does '\n'
   not get interpreted as a new line.
A: The \n and other escape characters prefixed by '\' are not
   actually processed by printf but are in fact part of the C
   language when defining constant strings. In TopSpeed Modula-2
   you can use string constant concatenation: e.g.
      printf("hello world"+CHR(13)+CHR(10));

Q: How can I use conditional compilation to include or exclude
   IMPORTs.
A: You can do this by having a boolean constant in a definition
   which then can be imported before the conditional compilation
   is needed.
   E.g.

       DEFINITION MODULE OSVER;
         CONST MSDOS = TRUE;  OS2 = NOT MSDOS;
       END OSVER.

   and in your implementation:

       FROM OSVER IMPORT MSDOS,OS2;
       ...
       (*%T MSDOS*)
       FROM SYSTEM IMPORT Seg,Ofs,Registers,CarryFlag,ZeroFlag;
       (*%E*)
       (*%T OS2*)
       IMPORT Dos,Kbd ;
       (*%E*)

Q: How do I export a procedure from a local module that is
   defined in the definition module:
A: As the definition of the procedure is already defined this
   procedure must be IMPORTed into the local module (not
   EXPORTed).
   E.g.
        DEFINITION MODULE test;
        PROCEDURE embedded;
        END test.

        IMPLEMENTATION MODULE test;
           MODULE local;
             IMPORT Embedded;
             PROCEDURE Embedded;
             BEGIN
             END Embedded;
           END local;
        END test.

   Note that using EXPORT instead of IMPORT is not supported.