
;   File:   projct01.asm
;   Author: Jonathan Dale Kirwan
;
;   Creation Date:  Mon 29-Mar-1999 00:16:41
;   Last Modified:  Mon 29-Mar-1999 01:13:57
;
;
;   DESCRIPTION
;
;   This lab introduces assembly source code and the principle elements of
;   DOS COM programs.  This code is fully functional, as it stands, but it
;   only displays a short message.
;
;   Once this program is assembled into a COM program, you should be able
;   to type this:
;
;       PROJCT01
;
;   and get:
;
;       Hello, world.
;
;   as the output from the program.  The program just displays a short
;   message.  Nothing more complicated.
;
;
;   CONCEPTS
;
;   (1) Assembly source code appearance,
;   (2) Assembling source code into COM programs,
;   (3) DOS COM program features,
;   (4) Using DOS to display messages, and
;   (5) Assembly labels and symbols.
;
;
;   MODIFICATIONS
;
;   Original source.
;
;
;   COPYRIGHT NOTICE
;
;   Jonathan Dale Kirwan grants you a non-transferable, non-exclusive,
;   royalty-free worldwide license to use, copy, modify, prepare deriva-
;   tive works of and distribute this software, subject to your agreement
;   that you acquire no ownership right, title, or interest in this soft-
;   ware and your agreement that this software is research work which is
;   provided 'as is', where Jonathan Dale Kirwan disclaims all warranties
;   with regard to this software, including all implied warranties of
;   merchantability and fitness of purpose.  In no event shall Jonathan
;   Dale Kirwan be liable for any direct, indirect, consequential or
;   special damages or any damages whatsoever resulting from loss of use,
;   data or profits, whether in an action of contract, negligence or
;   other tortious action, arising out of or in connection with the use
;   or performance of this software.


;   PROGRAM MODEL
;
;   .MODEL is one of the newer "simplified" assembler directives.  (They
;   were probably added because a lot of programmers had a hard time
;   learning to understand and properly use the SEGMENT directive.)
;
;   The program models are TINY, SMALL, MEDIUM, COMPACT, and LARGE.  The
;   first big difference is that TINY programs result in .COM files, while
;   the other models must be coded into .EXE files (usually, but there
;   *is* EXE2BIN.EXE which modifies this statement slightly.)  DOS handles
;   these two different kinds of programs differently, as you will see.
;   The rest of the models just set up the four possible combinations of
;   assuming offset-only or segment/offset for code and data pointers.
;
;   There is a side effect to the order in which .MODEL and .386 are
;   placed in the source code.  If .MODEL occurs first, the assembler
;   assumes 16-bit segments.  If .MODEL occurs after the .386, the
;   assembler assumes 32-bit segments.  Nasty, but true.

                    .MODEL  TINY, STDCALL, NEARSTACK
                    .386


;   DATA ELEMENTS START HERE
;
;   The .DATA simplified directive sets up the default segment name and
;   options for the default data segment in the given program model.  In
;   short, though, it just means that you can add your data and variables
;   here.
;
;   In this example, we've got only one thing -- the message we will
;   print out.

                    .DATA

    Message         DB      "Hello, world.$"


;   COM PROGRAMS START HERE
;
;   The .CODE simplified directive sets up the default segment name and
;   options for the given program model.  The .STARTUP simplified directive
;   just positions the default starting point in the code for .COM files at
;   0100h and for .EXE files it generates some standard prologue code.  I
;   won't belabor this here, though.  Just accept that the instruction that
;   follows .STARTUP will be the first one to execute when the program is
;   started up by DOS.
;
;   DOS always starts a COM program at 0100h.  The .STARTUP assembler
;   command causes the assembler to position the default memory offset
;   to begin at this point.  This is done so DOS can place the PSP data
;   in the locations from 0000h to 00FFh.
;
;   When DOS tries to run a COM program, it first allocates the largest
;   available block of memory.  (Under normal circumstances, there's only
;   one block and this is almost always several hundreds of kilobytes, in
;   size.)  DOS then prepares the first 256 bytes of the allocated block,
;   by filling in the elements of the PSP (noted above) and then loading
;   the COM program file, starting just after the PSP.  Once this is done,
;   the registers are set up as noted below and DOS transfers control by
;   setting the CS register to the base segment value of the allocated
;   memory and setting the IP register to 0100h (both can be set at the
;   same time by a "far jump.")
;
;   DOS always places a double-byte 0 (word 0) at the end of the stack,
;   in effect a PUSH 0, so that a RET (return from subroutine) instruction
;   will go to offset 0 (in the PSP) where a special instruction exists to
;   cause the COM program to terminate, properly.  This is a convention
;   that is not the prefered way, however, to exit programs, including COM
;   programs.  So don't use it.
;
;   DOS starts the COM program with the following register defaults:
;
;   CS, SS, DS, ES
;       These segment registers are all loaded with exactly the same
;       value, determined by DOS when it attempts to allocate memory
;       to load the COM program.  This value, taken with an offset of
;       of 0, corresponds to the base 20-bit address of the allocated
;       memory block.
;
;   IP
;       The starting address offset of the COM program, namely 0100h.
;
;   SP
;       Unless DOS has a problem allocating a block of memory that's
;       at least 65536 bytes in size, the value will always be FFFEh.
;       If the largest available block of memory is smaller than this
;       value, but still big enough to prepare a PSP and load the COM
;       file into, then DOS will set the SP register to the largest
;       offset in the available memory block, less 1.  Either way, DOS
;       places a 0 byte at the address refered to by [SP] and [SP+1].
;
;   BX, CX
;       Together, these two 16-bit registers are considered to be a
;       single 32-bit integer, with BX being the upper 16 bits of this
;       value and the CX register being the lower 16 bits.  Since most
;       COM programs are under 64k-byte in size, this almost always
;       means that BX is 0.  Although DOS can load COM programs that
;       are larger than 64k-byte in size, they weren't designed for
;       such large sizes.
;
;   AX, DX, SI, DI
;       These are always set to 0, upon startup.  But it's probably
;       best not to rely on this behavior.  Just consider them as
;       available for immediate use, instead.

                    .CODE
                    .STARTUP

                    mov     dx, OFFSET message
                    mov     ah, 9
                    int     21h
                    mov     ah, 4Ch
                    int     21h

                    END
