
        -------------------------------------------------------------
        MDIR.COM   v1.05a  12-30-1999   C. Dye   raster@highfiber.com
         Freeware.  Copyright 1998, 1999, Charles Dye.  No warranty!
        -------------------------------------------------------------

     MDIR is a freeware directory-listing utility.  It is very similar in
     operation to the DIR command in MS-DOS 5 and later.  This command is
     therefore not terribly useful under recent versions of MS-DOS.  It's
     intended for use with DR DOS, FreeDOS, or older versions of MS-DOS.

     This program is free, and comes with no warranty.  USE IT AT YOUR OWN
     RISK.  I will not be responsible for any loss of data or any other
     damages, whether caused by program error, programmer error, user
     error, or act of God.


                                --------------
                                GENERAL SYNTAX
                                --------------

MDIR [filespec] [switches]

Only one filespec is allowed.  If not specified, a default of *.* will be
assumed.  The filespec may name a drive or directory.  The filespec may
contain forward slashes '/' -- they will be converted to backslashes '\'
automatically.  Filespecs may be enclosed in quotes to "trap" spaces.

More than one switch may be used.  They must begin with the DOS switch
character, usually the forward slash '/'.  If conflicting switches are
given, the last one on the command line takes precedence.

MDIR is switchar aware.  Under versions of DOS which allow changing the
switch character, MDIR will use the changed value.  The current switchar
also affects the filespec:  normally the filespec may not begin with a
forward slash, but if switchar is set to something different, a filespec
may begin with a slash.

Legal switches:

/N     Selects the Normal display, with dates, times, sizes, etc.  Use this
       switch to override any /W or /B.  The format of the /N display can be
       customized with the switches /4 /Y /E /Z /12 /24 /F:n /D and /U.

/W     Wide display.  Prints filenames in columns across the screen, left to
       right.  The number of columns depends on the width of the display;
       usually there are five columns.

/B     Bare display.  Use this switch to create file lists.  If /S and /R are
       not specified, /B will display filenames only (without paths.)  If /S
       or /R is used, /B will display filenames including paths.  If /B and
       /W are both used, /B takes precedence.

/V     Verbose display.  Shows dates, times, sizes, space used by files, and
       attributes.  This switch combines /N /4 /Y /E /Z and /U into one.

/S     Search into most subdirectories.  As in the Microsoft command, /S will
       not search into subdirectories with the Hidden or System attributes.

/R     Recurse into all subdirectories, even those with the Hidden or System
       attributes set.  If /S and /R are both used, /R wins.

/A     Find All matching files or directories; ignore attributes.  Normally,
       MDIR will not list items with the Hidden or System bits set.

/A:[r][-x]     Attribute masks.  Both r (required attributes) and x (excluded
               attributes) are optional.  Each may contain one or more of the
       following letters:  A (Archive needed), D (subDirectory), S (System),
       H (Hidden), or R (Read-only).  MDIR will only list items which have
       all bits listed in r set, and all bits listed in x clear.  For example
       /A:DH-S will list only Hidden subDirectories without the System
       attribute.

/O[:flags]     Sort found items into Order.  Flags may contain one or more of
               the following letters:

       N = sort by base filename          E = sort by extension
       G = subdirectories before files    S = sort by size
       D = sort by date and time          P = sort by DR DOS password level
       A = changed files first            R = read-only files first
       H = hidden items first             Y = system items first

       You may precede any letter with a minus sign '-' to reverse its
       effect.  Sorting criteria are applied from left to right.  /O:SN will
       sort all items by size; files with the same exact size will be sorted
       alphabetically by filename.  /O:NS will sort by filename; items with
       the same base name will be sorted by size.

       If /O is used with no flags, a default of /O:GNE will be used.

/P[:n]     Pause after each screenful, or after every n lines.  Use /P:0 to
           disable pausing.

/L[:n]     Letter case mode.  This affects the display of file and directory
           names.  Legal values for n are 0 (uppercase), 1 (lowercase), 2
       (petercase -- filenames in lowercase, directory names uppercase), or
       3 (word case).  If /L is used with no n, the default is 1 (lowercase).
       If no /L is specified, the default is uppercase.

/K:n   Select the method of counting files.
       /K:0 -- count files and directories separately, ignoring  . and ..
       /K:1 -- count files and directories separately, including . and ..
       /K:2 -- count files and subdirectories together

/4     Show four-digit years.  This should become more useful as we cross the
       century mark.  Only affects the normal /N display.

/Y     Show days of the week.  I think this makes dates more meaningful.
       Invalid dates like February 30 will show '---' instead.  Only affects
       the /N display.

/E     Show seconds in file time stamps.  Only affects /N.

/Z     Show file attributes.  Only affects /N.

/12    Display time stamps in 12-hour format.  MDIR defaults to the local
       format set by the COUNTRY= statement in CONFIG.SYS.  Only affects /N.

/24    Display time stamps in 24-hour format.  MDIR defaults to the local
       format set by the COUNTRY= statement in CONFIG.SYS.  Only affects /N.

/F:n   Selects the Format used to display date stamps.  N may be U, E, or J.
       /F:U   United States format, MM-DD-YYYY
       /F:E   European date format, DD-MM-YYYY
       /F:J   Japanese date format, YYYY-MM-DD
       MDIR defaults to the local format set by the COUNTRY= statement in
       CONFIG.SYS.  Only affects the /N display.

/D     Shows the DR DOS password level.  This switch has no effect unless you
       are actually running DR DOS.  The password level will be displayed as
       /P (password required to access directory), /R (password required to
       read/write/delete file), /W (password required to write or delete
       file), /D (password required to delete file), or nothing (no password
       set.)  This switch only affects the /N display.

/U     Shows the amount of disk space Used by each file.  Since DOS allocates
       one or more sectors at a time, this value is usually greater than the
       file size.  This switch only affects the /N display.  /U will also
       report other useful disk-space information like the total size of the
       volume, the percentages of disk space used/free, the percentage of
       total disk space used by the files displayed, and the fraction of
       space wasted by cluster overhang ("slack") for the files listed.

       For non-DOS drives such as network volumes, Stacker drives, CD-ROMs,
       etc. much of this info will probably be wrong!  If MDIR detects that
       the disk is not controlled by DOS it will suppress the /U display.

/X     Do not display . and .. entries.

/?     Displays the main syntax screen.  This screen is sent to standard
/H     output; you can redirect it into a file if you wish.  (Error messages
       caused by program errors will be sent to standard error instead.)
       Several of the more complex switches also have their own mini-syntax
       screens; you can use /A? /O? /P? /L? /K? or /F? to view these.


                         ---------------------------
                         INSTALLATION AND INVOCATION
                         ---------------------------

Copy the program into some directory listed in your path.  It's probably most
convenient to simply put it in your \DOS or \DRDOS directory, so it will be
available after a clean boot (when DOS uses its default path.)

If you like, you can rename MDIR.COM to some other name which is easier to
type and remember.  D.COM or LS.COM are good possibilities.  But if you're
like me, you'll want to intercept the standard DOS DIR command and substitute
MDIR automatically.  How you accomplish this depends on what version of DOS
you're running, and any command-aliasing utilities you are using.


* DR DOS:

Under recent versions of DR DOS (including Novell DOS 7 and all of Caldera's
OpenDOS/DR-DOS releases) you can use DOSKEY to intercept the internal DIR
command.  The command looks like this:

   DOSKEY DIR=MDIR $*

After doing this, any DIR commands you type will be converted by DOSKEY to
MDIR.  (The $* tells DOSKEY to pass any command-line arguments along.)  To
remove the macro and revert to the internal DIR command, type this:

   DOSKEY DIR=

If you want to use the internal DIR command instead of MDIR without removing
the macro, you can begin the command line with a period.  This tells DOSKEY
not to make any substitutions on the current line:

   .DIR *.TXT


* MS-DOS, PC DOS, IBM DOS:

MS-DOS (PC DOS, IBM DOS) versions 5 and later also include a DOSKEY utility.
It works pretty much the same as the DR DOS version for purposes of
intercepting internal commands.  The only significant difference is in the
way you disable substitution for a single line.  Using Microsoft's DOSKEY,
begin a command line with a space (not a period) to prevent the substitution:

   <space>DIR *.TXT


* FreeDOS:

Using the FreeDOS command shell ("FreeCOM") you can intercept internal
commands using ALIAS.  This is even simpler than the DR DOS method:

   ALIAS DIR=MDIR

To remove the alias:

   ALIAS DIR=

Recent versions of the FreeDOS command shell allow you to suppress macro
expansion by beginning the line with an asterisk:

   *DIR *.TXT


* 4DOS:

JP Software's popular command shell 4DOS includes an ALIAS command which can
be used to intercept internal commands.  To replace the 4DOS DIR command with
MDIR, use:

   ALIAS DIR=MDIR

To remove the alias:

   UNALIAS DIR

You can prevent the alias from being expanded on a single line by starting
the line with an asterisk:

   *DIR *.TXT


* Older versions of DOS, the alias method:

MS-DOS prior to version 5, and DR DOS prior to version 7, did not include any
programs to provide command aliases.  However, various third-party command-
line editing utilities are available as shareware or freeware.  Details on
how to intercept internal commands vary from program to program; see the
documentation for details.  You might use:

   :DIR MDIR                 (Anarkey by Steven Calwas)
   CED SYN DIR MDIR          (CED by Christopher J. Dunford)
   PCMKEY DIR MDIR           (PCMKEY by Bouglas Boling, PC Magazine)
   DIR MDIR %* <alt-A>       (Wced by Stuart Russell)


* Older versions of DOS, the Computer Guru method:

If you are using an older version of DOS which doesn't support aliasing, and
you don't want to install any command-line editing utilities, it is still
possible to use MDIR instead of DIR by patching COMMAND.COM and renaming
MDIR.COM to DIR.COM.  If you don't feel comfortable hacking binary files,
then this method is definitely not for you.  I won't give instructions -- if
you don't understand what I'm talking about, you shouldn't be doing it!

I will make two suggestions, though.  First, if you do choose to modify your
COMMAND.COM, change the internal DIR command to some other three-letter
command which is easy to remember; perhaps CAT or D1R.  That way you'll still
be able to list directories if something should happen to MDIR.  Second, be
sure to make backup copies of the shell before patching it.  Keep at least
one copy on a bootable floppy disk, just in case.

Note:  if you patch COMMAND.COM, MDIR will replace DIR in batch files, not
just at the command prompt.


                         ---------------------------
                         SPECIFYING DEFAULT SWITCHES
                         ---------------------------

There are two ways to set default switches for MDIR.  You can put them into
the command used to intercept DIR, or you can use an environment variable.
For example, to make the /O /P and /L:3 switches the default using DOSKEY:

   DOSKEY DIR=MDIR /O /P /L:3 $*

Alternatively, you could do either one of the following:

   SET DIRCMD=/O /P /L:3
   SET MDIRCMD=/O /P /L:3

The DIRCMD variable is processed before MDIRCMD.  Both environment variables
are handled before arguments passed on the command line (or via DOSKEY.)  You
can put default switches for Microsoft's DIR into DIRCMD, and use the MDIR
variable to override them, or for switches which DIR does not support:

   SET DIRCMD=/O /W
   SET MDIRCMD=/-W /L:3

Only switches will be used from the environment variables.  Any filespecs
found in the environment will be ignored.


                  ------------------------------------------
                  DIFFERENCES FROM THE MICROSOFT DIR COMMAND
                  ------------------------------------------

There are many, most of them subtle.  The most obvious difference between the
two is in the counts at the end of the listings:

   C:\TEST>dir

    Volume in drive C is blissful   
    Volume Serial Number is 255E-AF74
    Directory of C:\TEST

   .            <DIR>         12-05-98   8:39p
   ..           <DIR>         12-05-98   8:39p
   A_FILE   TXT           514 11-23-98   8:21p
   ANOTHER  DOC           443 12-05-98   4:48p
   SUBDIR       <DIR>         12-08-98   7:01p
           5 file(s)            957 bytes
                        355,934,208 bytes free

   C:\TEST>mdir

    Volume in drive C is blissful
    Volume Serial Number is 255E-AF74
    Directory of C:\TEST

   .            <DIR>         12-05-98   8:39p
   ..           <DIR>         12-05-98   8:39p
   A_FILE   TXT           514 11-23-98   8:21p
   ANOTHER  DOC           443 12-05-98   4:48p
   SUBDIR       <DIR>         12-08-98   7:01p
           2 file(s)            957 bytes
           1 dir(s)     355,934,208 bytes free

Microsoft lumps files, subdirectories, and the . and .. markers together in a
single "file(s)" count.  MDIR, on the other hand, counts subdirectories and
files separately; . and .. are not counted.  Use /K:n to change the way MDIR
counts items.  /K:1 includes . and .. entries in the subdirectory count, like
the Windows 95 DIR command.   /K:2 lumps files and subdirectories together,
like DIR in earlier versions of DOS.

MDIR respects the switchar.  If you set the switchar to '-' then you can list
all .BAT files in the root directory, in wide format, with a command like
MDIR /*.BAT -W

/P has no effect when standard output is redirected.  You can safely do
MDIR /P > FILELIST.TXT

/W checks the screen width and adjusts its output accordingly.  If your
screen is 132 columns wide, you'll get eight filenames on each screen row,
instead of only five.

Sorting directories requires memory.  A directory containing very many items
may be too large to buffer, forcing DIR or MDIR to display them out of order
(unsorted.)  If this happens, MDIR will display a warning message ("This
directory not sorted!")  Microsoft's will not display any warning message in
this situation.  Also, MDIR usually can buffer and sort more items than DIR
can, depending on free memory.  See the next section for details.

When MDIR is displaying a long listing, you can slow the scrolling by holding
the Control key.  You can also pause a very long listing by pressing the Alt
key; this will cause MDIR to halt and wait for a key, as if you had used /P.

If you have a floppy containing Windows 95 long filenames, try viewing it
with any older version of DOS.  You'll probably see a strange volume label.
MDIR avoids the problem, displaying the actual volume label and not part of
an LFN entry.

You may use the DOS shortcut directory names . (current directory) and ..
(parent directory) on the command line.  MDIR allows more than two dots
in a row; ... is "grandparent" directory, .... is the directory three levels
up, and so on.  If you try to dot-dot-dot up past the root directory, you'll
get an error message.

MDIR will recurse through subdirectories in a different order than DIR.


                               ----------------
                               SORT BUFFER SIZE
                               ----------------

The number of items which can be sorted using the /O switch depends on the
amount of memory available to MDIR.  The program requires about 13 kilobytes
to run (code and stack.)  If the /S or /R switches are used, 64 kilobytes is
allocated as a "tree buffer" to remember subdirectory names.  (If neither /S
nor /R is specified, the tree buffer is not allocated.)  After that, the
largest contiguous block of memory left is allocated for the sort buffer.
One kilobyte of sort buffer is enough to hold 32 items.

Suppose you have 400 kilobytes of conventional memory free, and you type
MDIR /R /O:N.  Thirteen kilobytes are used by the program, and another 64 for
the tree buffer, leaving 323 kilobytes for the sort buffer.  This is enough
to hold 10,336 items.  Any directory containing more than 10,336 files and
subdirectories will not be sorted correctly (a warning message will appear.)
Directories which contain fewer items will be sorted correctly.  If /R were
not used, MDIR would have an additional 64K of sort buffer, enough for 2,048
more items (12,384 total.)


                                  -----------
                                  WHAT'S NEW?
                                  -----------

1.05a: 7,316 bytes   12-30-1999                 CRC32: 3F53CEC2    XDIR: DD64

Changes to /A for compatibility with Microsoft's DIR.  Added /T which is just
a synonym for /Z for compatibility with 4DOS.


1.05:  7,997 bytes   05-30-1999                 CRC32: F8C91E15    XDIR: 3119

Removed all 'expansion' of dots in the volume label, which just caused too
many problems.  Rearranged variables to make the executable smaller.  Renamed
this documentation file to MDIR.TXT.


1.04:  8,037 bytes   04-11-1999                 CRC32: FD0CC243    XDIR: 7E87

New switch /X suppresses the display of fules.  Added four new sort flags (A,
R, H, Y.)  Unknown flags after /O will now trigger the /O help display, not
the general syntax screen.  Also, added a check for the remote possibility of
unbalanced quote marks in either environment variable.


                                   -------
                                   CREDITS
                                   -------

MDIR was created using Eric Isaacson's A86 assembler.

I compress the executable using UPX, a freeware executable packer.  The UPX
home page is:   http://wildsau.idv.uni-linz.ac.at/mfx/upx.html


                              ------------------
                              ERRORLEVEL RETURNS
                              ------------------

         0:  Normal exit:  Everything is beautiful
         1:  Disk error:  Invalid drive, drive not ready, path not found
        16:  General syntax error, or syntax request
        17:  Not enough memory (running on a TRS-80?)
        18:  Bad DOS; version 3.0 or better required
        20:  Internal buffer overflow (filename too long?)
        21:  Error resolving directory name (dots_fix)
        22:  Tree buffer overflow (directory structure too complex)


                                 ------------
                                 DISTRIBUTION
                                 ------------

Free.  You may use this program without registration or payment.  It is,
however, copyrighted and *not* in the public domain.  You may distribute it
freely to others.  You may not charge money for the program, but you may
charge normal fees for media, duplication, connect time, and so forth.  This
software is supplied with no warranty whatsoever.  The author accepts no
liability for anything bad that happens in your life.

A86 source code is available on request.

