Click above to get retro games delivered to your door ever month!

 External               External Assembler Procedures                 pp 210

 Syntax:  Procedure (Parms) ; External 'FileName.Com' ;
                                   or
          Function  (Parms) : Type ; External 'FileName.Com' ;

 Type:    N/A

 Form:    Function or Procedure

 Purpose: Declare a function or procedure to be an external binary file.

 Notes:   The reserved word external is used to declare external
          procedures or functions, which are typically written in
          assembly language.

          There is no body in the procedure declaration.  The reserved
          word Procedure is followed by the procedure name, parms,
          semicolon, the reserved word external and the name of the
          binary file in quotes.

          If no file extent is specified, .COM is assumed.

          During compilation, the specified file is included in the object
          code.  The code must be entirely relocatable and therefore
          can't contain any embedded data.  Local storage can be created
          on the stack.

          User written external functions must return their results
          exactly as specified below:

          Scalar values must be returned in the AX register.
          Byte values must return in AL with AH set to zero.

          Boolean values must be returned in the Z flag register.
          ZF = true and NZ = false.

          Real and Set values must be returned on the stack.
          For Reals the exponent is at the lowest memory address.
          Insure the RET x does not pop the Real/Set parameter.

          Pointer values are returned in DX:AX as Segment:Offset


          Procedure Test
            (VAR parm1, parm2, parm3 : Integer) ; External 'FileName.Com' ;


          Stack image at entry to EXTERNAL code after PUSH BP:

             [BP + 04h]            ; Offset  of last parm (parm3 above)
             [BP + 06h]            ; Segment of last parm (parm3 above)
             [BP + 08h]            ; Offset  of parm2
             [BP + 0Ah]            ; Segment of parm2
             [BP + 0Ch]            ; Offset  of parm1
             [BP + 0Eh]            ; Segment of parm1

             Push  BP              ; Must save BP entry value
             Mov   BP,SP           ; Set BP to address the stack
             Mov   AX,[BP + 04h]   ; Offset  of last parm (parm3 above)
             Mov   DS,[BP + 06h]   ; Segment of last parm (parm3 above)
             Lds   AX,[BP + 04h]   ; Load DS,AX with parm3 segment:offset
             Lds   BX,[BP + 08h]   ; Load DS,BX with parm2 segment:offset
             Lds   CX,[BP + 0Ch]   ; Load DS,CX with parm1 segment:offset


 ----------------------------------------------------------------------------


 Usage:
       CONST
         One     : Integer = 1;
         Two     : Integer = 2;
         Three   : Integer = 3;

       VAR
         Sum     : Integer;


       Function Add
         (var p1,p2,p3 : Integer) : Integer ; External 'Add.Com' ;


       BEGIN
          Sum := Add (One,Two,Three) ;
          WriteLn (Sum);
       END.


  (*            Assembler Source Code

  Add           Proc    Near

        Push    BP                              ; Save entry BP
        Mov     BP,SP                           ; Stack pointer to BP
        Push    DS                              ; Current DS value

        Lds     SI,[BP + 0Ch]                   ; Seg:Ofs of parm1
        Mov     CX,[SI]                         ; Parm1
        Lds     SI,[BP + 08h]                   ; Seg:Ofs of parm2
        Mov     BX,[SI]                         ; Parm2
        Lds     SI,[BP + 04h]                   ; Seg:Ofs of parm3
        Mov     AX,[SI]                         ; Parm3

        Add     BX,CX                           ; Add CX to BX
        Add     AX,BX                           ; Add BX to AX

        Pop     DS                              ; Restore current DS value
        Pop     BP                              ; Restore entry BP
        Ret     3                               ; Pop 3 parms off stack
                                                ; Return function in AX
  Add           Endp
  *)