home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 9 / 09.iso / l / l010 / 5.ddi / C5.ARC / BBX_ASM.DOC < prev    next >
Encoding:
Text File  |  1989-12-20  |  11.5 KB  |  327 lines
  1. Assembly language provides the most freedom for writing BlackBoxes and
  2. supporting them in multiple languages.  All types of source-code BlackBoxes
  3. can be easily written under this system.
  4.  
  5.  
  6. ; ----------------------- MEMORY-BASED BLACKBOXES -----------------------
  7.  
  8.  
  9. The Following Macros are used for all memory-based BlackBoxes written in
  10. Assembly Language.  We recommend that you do not bypass these macros,
  11. since they will use the correct segment naming conventions for each of
  12. the different languages, as well as label naming convensions.
  13.  
  14.  
  15. _BBX_START_DATA
  16.  
  17. ; starts the data segment for a blackbox.
  18. ; this is optional, since a blackbox may contain no private data
  19.  
  20.  
  21. _BBX_END_DATA
  22.  
  23. ; Ends the data segment for a blackbox
  24. ; Required if and only if _BBX_START_DATA has been used.
  25.  
  26.  
  27. _BBX_START_CODE
  28.  
  29. ; Starts the code segment for a blackbox
  30.  
  31.  
  32. _BBX_END_CODE
  33.  
  34. ; Ends the code segment for a blackbox
  35.  
  36.  
  37. _END_PROG
  38.  
  39. ; Ends the file
  40.  
  41.  
  42. _BBX_PROC     name_of_blackbox <, .NO_DATA or , .NOTHING>
  43.  
  44. ; This begins a BlackBox procedure.  For C, an underscore will automatically
  45. ; be generated in front of the label.  The label is automatically public-ed
  46. ;
  47. ; If nothing follows the name of the blackbox, then BP is pushed, set to
  48. ; sp to access the calling stack frame, and then all registers required not
  49. ; to change are pushed on the stack.  Finally, the data segment of the
  50. ; blackbox's private data is moved into DS, using AX.
  51. ;
  52. ; If .NO_DATA follows the name of the blackbox, then the stack frame is set
  53. ; up exactly as above, but the data segment is not moved into DS.  This is
  54. ; required if no _BBX_START_DATA was used to declare a data segment.
  55. ;
  56. ;
  57. ; If .NOTHING follows the name of the blackbox, then no stack frame is set
  58. ; up, and no data segment is moved into ds.  The procedure is merely declared.
  59. ;
  60. ; This should be used ONLY for the BlackBox procedure, not for any near
  61. ; procedures called within the blackbox.  Those would be declared normally,
  62. ; using the proc operand.
  63.  
  64.  
  65. _BBX_ENDP     name_of_blackbox
  66.  
  67. ; This ends a BlackBox procedure.  For C, an underscore will automatically
  68. ; be generated in front of the label.
  69.  
  70.  
  71. _PUBLIC       label_to_public
  72.  
  73. ; declares the label public in the executable .BBX, but does not declare it
  74. ; public in C, Pascal, or Basic.  For symbolic debugging purposes, or to
  75. ; generate a detailed .MAP file, you may wish to declare labels public.
  76. ; However, in the .OBJ's created in C or BASIC, these private labels should not
  77. ; be public, and in Turbo Pascal, these labels CANNOT be public, so the
  78. ; macro will not declare them when compiled for those languages.
  79.  
  80.  
  81. _BASIC_STRING  segment_register, address_register
  82.  
  83. ; When working with pointers to text or pointers to check boxes, the BASIC
  84. ; calling procedure passes the address of a string descriptor, rather than
  85. ; the address of the data itself.  Once the pointer has been loaded into
  86. ; registers, this macro should be used to get the pointer to the actual
  87. ; data.  In any language except BASIC, this macro does nothing.
  88. ;
  89. ;   Example:
  90. ;
  91. ;        les       di,PASSED_FILE_NAME
  92. ;        _BASIC_STRING es,di
  93. ;
  94. ;       ; Now, no matter what language, es:[di] points to the string.
  95. ;
  96. ; Note that the address_register must be one that can be used as a pointer!
  97. ;
  98. ; If you are not going to support direct compilation of BASIC programs, you
  99. ; do not have to use this macro.
  100. ;
  101.  
  102. _SETUP_STACK
  103.  
  104. ; This sets up the stack frame as described in _BBX_PROC
  105. ; You may wish to use this if the .NOTHING parameter was used with _BBX_PROC
  106.  
  107.  
  108. _RESTORE_STACK     pop_value
  109.  
  110. ; You must use this macro to restore the stack and return from your BlackBox.
  111. ; The pop_value is the amount to pop off the stack when returning to Pascal
  112. ; or BASIC programs.  If no pop_value is supplied, even in BBX or C compiling,
  113. ; a warning will be displayed on the screen, but not counted as a warning by
  114. ; the assembler.
  115.  
  116.  
  117. _RETURN_VALUE      return_address, return_reg
  118.  
  119. ; This macro will aid in returning check box values from your BlackBox.
  120. ; The return_address is an equate in the form of [BP+BBXC_BASE+?], and the
  121. ; return_reg should be a byte register.
  122.  
  123.  
  124.  
  125. _BBX_ICALL    name_of_call, pop_value
  126.  
  127. ; This macro will call an internal LAYOUT function.
  128. ; The name of the call is one of the equates described in the beginning of
  129. ; EQUATES.ASM, and the pop_value is the amount of bytes pushed on the
  130. ; stack to the internal procedure.
  131.  
  132.  
  133. _mov_addr     register, variable_label
  134.  
  135. ; This macro will move the offset of a private variable in the BlackBox to
  136. ; the register indicated.  In BBX and Pascal format, this simply uses the
  137. ; OFFSET operand, but in C and BASIC it uses an LEA instruction because the
  138. ; OFFSET operand will not work.  If LEA is always used to access the address
  139. ; of a private variable, this macro is not needed.
  140.  
  141.  
  142. The Following Equates are available to all memory-based BlackBoxes written in
  143. Assembly Language.
  144.  
  145. REVERSE_ORDER      ; an internal equate indicating whether the current
  146.                    ; language of compilation usually passes in reverse order
  147.  
  148.                    ; Note that BlackBoxes are ALWAYS passed parameters by
  149.                    ; pushing in the requested order, so that the first
  150.                    ; requested parameter is ALWAYS at the highest address,
  151.                    ; regardless of the calling procedure's language.
  152.  
  153.  
  154. RETURN_AND_POP     ; an internal equate indicating whether the current
  155.                    ; language of compilation will pop parameters off the
  156.                    ; stack for the BlackBox
  157.  
  158.  
  159. BBX_LANGUAGE_VALUE ; an internal equate indicating the current language of
  160.                    ; compilation.
  161.  
  162. language_type      ; the position from BP in the passing stack frame of the
  163.                    ; calling procedure's language value
  164.  
  165. bbxc_base          ; the position from BP in the passing stack frame of the
  166.                    ; calling procedure's last requested parameter
  167.  
  168. _DATA_SEG          ; the private data segment
  169.  
  170.  
  171. language           ; an internal equate set at compile time to indicate the
  172.                    ; current language of compile.  The values for language
  173.                    ; are EXE, C, TURBO, BASIC
  174.                    ;
  175.                    ; To conditionally compile EXE code for example:
  176.                    ;
  177.                    ;    ife language - exe
  178.                    ;         ; put code for only BBX/EXE here
  179.                    ;    endif
  180.  
  181.  
  182.  
  183. The steps for writing a Memory-Basied BlackBox in Assembly are as follows:
  184.  
  185.  
  186. 1.  Include the files LANGUAGE.LIB and EQUATES.ASM
  187.  
  188. 2.  If desired, use the _BBX_START_DATA to declare a data segment
  189.     a. declare internal data
  190.     b. use _BBX_END_DATA to end the data segment
  191.  
  192. 3.  Use _BBX_START_CODE to declare the code segment
  193.  
  194. 4.  If you are putting more than one BlackBox in the current source file,
  195.     you should declare a series of near ptr jumps into the code.  This
  196.     guarantees that the entry addresses do not change for BlackBoxes following
  197.     the first, and no change in header files is required.
  198.  
  199. 5.  Declare any external procedures for non .BBX code that will be used.
  200.     This is ONLY for BlackBoxes taking advantage of the INT 0F4H calls.
  201.  
  202. 6.  Declare the passing stack structure in the same method as follows:
  203.  
  204.     your_prog_varln     equ  10 + 2                   ; always +2 for language
  205.     parameter1          equ  [bp+bbxc_base+6]         ; passed by reference
  206.     parameter2          equ  [bp+bbxc_base+4]         ; passed by value
  207.     parameter3          equ  [bp+bbxc_base]           ; passed by reference
  208.  
  209.     For double word pointers, add 4 to get to the next parameter.
  210.     For values passed as words, add 2 to get to the next parameter.
  211.  
  212.     Always declare a passed variable length (varln) equate to indicate the
  213.          amount that must be popped off the stack before returning to Pascal
  214.          or Basic procedures. Remember that this value will always be 2 more
  215.          than the amount for your declared parameters, since a language type
  216.          value will also always be passed at a lower address than the lowest
  217.          parameter on the stack.
  218.  
  219. 7.  Declare the procedure using _BBX_PROC
  220.  
  221. 8.  Write the code that performs the action of the BlackBox
  222.  
  223. 9.  If you are returning a Check Box parameter, use the _RETURN_VALUE macro
  224.     to do this.
  225.  
  226. 10. Return from the BlackBox using the macro _RESTORE_STACK
  227.  
  228. 11. End the procedure using _BBX_ENDP
  229.  
  230. 12. Repeat steps 5-10 for any other BlackBoxes within this file.
  231.  
  232. 13. End the BlackBox file using _BBX_END_CODE and _END_PROG
  233.  
  234. 14. To create a Turbo Pascal version of your object file, you must create a
  235.     .PAS file to compile into a .TPU file.  The .PAS file should declare the
  236.     name of the unit, declare the BlackBox procedure(s) (any parameters
  237.     passed by reference should remain untyped) in the interface section,
  238.     declare them again in the implementation section as external procedures,
  239.     and then include the .OBJ using the $L command.
  240.  
  241. 15. To compile this Blackbox, use the batch file M_BBX.BAT
  242.  
  243.     M_BBX name <, alternate_name>
  244.  
  245.  
  246.     If you wish to compile without the batch file:
  247.  
  248.     MASM name /DEXE_TYPE;
  249.     LINK name, name.bbx;
  250.  
  251.     MASM name,namec /DC_TYPE;
  252.     MASM name,nameb /DBASIC_TYPE;
  253.  
  254.     MASM name,namep /DTURBO_TYPE;
  255.     TPC name
  256.  
  257.  
  258.  
  259.  
  260. ; ------------------------ DISK-BASED BLACKBOXES ------------------------
  261.  
  262. A Disk-Based BlackBox can be written in any assembly language style most
  263. comfortable for the developer.  Since it is basically an executable program,
  264. it is written as a stand-alone program which follows a few basic rules.
  265.  
  266. 1.  Any memory which is allocated by the disk-based blackbox MUST be
  267.     deallocated before exiting the program.
  268.  
  269. 2.  Any File Handles which are opened must be closed before exiting the
  270.     program.
  271.  
  272. 3.  The Disk-Based BlackBox CANNOT leave the screen in text mode before
  273.     exiting, and it should preserve the top two lines of the screen in
  274.     case a menu is present from the calling procedure.
  275.  
  276. 4.  The Interrupt vectors 0F3H and 0F4H cannot be replaced.
  277.  
  278. 5.  The program must exit normally, it cannot terminate and stay resident.
  279.  
  280.  
  281. The procedure for calling a disk-based blackbox is as follows:
  282.  
  283. 1.  The parameters are pushed on the stack as if calling a memory-based
  284.     blackbox.  Note that the last parameter pushed will always be the
  285.     LANGUAGE_TYPE integer value.
  286.  
  287. 2.  The value of the stack pointer and stack segment is stored in the
  288.     graphics device driver using int 0F3H
  289.  
  290. 3.  An EXEC call (DOS CALL 21H, subfunction 4BH) is made to load and
  291.     execute the disk-based blackbox.
  292.  
  293. 4.  Your Disk-Based BlackBox makes a call to int 0F3H to obtain the
  294.     stored pointer to the passed data.
  295.  
  296. 5.  Whatever action required is performed.
  297.  
  298. 6.  Return whatever status values using the pointers passed.
  299.  
  300. 6.  Your Disk-Based BlackBox returns using the DOS CALL 21H, subfunction 4CH
  301.     (the error code is not read by LAYOUT, so a return status of 0 is normal)
  302.  
  303. 7.  The calling program continues execution.
  304.  
  305.  
  306. The call for obtaining the pointer to the passed data is:
  307.  
  308.     AH = 214
  309.     AL = 7
  310.  
  311.     INT 0F3H
  312.  
  313.     RETURNS:  DX = segment
  314.               BX = offset
  315.  
  316.     Example:
  317.  
  318.          mov       ax,214*256 + 7
  319.          int       0F3H                ; get the pointer to the parameters
  320.  
  321.          mov       word ptr parameter_block,bx
  322.          mov       word ptr parameter_block[2],dx
  323.  
  324.  
  325.  
  326.  
  327.