HomeWare 14/HOMEWARE14.bin/prog/a86v371.arj/A03.DOC

Text File | 1994-01-24 | 23KB | 503 lines

CHAPTER 3   OPERATION AND REQUIREMENTS


Creating Programs to Assemble

Before you invoke A86 you must have an assembly-language source
program to assemble.  A source program is an ASCII text file,
created with the text editor of your choice.  The editor must
produce a file that is free of internal records known only to the
editor.  Some of the fancier word processors will require you to
use a "plain text" mode to insure that the file is free of such
records.

This manual will fully explain to you the correct syntax of an
A86 program, but it is not intended to teach you about the
86-family instruction set, or about assembly-language interfacing
to your computer or your operating system.

The instruction set charts in Chapters 6 and 7 give concise,
one-line descriptions of each instruction, but they don't go into
any detail about instruction usage, or about how to make system
calls to input from keyboard or disk, output to screen, printer
or disk, etc.  For that, you need a book that covers the MS-DOS
operating system and the BIOS for the IBM-PC.  I am currently
using DOS Programmer's Reference by Terry Dettmann, available by
mail from Public Brand Software at 1-800-426-3475.  At a more
instructional level, my users report that Peter Norton's Assembly
Language Guide to the IBM-PC has been helpful.


Program Invocation

To invoke A86, you must provide a program invocation line, either
typed to the console when the DOS command prompt appears, or
included in a batch file.  The program invocation line consists
of the program name A86, followed by assembler switches
(described in the next section), and the names of the source
files you want to assemble, and of the output files you want to
produce.  If the output files all have their standard extensions,
they may appear in any order: before, after, or even intermixed
with the source file names.  If they don't have their standard
extensions, you must give the source file names first, followed
by the word TO, followed by the output file names.  Each
non-standard name following the word TO will be assigned to the
first previously- unassigned output file in order: program,
symbols, listing, then cross-reference.

You may use the wild card delimiters * and ? if you wish, to
denote a group of source files to be assembled.  A86 will sort
all matching names into alphabetical order for each wild card
specification; so the files will be assembled in the same order
even if they get jumbled up within a directory.

If you provide a name without a period or an extension, A86 will
use that as the output program file name, appending to it the
default extension as follows:

1. .OBJ if you invoked the +O switch, for linkable object file
   production.
                                                              3-2

2. .BIN if there is no +O switch, but there is an ORG 0 of in
   your program, without a later ORG 256.

3. .COM otherwise.

If you want your program file to have no extension, you end the
file name with a period.

You may omit any of the output file names if you wish.  If you do
so, A86 will output the program source.COM (or source.OBJ or
source.BIN), where "source" is a name derived from the list of
source files, according to the rules described in the section
"Strategies for Source File Maintenance" later in this chapter.
Any of the other output files will use the name of the program
output file, combined with the standard extension for that output
file.


Assembler Switches

In addition to input and output file names, you may intersperse
assembler switch settings anywhere after the A86 program name.
They are all acted upon immediately, no matter where they are on
the command line.  Some of the switches are discussed in more
detail elsewhere; I'll summarize them here:

+C     causes the assembler to output symbol names with lower
    case letters to its OBJ and SYM files.  The case of letters
    is still ignored during assembly.  I output the name as it
    appears in the last PUBLIC or EXTRN directive containing it;
    if there is no such directive, I use the first occurrence of
    the symbol to control which letters are output lower case.
    (+C duplicates Microsoft MASM's /mx switch.)

+c     causes the assembler to consider the case of letters
    within all non-built-in symbols as significant both during
    assembly and for output.  Thus, for example, you can define
    different symbols X and x.  (+c duplicates MASM's /ml
    switch.)

+D     causes the default base for numeric constants to be
    decimal, even if the constants have leading zeroes.

-D     causes the default base to be hexadecimal if there is a
    leading zero; decimal otherwise.

+E     causes the error-message-augmented source file to be
    written to yourname.ERR within the current directory, in all
    cases. With +E, A86 will never rewrite your original source
    file.

-E     causes A86 to insert error messages into your source file,
    whenever the file is in the current directory.  If the file
    is not in the current directory, A86 writes an ERR file no
    matter what the E switch setting is.
                                                              3-3

+F     causes A86 to generate the 287 form of floating point
    instructions (no implicit FWAIT bytes are generated before
    the instructions).  This mode can also be specified in the
    program with the .287 directive.

+f     causes A86 to support emulation of the 8087.  When A86
    sees a floating point instruction, it generates external
    references to be resolved by the standard emulation library
    (provided by Microsoft, Borland, etc.).  When you LINK your
    program to the emulation library, the floating point
    instructions are emulated by software.  NOTE you must be
    assembling to a linkable OBJ file for this mode to have
    effect; otherwise, +f is ignored.

-F     causes emulation and default-287 to be disabled.  You'll
    still get 287 generation if there is a .287 directive in your
    program.

+G  n         causes A86 to implement one or more of the
    following minor options for code-generation.  All these
    options enhance MASM compatibility.  The first three do so at
    the expense of program size.  The number n should be the sum
    of the numbers for each of the options selected.  For
    example, +G10 will select the options numbered 2 and 8.

    1    causes A86 to generate a longer (3-byte) instruction
        form for an unconditional JMP instruction to a forward
        reference local label, e.g. JMP >L1.  A86 normally
        assumes that since it's a local label, it will be nearby
        and the short, 2-byte form will work.  With this option
        your code will usually be longer than necessary, but
        you'll be spared having to occasionally go back and code
        an explicit JMP LONG >L1.

    2    causes A86 to refrain from optimizing the LEA
        instruction. Without this option A86 will replace an LEA
        with a shorter, equivalent MOV when it sees the chance.

    4    causes A86 to generate a slightly more inefficient
        internal format for memory references within an OBJ file.
        The Power C compiler's MIX utility requires the
        inefficient form. The makers of Power C refused to
        support their customers on this by enhancing MIX, so I am
        forced to offer this option.

    8    causes A86 to assume that all ambiguous forward
        reference operands to instructions other than jumps or
        calls refer to memory variables and not offsets or
        constant values.  You can override this on a one-by-one
        basis, with the OFFSET operator.

    16   causes A86 to require that undefined names be explicitly
        declared with an EXTRN when A86 is producing a linkable
        .OBJ file.  This switch has no effect when A86 is making
        a .COM file.  Without the switch, A86 will, when
        assembling to an .OBJ file, quietly assume that all
        undefined names are valid external references.
                                                              3-4

-G      causes A86 to revert to its default for all the above
options.

+H  n      causes A86 to produce n extra listing lines, as
    necessary, containing excess hex bytes of object code
    produced by each source line.  Without this switch, A86
    produces extra hex lines only if it producing extra lines
    anyway to display excess source code.

+I  n       controls the indentation of the source line within an
    A86 listing line (and thus the amount of room allocated for
    the hex object display).  You may have any indentation up to
    127.  The default value is 34, which gives room for 6 hex
    object bytes.  You may add or subtract 3 to that value, to
    increase or decrease the hex object bytes.  If you add 128 to
    the value of n, the listing of the line number is suppressed
    (so you can subtract 6 from the indentation to get the same
    number of hex digits).

+L  n       causes A86 to produce a listing file of the assembly.
    The n is optional, and controls what will be included in the
    listing.  You add numbers from the following table to produce
    an n which specifies the combination of elements you want:

    Use at most one of the following three values:

         * Use 1 if you want A86 to eliminate all conditional
            assembly control lines (#IF, #ENDIF, etc.) and all
            conditionally skipped code from the listing.

         * Use 2 if you want A86 to include the control lines but
            not the skipped code.

         * Use 3 if you want A86 to include both control lines
            and skipped code.

    4   causes A86 to include the lines produced by macro
       expansions.  Otherwise, only the macro call line is
       listed.

    8   causes listing control lines (TITLE, SUBTTL, PAGE) to be
       listed.

    16  causes the hex output object pointer to be included on
       all listing lines, whether they have produced hex object
       bytes or not.  Otherwise, the 4-digit pointer is included
       only on lines producing object bytes; on other lines, the
       field is blank (but the line itself is listed!).

    32  causes a symbol-table listing to be produced at the end
       of the listing file.
                                                              3-5

    If n is not given after +L, a value of 39 is assumed: symbol
    table, hex pointer only if there are object bytes, no listing
    control lines, and macro expansion lines, conditional control
    lines, and skipped lines are all listed.  If +L is not given
    at all, then a listing file will be produced only if it is
    explicitly named on the invocation line.

+O     causes A86 to produce a linkable .OBJ file when the output
    file name extension is not explicitly given.

-O     causes A86 to produce an executable .COM file when the
    output file name extension is not explicitly given.

+P  n      controls which processor A86 is assembling for.  You
    choose one of the following values for n, for the level of
    Intel processor support you wish:

          * Choose 0 for the base 8086/8086 instruction set only.
            Use this value if you want your programs to run on
            all machines.

          * Choose 1 for instructions up through the 186.

          * Choose 2 for instructions up through the 286.  Use
            this value if you are assembling for a more recent
            processor (386, 486, etc.), until A386 is available.

    In addition, you may add the value 32 to n if you wish the
    NEC-specific instructions to be assembled.  Since the NEC
    processor include the 186 instructions, you specify +P33 to
    assemble for a NEC processor; use +P35 if you wish to allow
    all possible instructions (which is what older versions of
    A86 allowed).

    The switch setting +P64 specifies assembly of the base-level
    8086/8088 instruction set, but with special handling of a few
    of the later instruction forms, to generate compatible code.
    Specifically: all shift and rotate instructions with an
    immediate shift value greater than 1 will generate that many
    repetitions of the 1-value instruction form; e.g., ROL BL,3
    will generate 3 copies of ROL BL,1.  The mnemonics PUSHA and
    POPA will be honored, generating appropriate sequences of
    multiple PUSHes and POPs.

    The default setting for this switch is for A86 to assemble
    for the processor on which it is currently running; +P64 if
    that processor is an 8086 or 8088.

+S     suppresses the creation of the symbol table (.SYM) file.
    This is overridden if you give an explicit symbols file name
    in the invocation line.

+T  n     controls various options conerning the titling and
    pagination of listing files.  You add together your selection
    of options from the following list, to produce a value of n
    containing the combination you want:
                                                              3-6

    The following values control the automatic incrementing of
    section numbers in an A86 listing.  The section number
    appears to the left of the hyphen in a page number.  Use at
    most one of the following three values:

          * Use 1 if you want A86 to refrain from incrementing
            the section number whenever there is a change to the
            source file.  If you choose this option, and you
            don't manually increment the section number in a PAGE
            directive, then page numbers will be single numbers
            without any hyphenation.

          * Use 2 if you want A86 to increment the section number
            for each new main source file, but not for INCLUDE
            files.

          * Use 3 if you want A86 to increment the section number
            for all source files, INCLUDE files, and returns from
            INCLUDE.

    4   causes A86 to automatically issue a page break at
       reasonable places in the code (file breaks, and gaps of
       consecutive blank lines of various lengths occurring near
       the end of a page).  This is described in more detail in
       Chapter 13.

    8   causes A86 to issue the page-ending formfeed instead of
       the last linefeed, rather than in addition to it.  The
       advantage of this is that you can specify one more line on
       a page for many printers. The disadvantage is that some
       editors and file-viewing programs will not display such a
       file correctly; e.g. LIST will not show the last line of a
       page.

    16   causes A86 to use the current source-file name as a
       default TITLE if there has been no TITLE directive in the
       program; as an implicit SUBTTL at the beginning of each
       file if there is a TITLE explicitly given.

    32   causes A86 to output a 2-line gap, followed by a line
       containing the name of the source file, every time the
       source file changes in the listing.

    If -T (or +T0) is specified, then no titling or pagination is
    done at all.  If the switch is not specified at all, a
    default value of 52 (auto-paging, auto-titling, and source
    file line, but no auto-section and no FF instead of LF).  Of
    course, if there is no listing file the T switch has no
    effect.

+W   n       controls the characteristics of wide lines in the
    A86 listing file.  You add together your selection of options
    from the following list, to produce a value of n containing
    the combination you want:
                                                              3-7

    0--3    (at most one value!) determines the indentation from
       the beginning of the source line for wrapped-around source
       code on subsequent lines.  The indentation will be 5
       spaces times the number given: 0,5,10,15 spaces
       respectively.

    4   causes A86 to truncate lines that exceed the page width.
       Exception: if A86 is outputting a line with trailing hex
       bytes anyway (via the H switch), any wrapped-around source
       will be shown on those lines.

    8   causes A86 to start with a listing line width of 79.
       Without this option, the width is 131.  The width can be
       set to other values in the source code via the PAGE
       directive, described in Chapter 13.

    16   causes the title lines at the head of the page not to
       exceed 79 bytes in width, even if the other listing lines
       are longer.  This option is handy if you are viewing a
       listing on the screen, with a viewing program that
       truncates long lines: the page headers will still be
       visible during normal scrolling.

+X      causes A86 to produce a cross-reference file (the same
    file that was produced by the XREF utility in earlier
    versions of A86).

Unless otherwise stated, the default setting for all the switches
is "minus".  Multiple switches can be specified with a single
sign; e.g. +OG15L55 is the same as +O+G15+L55.



The A86 Environment Variable

To allow you to customize A86, the assembler examines the MS-DOS
environment variable named "A86" when it is invoked.  If there is
such a variable, its contents are inserted before the invocation
command tail, as if you had typed them yourself.

For example, if you execute the command SET A86=+O while in DOS
(typically in the AUTOEXEC.BAT file run when the computer is
started), then the O switch will be "plus", unless overridden
with a "minus" setting in the command line.

You may also include one or more file names in the A86
environment variable.  Those files will always be assembled
first, before the files you specify on the command line.  This
allows you to set up a library of macro definitions, which will
always be automatically available to your programs.  Thus, for
example, the DOS command  SET A86=C:\A86\MACDEF.8 +O  will cause
both the O switch to default ON, but will also cause the file
MACDEF.8 of subdirectory A86 of drive C to always be assembled.
                                                              3-8

Using Standard Input as a Command Tail

The following feature is a bit advanced.  If you're not familiar
with the practice of redirecting standard input, you may safely
skip this section.

A86 can also be configured to take its command arguments from
standard input, in addition to the invocation command tail or the
A86 environment variable.  This allows A86 to be used in those
menu-driven systems that don't generate command tails for
programs.  It also allows other programs to create lists of files
to be assembled, then "pipe" the list to A86.

Here's how the feature works: when the command argument A86 is an
ampersand &, A86 will prompt for standard input.  If the
ampersand is seen but there are other things following it, the
ampersand is ignored.

For example, you can place a list of file names and switch
settings into a file called FILELIST.  You can then invoke the
assembler via

A86 <FILELIST &

which will cause the contents of the FILELIST file to be used as
a command line.

You may place an ampersand at the end of your A86 environment
variable.  If you do so, then A86 will prompt for file names
whenever it is invoked without any command arguments (you type
A86 followed immediately by the ENTER key to the MS-DOS prompt).
This is the mode used if you have a menu system that can't
generate an invocation command tail.

Note: when you redirect standard input so that it comes from a
file, A86 will read all the lines of the file (up to a limit of
1023 bytes), and substitute spaces for the line breaks.  Thus you
may give the file names on individual lines, for readability.
However, if the feature is invoked manually (no redirection), so
that you are typing in the line after the prompt, A86 will take
the first line only.  You need to give all your switches and
files on that one line.



Strategies for Source File Maintenance

A86 encourages modular programming, by letting you break your
source into separate files, with complete impunity.  A86 has no
concern whatsoever for file breaks-- it treats the sequence of
files as a single source code stream.

You should consider one or more of the following strategies,
which I have adopted in my source file management:
                                                              3-9

1. I name all my A86 source files with the same extension, which
   is found on no other files. The particular extension I have
   chosen is ".8". I did not choose the more common .ASM, because
   I have a few source files designed for MSDOS's assembler.  If
   you don't like .8, I would suggest .A86.

2. I keep a separate subdirectory on my hard disk for each
   multi-source-file A86 program I have.  Then the simple command
   "A86 *.8" performs the assembly for the current directory's
   program.

3. I exploit the fact that A86 expands wild cards into
   alphabetical order.  Whenever I want a source file to be
   assembled first (e.g., when it contains variable
   declarations), I append a decimal digit to the start of the
   file name: 0 for the first file, 1 for the second, etc., for
   however many files that need to be explicitly ordered.  If a
   file needs to come last, I append a "Z" to the start of the
   file name.

   To accommodate this strategy, I have programmed A86 to a
   somewhat complicated algorithm for determining the default
   output file name.  I use the name of the first source file;
   but I truncate the first character if it is a decimal digit.
   However, you may have a general-purpose file that must come
   first; so I have provided the following exception: if you have
   a source file whose name begins with the digit "9", that name
   (without the 9) is used.  If you don't like this, you can
   always explicitly give the program name you want: "A86 *.8
   MYPROG".


System Requirements for A86

A86 requires MS-DOS V2.00 or later.  No BIOS or lower-level calls
are made by A86, so A86 should run on any MS-DOS machine.  Please
let me know if you find this not to be the case.

A86 itself is a small program, and it is fairly flexible about
the memory it uses.  You can assemble with only 32K bytes of
memory beyond the program itself, which in the current version is
under 31K bytes-- a total of 63K bytes beyond the operating
system.  There is no longer any limit on the size of source files
assembled under A86.  The more memory you have, the more capacity
A86 has, in symbol table size and output file size.  If it can,
A86 will use up to 400K bytes of memory.