;
                                     D.COM                                    

             Size (recs) CRC   Version    Author/Latest Issue      Disk
               4k (32)   BA87  2.1        Gene Pizzetta 11/91      Z3COM4

  1- Syntax/Options  2- Installation  3- Notes  4- History  5- Examples/Use   

   D provides a number of features not  provided by other directory utilities.
The display is in lowercase, which makes it more readable to most people.   It
shows total disk capacity,  total number of bytes used by the displayed files,
number of bytes remaining on disk,  and number of remaining directory entries.
It also shows  SYS,  ARC,  R/O,  and other file attributes, and displays files
from all user areas in a single listing.  It sets the program error flag if no
files are found matching a given file mask,  and will also store the number of
matching files in a  ZCPR  register,  if you  so  desire.   And D will operate
quietly, if you wish, with no screen display.  All in a size under 4k.

   D  was originally written for CP/M 3.0,  but it has  been revamped  to work 
with version 2.2 under ZCPR3.3+.  Original program by Hank Blake (1984).
:1
    Syntax   D {dir:}{{afn}.aft} {{/}<options>}

   If a DU or DIR is omitted,  the current drive and user are assumed.   If  a
filename is omitted then  all files (*.*) is assumed.   If a filetype is given
without a filename,  D wildcards the filename (*.typ).   If no option is given
then all non-system files are displayed.   Under CP/M,  D  works  only  in the
current user area; any user given in the filespec is ignored.

   A filename mask may include slashes,  but if it  begins  with  a slash, the
mask must be preceded by a DIR or DU specification, or simply a colon;  other-
wise D will think it has an option list.

   If no files are found that match the given options or ambiguous filename, D
will set the program error flag.   That will allow to  detect the existence of
particular types of files and  act on their absence or presence  using  the IF
ERROR command.  Other errors also set the error flag, but the values are diff-
erent:
       2 = invalid directory
      10 = no matching files found
      12 = TPA overflow (which shouldn't happen)

   D is re-entrant and may be used with the "GO" command.
   
   The number of columns used for the display varies,  depending on the number
of files,  the options chosen,  and the width of your screen.   Under Z-System
the screen width will adjusted according to your current  environment.   Under
CP/M, 80 columns is always assumed.


    Options   A    archived files only
              B    include both non-system and system files
              C    comprehensive, complete file control block information
              F    suppress file sizes (shows more files on screen)
              L    send to printer
              M    put number of matching files in registers 18 and 19
              N    no screen paging, no formfeeds to printer
              O    read-only files only
              P    no screen paging, no formfeeds to printer
              Q    quiet operation with no display
              R    reset disk system
              S    only system files
              U    include files from all user areas
              W    only read/write files
              X    do not sort
              Z    only non-archived files

   Options must be preceded by a space and slash (/), unless a DU or DIR spec-
ification  and/or  a filename  or  filetype is given.   Several options may be
included without intervening spaces.  If two successive slashes are used, then
a brief usage message is displayed.
 Explanations of Options - 1/5 

   Some options,  particularly those that  regulate the display,  are mutually
exclusive.   If two  or  more  such  options  are  given in  the command line, 
generally the more  comprehensive  options take precedence.   Unknown  options 
are ignored.

     A    Archived files only.   This filters for files  with the  Archive bit 
          set and only those files are displayed.  (The Archive attribute is a
          CP/M 3.0 feature that has also been implemented by ZRDOS,  ZSDOS and 
          other 2.2 replacements).  See also Z option.

     B    Both system and  non-system files included.   This option turns  off 
          the system file filter and displays  all  files  on  the disk,  both
          system and non-system.  System files are highlighted.   This  option
          can be configured as the default.   In that  case,  B  will  exclude
          system files.  See also S option.
 Explanations of Options - 2/5 

     C    Comprehensive  file  information.   Displays the  complete directory
          entries for the selected  files.   The files  are  unsorted  but the
          filters  work  normally (the default is all  non-system files.   All
          file attributes,  including  F1  through  F8,  are shown using high-
          lighting on the corresponding characters of the filename.

     F    File sizes suppressed.   Displays files without  file  size informa-
          tion, resulting in  a  more compact  display,  with  one  additional
          column of filenames.

     L    LST (printer) echo.   Sends the directory to the printer, as well as
          to the screen  (but there is no screen page pause).   Printer output
          works even in quiet mode (see option Q).  Normally the printer list-
          ing is paged (every 4 lines less than your page length), and a final
          formfeed is sent when the  listing  is  completed,  but  see  also P
          option.  In earlier versions, this was the P option.
 Explanations of Options - 3/5 

     M    Put number of matching files in user registers.   As distributed,  D
          uses registers 18 and 19, with the low byte in 18.    Some programs,
          don't work if they have to deal with more than 255  files.   You can
          detect this by checking for a  non-zero  value in register 19.   The
          registers used can be changed with ZCNFG.   In addition, this option
          can be configured as the  default, in  which  case  M  will turn the
          option off.

     O    Read-only  files  only.   This filters for  files  that  have the RO
          attribute set.  Only those files are displayed.  See also W option.

     P    No paging, no formfeeds.   This option turns off screen paging.   If
          the L option is specified, this option also causes printer formfeeds
          to be suppressed.   (Screen paging is  always  turned  off if  the L
          option is given.)   This option can be configured as the default, in
          which case P will turn paging back on.
 Explanations of Options - 4/5 

     Q    Quiet operation.   Suppresses the screen display, useful if your are
          using D for simple file detection with the error flag, or if you are
          using the M option, in a SUBMIT/ZEX batch file.

     R    Reset disk system.  The disk system is reset before the directory is
          read, so that the correct disk space is given under CP/M 2.2 compat-
          ible systems if the  disk is changed.   This option  should  not  be 
          necessary under CP/M Plus or ZSDOS, but it never hurts.

     S    System files only.   This filters  out non-system files and displays 
          only system files.  See also the B option.

     U    All users included.  Displays files from all user areas of a disk in
          a single listing.   This is the only way to get access to other user
          areas under vanilla CP/M.

     W    Read/write files only.  This option displays only files that are not
          read-only.  See also R option.
 Explanations of Options 5/5 

     X    Cancel sort.   The directory files is  not  sorted  in  the display.  
          This is handy to find out the order that the filenames appear in the
          directory.   Some files with multiple directory entries that are not 
          sequential will be listed more than once.

     Z    Non-archived files only.   This filters  for files that  do not have 
          the Archive bit set and allows you to  determine how many files need 
          to be backed up.  See also the A option.
:2
 Installation 

   No installion is required, except for vanilla CP/M operation.   The  number
of screen lines defaults to 24 and the number of printer lines defaults to 66,
so those parameters will have to be  changed using  ZCNFG  if  your  screen or
printer differs.   For Z-System users those values are taken from the environ-
ment descriptor.

   Z-System users with reverse video highlighting should use  ZCNFG  to change
the reverse video configuration parameter to  "Yes".   The  display  will look
much better if you do.

   Several other configuration options are  available:  display of  CP/M  Plus
disk labels instead of named directories,  selection of the registers in which
D saves the matching file count,  and the default for command line options  B,
M, and P.  See the ZCNFG help screens for the details.
:3
 D Notes - 1/3 

   a. DISPLAY FEATURES:   The directory display is fairly obvious,  but  a few 
      items might need clarification.  

      - The default filter excludes system files.
      - Sorting the file entries alphabetically by filename is also a default.
        Files, sorted or unsorted, are displayed in a columnar format.
      - System files are  displayed  in  alternate  video  (dim  or  reverse), 
        whether the B or S option is used,  if alternate video is supported by
        your TCAP.  Alternate video is not available under vanilla CP/M.
      - Following the file size is  either  a k (for kilobytes) or an r (for a 
        read-only file).   The size is  always in kilobytes, regardless of the 
        letter.   If the letters are uppercase (K or R) then the corresponding 
        file has the Archive bit set.
      - The characters  in  the  filename  display  are  reverse-cased.   Most
        filenames will be in lowercase, but a filename in lowercase (it's easy
        to do with MBASIC) is displayed in uppercase.
      - If a directory entry has a non-printable character in it, the 
        character is replaced by a question mark (?).  That can be useful
        because it doesn't mess up your display and you know it's there.
 D Notes - 2/3 

      - If the C option is  used,  any space characters with  an attribute bit
        set  are replaced  with  an  asterisk (*),  so  the  attribute  can be 
        displayed using dim video.

   b. SPECIAL CONSIDERATIONS:  Be cautious when the  disk in question is read-
      only.  Incredibly spurious results can occur, especially under CP/M 3.0.
      For that reason D will display a "Disk is Read Only" message, so you can 
      treat the results with a  grain of salt.   You can also use the R option
      (reset disk system) to eliminate the problem. 

     - If you use CP/M 3.0,  you may have noticed  that  single-letter program 
       names followed by the name of  a file on another disk confuses the CCP.  
       That is, if you type (from the prompt)  A>d b:*.bar  the CCP can't find 
       D and reports an error.   This is a bug in the CCP and there are public 
       domain patches available to  fix it.   If  your  CCP  isn't  patched, I 
       recommend renaming  single-letter  programs  like  D  to something else 
       under CP/M 3.0.   Try something like DD.COM.  Or you can use any single 
       character name above P.
 D Notes 3/3 

     - CP/M 3.0 also supports disk labels,  which are  a directory entry under
       user 32.   D can be configured to look for a user  32  entry and, if it
       finds one,  list it as the disk name just after the user/drive callout.
       User 32 is not available to  D  under any  other  circumstances.   This
       feature is probably more useful for users of floppy drive-based systems
       under CP/M Plus than would be named directories.   If users of CP/M 2.2
       desire such labels on their  disks,  they  must find a way to install a
       directory label entry in user 32.   Any disk utility, such as DU, could
       be used to do this by modifying a null (0K) directory entry to user 32.
       Only experienced  users  should  try  this.   Normally D displays ZCPR3
       named directories instead of disk labels.
:4
 History - 1/6 

   a. Vs 2.1 updates (11/18/91, Gene Pizzetta):
      - False advertising.   Version 2.0 did  NOT  work under  plain  CP/M  as
        stated because of an  elementary  programming  error I spotted shortly
        after release.   You don't push a register and then return from a sub-
        routine.  That's fixed, so hopefully all is well.

   b. Vs 2.0 updates (11/17/91, Gene Pizzetta):
      - Snuffed some long-standing bugs:   D would occasionally show incorrect
        disk free space under 2.2 systems.   Especially when the disk was full
        or nearly full, D calculated one too many allocation blocks were free.
        The comprehensive display  (option C)  did not count  files correctly.
        When the first extent was 1,  they sometimes  weren't counted  at all.
        Large files were sometimes counted more than once because the  S2 byte
        was not being considered.
      - Snuffed some more recent bugs:  D did not properly handle TCAP strings
        that included escape characters.   When printer output was selected, D
        output an extra CRLF to clear the printer buffer,  but also  output it
        to the screen.  Now it goes only to the printer.
 History - 2/6 

      - Should now work under vanilla CP/M  when dropping out of NZCOM, though
        only in the current user area and without highlighting.  
      - Z-System features now look first for an installed  ENV  address and do
        nothing if it's not there.  The Z routines modified were CRT lines and
        width, printer lines, user areas,  standout strings, register storage,
        error flag, and named directories.  
      - Under ZCPR3, D now reports an invalid directory spec, rather than just
        displaying the default directory.  
      - Output can now be sent to the printer in quiet mode.  
      - All console and list  I/O  is now via the  BIOS  for greater speed and
        control.  
      - Option changes:  Former option P is now option L (printer/LST output),
        and former option  N  is now  option  P  (paging toggle),  making them
        similar to other Z utilities.   Options B  (both system and non-system
        files),  M  (store matches to memory  registers),  and  P  (screen and
        printer paging) are now  toggles  and  can  be  configured  to default
        either way.
 History - 3/6 

   c. Vs 1.9 updates (3/25/91, Gene Pizzetta, not released):
      - Added ability to display up to 6  columns  (7 with F option)  on  wide
        screens.

   d. Vs 1.8 updates (3/3/91, Gene Pizzetta):
      - Option N now turns off screen paging, in addition to turning off form-
        feeds if P option is selected.  
      - Also converted source to Zilog mnemonics.
      
   e. Vs 1.7 updates (Gene Pizzetta 9/90)
      - Nobody ever reported it, but I discovered it myself:  the U option was
        not displaying files in users above 15.  It does now.  
      - Added configuration bytes for CP/M Plus disk label usage,  for reverse
        video selection,  and  for register usage  (separate  versions and re-
        assembly no longer required).   These three configuration bytes can be
        changed using ZCNFG.
      - Changed all possible jumps to relative jumps, saving 80 bytes.
 History - 4/6 

   f. Vs 1.6 updates (Gene Pizzetta 12/89)
      - now sets error flag if no matching files are found or if D runs out of
        memory.
      - adds M option to store number of matching files in user registers.
      - adds Q operation to suppress screen output.

   g. Vs 1.5 updates (Gene Pizzetta 10/89)
      - corrected problem with file mask,  DU, and options selection that only
        occurred under BGii.  
      - now needs environment to determine nr of lines on screen, nr of screen
        columns, and nr of lines on printer page.
      - now re-entrant for use with "GO" command.

   h. Vs 1.4 updates (Gene Pizzetta 9/89)
      - horizontal lines in dim video.
      - added equate for reverse video version.
      - revamped command l ine parser:  slash (/) no  longer  required  before
        options,  if option list is second token on the command line; and if a
        filetype is given,  but not a filename,  the filename is automatically
        wildcarded.  
 History - 5/6 

   i. Vs 1.3 updates (Gene Pizzetta 8/89)
      - no longer sends initial formfeed to printer,  but sends formfeed after
        every 62 lines and  a final formfeed after printing directory,  unless
        "N" option is used. 
      - changed "Ext" to "Typ" in display.
      - now prints  ZCPR3 named dir following  du spec,  if  the  DSKLBL label 
        below is set to FALSE, otherwise looks for CP/M Plus disk label.

   j. Vs 1.2 updates (Gene Pizzetta, 7/89)
      - now searches for filenames containing slashes, but not ones begginning
        with a slash unless it is preceded by a DU or DIR spec 
      - added R option to reset disk system
      - renamed old R option to O option.  
      - added TCAP support for dim or reverse video; no installation required

   k. Vs 1.1 updates (Gene Pizzetta, 6/89)
      - added du/dir support for ZCPR3, "//" help screen.
      - option delimiter changed  from "[" to "/".   "G" (specified  user area
        option eliminated)
 History - 6/6 

   l. Vs 1.0 - Hank Blake (84)
     For CP/M 2 and 3.  Source code not released.
:5
 Examples of Use 

   A0>d b: /a       displays all the  archived files from the current user area 
                    (0) on drive B.

   A0>d e4:         displays all non-system files from user 4 on drive E.

   A0>d /so         displays all the  read-only system  files from  the current 
                    user area and drive (A0).

   M0>d edit:foo.*  displays  all non-system  files named  FOO  from  the named
                    directory EDIT.

   A0>d c23:.bar    displays all files, both system and non-system, from user
                    23 on drive C with a filetype of .BAR.

   B1>d :/*.* u     displays all filenames beginning with a slash in all user
                    areas of drive B (the default drive).
