
;   File:   projct02.asm
;   Author: Jonathan Dale Kirwan
;
;   Creation Date:  Mon 29-Mar-1999 01:02:16
;   Last Modified:  Mon 29-Mar-1999 01:24:12
;
;
;   DESCRIPTION
;
;   This lab introduces the principle elements of communicating with BASIC
;   programs as a subroutine called from BASIC.  This particular lab shows
;   how to accept two INTEGER numbers from BASIC, add them, and return an
;   INTEGER result in a fashion compatible with CALL ABSOLUTE.
;
;   In order to make this project work with all versions of BASIC, including
;   QBASIC, the resulting object file is NOT used.  Instead, the linker is
;   ordered to convert this MEDIUM model project into a .COM file (which
;   violates the rule that MEDIUM model programs are always .EXE files.)
;   We then read this .COM file to produce some BASIC DATA statements that
;   can be read into an array and used with CALL ABSOLUTE.
;
;
;   CONCEPTS
;
;   (1) Assembling MEDIUM model source code into COM programs,
;   (2) Steps for processing assembly code into BASIC source code,
;   (3) Passing parameters between assembly routines and BASIC code, and
;   (4) Using CALL ABSOLUTE with assembly code.
;
;
;   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
;
;   BASIC code should always be assembled as the MEDIUM memory model.  In
;   addition, you can add the BASIC option so that the assembler knows
;   about naming conventions and prologue and epilogue code that should
;   be used.  (I know, more of those terms, eh?  Epilogue, prologue?)

                    .MODEL  MEDIUM, BASIC
                    .386


;   CODE SECTION
;
;   The following code will become BASIC DATA values, after some processing.

                    .CODE


;   AddTwoIntegers
;
;   This routine accepts three parameters, adding the first two together and
;   then storing the result into the third parameter.  The third parameter
;   must be a legal variable that can accept a value (don't specify 5, for
;   example, although (5) would be legal and useless.)
;
;   When using CALL ABSOLUTE, BASIC does not accept return values like
;   functions.  Instead, CALL ABSOLUTE is always used just like a subroutine
;   call.  When setting up the parameters to this routine, BASIC doesn't
;   just pass the values directly.  Instead, BASIC passes a memory address
;   of each parameter.  So to get the values, we have to get the address
;   first, then use the address to get the value.  That's the reason for
;   using two assembly statements for each parameter, rather than one.
;
;   In essence, this just means that BASIC passes the VARPTR() of each of
;   the passed parameter values and not their actual values, instead.

AddTwoIntegers      PROC    addend1:PTR WORD, addend2:PTR WORD, result:PTR WORD

            ;   Get the first value into register AX.

                    mov     bx, addend1
                    mov     ax, [bx]

            ;   Add the second value to the first value already in AX.

                    mov     bx, addend2
                    add     ax, [bx]

            ;   Store the resulting sum into the third variable given.

                    mov     bx, result
                    mov     [bx], ax

                    ret

AddTwoIntegers      ENDP

                    END
