TERRA Datentechnik / With permission from Tayloris AG 

Manual for:
TaylorModula-2 for MS-DOS: Object File Decoder 	Version 3.2
=========================================================================================

The information contained herein is the property of Tayloris Software AG and shall neither 
be reproduced in whole or in part without prior written approval from Tayloris Software AG.
All rights are reserved, whether the whole or part of the material is concerned, specifically 
those of translation, reprinting, re-use of illustration,broadcasting, reproduction by photocopying
machine or similar means and storage in data banks. Tayloris Software AG reserves the right to 
make changes, without notice, to the contents contained herein and shall not be responsible for
any damages (including consequential) caused by reliance on the material as presented.

contents:

1. Decoder Features
2. Operating
3. Decoder Symbols
4. Restrictions	
5. Error messages


1. Decoder Features

The Object File Decoder converts a TaylorModula-2 object file (.OBJ file) into an assembly langguage source
file compatible to the Microsoft-Macro Assembler.  The assembler source may be used to verify the code
generated by the compiler, as an aid for assembly level debugging, to create a framework for an assembly
language module, or to allow manual optimization of the compiler's code.
The Decoder's main features are:

- The created assembler source may be used as input for the Microsoft MASM without any modifications.

- Support for the entire real mode instruction set of the 8088/8087 to 80286/80287 processor family.

- Automatic creation of procedure and jump target labels.

- If the decoded module was compiled with $LineNumbers +, procedure names are symbolic, and the
  assembler source contains the Modula-2 source as comments.

- To avoid the creation of huge assembler sources (it is easy to create a 200 kbyte assembler source 
  with the decoder), single procedures may be selected for disassembly.

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


2. Operating

Normally the Decoder returns with a DOS return code of 0. However, if an error has occured, the return code
is 4. A fatal error (invalid file, disk full out of memory, internal error) gives a return code of 8. 
The DOS return code can be checked by the parent process. In a batch procedure, you can check it with the IF
ERRORLEVEL command.

The evocation format of the Object File Decoder is:

	TOBJ2ASM OBJFile{/P:Procedure} ASMFile ModulaFile
or
	TOBJ2ASM OBJFile; (default assumed for ASMFile and ModulaFile)
or
	TOBJ2ASM          (user will be prompted for all parameters)
etc.

- OBJFile is the name of the object file to be disassembled.  Its default extension is .OBJ .

- ASMFile is the name of the assembler source to be created. lt defaults to the name of the OBJFile and the
  extension .ASM.

- ModulaFile is the name of the Modula-2 source to be used if $LineNumbers was on.  It defaults to the name
  of the OBJFile and the extension.MOD. If the object file does not have a line table, TOBJ2ASM will not
  prompt for it.

- /P:Procedure: optional and repeatable switch to select single procedures for disassembly.  The selected
  procedure will not be listed if the object file does not have a line table (i.e. if it was compiled with
  $LineNumbers-) and if the procedure is not public. If /P is not specified, the entire object file is
  disassembled.  If /P is specified, the created source will normally not assemble without errors.

	exemples:

To decode the object file MYPROG1.OBJ into an assembler source MYPROG1.ASM using the source
MYPROG1.MOD, enter

        TOBJ2ASM MYPROG1;

To decode the procedures Get and Put in the object file  MYMOD1.OBJ to the printer using the source
MYMOD1.IMP, enter

        TOBJ2ASM MYMOD1/P:Get/P:Put PRN .IMP


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


3.Decoder Symbols

The following rules apply to the symbols created by the decoder:

- Jump target labels are of the form lbl1, lbl2 and so on, where lbl1 is the first label appearing in the source,
  lbl2 the second label, and so on.

- If the Modula-2 source was compiled with $LineNumbers + , local procedure names are identical to the
  Modula-2 names.  Global (public) procedure names are always the same as in the object file.
  Other procedures are labeled procl, proc2 and so on.

- References to segments containing load time data are of the form @SegmentOffset, where Offset is the offset
  in the segment.

- References to segments not containing load time data are of the form Segment + Offset, where Offset is the offset
  in the segment.

- External references are of the form they have in the object file.

- Case tables are labeled casel, case2 and so on.

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


4. Restrictions	

- Generally, the Decoder relies on the structure of the code as created by the compiler.  Decoding of other
  object modules (e.g. a standard library module or a foreign language module) will not always work.

- Procedures not called in the code will not be correctly labeled if $LineNumbers was off.

- By default, $LineNumbers + disables some optimizations.  To decode the fully optimized code, use the
  sequence $LineNumbers + $Optimize:Size or $LineNumbers + $Optimize:Speed or reenable
  optimizations manually.

- A near return in a far procedure or a far return in a near procedure will be disassembled as RETN or
  RETF, respectively.  MS-MASM supports RF-TF and RF-TN instructions starting with version 5.0. With
  earlier versions, use following macros:

                    RETF  MACRO  psize                 RETN  MACRO  psize
                          IFB    <psize>                     IFB    <psize>
                          DB     0CBH                        DB     0C3H
                          ELSE                               ELSE
                          DB     0CAH                        DB     0C2H
                          DW     psize                       DW     psize
                          ENDIF                              ENDIF
                          ENDM                               ENDM

- 8087 instructions in emulator calls (after the INT 7) must not contain a preceding WAIT.  However, some
  older assemblers may automatically insert WAIT's before every 8087 instruction in spite of the .287
  directive.  In this case, the reassembled object module will not work correctly in conjunction with the
  floating point emulator.

5. Error messages

errors detected by the Decoder are written to standard output.  The following messages may appear:

DC1: More than n names
     The LNAMES list in the object module contains too many names.

DC2: More than n segments
     There are too many SEGDEF records in the object module.

DC3: Absolute segment i ignored
     The ith SEGDEF record contains an absolute segment.  Absolute segments are not supported by the
     decoder.

DC4: More than n groups
     There are too many GRPDEF records in the object module.

DC5: More than n group components.
     There are too many segments in the group.

DC6: More than n (public) symbols.
     There are too many symbols (publics, fixups, local labels etc.).

DC7: More than n external symbols.
     There are too many external symbols.

DC8: Type index in external symbol ignored.
     The decoder does not support type indexes (communal variables).

DC9: Nested iterated data blocks are not supported.
     The decoder does not support nested LIDATA records.

DC10:Invalid self relative fixup in segment i
     The ith segment contains a self relative fixup that cannot be correctly interpreted.

DC11:Invalid frame method in segment i
     The decoder does not support frame method 4.

DC12:Cannot fill STACK segment
     The stack segment cannot be load time initialized.

DC13:n invalid opcodes found
     n opcodes that could not be disassembled were found. 
     These codes appear as "???" instructions in the assembler source.

Except errors DC8, DC9 and DC13, all errors will suppress creation of the assembler source.

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