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.