home *** CD-ROM | disk | FTP | other *** search
/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / CPM / ZCPR33 / A-R / MATH24.LBR / MATH24.DZC / MATH24.DOC
Text File  |  2000-06-30  |  9KB  |  272 lines
  1. 24-BIT MATH ROUTINES:
  2.  
  3. I designed these routines to help me complete work on ZPATCH, the Z-system
  4. file patcher.  What was wanted was a way to specify byte addresses within
  5. files.  It would have been possible to use some implementation of LONG
  6. INTEGERS, if I had had access to one, but I didn't, and 24 bits was
  7. sufficient to address every byte in a legal CP/M file.  The largest 
  8. legal CP/M file is 8 megabytes; 24 bits yields 16 megabytes.  They require
  9. the z-80 microprocessor.
  10.  
  11. No claim is made for thoroughness, efficiency, or anything else, although
  12. all appear to work.  Anyone may feel free to tinker with them or improve 
  13. them, although, I feel it only fitting than anyone making any such changes
  14. should at least let me know what he has done, particularly if the interface
  15. to the user is in any way changed.
  16.  
  17. The routines can be divided into two broad categories, subroutines and
  18. macros.  I chose between them when coding only on the basis of what seemed
  19. best at the time.  
  20.  
  21. I apologize in advance for the patchwork quilt quality of this library.
  22. I am only releasing it to provide interested persons with the complete
  23. source code for ZPATCH.
  24.  
  25. This library is released through the good offices of ZSIG,
  26. the Z-system user's group.  
  27.  
  28. I may be reached via electronic mail via Z-SIG's official
  29. remote access system, the Lillipute Z-Node in Chicago, at
  30. 312-649-1730.
  31.  
  32. March 21, 1987
  33. Steven M. Cohen
  34.  
  35. -------------
  36. MACROS:
  37. -------------
  38.  
  39. The following routines are implemented as macros.  This means of course,
  40. that they are expanded to their full length in the object code, rather
  41. than coded once and called.  They are designed to be reminiscent of
  42. the typical 16-bit arithemetic instructions they parallel.
  43.  
  44. In all these macros, the alternate HL,DE,and BC 
  45. registers are affected, the primary registers being protected by 
  46. EXX instructions.  The PSW, both accumulator and flags is also
  47. affected.  No other registers are affected.
  48.  
  49. To use these macros, simply include the library into your source code,
  50. typically with the MACLIB or INCLUDE pseudo-op.
  51.  
  52. -------------------------------------------
  53.  
  54.     M24BQ
  55.  
  56. This macro simply executes a DS    3 instruction, reserving space for
  57. a 24-bit number in memory.  It is a mnemonic name helping code clarity
  58. because it indicates immediately the purpose of the three-byte allocation.
  59.  
  60. -------------------------------------------
  61.  
  62.     MOV24
  63.  
  64. Moves a 24-bit number from one 3-byte buffer (M24BQ) to another.
  65. Their addresses are specified in the operand field of the instruction.
  66.  
  67.     MOV24    DEST,SOURCE moves 3 bytes of data from the addresses
  68. SOURCE..SOURCE+2 to the addresses DEST..DEST+2.  
  69.  
  70. -------------------------------------------
  71.  
  72.     ADD24
  73.  
  74. Adds the 24-bit number whose address is given as the second operand 
  75. to the 24-bit number whose address is given as the first operand
  76. with the result going into the latter.  The carry flag is set if there
  77. is carry after the most significant bytes are added.  The routine is 
  78. thus perfectly analogous to the ADC HL,DE instruction.
  79.  
  80. -------------------------------------------
  81.  
  82.     SUB24
  83.  
  84. Subtracts the 24-bit number whose address is given as the second operand 
  85. from the 24-bit number whose address is given as the first operand
  86. with the result going into the latter.  The carry flag is set if there
  87. is carry after the most significant bytes are subtracted.  The routine is 
  88. thus perfectly analogous to the SBC HL,DE instruction.
  89.  
  90. -------------------------------------------
  91.  
  92.     ADD1624
  93.  
  94. Adds a CONSTANT 16-bit quantity (NOT the contents of a memory location)
  95. whose VALUE is given as the second parameter to a 24-bit quantity whose
  96. ADDRESS is given as the first parameter.  The result goes into the latter.
  97. The carry flag is set if there is carry from the addition into the most 
  98. significant byte.
  99.  
  100.  
  101. -------------------------------------------
  102.  
  103.     SUB1624
  104.  
  105. Subtracts a CONSTANT 16-bit quantity (NOT the contents of a memory location)
  106. whose VALUE is given as the second parameter from a 24-bit quantity whose
  107. ADDRESS is given as the first parameter.  The result goes into the latter.
  108. The carry flag is set if there is carry from the subtraction into the most 
  109. significant byte.
  110.  
  111.  
  112. -------------------------------------------
  113.      
  114.     INC24 and DEC24
  115.  
  116. Simply increment and decrement the 24-bit quantity whose address is given 
  117. as the only parameter.
  118.  
  119. +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  120.  
  121. ----------------
  122. SUBROUTINES
  123. ----------------
  124.  
  125. The following are implemented as callable subroutines located in the
  126. library M24.REL.  Source code for the various modules contained is in this
  127. library M24.LBR.  Some of these routines use the macros contained in 
  128. MATH24.LIB.
  129.  
  130. -------------------------------------------
  131.  
  132.     DOUBLE24 and HALVE24
  133.  
  134. Routines that as their name implies, double and halve 24 bit quantities.
  135. The address is specified in HL.  The output value is stored in the same
  136. 3-byte buffer as the input value.  No registers are effected and there are
  137. no side effects to these routines.
  138.  
  139. -------------------------------------------
  140.  
  141.     ZEROBUF
  142.  
  143. Initializes a 3-byte buffer (24-bit number) to zero.  On input HL points
  144. to the address of this buffer.  No registers are affected and there are
  145. no side effects.
  146.  
  147. -------------------------------------------
  148.  
  149.     RADIX
  150.  
  151. Sets or returns the default radix which all the following input routines 
  152. expect.  The value is stored internally within this module.
  153.  
  154. On input the value of the desired default radix is in the return address.
  155. Legal values are 2,10, or 16 for binary, decimal, or hexadecimal radices.
  156. If the value in the return address is 0, RADIX interprets this as a request
  157. for the value of the current default radix, which is returned in A.
  158. If the value in the return address an error results which is detected by
  159. the carry flag being set.  With a properly designed call this should never
  160. happen.
  161.  
  162. Example:
  163.  
  164.     CALL    RADIX        ;change the default radix 
  165.     DB    2        ;to binary
  166.  
  167.     CALL    RADIX        ;a request for the default radix
  168.     DB    0        ;which is returned in A
  169.     CP    16        ;test for hexadecimal
  170.  
  171. The usefulness of this routine will be more apparent with the following.
  172.  
  173. -------------------------------------------
  174.  
  175.     RADIXDSP
  176.  
  177. This routine simply calls RADIX and based on the result prints the strings
  178. (BIN),(DEC),or (HEX) on the screen (usually after a prompt) to give further
  179. information to the user as to which radix the program is expecting.
  180. Registers affected: PSW.
  181.  
  182. -------------------------------------------
  183.  
  184.     INPNUM
  185.  
  186. Performs the following function:
  187.  
  188. Prints a ": " on the screen (this routine is designed to be called just
  189. after a prompt is printed on the screen asking for numeric input).  Then
  190. calls a line inputter (SYSLIB's BLINE) to read in the input.  Then the
  191. string is evaluated and the result placed in a 3-byte buffer whose address
  192. is given in DE.  If the evaluator detects an error, the beeper is sounded.
  193.  
  194. Input is evaluated in accordance with the rules specified under EVAL24
  195. below.
  196.  
  197. Inputs:
  198.     DE - address of 3-byte buffer
  199.  
  200. Outputs:
  201.     DE - address of 3 byte buffer, now containing the 24-bit equivalent
  202.     of the input value.
  203.  
  204. Registers affected: PSW,HL
  205.  
  206. -------------------------------------------
  207.  
  208.     NUMINP
  209.  
  210. Exactly the same as INPNUM except that it calls RADIXDSP first so that
  211. the radix indicator string is printed before the ": " giving a fuller
  212. prompt.
  213.  
  214. Example:
  215.     CALL    RADIX
  216.     DB    10        ; we're expecting decimal
  217.     CALL    PRINT        ; print prompt
  218.     DB    "Number of miles",0
  219.                 ; note no colon in string, NUMINP takes care
  220.                 ; of that
  221.     LD    DE,MILEAGE    ; address where number will reside
  222.     CALL    NUMINP
  223. ;
  224. ;
  225. ;
  226. MILEAGE:    
  227.     M24BQ            ; a 24 bit number buffer
  228. ;
  229. -------------------------------------------
  230.  
  231.     N24EVAL
  232.  
  233. This routine evaluates a string, and deposits a 24-bit value into 
  234. a 24-bit buffer corresponding to the string.  The string can be 
  235. binary, decimal, or hexadecimal.  It is expected to be 
  236. null-terminated.  It is expected to use the currently selected 
  237. default radix (see RADIX), or if not in the currently selected 
  238. default radix, it should be followed by a radix indicator as follows:
  239.  
  240.     radix      radix indicator char
  241.       2                 %
  242.      10                 #
  243.      16                 H
  244.  
  245. for example 256#=100000000%=100H.
  246.  
  247.  On input, DE points to a 3-byte buffer into which the number will be stored
  248.  HL points to a NULL-TERMINATED string of ASCII binary, 
  249.  decimal, or hexadecimal characters to convert to binary; this string may 
  250.  take any of the following forms --
  251.  
  252.     bbbbbbbbbbbbbbbbbbbbbbbb
  253.     OR bbbbbbbbbbbbbbbbbbbbbbbb%-- b=0 or b=1; binary string
  254.     ttttttttt or ttttttttt# -- 0<= t <= 9; decimal string
  255.     hhhhhh or hhhhhhH -- 0<= h <= F; hexadecimal string
  256.     
  257.  
  258.     On return, DE points to value (3-byte buffer), 
  259.            HL points to next byte after string, 
  260.            A lowest order byte  of three-byte buffer 
  261.            BC is not affected.
  262.     On return, CARRY Set means error, and HL pts to byte after error
  263.  
  264. -------------------------------------------
  265.  
  266.     EVALB24, EVALD24, EVALH24
  267.  
  268. These are the binary, decimal, and hexadecimal evaluation routines that are
  269. called by N24EVAL.  They are also callable individually in a case where only
  270. one radix is allowable, for example.  Input and output parameters are the same 
  271. as for N24EVAL.vidually in a case where only
  272.