                                
                            === THE PROGRAM ===

This documentation file covers LOCATE.COM by Charles Dye, version v1.25c,
dated 09-05-1998.  At present, I can be reached as raster@highfiber.com.

LOCATE.COM is a freeware file locater.  It works similarly to the FL program
included in the Norton Utilities, but may be freely distributed.  LOCATE is
copyright 1995-1998, Charles Dye.  (I'm including the copyright notice to
protect my right to require free distribution.)


                             === THE FILES ===

LOCATE.COM   The program file, of course.

LOCATE.DOC   This documentation file.  Not required for program
             operation; you can safely delete it.

LOCATE.S     Program source code.  If you're not planning to modify
             LOCATE, delete it and save disk space.


                           === THE BASIC IDEA ===

Type LOCATE followed by a filename, and LOCATE will find the file.
For example:

C:\> locate attrib.exe

C:\DOS\
   attrib.exe     Tue  5-31-1994   6:22 am  A....      11,208 bytes    10.95 K

1 item found:  1 file, 0 directories.
   Total of file sizes:  11,208 bytes    10.95 K

The file ATTRIB.EXE is in the C:\DOS directory.  As you can see, LOCATE
provides a count of the number of items found.  It's also possible to search
using wildcards:

C:\> locate disk*.com

C:\DOS\
   diskcopy.com   Tue  5-31-1994   6:22 am  A....      13,335 bytes    13.02 K
   diskcomp.com   Tue  5-31-1994   6:22 am  A....      10,748 bytes    10.50 K

2 items found:  2 files, 0 directories.
   Total of file sizes:  24,083 bytes    23.52 K

The bits following the time stamp indicate the files' attributes:  'A' notes
a file with the 'Archive needed' attribute, 'S' marks a System file, 'H' a
Hidden file, and 'R' a Read-only file.  A 'D' indicates that the item found
is a subDirectory, not a normal file:

C:\> locate windows

C:\
   WINDOWS        Sat  8-24-1996  11:11 am  .D...      <Dir>

1 item found:  0 files, 1 directory.

The line with the file and directory counts may contain an extra notation
to indicate the number of items with the Hidden or System attributes:

C:\> locate tool*

C:\DOS\
   TOOLS          Thu  5-23-1996   2:27 pm  .D.H.      <Dir>

C:\WINDOWS\SYSTEM\
   toolhelp.dll   Sat  8-24-1996  11:11 am  A....      12,112 bytes    11.83 K

2 items found:  1 file, 1 directory (1 H/S).
   Total of file sizes:  12,112 bytes    11.83 K

The (1 H/S) after the directories count means that one of the directories
found has either a Hidden or a System attribute (or both.)  Looking at the
attributes, you can see that the C:\DOS\TOOLS directory is, in fact, Hidden.
This notation is actually more likely to appear in the files count, since
files are hidden much more frequently than directories.

The sizes of large files are not only displayed in bytes, but in terms of
kilobytes or megabytes as well.  A kilobyte is defined as 1,024 bytes; a
megabyte is 1,048,576 bytes.  The fractional part may be off by plus-or-minus
one in the least significant digit.


                            === PROGRAM SYNTAX ===

LOCATE [filespec] [switches]

Type LOCATE, followed by a filespec of the files to find, or switches to
modify the way LOCATE works, or both, or neither.  If you type a filespec
and switches both, you must have at least one space between the filespec and
the first switch.  Some examples:

    LOCATE                      find all files and directories
    LOCATE *.SYS                find everything with the extension .SYS
    LOCATE /H                   find all hidden files and directories
    LOCATE *.SYS /H             find all hidden items with .SYS extension

The /H switch means "find Hidden files or directories."  The default filespec
is *.* , as the first and third examples demonstrate.  In the fourth example,
notice the space between the *.SYS filespec and the first switch, /H.


                            === THE FILESPEC ===

If you do not specify an extension, LOCATE will automatically supply a .*
(like DIR does.)  LOCATE T* is the same as LOCATE T*.*, only easier to type.
If you want to find only files with no extension, end the filename with a
period:  LOCATE T*.

A question mark will match exactly one character.  An asterisk will match
any zero or more characters.  Neither the question mark nor the asterisk is
permitted to match the period separating the filename from its extension.

You can also use Unix-like character classes, enclosed in square brackets.
Use [list] to match any characters in list, or [^list] to match any that are
not in the list.  You can specify ranges as well:  [a-z] would match any
letter, and [^0-9a-z] would match any character which is not a letter or a
digit.

Some examples will make LOCATE's pattern matching clearer:

This:       Would match these:                  But not these:

FOO         FOO, FOO.COM, FOO.DAT, FOO.ZIP      FO, FOOBAR, FOONLY.EXE
FOO.        FOO                                 FOO.COM, FOO.ZIP, FOONLY.EXE
FOO*        FOO, FOO.COM, FOOBAR, FOONLY.EXE    FO, FO1, FOXPRO.EXE, F00
FOO*.       FOO, FOOBAR, FOOTBALL               FOO.COM, FOONLY.EXE, FOOT.DAT
FO?         FOO, FOX, FOO.COM                   FO, FOOT, FOONLY.EXE
FOO.?*      FOO.COM, FOO.1, FOO.DB              FOO
FOO.??      FOO.DB, FOO.EX                      FOO, FOO.COM, FOO.1
*FOO        FOO.COM, SNAFOO.DOC                 FOOTBALL.DAT
*FOO*       FOO.COM, SNAFOO.DOC, DAMNFOOL.BAT   FO.O
*~*         PROGRA~1, STRAWM~1.BMP, ~FILE       FILENAME.~~~
*1?8*       128, FILE168B.DOC                   1228, FILE18B.DOC
S???COM     STARCOM, SPUDCOM                    SITCOM, SYS.COM
F*O         FO, FOO, FIERO, FOXPRO.EXE          FOX.PRO, FOOBAR.BAZ
*.*S*       CONFIG.SYS, LOCATE.S, FOO.RST       S, SYSTEM.CFG, STARCOM.DAT
SP[AI]CE    SPACE.DOC, SPICE.EXE                SPAICE.TXT, SPLICE
SP[^AI]CE   SPOCE.DOC, SP1CE.EXE                SPACE.DOC, SPICE.EXE
*[0-9]*     11TEST, FILE4YOU, FINAL8.SCR        FILEFOR.YOU, FILEFORU.222
*[^0-9]*    FILEFOR.YOU, FILEFORU.222           11TEST, FILE4YOU, FINAL8.SCR

The filename may also contain a drive letter, directory name, or both.
If a drive letter is specified, only that drive will be searched.  If no
drive is specified, LOCATE will decide for itself which drives to search.

Everything preceding the final backslash in the filespec is assumed to be
the name of a directory to search.  If a directory name is specified, LOCATE
will search that directory, plus all subdirectories below it.  If a directory
name is specified, but no drive letter, the directory is assumed to be on the
current drive; only the current drive will be searched.  Wildcards are not
permitted in the directory name.

Some more examples:

    LOCATE C:S*
        looks for files beginning with 'S' on drive C: only

    LOCATE C:\DOS\*.COM
        looks for .COM files in C:\DOS, C:\DOS\DATA, C:\DOS\TOOLS, etc.
        does not search other drives, or C:\OLD_DOS, C:\BIN\DOS, etc.

    LOCATE \DOS\
        lists everything in the \DOS directory or below, on the current drive

    LOCATE \DOS
        looks for items named DOS on the current drive
        (only the part before the \ is considered to be a directory name!)

    LOCATE DOS\
        lists everything in the DOS directory within the current directory
        does NOT look in \DOS directory, unless the current directory is root

    LOCATE .
        lists everything within the current directory or below

    LOCATE ..
        lists everything within the parent of the current directory, or below
        (. and .. are DOS shorthand for 'current' and 'parent directory')

    LOCATE C:\W*\*.EXE
    LOCATE D?\LOCATE.COM
        both illegal!  Wildcards are not permitted in directory names.

Slashes within a filespec will automatically be converted to backslashes for
the convenience of Unix thinkers.  So, C:/DOS/TOOLS/ means the same thing as
C:\DOS\TOOLS\.  This is the reason that you must have a space between the
filespec and the first switch:  both switch characters (minus and slash) are
also legal within the filespec.  The first character of a filespec may not be
a slash:  LOCATE /WINDOWS/ would be interpreted as LOCATE *.* /W.  Use either
LOCATE \WINDOWS\ or LOCATE :/WINDOWS/ instead.

More on drive letters:  beginning with version 1.16, the syntax for drive
letters gets 'looser.'  All of the following are now legal:
   
    LOCATE C: *.FOO           (may separate drive from filespec with a space)
    LOCATE C: D: E: FILE.TXT  (may specify more than one drive)
    LOCATE C:D:E:*FOO*        (multiple drives; looks weird, but it works)
    LOCATE CDE:TESTY.POO      (more than one drive, TARGET-style)
    LOCATE :README            (search only the current drive)

What happens if you don't specify a drive letter?  LOCATE will decide for
itself which drives to search.  The rules are:  (1) if more than one drive
letter refers to the same network drive, only the lowest letter will be
searched.  (2) If drive letters A: and B: both refer to the same floppy
drive, LOCATE will only search it once, and will call it A:.  (3) The search
will start at drive C: and proceed to drive Z:, unless the current DOS
default drive is either A: or B:, in which case the search will run from A:
to Z:.  This last rule is somewhat inelegant, but the best way I have found
to decide whether or not the user is interested in the floppies.


                            === THE SWITCHES ===

/H      Finds only files which have the Hidden or system attributes.  Aside
        from snoop value, this switch can be invaluable before starting an
   XCOPY.  XCOPY doesn't copy hidden or system files.  CHKDSK will tell you
   how many hidden files are on a given drive, but won't tell you what they
   are or how to find them.

   If you use /H, the (n H/S) notation will be suppressed in the final file
   and directory counts, because it would be redundant.

/X      Finds only files with extensions of .COM, .EXE, or .BAT.  May be
        used in conjunction with /T to find out what external commands are
   available at the moment.  /X will only find files, not directories.

   Note that /X does NOT mimic COMMAND.COM's extension order of .COM, .EXE,
   .BAT; instead, LOCATE simply displays files in the order in which it
   finds them.

/D      Finds files and Directories (the normal default behavior)
/D-     Finds files only, not Directories (default behavior with /B /K /X /0)
/D+     Finds Directories only, not files

   LOCATE, by default, finds both files and directories.  (So does Norton FL,
   coincidentally.)  Some people like this behavior, and some people hate it.
   If you're in the second group, it's worthwhile to add a line SET LOCATE=D-
   in your AUTOEXEC.BAT file.

   A few switches change the default behavior to finding files only.  See /B,
   /K, /X, and /0 for details.

/0      Finds only empty (0-byte) files.  Useful for cleanup purposes -- see
        /K, below.  Also, note that the COPY command won't copy empty files.
   This switch implies an automatic /D-.  It will only find empty files, not
   subdirectories, although subdirectories usually have a "size" of zero.

/C...   Check attributes.  Useful if you want to find only files with certain
        attributes set or cleared.  Here are some examples:

      LOCATE C: /CR+      find only Read-only files on drive C:
      LOCATE /CDS+        find only Directories with the System attribute
      LOCATE CD: /CA+     find only files in need of backing up on C: and D:
      LOCATE /CD-H+       find Hidden files, but not Hidden Directories
      LOCATE /CS+H-       find only items which are System but not Hidden

   /CD+ and /CD- function the same as /D+ and /D-.  However, /CH+ is not the
   same as /H.  /CH+ will find only files with the Hidden attribute.  /H will
   find files with either the System or the Hidden attribute, or both.  /CSH+
   will find only files with both the System and the Hidden attributes.

/D:[start][,end]   Check Date stamps.

      LOCATE /D:5-23-1995          Finds only items dated May 23, 1995, or
                                   later.
      LOCATE /D:5-23-1995,7-4-96   Finds only items dated from May 23, 1995
                                   through July 4, 1996.
      LOCATE /D:,7-4               Finds only items dated July 4 of this year
                                   or earlier.
      LOCATE /D:5-31-94,5-31-94    Finds only items dated May 31, 1994.
      LOCATE /D:5-31-94!           Same as above, but easier to type.
      LOCATE /D:T                  Finds only items dated Today (or later!)
      LOCATE /D:T-10               Items dated ten days ago, or later
      LOCATE /D:T-10D              Ten days old, or later; same as above
      LOCATE /D:T-3W,T-1W          Items between one week and three weeks old
      LOCATE /D:T-2Y,T-18M         Items from 18 months to two years old

   Note that /D masks off files or Directories, but /D: checks Dates.  If
   you try to check dates but omit the colon, the parser *might* figure out
   what you mean and handle it correctly.  To be safe, always type the colon
   if you want a date range.

   The exact format in which the date is entered depends on the COUNTRY=
   directive in your CONFIG.SYS file.  In the US, the date is entered as
   MM-DD-YYYY.  In France, it's DD/MM/YYYY; in Canadian-French, YYYY-MM-DD;
   in Finland, DD.MM.YYYY.  To see the current format, type LOCATE /D?
   The year value is flexible:  you can enter it as four digits (1984, 2002),
   as two digits (84, 02), or omit it altogether (in which case the current
   year is assumed.)  While the order is important, I'm not evil enough to
   check the date separator characters; you can use / in the US, - in
   Finland, whatever.  Only minimal validity checking is done on the date:
   February 32 is illegal, but February 31 is considered okay.

/D:dowlist   Mask days of the week.

      LOCATE /D:THURSDAY       Only find items dated from Thursdays
      LOCATE /D:MON,WED,FRI    Only find items dated Monday, Wednesday, or
                               Friday
      LOCATE /D:SUN-TUE        Only find items dated Sunday, Monday, or
                               Tuesday

   This mask is separate from the normal Date range.  You can combine them:

      LOCATE /D:1-1-91,12-31-91  /D:SAT,SUN

   will only find items dated from weekends in 1991.  Sunday and Saturday are
   assumed to be the first and last days of the week, so SAT-SUN is not a
   very useful range.  Only the first two letters are required.  Legal days-
   of-the-week are SUnday, MOnday, TUesday, WEdnesday, THursday, FRiday,
   SAturday, and XX (which matches illegal dates like February 31.)

/T:[start][,end]   Check Time stamps.

      LOCATE /T:5:00,10:00     Finds only items marked 5 A.M. to 10 A.M.
      LOCATE /T:9:00P          Items marked 9 P.M. or later
      LOCATE /T:21.00          Items marked 9 P.M. or later, as above
      LOCATE /T:,8:27:36       Items marked 8:27:36 A.M. or earlier
      LOCATE /T:6:22!          Items marked 6:22 A.M. exactly

   The seconds value is optional; if not specified, seconds will default to
   00 for the start time, 58 for the end time.

   Again, note that /T: checks Times, but /T searches the currect directory
   and the path.  Use the colon to make certain you're checking Times.

/T      Search only current directory and search path.  I provide this switch
        to be somewhat compatible with Norton FL.  LOCATE looks in the
   current directory first, then searches each directory in the search path.
   If the current directory is listed in the search path, it will be searched
   before the rest of the path, but won't be searched twice.  This is
   different from FL's behavior (FL isn't interested in the current
   directory), but similar to the way COMMAND.COM works.  /T goes nicely with
   /X.

/R      Prevents LOCATE from searching Removable drives (floppy, CD-ROM) or
        Remote drives (network or IFS drives.)  Useful if you only want to
   search local hard drives.

/Fn     List only the First n items found.  Again, a Norton-alike switch.
        LOCATE S* /F12 will display the first twelve items it finds which
   begin with S.  If twelve are found, a warning message is displayed (there
   may be more than twelve files; only the first twelve are listed.)  If
   fewer than twelve are found, the warning message is not displayed (you've
   found all there are.)  The maximum value for n is 65,535, which should be
   enough for anybody.

   /Fn may appear in the LOCATE variable, to provide a default 'finds' value.
   If so, you may override it by specifying a different /Fn on the command
   line.  Or, you can add a /F- to the command line to set the 'finds' count
   to 'no limit.'

/G      Go there!  Switch to drive and directory.

   LOCATE ATTRIB /G will present all files and directories named ATTRIB, one
   at a time, and ask if you want to go there.  Type 'Y' to switch to the
   drive and directory containing the file and exit from LOCATE.  Type 'N' to
   continue the search.  (You may also press 'Q' to Quit the search, or 'C'
   to Cease the /G prompt and just display items normally.)

   LOCATE DOOM2 /D+/F1/G (or just LOCATE DOOM2 /D+/G1) will go to the first
   directory named DOOM2 which it finds.  LOCATE DOOM2 /D+/G3 will go to the
   third DOOM2 directory found, assuming there are at least three; otherwise,
   the drive and directory will not be changed.  Here is a short batch file
   to find and switch to a specified directory on your hard drive:

      @ECHO OFF
      LOCATE %1 /D+ /G1 /R >NUL

   Incidentally, 'go there' means something slightly different for files
   versus directories.  If a file was found, LOCATE will go to the directory
   containing the file.  However, if the item found was a directory, LOCATE
   will go to that directory, and not its parent.  This is an inconsistency,
   but one which seems intuitive to me.

/K      Kill (delete) items.

   LOCATE C:*.TMP /K will find all files with an extension of .TMP on your
   C: drive and give you the option to delete each one.  Press 'Y' to delete
   the file displayed.  Press 'N' to let it live.  (You may also press 'Q'
   to Quit the search and exit the program, or 'C' to Cease the /K prompt and
   just display items normally.)  You can use /K together with /Y to delete
   files without a prompt.

   /K implies an automatic /D-, to delete files only.  You can combine /K
   with /D+ to find and remove empty subdirectories, or with /D to delete
   both files and subdirectories.

   /K cannot remove non-empty subdirectories.  If for some strange reason
   you need to locate and remove non-empty subdirectories, you can use
   /B:"DELTREE" to create a batch file, and then call the batch file.  Be
   sure to delete this batch file when you're through with it!

   I do not allow the /K switch in the LOCATE variable.  You may only use /K
   on the command line.

/N      Naked listing.  Prints only fully justified filenames, not file info
        or the final counts of items.  The output from LOCATE /N may be
   redirected to a file, which will then contain a file list suitable for
   manipulation or use by other programs.  Many of the DR/Novell/Caldera DOS
   utilities, for example, can use file lists:

      LOCATE *.TMP /D-/R/N >TEMPFILE.LST         create list of .TMP files
      XDEL @TEMPFILE.LST /P                      delete them, with prompt
      DEL TEMPFILE.LST                           clean up

/S      Summary info only; don't list the actual names.  Use this switch when
        you're only interested in the final counts (not displaying the file-
   names speeds the program up considerably.)  So useful, I'm going to give
   some more examples:
        
      LOCATE C: /H /S        how many hidden files on drive C: ?
      LOCATE C:\DOS\ /S      how many files in C:\DOS or below?
      LOCATE C: /CA+ /S      how many files on C: need to be backed up?
      LOCATE D: /S           how many files on my CD-ROM drive?
      LOCATE F: /S           how many files on my file server?

   In a word, LOCATE /S gives you the same kind of information that CHKDSK
   does, but can be used in places where CHKDSK can't.  For the file server
   example, remember to log in as supervisor first; otherwise, you won't be
   permitted to 'see' all the files.

/W      Wide-Peter display.  Displays filenames five to a line.  This
        switch is provided for compatibility with Norton FL, of course.

/P      These two switches function identically.  They format the display
/A      Peter-style, with file attributes, dates, times and sizes.

   Peter-style output is now the default for LOCATE; /P and /A remain for
   compatibility with older versions of the program.  You can use them to
   override other switches which alter the display.  For instance, if you
   have SET LOCATE=W in your AUTOEXEC.BAT file, you could type
   LOCATE C:FOO /A to see the files displayed with their dates, times and
   sizes.

/I      Index.  Similar to Peter-style display, but you also see the number
        of each found item.

   If you want to use LOCATE /Gn to go the the nth found item, it's useful
   to know in advance what n should be!  Use /I first to browse through a
   large number of possible matches; when you spot the correct item, hit
   ESC to exit, then LOCATE /Gn to go there.  Of course, either or both
   steps could be simplified with a short batch file.  You could also do a
   SET LOCATE=I to make this mode the default.

   The former /I has been kaput for over a year now, so hopefully this won't
   cause compatibility probs for anyone.

/L      Display Windows 95 Long filenames.  This switch will only work
        under Win95.  Not even under MS-DOS 7.x.  If you specify /L when
   Windows 95 is not running, it has no effect.

   This switch only affects the display!  LOCATE still searches for files
   using the old, 8.3 filenames.  If you want to search for a specific long
   filename, I recommend that you type only the first five letters, followed
   by an asterisk:  LOCATE BLUER* /L to find a file named "Blue Rivets.bmp".
   (This file has a short filename of BLUERI~1.BMP, so BLUER* will match it.)
   To find all the short "aliases" which refer to non-8.3 filenames, you can
   use a filespec like *~*

/B:"command"    Automatic Batch file creator!  Lists all files prefixed by
                "command".  Redirect the output from LOCATE into a batch
   file.  Here's an example:

      LOCATE CD:CHKLIST /B:"Del" > C:\KILLSUMS.BAT

   would result in a file C:\KILLSUMS.BAT, which might contain:

      @echo off
      Del C:\CHKLIST.MS
      Del C:\CHKLIST.CPS
      Del C:\DOS\CHKLIST.MS
      Del C:\DOS\CHKLIST.CPS
      Del C:\WINDOWS\CHKLIST.MS

   and so forth.  Running this batch file would delete all MSAV and CPAV
   checksum files from drives C: and D:.  You may also specify a number of
   replaceable arguments for the batch file.  Use LOCATE /Bn:"command", where
   n is 1 to 9.  For instance,
        
      LOCATE C:*.TMP /B3:"ATTRIB" > CHANGEA.BAT

   would produce a file CHANGEA.BAT, with lines like this:

      @echo off
      ATTRIB C:\TEMP\02134.TMP %1 %2 %3
      ATTRIB C:\TEMP\87A540E2.TMP %1 %2 %3
      ATTRIB C:\DOS\TMP\PIPEDATA.TMP %1 %2 %3

   and so on.  /B implies an automatic /D-, to prevent the batch file from
   trying to act upon directories.  If you happen to have a directory named
   D:\SHOPPING\CHKLIST and type LOCATE CD:CHKLIST /B:"DEL", the resulting
   batch file will not contain a line DEL D:\SHOPPING\CHKLIST.  If you want
   the batch file to act on directories as well as on files, or instead of on
   files, you must specify a /D or /D+ on the command line.

/O:"format"     Macro Output.  For each item found, LOCATE will print out the
                string between quotes exactly as typed, except that certain
   macros beginning with an ampersand (&) will be replaced.

   macro  what it displays             example

   &F     fully qualified filename     C:\DOS\DISKCOPY.COM
   &D     directory name, canonical    C:\DOS
   &P     directory name with \        C:\DOS\
   &N     filename                     DISKCOPY.COM
   &R     filename without extension   DISKCOPY
   &X     extension only               COM
   &S     filespec without drive       \DOS\DISKCOPY.COM
   &L     drive letter                 C:
   &G     copy target, no drive        \DOS
   &J     right-padded with spaces     win.com
   &A     attributes, standard         +A -S -H -R
   &B     attribute bits               A....
   &W     Windows 95 long filename     "C:\Directory Name\Long Filename"
   &Z     long filename only, no path  "Long Filename"
   &Y     long directory name with \   "C:\Directory Name\"
   &1     date created                 5-31-1994
   &2     time created                 6:22 am
   &3     file size                    13335
   &4     day of week created          Tue
   &5     nice file size               13,335 bytes
   &6     file size in KB or MB        13.02 K
   &U     show summary info at end

   &T  terminate line    &&  ampersand     &E  escape    &Q  quote mark
   &I  five-space tab    &C  conditional   &H  header    &# or &@  index

   The directory name produced by &D will not end in a backslash unless it's
   the root directory.  The directory name displayed by &P will always end
   with a backslash.  In either case, the name displayed will be the name of
   the parent directory (containing the file or directory which was found.)

   &W provides the long filename for &F.  &Z corresponds to &N, and &Y to &P.
   If these macros are used when Windows 95 is not running, &W is identical
   to &F, &Z is identical to &N, and &Y is identical to &P.

   The date and time produced by &1 and &2 will vary according to the country
   code specified in CONFIG.SYS; you can use /US to force United States
   format if required.  &J displays the filename petercased (lowercase for
   filenames, uppercase for subdirectory names) and right-padded with spaces.

   The index macros &# and &@ display the number of each found item:  1 for
   the first, 2 for the second, etc.  You may follow the macro with a single
   digit 0-9 to force the number to at least n characters:  &# will left-pad
   with spaces, and &@ will left-pad with zeros.  So &#4 might display
   "  12" (without the quotes) where &@4 would show 0012 instead.

   The 'header' macro, &H, allows you to print a header once per directory,
   similar to the Peter-style display.  Anything preceding the &H will be
   printed only once per directory.  This header string may contain other
   macros -- &D, &P and &L are most likely to be useful in a header.  Two
   examples using the header macro; try these to see what they do:

      LOCATE C:*.TXT /O:"&P&H  &J&U"
      LOCATE *.TXT /O:"&L&TCD &D&HTYPE &N&TPAUSE"
   
   The 'conditional' macro, &C, allows you to print one of two different
   strings depending on the value on an attribute bit.  It looks like this:
   &Ca'true-string'false-string'   Both the true-string and the false-string
   must be present, though they may be empty.  You can use most other macros
   inside the true- and false-strings, but &C, &H and &U are not permitted
   (you can't nest &Cs.)  The attribute letter may be any one of A, D, S, H,
   or R.  Try this to see how the conditional macro works:

      LOCATE /O:"&D&H   &J  &CD'-SUBDIR-'&3'"

/Y      Combine with /K to disable prompting -- files will be deleted without
        any warning or chance to intervene.  Useful, but dangerous.  Like /K,
   /Y is not permitted in the environment variable.

/M      Disable test for duplicate network drive Mappings.  Useless.

   Unless /M is specified, LOCATE will eliminate duplicate drive mappings.
   For example, on a Novell Netware network, drives F:, V:, W:, X:, Y:, and
   Z: might all refer to the same drive on the file server.  (V: through Z:
   are 'search drives', used by Novell to keep the search path short.)
   Normally, LOCATE would search only drive F:.  LOCATE /M would search the
   file server six times, taking six times as long to complete, reporting
   each item six times, and slowing down access for other users for six times
   as long.  (Believe it or not, that's exactly what Norton FL does when you
   specify the /A switch!)

/US     Force United States date format.
/UK     Force United Kingdom date format.
/UJ     Force Japanese date format.

   If /US appears before /D: on the command line, the date(s) for /D: must be
   entered in United States format.  If /D: appears before /US on the command
   line, the date(s) for the /D: must be entered in the local date format.
   Likewise /UK and /UJ.

/12     Display time in 12-hour format.
/24     Display time in 24-hour format.

/NP     No pausing.  Default is to pause if output is to the screen.  Not
        a terribly useful switch.

/NR     No recursion.  Searches only the specified directory (or the current
        directory) and not any child subdirectories.

/V      Swaps the effects of the Enter key and the space bar when output is
        paused.  Use according to taste.


With the switches, as with the filespec, I permit the Unix way of life.
LOCATE -T -W works just as well as LOCATE /T /W.  Only the first switch after
the filespec must be preceded by a space:  LOCATE S* /T/W is okay.  You may
type LOCATE S* T,W or even LOCATE S* TRACE,WIDE.  If you don't specify a
filespec, the first switch must be preceded by either a slash or a minus.

A few switches (/D, /F, /G, /L) may use the minus character as a modifier.
A minus immediately following any of these switches will be treated as a
modifier, not a switch character.  So,

    LOCATE -D-W   will display files, but not directories, wide-Peter style.
    LOCATE -D -W  will display both files and directories, wide-Peter style.


                        === ENVIRONMENT SWITCHES ===

It's possible to set up default switches for LOCATE, using an environment
variable named (surprise) LOCATE.  For example, if you vastly prefer the
wide-Peter display, just type SET LOCATE=W (or add it to your AUTOEXEC.BAT
file.)

Most of LOCATE's switches are legal in the LOCATE variable; only /K and /Y
are not permitted.  The rules are a little different, however.  You don't
have to separate the switches with slashes, minuses, spaces, or anything
else, although you can if you really want to.  Also, while a few of LOCATE's
switches may be spelled out on the command line (LOCATE /WIDE), this is
never legal in the variable (SET LOCATE=WIDE is not allowed.)


                 === REDIRECTION, PAGING, AND SCROLLING ===

LOCATE is intended for use both as a command-line tool, and as a batch tool.
Most info is written to the standard-output channel, so LOCATE's display can
be redirected or piped.  The program checks its own output stream, and deals
appropriately with redirection.  LOCATE does not read from the standard input
channel:  you cannot pipe into it.  The keyboard BIOS is used to fetch
keystrokes.  In a few situations, stdout will not be used:  error messages go
to stderr, and /G or /K may force output to the screen.

If LOCATE's output is not redirected, the program will pause every 22 lines
or so (depending on the screen height.)  When output is paused, you can press
the spacebar to scroll another screen's worth, Enter to scroll a single line,
the slash key to scroll a half-screen, Esc to exit, or C to disable paging
and scroll continuously (hit any key to resume paging.)  Hold down the
Control key to slow scrolling, sort of like the Commodore 64.  Use /NP to
disable paging (you can still hit a key to pause.)  Use /V to swap the Enter
key and spacebar.

If LOCATE's output is redirected, it will not be paged.  All the features
described above will be unavailable, and /NP and /V will have no effect.  A
batch file can use LOCATE to create file lists or secondary batch files with
no user intervention.

Robert J. Bull has pointed out that if the Disaster Time switches /K and /Y
are used, automatic paging provides an opportunity to abort before more than
about 20 files get toasted.  So:  /K /Y is Extremely Dangerous, but /K /Y /NP
is Even More Extremely Dangerous.  Likewise /K /Y with output redirection.
Always be extra careful whenever you use /K.


                         === ERRORLEVEL RETURNS ===

0       One or more items found.
1       No matches found.
2       Illegal filespec.
3       User abort -- F3 pressed.
4       Error allocating tree buffer.
5       Invalid operating system (DOS 3.2 or higher required).
6       Tree buffer overflow.  Directory structure too complex.
16      Syntax error.


                            === ON A DIET ===

LOCATE.COM has grown to over 12 kilobytes in size.  I compress the executable
file with DIET v 1.45f.  The 12K program now takes only 9K of disk space.
Cool.  Compression should not affect the program's operation in any way.
However, if you reassemble it, you may be amazed at how the program grows!
No problem; just re-compress if you wish.


                           === DISTRIBUTION ===

LOCATE is free.  You aren't expected to register it or pay for it.  Like
all free things, it comes with no guarantees or warranties.  I will not
be liable for any damages, whether due to bugs in the code or user error
or for any other reason.  And yes, LOCATE can wreak havoc.  For instance,
/B and /O can both create batch files to perpetrate widespread carnage, and
/K can nuke files directly.

You may distribute LOCATE if you like.  An archive file (ZIP, LHA, ARJ, RAR)
is the preferred method, since it retains the file attributes and date-and-
time stamps, and keeps related files together.  If you distribute LOCATE.COM,
please keep this file LOCATE.DOC with it unless space is unusually limited.
You may include the source file or not, as you choose.  The source is big and
ugly, and most users will have no use for it.

You may even distribute modified versions of LOCATE!  Say, you've added a
bug fix or a new feature.  If you wish to distribute an altered LOCATE, I
ask that you:  (1) retain my name and version number on all files, and (2)
add your name, a summary of changes made, and possibly a revision number
to all files.  In particular, please update the syntax display:

    LOCATE.COM   v1.25c   09-05-1998   C. Dye   raster@highfiber.com
    Freeware.  Copyright 1995-1998, Charles Dye.  No warranty!
    File CRC code r1.1 by J. R. Hacker, 02-29-2000

    Syntax:  (and so on, and so forth.)

and also note changes in the source, if you choose to distribute that as
well.

Alternatively, you may instead distribute this program in accordance with the
terms of version 2.0 of the GNU General Public License by the Free Software
Foundation; or, at your option, any later version of the GNU General Public
License.


                          === SUNDRY CREDITS ===

Thanks to Yves Bellefeuille for suggesting Polite Tourist enhancements.

Howard Schwartz pointed out that my wildcards were too tame, and also
pointed out the need for the 'find' counter.

Donald Adaway suggested the /L revamp.  Yes, it was butt-ugly, wasn't it?

Fidonet's Robert J. Bull has made numerous helpful suggestions regarding the
program and documentation.

Donald Adaway and Howard Schwartz both suggested documentation improvements.

William G. Thompson found an obscure incompatibility with batch files.  It's
tough to pass commas or semicolons as arguments to a batch, hence the need
for another delimiter.


                            === WHAT'S NEW ===

v1.25   02-16-1998
        Mass reorganization of /L display -- now it looks more like /P.
        Only SFN, date, attribs and size are shown in addition to the LFN.
/L having been the last of the two-line modes, removed the requirement for
scroll length to be even.  New macro &Y provides long parent-directory
name, corresponding to &P.  Also, LOCATE now uses screen widths of more
than 80 columns for /W and /L.

v1.25a  07-23-1998
        New macros &# and &@ to display the number of the current item.
        May be followed by a single digit to justify to n characters.
&# will left-pad with spaces; &@ will left-pad with zeros.  Otherwise, the
two macros are identical.  New display mode /I is similar to /P but shows
the index number.

v1.25b  08-30-1998
        NUL may end the command line as well as CR.  (Fix for a FreeDOS
        compatibility issue.)

v1.25c  09-05-1998
        Fix for the last fix, which royally screwed the /T path search.


For a complete version history, see the end of the file LOCATE.S.
