Category : Utilities for DOS and Windows Machines
Archive   : TOASM11A.ZIP
Filename : TOASM.DOC

 
Output of file : TOASM.DOC contained in archive : TOASM11A.ZIP
TOASM

Version 3.4a

Shareware Version 1.1a

Copyright (c) 1988,1989
PRINCE WILLIAM CUSTOM COMPUTERS
P.O.B. 2106
Woodbridge, VA 22193
(703) 590-3360





---------TABLE OF CONTENTS---------

INTRODUCTION 1
INVOKING TOASM 2
HOW TOASM WORKS 2
OUTPUT DESCRIBED 3
BUILDING A .USR FILE 4
NOTES 5
KNOWN ERRORS 5














SHAREWARE NOTES

This Shareware version of TOASM is fully functional but somewhat
limited in the size of the files that can be converted. The symbol
table is restricted to 1024 entries to reduce the memory required.
The number of possible user comments and user labels is also reduced.
This is to allow users with limited available memory to use TOASM.
Registered users will receive two copies of TOASM.EXE, one with
similar capabilities to this version and one optimized for 640kb
equipped machines. Registered users will also receive one free update
and discounts on further updates.

Registration is only $45.00!





- -TOASM-
INTRODUCTION


TOASM is a program which converts .EXE and .COM files to assembly
language. The generated assembly language is fully compatible with
MASM 4.0 from MicroSoft. While many programs can be converted without
intervention by the user, the user can also provide input through a
.USR file to improve the results. Several programs are included with
TOASM to aid the user in developing a .USR. Also included are several
programs which demonstrate the operation of TOASM.

DUMP is a program which will dump any file in both hexadecimal and
ascii to either the screen, a printer or a file.

FREF is a program which looks through a specified file for references
to addresses provided by the user.

COMPARE is a program which compares files and reports any differences
found. Unlike the DOS COMP command, COMPARE does not stop if file
lengths are different but compares up to the size of the smaller file.

TESTEXE.EXE is a EXE type program which is being used in the
development of TOASM. It has no practical value as anything other
than a test for TOASM and to demonstrate the operation of TOASM with
.EXE type files.

TESTEXE.USR is a sample .USR file which is used to convert
TESTEXE.EXE.

TESTCOM.COM is a COM type program which is being used in the
development of TOASM. It has no practical value as anything other
than a test for TOASM and to demonstrate the operation of TOASM with
.COM type files.

TESTCOM.USR is a sample .USR file which is used to convert
TESTCOM.EXE.

TST.BAT is a batch file which will convert both TESTEXE.EXE and
TESTCOM.COM to assembly language. The user may need to change some
commands in this file for different assemblers and/or linkers.

















- -TOASM-1-
INVOKING TOASM


TOASM is started from the DOS command prompt. The only required
argument is the file name of the file to be converted. Two optional
parameters are available.

TOASM InFil.ext [OtFil] [UsrFil]

InFil is the name of the file to be converted. The file name extension
(.ext) is required.

OtFil is an optional name for the generated output file. If not
provided, then the .ASM file will be named InFil.ASM where InFil is
the same as the input file name. It is usually a good idea to provide
the OtFil name so that the original InFil is not overwritten when the
.ASM file is subsequently assembled and linked.

UsrFil is an optional name for the .USR input file. If not provided,
the .USR file (if any) will be presumed to be named InFil.USR where
InFil is the same as the input file name.



HOW TOASM WORKS


TOASM first initializes several internal tables and builds an empty
symbol table. It next reads the .USR file (if provided) and installs
corresponding symbols in the symbol table. If a user provided symbol
includes a label, the label is placed in an internal label table. The
same is true for user provided comments. Next, TOASM reads any
relocation information contained within the file to be converted and
places corresponding entries in the symbol table. Then, TOASM builds
the rest of the symbol table by reading through the entire file to be
converted looking for references. Once the symbol table is fully
built, TOASM reads the entire file one more time while generating the
.ASM output.



















- -TOASM-2-
OUTPUT DESCRIBED


Please execute the TST.BAT file included with TOASM and refer to the
output file (TEXE.ASM) for the following discussion.

The first line generated by TOASM is a title line made up from the
file name of the file to be converted.

Next, any macros used will be found. All "RET" instructions are coded
as macros so that "PROC" statements are not needed.

Following the macros, several "EQU" statements will be found which are
included to reduce the size of the generated file.

The next line is pretty interesting! It defines a label called junk!
This label is only needed if an XLAT instruction with segment override
is found in the file to be converted - MASM gets upset if no label
follows the segment override.

The "Initial Seg Values" comment line shows the segment values found
in the exe header for .EXE files or the presumed values for .COM
files.

While none occurred within the test files, any line containing code
which TOASM does not understand will be flagged with '?', '??' or
'???'. A comment will also be included on the line describing what
TOASM did not like about the instruction. These flags are not
preceded with a ';' so that MASM will generate an error when the line
in error is assembled. The total number of these flags generated is
displayed in the 'ERRORS' line of the execution screen. The most
important part of any file conversion will be to resolve any line
flagged in this manner.

Segment labels are prefixed with 'S' while all other TOASM generated
labels are prefixed with 'L'. The remaining characters within labels
are the 4 hex characters which relate to the offset within the input
file of the label. For .COM input files, the hex value will be the
actual file offset of the label. For .EXE files, the hex value
denotes the offset within the load image contained within .EXE file.

The flag <> will be added to the comment of any line which
contains a relocatable symbol. These symbols are those which were
found in the relocation entries during pass 1.

'Ofs' precedes labels whenever TOASM finds it questionable as to
whether the value is a constant or actual offset. It is up to the
user to determine which of the labels should be treated as constants
and which should be treated as labels.








- -TOASM-3-
BUILDING A .USR FILE


The .USR file is a list of special instructions to TOASM which is
optionally created by the user. The format of each line in the .USR
file must be one of the following...

addr--command
or
addr--command--label
or
addr--command--label--comment

"addr" represents the input file offset at which to define the
command. All "addr" values must be in numerical sequence in the file.

"command" may be 'C', 'B', 'W', 'S', 'D', 'V'.

C---The bytes encountered are assumed to be code (machine
instructions).

B---The bytes encountered are assumed to be data byte (DB) values
until changed by another "command". The value found will be
treated as a constant.

W---Two byte values encountered are assumed to be data word (DW)
references until changed by another "command". The value found
will be treated as a label.

V---Two byte values encountered are assumed to be data word (DW)
values until changed by another "command". The value found will
be treated as a constant.

S---The bytes encountered are assumed to form a string of ascii
byte values. Quoted text will be produced for valid ASCII
characters and byte values for others.

D---The operand of the instruction is assumed to be a constant.
This command is for one address only. Code is automatically
assumed for the next address.

"label" is optional and will be used for references to this "addr"
instead of the label TOASM would generate.

"comment" is optional and must be preceded by the "command" and
"label" fields unless a ":" is used. The comment field may include
spaces and tabs. User defined comments over-ride any TOASM generated
comments.

Notes...

While reading lines from a .USR file, TOASM first discards all
characters following any ';' found in a line. It then copies all
characters following any ':' found in a line to the internal comment
table.


- -TOASM-4-

When converting .EXE files, the address of the data segment is unknown
to TOASM. Since this can cause problems, the user can include a line
in the .USR file which specifies the data segment address. To do this
use: @xxxx where xxxx is the address to be assumed for the data
segment. Only one such line should be included within the .USR file.
TESTEXE.USR makes use of this option.

Upper or lower case is acceptable. TOASM converts all characters read
from the .USR file to uppercase as they are read.

Blank lines are considered to be comments an are ignored by TOASM.

Any number of spaces or tabs may separate fields as long as at least
one of either is used.

The address field may contain a trailing 'H' but it is not required.

All addresses are presumed to be in hex.



NOTES


Given the opcode and succeeding bytes of 83h,e3h,10 TOASM will
generate "AND BX,10H". This is correct. When the opcode is 83h, the
80x86 will "sign extend" the data byte (10h) and perform the and
operation. Some assemblers (PASM) will generate 81h,e3,10,00. While
the outcome for this will be the same, any attempt to compare the
original file with the reassembled file will have errors. If
comparison is to be done, we recommend that the three bytes be flagged
in the .USR file as byte values so that the assembler has no choice
but to generate the desired values.



KNOWN ERRORS


At the time of this writing, there are no known errors in TOASM. This
is not to say that there are no errors, there are probably many!
Please let us know if you find any.














- -TOASM-5-


  3 Responses to “Category : Utilities for DOS and Windows Machines
Archive   : TOASM11A.ZIP
Filename : TOASM.DOC

  1. Very nice! Thank you for this wonderful archive. I wonder why I found it only now. Long live the BBS file archives!

  2. This is so awesome! 😀 I’d be cool if you could download an entire archive of this at once, though.

  3. But one thing that puzzles me is the “mtswslnkmcjklsdlsbdmMICROSOFT” string. There is an article about it here. It is definitely worth a read: http://www.os2museum.com/wp/mtswslnk/