;
                                     D.COM                                    

             Size (recs) CRC   Version    Author/Latest Issue      Disk
D15.COM        4k (30)   4AD0  1.6        Gene Pizzetta 12/89      Z3COM4

  1- Syntax/Options  2- Installation  3- Notes  4- Examples of 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.   In
addition, it shows total disk capacity,  the total number of bytes used by the 
displayed files, the number of bytes remaining on the disk,  and the 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.  
Written for CP/M 2.2 and above, it is designed to give most of the information
a user requires, while remaining under 4K in size.

   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 preliminary formfeed to printer
              O    only read-only files
              Q    quiet operation with no display
              P    send to printer
              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 at the REG equate and the source code reassembled.
          (Remember that ZDE uses registers 16 and 17.)
 Explanations of Options - 3/5 

     N    No formfeeds.   If the P option  is specified,  this  option  causes 
          formfeeds to be suppressed.  Without the P option, N has no effect.

     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, ina SUBMIT or 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  with  version 1.2.   Alternate  video,
which is used for some displays, is now determined by the TCAP.  The width and
length of your screen and the page length of your printer  are determined from 
your environment descriptor..

   There are two  assembly-time options that  may  be set  in the source file.
Set DskLbl to True if you'd  rather display CP/M Plus  disk labels, than ZCPR3
directory names.   Set RevVid to True if you  use reverse video for highlight-
ing.
:3
 D Notes - 1/6 

   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.
      - 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 (?).
 D Notes - 2/6 

      - 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/6 
 
     - CP/M 3.0 also supports disk labels,  which are  a directory entry under
       user 32.   If D is assembled with the DSKLBL label  TRUE,  then D looks 
       for a  user 32 entry and,  if it  finds one,  lists it as the disk name 
       just after the user/drive callout.  User 32 is not available to D under
       any other circumstances.    This feature remains  as  an  assembly-time
       option because it is probably  more useful  for users of floppy drivers
       under CP/M Plus  than  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.
 D Notes - 4/6 

   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.

   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 Pizetta 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.  
 D Notes - 5/6 

   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)
:4
 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).