;
                                     D.COM                                    

             Size (recs) CRC   Version    Author/Latest Issue      Disk
               4k (30)   D10B  1.8        Gene Pizzetta 3/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.   If no option is given then all 
non-system files are displayed.

   Options must be  preceded by  a  space and  slash (/),  unless  a DU or DIR 
specification and/or  a filename or filetype is given.  Several options may be
included without intervening spaces.  A filename mask may include slashes, but
if it  begins with  a slash,  then the  mask must  be preceded by  a DIR or DU 
specification, or simply a colon.

   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.

   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. 


    Options   A    archived files only
              B    include both non-system and system files
              C    comprehensive, complete file control block information
              F    suppress file sizes
              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    send 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

   All options are specified  after  a space  and slash.   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,  whether 
          they are  system  or  non-system.   System  files  are  highlighted, 
          however.  See also S option.
 Explanations of Options - 2/5 

     C    Comprehensive  file  information.   Displays the  complete directory 
          entry 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.

     M    Put number of matching files in user registers  18 and 19.   The low
          byte is put in 18.   Some programs, for instance, 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.  (Remember that ZDE uses registers 16 and
          17.)
 Explanations of Options - 3/5 

     N    No paging, formfeeds.  This option turns off screen paging.  If the
          P option is specified,  this  option  also  causes  formfeeds to be
          suppressed.  (Screen paging is always turned off if the P option is
          given.)

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

     P    Printer echo.  Sends the directory to the printer, as well as to the
          screen (but there is  no page pause if the screen fills).   Normally 
          the printer listing is  paged (every 4  lines  less  than  your page 
          length) and a  final formfeed is sent when the listing is completed, 
          but see also the N option.

     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.   As a  side effect,
          printer output is also suppressed.
 Explanations of Options - 4/5 

     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.

     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.  

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

     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.
 Explanations of Options - 5/5 

     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 

   Installation is no longer required.   The alternate video string is determ-
ined from your TCAP.   The width and length of your screen and the page length 
of your printer are determined from your environment descriptor.

   Three configuration options are provided, however, that may be changed with
ZCNFG.   One option allows display of CP/M Plus  disk labels  instead of named
directories.  Another option makes the screen display look better on terminals
that use reverse video highlighting.   Lastly,  the registers in which D saves
the matching file count can be changed from the default.
:3
 D Notes - 1/4 

   a. D vs 1.7 as distributed is designed to use  dim video highlighting.   If
      your TCAP uses reverse video  highlighting  the  display  will  not look
      right until you use ZCNFG and answer yes  to the  reverse  video option.
      If you use  CP/M Plus and you  would like D to look for and display CP/M
      Plus disk labels, instead of ZCPR3 named directories, then answer yes to
      the disk label option.  Because of these configuration options, distrib-
      uting four separate versions of D is no longer necessary.
 
   b. 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.
 D Notes - 2/4 

      - 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 (?).
      - 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.
 D Notes - 3/4 

   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 4/4 

     - 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.   The  regular version of D
       displays ZCPR3 named directories instead of disk labels.
:4
 History - 1/4 

   a. 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.
      
   b. 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.

   c. 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.
 History - 2/4 

   d. 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.

   e. 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 - 3/4 

   f. 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.

   g. 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

   h. 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 - 4/4 

   i. 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).
