AFIX conversion tool, V1.0                 February 18, 1990
Copyright 1990 Eric Isaacson.  All rights reserved.

Eric Isaacson
416 E. University Ave.
Bloomington, IN 47401-4739
(812)339-1811

The AFIX package consists of this AFIX.DOC file, the program 
AFIX.COM, and the set of files with the .FIX extension, that
are fed to the AFIX program.

I consider the legal status of the AFIX package to be the same 
as that of the free-distribution parts of my A86 package: I 
grant permission for anyone to copy the complete, unmodified 
package and use it to try out A86.  There is no separate 
registration fee for AFIX: if you register for A86, that covers 
the usage of AFIX.  See the A86 package (V3.22 or later) for 
details of my copying permissions/restrictions, including my 
reservation of the right to inform specific parties that they 
may not distribute some or all of my software.


Overview of AFIX

In an effort to expand the test base for my A86 assembler, I 
recently converted 61 assembly-language source files, published 
by PC Magazine during the past 3 years.  These files were 
written for various versions of the inferior but more widely-
distributed MASM assembler by Microsoft.  I made the minimum 
modifications necessary so that A86 would assemble the source 
files directly to COM files that are functionally equivalent to 
the files produced by MASM, LINK, and EXE2BIN. I would like to 
make the modified files as widely available as the original MASM 
files; but simply distributing them would violate their 
copyright. 

AFIX was written to solve this legal problem.  For each modified 
source file, I am publishing a special file with the extension 
.FIX, that contains the specifications for modifying the 
original PC Magazine source file.  The FIX files contain 
absolutely nothing from the original .ASM files; so they are 
entirely mine and I can copyright and distribute them as I 
please. 

To run AFIX, you must place AFIX.COM, the original .ASM file, 
and the corresponding .FIX file into your current directory, and 
type AFIX followed by the file name to the DOS prompt.  AFIX 
will verify that the .ASM file has the same size and 16-bit 
checksum as the file I have.  If it does, AFIX will produce an 
A86-compatible file, with the extension .8.  A comment line is 
inserted at the top of the file, giving the A86 invocation line 
that will assemble the program.  If the original file was more 
than 64K in size, the output will be split into multiple files, 
with names ending in _1, _2, etc. 

You do not need to run AFIX for each individual source file: 
AFIX will accept wildcards in the program name.  In fact, if you 
simply type AFIX to the DOS prompt, with no arguments, then 
*.FIX is assumed, and AFIX will convert all programs for which a 
.FIX file and the correct .ASM file both exist.  If you do this, 
you might want to redirect standard output to a disk file, so 
that you can review the status messages at the end: 

    AFIX >AFIX.LOG

If you get AFIX from a disk you have purchased from me or from a 
shareware distribution house, the disk will not contain the .ASM 
files you need-- they are copyrighted and cannot be sold.  
You'll need to download them from a BBS, or from the utilities 
forum of PCMagnet. 


What AFIX Doesn't Do

AFIX is not a general-purpose MASM-to-A86 translation tool-- you 
**cannot** apply it to files you have created.  AFIX is merely a 
tool that allows me to communicate, in a machine-readable 
format, the changes that I manually made to the copyrighted 
source files.  It works only with the .FIX files that I have 
supplied.  I do hope to write a MASM-to-A86 tool that will 
assist you in converting any program; but there are other 
improvements I would like to make to A86 first.  Meanwhile, this 
present effort makes over 2 megabytes of A86 source code 
publicly available.  That should be enough to keep you busy for 
awhile! 


Some Comments About the Converted Programs

This conversion effort has substantially improved both the 
reliability and compatibility of A86.  I made several dozen 
changes for the V3.22 release, to minimize the changes needed 
for the successful conversion.  I added a new switch, +L8, that 
changes assumptions made about untyped forward references, 
reducing the number of B and W type-specifiers needed. The +D 
switch already made the syntax of numeric constants MASM-
compatible.  Thus, for maximum compatibility, the converted 
files are assembled with the +DL8 switch setting. 

Chapter 12 of the A86 manual goes into detail about what needs
to be done to convert files from MASM to A86.  All 61 source
files assemble to complete .COM programs.  The changes made to
these files fell into five categories: 

1. Most of the changes comprised the addition of explicit 
   segment-override operators to memory references.  MASM 
   inserts such overrides behind the programmer's back, as 
   controlled by the confusing and misunderstood ASSUME 
   directive.  These overrides appear primarily in the
   handlers for interrupts taken over by memory-resident
   (TSR) programs.  For simple, non-resident COM programs,
   all segment registers point to the program segment,
   so that overrides aren't needed.

2. Two of the 61 source files contained macros.  A86's
   macro definition syntax is different, so the definitions
   had to be converted.  These were the only two files
   that did not retain MASM-compatibility after conversion.

3. There were some forward-reference symbols whose type
   needed to be specified, usually with the OFFSET operator.

4. There were a few expressions involving forward references
   that A86 couldn't handle.  The expressions were moved into
   EQU directives placed below the symbols referenced.

5. There were a couple of built-in mnemonics, such as WAIT, that 
   doubled as user symbols.  MASM allows this; A86 doesn't.  The 
   symbols were modified by appending an underscore character. 

I verified the correctness of the converted files by generating a 
proprietary version of A86 that mimicked as closely as possible 
the (mostly inferior) code generation of MASM.  This reduced the
number of discrepancies in the resulting .COM files to a small
enough number that I could manually verify their functional
equivalency.  I did not attempt to test the execution of the
programs themselves.

The total size of changes was minuscule in proportion to the 
total size of the source files.  In fact, the one-line comments 
appended to the top of each program totalled more bytes than the 
code changes made!  Without those comments, the total changes 
(moved bytes plus inserted bytes plus deleted bytes) for the 59 
non-macro files were 3363 out of 2231783 bytes.  I can thus 
claim that for COM programs not containing macros, A86 is 99.83% 
MASM-compatible.  Twenty of the files required no changes
whatever. 

