home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / jsage / znode3 / uploads / z3help43.lbr / ARRAYLIB.HZP / ARRAYLIB.HLP
Encoding:
Text File  |  1991-11-18  |  10.1 KB  |  222 lines
  1. ;
  2.                                 ARRAYLIB.REL                                  
  3.  
  4.              Size (recs) CRC    Version   Author/Latest Issue      Disk
  5. MARRYLIB.REL   3k (17)   21AF   1.0       Al Hawley 12/90          Z3UTIL1
  6. SARRYLIB.REL   3k (15)   181B   1.0       Al Hawley 12/90          Z3UTIL1
  7.  
  8.    1- Overview  2- Assembly  3- Notes  4- Help Files                          
  9.  
  10.    ARRAYLIB provides a set of routines which can  be included in  a program to
  11. provide for  semi-automatic  maintenance  of  the  bit-map.   The  map  can be
  12. manually prepared in an  intuitive  manner if desired.   The  Map  can also be
  13. configured from Max DU in the program or from the  ZCPR3  Environment Descrip-
  14. tor, from the ZCPR3  Named  Directories segment, or from combinations of them.
  15. Since a bitmap is really an array of bytes the routines are arranged in such a
  16. way that they can be used to manipulate an array of bytes with equal ease.  In
  17. fact, the routines are useful for byte arrays whose rows and columns are up to
  18. 255 bytes in extent.  (That would fill a 64K memory bank!)
  19. :1
  20.  Overview - 1/7 
  21.  
  22.    ARRAYS is  a set of routines which started out  as  a  means of providing a
  23. Disk/User bit-map for controlling directory access by programs like  FINDF and
  24. SDIR.  The routines utilize a bit map of all  possible  drives/user  areas and
  25. permit arbitrary designation of  which  of  the D/U  combinations  are allowed
  26. access by transient programs.  The concept (and routines) is easily extensible
  27. to BIOS functions, and to the manipulation of byte arrays of arbitrary data.
  28.  
  29.    Many programs use a  Maximum  Drive  and  Maximum  User  number above which
  30. program access is forbidden.  Satisfactory as that scheme has been, it has one
  31. major drawback: if a device like Ramdisk is assigned a drive designation which
  32. is not contiguous,  then you must choose between ignoring that drive or having
  33. programs attempt to access  non-existant  drives!   On one system, I have four
  34. floppies (A: - D:) and a Ramdisk which is assigned as drive M:.  These assign-
  35. ments are a BIOS function;  to  change  them  is no  small  task.   A  bit-map
  36. approach (in each program!)  is  obviously  a  solution,  but could still be a
  37. great deal of trouble  to  maintain  as  assignments  change.  SDIR  uses this
  38. approach for the Drives  that  are  accessible  (but not the User Areas),  and
  39. must be manually  maintained and  reassembled if the logical drive assignments
  40. change.
  41.  Overview - 2/7 
  42.  
  43.    The ARRAYS routines are fully documented in  the  accompanying  HELP files.
  44. They are intended to be used in the  same  way as  SYSLIB,  VLIB,  Z3LIB,  and
  45. similar relocatable  object  sources.   They  provide a set of general purpose
  46. basic tools that can be used with any program written for ZCPR3.
  47.  
  48.    The following notes on DU maps may  help  provide  an  overview  to help in
  49. understanding the rationale behind ARRAYS routines..
  50.  
  51. Structure of the DU map
  52.  
  53. dumap:
  54. row0:    ds    (maxdu+1)/8    ;for drive 1 (A:)
  55. row1:    ..    .....        ;for drive 2 (B:)
  56. ...    ..    .....        ;  etc.
  57. ...    ..    .....        ;  etc.
  58. row15:    ds    (maxdu+1)/8    ;for drive 16 (P:)
  59.  Overview - 3/7 
  60.  
  61. for maxdu=31 (typical) and  maxdrv = 4,  the  following  array is  defined: (4
  62. physical drives, and system limit is 32 users)  The 1's mark user numbers that
  63. are allowed. Each row represents a drive; if the row contains all 0's then the
  64. corresponding drive is considered not available for access.
  65.  
  66. dumap:    db    11111111b,11111111b,11111111b,11111111b
  67.     db    11111111b,11111111b,11111111b,11111111b
  68.     db    11111111b,11111111b,11111111b,11111111b
  69.     db    11111111b,11111111b,11111111b,11111111b
  70.     db    00000000b,00000000b,00000000b,00000000b
  71.     ..    ......... ......... ......... .........
  72.     ..    ......... ......... ......... .........
  73. row15:    db    00000000b,00000000b,00000000b,00000000b
  74.  Overview - 4/7 
  75.  
  76. If now the system access were restricted to the following LOGICAL assignments:
  77.     drive A: Users >15 not available
  78.     drive B: Users >10 not available
  79.     drive C: not available for access
  80.     drive D: Users >10 not available
  81.     drive D: Users 2 and 8 not available
  82. here is what the DU map looks like
  83.  
  84. ;user numbers->    7......0  15.....8  23....16  31....24
  85. dumap:
  86.     db    11111111b,11111111b,00000000b,00000000b
  87.     db    11111111b,00000111b,00000000b,00000000b
  88.     db    00000000b,00000000b,00000000b,00000000b
  89.     db    11111011b,00000110b,00000000b,00000000b
  90.     db    00000000b,00000000b,00000000b,00000000b
  91.     ..    ......... ......... ......... .........
  92.     ..    ......... ......... ......... .........
  93.     db    00000000b,00000000b,00000000b,00000000b
  94.  Overview - 5/7 
  95.  
  96. Notes on the DU array:
  97.  
  98. 1.  The maximum array size  (Z-System or  ZCPR3/CPM  operating  systems) is 64
  99.     bytes.  The 64 bytes provide one bit position for each possible drive/user
  100.     combination in a maximum size configuration.
  101.  
  102. 2.  Note that the  assignment of bits to  user  numbers  appears  to be "back-
  103.     wards".   This order is a  result of the  difference in the way assemblers 
  104.     describe bit positions and the way that humans conventionally write a list
  105.     of numbers.   This is an  awkward  situation if you want to generate a D/U 
  106.     map manually.  If the map is generated by a subroutine (from maximum disk/
  107.     user input, for example)  then there is no difficulty except for the usual 
  108.     translation from hex to binary notation (in the 'backward' form!)
  109.  Overview - 6/7 
  110.  
  111. 3)  One of the routines in ARRAYS is designed to make life a little easier for
  112.     manual bitmap generation.  It simply walks through the array reversing the
  113.     order of the bits in each byte.   You can  write the source  code with bit
  114.     assignments as shown below.  Then, before your program attempts to read or
  115.     write data in the bitmap, the ARINVERT routine is called.  Voila!  You AND
  116.     the program can be happy!
  117.  
  118. user numbers->    0......7  8.....15  16....23  24....31
  119. dumap:    db    00000000b,00000000b,00000000b,00000000b
  120.  
  121. Using this strategy,  the  bitmap  from  the  example  above could be manually
  122. entered as follows:
  123.  
  124. dumap:    db    11111111b,11111111b,00000000b,00000000b
  125.     db    11111111b,11100000b,00000000b,00000000b
  126.     db    00000000b,00000000b,00000000b,00000000b
  127.     db    11011111b,01100000b,00000000b,00000000b
  128.     db    00000000b,00000000b,00000000b,00000000b
  129.  Overview - 7/7 
  130.  
  131. Standard Register usage for DU oriented array:
  132.  
  133. B    = Drive number. Range 1-16
  134. C    = User Number. Range 0-31
  135. CY flag is used (when set) to indicate an error condition, and when
  136.     an error condition exists, register A returns containing a
  137.     value which identifies the type of error.
  138. :2
  139.  Assembly - 1/2 
  140.  
  141.    The following alias may be used to  assemble the  ARRAYx.Z80  source  files
  142. with the ZAS or ZMAC assembler.   Be sure that the equate in  ARRHDR.LIB reads
  143. 'ZAS EQU TRUE' before attempting the assembly with ZAS.   ZMAC recognizes both
  144. ZAS and M80 syntax;  no  changes need  be made  to  ARRHDR.LIB when using this
  145. assembler.
  146.  
  147.     ZASMBL.COM
  148. (Change 'ZAS' in this alias to 'ZMAC',  'M80',  or  whatever  you have renamed 
  149. your M80-compatible assembler.)
  150.  
  151.    The following Alias will create  the  relocatable  object library file from
  152. the Microsoft .REL files produced by assembly using  ZASMBL.COM  or ASMBLS.SUB
  153. (assembly with SLR assemblers).
  154.  
  155.     MKMLIB.COM
  156.  
  157. (Change the name of the library manager from ZLIB to ZMLIB, RLIB,
  158. or other ZMLIB compatible manager; change it to the one you use.)
  159.  Assembly - 2/2 
  160.  
  161.    The following files contain the  command  string  for  use  with the SLRxxx 
  162. Assemblers and Library Manager to create an SLR  format  .REL  object library.
  163. Set 'ZAS EQU FALSE' in ARRHDR.LIB before using either SLR or M80 assemblers.
  164.  
  165.     ASMBLS.SUB    MKSLIB.SUB
  166.  
  167.    The following command string file will, with the SLRxxx Assemblers, produce
  168. Microsoft format .REL files which can be collected into a  .REL object library
  169. with ZLIB or other compatible library managers that handle the Microsoft  .REL
  170. format.
  171.  
  172.     ASMBLM.SUB
  173.  
  174.    The following files are relocatable  object  libraries  created  using  the
  175. above utilities.
  176.  
  177.     MARRYLIB.REL - Microsoft format library of array routines
  178.     SARRYLIB.REL - SLR format library of array routines
  179. :3
  180.  ARRAYLIB Notes - 1/2 
  181.  
  182.    a. Vs 1.0 updates (12/8/90, Al Hawley):
  183.       - Minor changes in documentation to reflect  compatibility with the ZMAC
  184.         and ZMLIB assembler and library manager.
  185.  
  186.    b. Vs 1.0c updates (03/31/87, Al Hawley):
  187.       - Changed the common data area to DS type definition to maintain compat-
  188.         ibility between the ZAS, SLR, and M80 linkers.
  189.       - Created a new file, ARRHDR.LIB,  whose  function is to define the form
  190.         of the  COMMON statement  used in many of the  ARRAYLIB  modules.   As
  191.         included here,  modules will assemble properly with the ZAS assembler.
  192.         If you use M80 or SLR (perhaps others) assemblers then you must change
  193.         an equate in ARRHDR from ZAS equ TRUE to ZAS equ FALSE.
  194.  
  195.    c. Vs 1.0b updates (03/08/87, Al Hawley):
  196.       - Renamed the collection from ARRAYFN to the less esoteric ARRAYS
  197.       - Renamed the Help files to generic names, updated internal names.
  198.       - Edited the file ARRAYFN.Z80 into a group of ARRAYx.Z80 files
  199.  ARRAYLIB Notes - 2/2 
  200.  
  201.       - Assembled the ARRAYx files & built object libraries in Microsoft and 
  202.         SLR formats, so that during linking the amount of unused code included
  203.         in the final .com file is minimized.
  204.       - Included .sub files  (for SLR) and  aliases (for ZAS) used to assemble
  205.         the source files and build the libraries.
  206. :4
  207.                                  ARRAYS.HLP 
  208.  
  209.              Size (recs) CRC    Version   Author/Latest Issue      Disk
  210.              4k   (26)   81E7   1.0       Al Hawley 12/90          Z3UTIL1
  211. ==============================================================================
  212.  
  213.    ZCPR3 HELP file for the  ARRAYLIB routines.   This file calls the following
  214. detailed HELP files:  
  215.  
  216.                                  ARRAY0.HLP 
  217.                                  ARRAY1.HLP 
  218.                                  ARRAY2.HLP 
  219.                                  ARRAY3.HLP 
  220.  
  221. These files are available from the "Y" (Libraries) menu.
  222.