;
                                ARRAYLIB.REL                                  

             Size (recs) CRC    Version   Author/Latest Issue      Disk
MARRYLIB.REL   3k (17)   21AF   1.0       Al Hawley 12/90          Z3UTIL1
SARRYLIB.REL   3k (15)   181B   1.0       Al Hawley 12/90          Z3UTIL1

   1- Overview  2- Assembly  3- Notes  4- Help Files  5- ARRAYS.HLP           

   ARRAYLIB provides a set of routines which can  be included in  a program to
provide for  semi-automatic  maintenance  of  the  bit-map.   The  map  can be
manually prepared in an  intuitive  manner if desired.   The  Map  can also be
configured from Max DU in the program or from the  ZCPR3  Environment Descrip-
tor, from the ZCPR3  Named  Directories segment, or from combinations of them.
Since a bitmap is really an array of bytes the routines are arranged in such a
way that they can be used to manipulate an array of bytes with equal ease.  In
fact, the routines are useful for byte arrays whose rows and columns are up to
255 bytes in extent.  (That would fill a 64K memory bank!)
:1
 Overview - 1/7 

   ARRAYS is  a set of routines which started out  as  a  means of providing a
Disk/User bit-map for controlling directory access by programs like  FINDF and
SDIR.  The routines utilize a bit map of all  possible  drives/user  areas and
permit arbitrary designation of  which  of  the D/U  combinations  are allowed
access by transient programs.  The concept (and routines) is easily extensible
to BIOS functions, and to the manipulation of byte arrays of arbitrary data.

   Many programs use a  Maximum  Drive  and  Maximum  User  number above which
program access is forbidden.  Satisfactory as that scheme has been, it has one
major drawback: if a device like Ramdisk is assigned a drive designation which
is not contiguous,  then you must choose between ignoring that drive or having
programs attempt to access  non-existant  drives!   On one system, I have four
floppies (A: - D:) and a Ramdisk which is assigned as drive M:.  These assign-
ments are a BIOS function;  to  change  them  is no  small  task.   A  bit-map
approach (in each program!)  is  obviously  a  solution,  but could still be a
great deal of trouble  to  maintain  as  assignments  change.  SDIR  uses this
approach for the Drives  that  are  accessible  (but not the User Areas),  and
must be manually  maintained and  reassembled if the logical drive assignments
change.
 Overview - 2/7 

   The ARRAYS routines are fully documented in  the  accompanying  HELP files.
They are intended to be used in the  same  way as  SYSLIB,  VLIB,  Z3LIB,  and
similar relocatable  object  sources.   They  provide a set of general purpose
basic tools that can be used with any program written for ZCPR3.

   The following notes on DU maps may  help  provide  an  overview  to help in
understanding the rationale behind ARRAYS routines..

Structure of the DU map

dumap:
row0:	ds	(maxdu+1)/8	;for drive 1 (A:)
row1:	..	.....		;for drive 2 (B:)
...	..	.....		;  etc.
...	..	.....		;  etc.
row15:	ds	(maxdu+1)/8	;for drive 16 (P:)
 Overview - 3/7 

for maxdu=31 (typical) and  maxdrv = 4,  the  following  array is  defined: (4
physical drives, and system limit is 32 users)  The 1's mark user numbers that
are allowed. Each row represents a drive; if the row contains all 0's then the
corresponding drive is considered not available for access.

dumap:	db	11111111b,11111111b,11111111b,11111111b
	db	11111111b,11111111b,11111111b,11111111b
	db	11111111b,11111111b,11111111b,11111111b
	db	11111111b,11111111b,11111111b,11111111b
	db	00000000b,00000000b,00000000b,00000000b
	..	......... ......... ......... .........
	..	......... ......... ......... .........
row15:	db	00000000b,00000000b,00000000b,00000000b
 Overview - 4/7 

If now the system access were restricted to the following LOGICAL assignments:
	drive A: Users >15 not available
	drive B: Users >10 not available
	drive C: not available for access
	drive D: Users >10 not available
	drive D: Users 2 and 8 not available
here is what the DU map looks like

;user numbers->	7......0  15.....8  23....16  31....24
dumap:
	db	11111111b,11111111b,00000000b,00000000b
	db	11111111b,00000111b,00000000b,00000000b
	db	00000000b,00000000b,00000000b,00000000b
	db	11111011b,00000110b,00000000b,00000000b
	db	00000000b,00000000b,00000000b,00000000b
	..	......... ......... ......... .........
	..	......... ......... ......... .........
	db	00000000b,00000000b,00000000b,00000000b
 Overview - 5/7 

Notes on the DU array:

1.  The maximum array size  (Z-System or  ZCPR3/CPM  operating  systems) is 64
    bytes.  The 64 bytes provide one bit position for each possible drive/user
    combination in a maximum size configuration.

2.  Note that the  assignment of bits to  user  numbers  appears  to be "back-
    wards".   This order is a  result of the  difference in the way assemblers 
    describe bit positions and the way that humans conventionally write a list
    of numbers.   This is an  awkward  situation if you want to generate a D/U 
    map manually.  If the map is generated by a subroutine (from maximum disk/
    user input, for example)  then there is no difficulty except for the usual 
    translation from hex to binary notation (in the 'backward' form!)
 Overview - 6/7 

3)  One of the routines in ARRAYS is designed to make life a little easier for
    manual bitmap generation.  It simply walks through the array reversing the
    order of the bits in each byte.   You can  write the source  code with bit
    assignments as shown below.  Then, before your program attempts to read or
    write data in the bitmap, the ARINVERT routine is called.  Voila!  You AND
    the program can be happy!

user numbers->	0......7  8.....15  16....23  24....31
dumap:	db	00000000b,00000000b,00000000b,00000000b

Using this strategy,  the  bitmap  from  the  example  above could be manually
entered as follows:

dumap:	db	11111111b,11111111b,00000000b,00000000b
	db	11111111b,11100000b,00000000b,00000000b
	db	00000000b,00000000b,00000000b,00000000b
	db	11011111b,01100000b,00000000b,00000000b
	db	00000000b,00000000b,00000000b,00000000b
 Overview - 7/7 

Standard Register usage for DU oriented array:

B	= Drive number. Range 1-16
C	= User Number. Range 0-31
CY flag is used (when set) to indicate an error condition, and when
	an error condition exists, register A returns containing a
	value which identifies the type of error.
:2
 Assembly - 1/2 

   The following alias may be used to  assemble the  ARRAYx.Z80  source  files
with the ZAS or ZMAC assembler.   Be sure that the equate in  ARRHDR.LIB reads
'ZAS EQU TRUE' before attempting the assembly with ZAS.   ZMAC recognizes both
ZAS and M80 syntax;  no  changes need  be made  to  ARRHDR.LIB when using this
assembler.

	ZASMBL.COM
(Change 'ZAS' in this alias to 'ZMAC',  'M80',  or  whatever  you have renamed 
your M80-compatible assembler.)

   The following Alias will create  the  relocatable  object library file from
the Microsoft .REL files produced by assembly using  ZASMBL.COM  or ASMBLS.SUB
(assembly with SLR assemblers).

	MKMLIB.COM

(Change the name of the library manager from ZLIB to ZMLIB, RLIB,
or other ZMLIB compatible manager; change it to the one you use.)
 Assembly - 2/2 

   The following files contain the  command  string  for  use  with the SLRxxx 
Assemblers and Library Manager to create an SLR  format  .REL  object library.
Set 'ZAS EQU FALSE' in ARRHDR.LIB before using either SLR or M80 assemblers.

	ASMBLS.SUB	MKSLIB.SUB

   The following command string file will, with the SLRxxx Assemblers, produce
Microsoft format .REL files which can be collected into a  .REL object library
with ZLIB or other compatible library managers that handle the Microsoft  .REL
format.

	ASMBLM.SUB

   The following files are relocatable  object  libraries  created  using  the
above utilities.

	MARRYLIB.REL - Microsoft format library of array routines
	SARRYLIB.REL - SLR format library of array routines
:3
 ARRAYLIB Notes - 1/2 

   a. Vs 1.0 updates (12/8/90, Al Hawley):
      - Minor changes in documentation to reflect  compatibility with the ZMAC
        and ZMLIB assembler and library manager.

   b. Vs 1.0c updates (03/31/87, Al Hawley):
      - Changed the common data area to DS type definition to maintain compat-
        ibility between the ZAS, SLR, and M80 linkers.
      - Created a new file, ARRHDR.LIB,  whose  function is to define the form
        of the  COMMON statement  used in many of the  ARRAYLIB  modules.   As
        included here,  modules will assemble properly with the ZAS assembler.
        If you use M80 or SLR (perhaps others) assemblers then you must change
        an equate in ARRHDR from ZAS equ TRUE to ZAS equ FALSE.

   c. Vs 1.0b updates (03/08/87, Al Hawley):
      - Renamed the collection from ARRAYFN to the less esoteric ARRAYS
      - Renamed the Help files to generic names, updated internal names.
      - Edited the file ARRAYFN.Z80 into a group of ARRAYx.Z80 files
 ARRAYLIB Notes - 2/2 

      - Assembled the ARRAYx files & built object libraries in Microsoft and 
        SLR formats, so that during linking the amount of unused code included
        in the final .com file is minimized.
      - Included .sub files  (for SLR) and  aliases (for ZAS) used to assemble
        the source files and build the libraries.
:4
                                 ARRAYS.HLP 

             Size (recs) CRC    Version   Author/Latest Issue      Disk
             4k   (26)   81E7   1.0       Al Hawley 12/90          Z3UTIL1
==============================================================================

   ZCPR3 HELP file for the  ARRAYLIB routines.   This file calls the following
HELP files:

                                 ARRAY0.HLP 
                                 ARRAY1.HLP 
                                 ARRAY2.HLP 
                                 ARRAY3.HLP 
:5 :ARRAYS
