README.TXT for mixing V4.0 and V3.4 modules                 27-Mar-92/Stu
TERRA Datentechnik, Tech Support
(originally by Antoine Haas, Strasbourg)
-------------------------------------------------------------------------


Introduction
------------

One way to make modules that use CODE statements usable within V4.0 is to
make the OBJ-files generated by V3.4 linkable for V4.0. This needs some
modifications to the module that guarantee that

  - V4.0 does find all externals generated by V3.4
  - The V4.0 RTS does treat and initialize the V3.4 code correctly
  - The RTS-calls generated by V3.4 are correctly mapped onto V4.0 RTS-calls.


One of our Beta testers has found and implemented a solution for this way of
transporting "CODE-heavy" modules to V4.0, and kindly provided us not only
with a description of it, but also with the program to convert the definition
modules, and the permission to pass all this on to all future Modula-2 4.0
users.



Problem Description
-------------------

We want to link a implementation module 'Sample' that is compiled with
compiler version 3.4 and a module 'Main', compiled in version 4.0.
We describe a way to modify the module Sample that allows SAMPLE.OBJ
produced by version 3.4 to be linked into modules compiled by version 4.0.



files of this directory:
-----------------------

  README   TXT                This text

  CONVDEF  EXE                Program for automatic conversion of DEF files
  CONVDEF  MOD                  Source code of DEF-conversion program

  M2_OLD   ASM                Module that exports StackCheck__RTSMain,
  M2_OLD   DEF                  $INIT__RTSMain, FctRetError__RTSError,
  M2_OLD   OBJ                  ,...

                              Files for solution 1:
                              ---------------------
  SOLUTN_1\ MAIN.ARF
  SOLUTN_1\ MAIN.EXE
  SOLUTN_1\ MAIN34.MOD        Main module for V3.40
  SOLUTN_1\ MAIN40.MOD        Main module for V4.00
  SOLUTN_1\ MAIN40.OBJ
  SOLUTN_1\ SAMPLE34.DEF      Original DEF module of sample
  SOLUTN_1\ SAMPLE34.MOD      Original MOD module of sample
  SOLUTN_1\ SAMPLE.OBJ        <- the V3.40 SAMPLE.OBJ that shall be linked
                                 together with V4.00 modules
  SOLUTN_1\ SAMPLE40.DEF
  SOLUTN_1\ SAMPLE40.SYM

  SOLUTN_2\ SAMPLE.MOD        Dummy Sample.MOD for solution 2


1. First Solution (straight forward)
-----------------

  a) Definition Module:

   Create a new definition file SAMPLE.DEF :

     3.40:   PROCEDURE WriteVideo ( x,y         : CARDINAL;
                                    SourceAdr   : ADDRESS;
                                    WordsToMove : CARDINAL );

     4.00:   PROCEDURE WriteVideo ['L__WriteVideo__Sample']
                                  ( x,y         : CARDINAL;
                                    SourceAdr   : ADDRESS;
                                    WordsToMove : CARDINAL )
                                           [ALTERS(AX,BX,CX,DX,SI,DI,DS,ES)];

     The name as generated by the 3.40 compiler has to be specified,
     and the changed registers. For safety we change all registers.


   Version checking :
     To avoid any problems with the different module keys that are produced
     by the two compiler versions (V4.0 for DEF and V3.4 for MOD), we use the
     V4.0 facility to suppress version checking for the module Sample by
     specifying (*/NOCHECK:M*) in the definition module.


   Initalization code of Sample:
     (*/NOMODINIT*) has to be specified in the definition module, since there
     is no V4.0 implementation that could be executed according to V4.0.

     The initialisation routine has to be exported explicitly:

     PROCEDURE InitSample ['$INIT__Sample']()[ALTERS(AX,BX,CX,DX,SI,DI,DS,ES)];


   Conversion of DEF files :
     Use the program CONVDEF to do it, which has been provided by M.Haas.

  b) Implementation Module(s):

     Import initialisation routine(s) explicitely into main module and call
     them there. Example (Main.MOD):

            MODULE Main;

            FROM Sample IMPORT
              InitSample, ... ;

            BEGIN
              InitSample;

  c) Link:

     Use M2MAKE to generate Main.ARF file.
     M2Make needs MOD file for Sample:
      - hit just Escape,
        later add the path for Sample.OBJ manually to Main.ARF   or
      - create a dummy MOD file (see also under 2.)              or
      - copy the old MOD file                                    or
      - indicate the path in environment variable M2MOD

     Add the M2_Old.OBJ file reference to Main.ARF:
       M2_Old is an Assembler program which exports the neccessary functions
       to map the V3.4 RTS-calls onto V4.0:
       StackCheck__RTSMain, $INIT__RTSMain, FctRetError__RTSError,...

     Our Main.ARF:
       I:OBJ\MAIN.OBJ+
       I:OBJ\SAMPLE.OBJ+
       I:OBJ\M2_OLD.OBJ+        <--- added manually

     Link the modules. Our link batch file:
       m2l @i:arf\@Main.ARF,,,Main,, /CO/INFO

     If Sample uses the library M2LIB.LIB:
       m2l @Main.ARF,,,Main,\M2\M2LIB\LIB\M2LIB.LIB, /CO/INFO


2. Second Solution (automatic link)
------------------

  a) as before

  b) Main.MOD as before

     Create a dummy SAMPLE.MOD file (optional)

       IMPLEMENTATION MODULE SAMPLE;
       IMPORT M2_Old;
       END SAMPLE.

     which imports M2_Old, so link can be done automatically.

  c) no manual additions to Main.ARF necessary anymore.


3. Third Solution (another automatic link)
-----------------

  ( This would be another alternative to 2. for automatic link.
    We describe it here but didn't include sample files in the support disk. )

  a) as before

  b) Main.MOD as in 1.

     Create a dummy DEF (with /NOCHECK:M) and MOD file (Sample_ .MOD for example)
     and import it in Sample.MOD. Call the initialization code in Sample.MOD.
     Copy and rename old Sample.OBJ to Sample_.OBJ. (File dates may have to be
     changed).
     Use M2MAKE to create Main.ARF (which is now complete)

       DEFINITION MODULE Sample_;
       (*/NOCHECK:M*)
       (*/NOMODINIT*)
       PROCEDURE  InitSample ['$INIT__Sample']()
                                 [ALTERS(AX,BX,CX,DX,SI,DI,DS,ES)];
       END Sample_.

       IMPLEMENTATION MODULE Sample_;
       END Sample.

       IMPLEMENTATION MODULE Sample;
       IMPORT M2_Old,Sample_;
       BEGIN
         Sample_.InitSample; (* calls $INIT__Sample *)
       END OLD.

  c) no manual additions to Main.ARF necessary anymore.


4. Fourth Solution (best one: library)
------------------

   With a library containing the old modules ( e.g. Microsoft's LIB
   version 3.18), it's possible to create dummy MOD files and OBJ files
   (LINK accepts to load several OBJ files with the same name).
   (*/NOCHECK:M*) is not needed and initialization procedures can be called
   automatically in the mod files.

   DEFINITION MODULE Sample;
   PROCEDURE  InitSample ['$INIT__Sample'] () [ALTERS(AX,BX,CX,DX,SI,DI,DS,ES)];
   ...
   END Sample.

   IMPLEMENTATION MODULE Sample;
   IMPORT M2_Old;
   BEGIN
     InitSample; (*calls $INIT__Sample*)
   END OLD.


