

                            þþþ  THE PROGRAM  þþþ

This documentation file covers LOCATE.COM by Charles Dye, version v1.31,
dated 2003-12-09.  At present, I can be reached as raster@highfiber.com.

Locate is a freeware file finder for DOS.  It works similarly to the FL
program included in the Norton Utilities, but may be freely distributed.
Locate is copyright 1995-2003, Charles Dye.  (I include the copyright
notice to protect my right to require free distribution.)


                             þþþ  THE FILES  þþþ

LOCATE.COM     The program file.  Put it somewhere in your search path.

LOCATE.TXT     This documentation file.  Not required for program operation.

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

FILE_ID.DIZ    Descriptions of the archive's contents.  Not used by the
LOCATE.LSM     program, and may be deleted.

DESCRIPT.ION   4DOS file descriptions.  May be deleted.


                           þþþ  THE BASIC IDEA  þþþ

Type LOCATE followed by a filename, and Locate will search for the file:

  c:\> locate attrib.exe

  C:\DOS\
     attrib.exe     Tue May 31 1994   6:22:00a  A....       11,208    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\
     diskcomp.com   Tue May 31 1994   6:22:00a  A....       10,748    10.50 K
     diskcopy.com   Tue May 31 1994   6:22:00a  A....       13,335    13.02 K

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

The column after the time stamps shows the files' attributes:  'A' indicates
a file with the Archive 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 rather than a file:

  c:\> locate windows

  C:\
     WINDOWS        Fri Nov 21 1997   6:52:04p  .D...       <Dir>

  1 item found:  0 files, 1 directory.

The word "item" refers to either a file or a subdirectory.  The summary line
showing the file and directory counts may contain an extra notation to
indicate the number of items with the Hidden or System attributes:

  c:\> locate fonts

  C:\WINDOWS\
     FONTS          Sat Mar  8 2003   5:07:28p  .DS..       <Dir>

  C:\WINDOWS\INF\
     fonts.inf      Fri Apr 23 1999  10:22:00p  A....       54,859    53.57 K

  C:\PROGRA~1\NETSCAPE\COMMUN~1\PROGRAM\DYNFONTS\
     fonts.cat      Sun Dec  7 2003   9:25:22a  A....          898     0.88 K

  3 items found:  2 files, 1 directory (1 H/S).
     Total of file sizes:  55,757 bytes     54.45 K

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

The sizes of large files are not only displayed in bytes, but in kilobytes or
megabytes as well.  A kilobyte is 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] [options]

Type LOCATE, followed by a filespec of the files to find, or options to
modify the way Locate works, or both, or neither.  If you specify both a
filespec and options, you must type a space between the filespec and the
first option.  Some examples:

    LOCATE                      find all files and directories ("items")
    LOCATE *.SYS                find all items with a .SYS extension
    LOCATE /H                   find all hidden or system items
    LOCATE *.SYS /H             find hidden/system items with .SYS extension

The /H option tells Locate to search for items with either the Hidden or the
System attribute (or both.)  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 option, /H.


                            þþþ  THE FILESPEC  þþþ

If you do not specify an extension, Locate will automatically append .*
(as 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 filespec with a
period:  LOCATE T*.

A question mark will match any one character.  An asterisk will match any
zero or more characters.  (The period separating the base filename from the
extension is not a normal filename character; neither the asterisk nor the
question mark will match it.)

You can also use Unix-like character classes, enclosed in square brackets.
Use [list] to match any character in list, or [^list] to match any that is
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                SPOCE.DOC, SP1CE.EXE
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, FILE4YOU               12345.TXT, 6, 007.DOC

The filespec 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 before the last backslash in the filespec is assumed to be the
name of a directory to search; Locate will search that directory and any
subdirectories it contains.  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:\DOS622, 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 assumed 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 option:  both option 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.

You may specify more than one drive letter.  You may separate the drive
letter(s) from the filespec with spaces, if you like.
   
    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)

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 first 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:.


                    þþþ  OPTIONS (BRIEF DESCRIPTION)  þþþ

What to search for:
/D              both files and subdirectories (the normal default)
/D-             files only, no subdirectories (default with /B /K /X /S: /0)
/D+             subdirectories only, no files
/H              Hidden or system items only
/X              executable files only (.COM .EXE .BAT)
/0              empty (0-byte) files only
/S:[min][,max]  files within a Size range
/D:[min][,max]  items within a range of Dates
/D:dowlist      items from specific Days of the week
/T:[min][,max]  items within a range of Times
/A:[a+][a-]     mask by Attributes

Where to search:
/T       current directory and search path only
/NR      do Not Recurse into subdirectories
/R       local fixed disks only
/M       include duplicate network drive Mappings
/E:var   directories listed in an Environment variable

How to display found items:
/P            Peter-style display, with dates, times, attributes, and sizes
/I            with Index numbers, dates, times, attributes, sizes
/W            Wide display
/N            bare Naked display (file list)
/B:"command"  as a Batch file
/L            using Windows 95 Long filenames
/O:"string"   formatted Output using macros
/S            Summary info only
/US           use United States  date and time format (Tue May 31 1994)
/UK           use United Kingdom date and time format (Tue 31 May 1994)
/UJ           use Japanese (ISO) date and time format (Tue  1994-05-31)
/12           12-hour time format
/24           24-hour time format
/NP           No Paging

What to do with found items:
/G            Go to directory
/K            Kill (delete) found items
/C:"string"   execute Commands, using the same macros as /O
/F:n          stop after First n items

Other options:
/Y    Yes -- don't prompt for /K or /C
/NV   No Video BIOS calls
/V    swap spacebar and Enter key when paging
/NA   no not romanize letters for comparison


                         þþþ  OPTIONS (IN DEPTH)  þþþ

/D      Finds both files and subdirectories (the normal default behavior)
/D-     Files only, not subdirectories (default with /B /K /X /S:range /0)
/D+     Finds subdirectories only, not files

   Locate, by default, finds both files and directories.  A few of the
   options change the default behavior to finding files only.  See /B, /K,
   /X, /S:range, and /0 for details.


/H      Finds only items which have either the Hidden or System attribute
        (or both.)  If you use /H, the (n H/S) notation will be suppressed
   in the final summary as it would be redundant.


/X      Finds only files with extensions of .COM, .EXE, or .BAT.  May be
        used together with /T to find out what external commands are
   available at the moment.  /X will only find files, not directories.
   If Locate is run under 4DOS, .BTM is also considered an executable
   extension.

   Note that /X does NOT mimic COMMAND.COM's extension search order of .COM
   first, then .EXE, and finally .BAT.  Locate always reports files in the
   order in which it discovers them.


/X:list    Finds only files with the specified extensions (separate them
           with commas.)  LOCATE /X:TXT,DOC,ME will find all files ending
   in .TXT, .DOC, or .ME.  Up to ten extensions may be specified.


/0      Finds only empty (0-byte) files.  Useful for cleanup purposes -- see
        /K, below.  Also note that COMMAND.COM's internal COPY command won't
   copy empty files.  This option implies an automatic /D-.  It only finds
   empty files, not subdirectories.  Actually, /0 is just syntactic sugar for
   /S:0! or /S:,0


/S:range    Size range.  The range may contain an optional minimum size,
            optionally followed by a comma and a maximum size.  Or, the range
   may be a single size followed by an exclamation point, to find only one
   specific size -- that is, the minimum and maximum sizes are equal.

      LOCATE /S:500            Find only files of 500 bytes or more.
      LOCATE /S:5K             Only files of 5 kilobytes or more.
      LOCATE /S:,1M            Only files of one megabyte or less
      LOCATE /S:256K,1M        Only files of 256 kilobytes to one meg
      LOCATE /S:4096!          Only files of 4096 bytes exactly

   Note that /S: specifies a Size range, but /S displays only Summary info.
   Use the colon to ensure that the progam does what you expect.  Also note
   that /S: will only find files, not subdirectories.  Subdirectories do not
   have a size per se.


/D:range    Date range.  The range may contain an optional starting date,
            optionally followed by a comma and an ending date.  Or, the
   range may be a single date followed by an exclamation point, to match only
   one specific date -- that is, the starting and ending dates are equal.

      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,T                Finds only items dated Today exactly
      LOCATE /D:T!                 Finds only items dated Today exactly
      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-10              Items dated ten days ago, or earlier
      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
   want 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 date should be entered either in the default local format set by the
   COUNTRY= directive in your CONFIG.SYS file, or else using the ISO standard
   date format YYYY-MM-DD.  If you elect to use the ISO format, you must use
   a four-digit year.  If instead you use the local date format, the year may
   be specified with either two or four digits; 00 through 79 are assumed to
   mean 2000 through 2079, and 80 through 99 are treated as 1980 through
   1999.  Date elements may be separated using hyphens, slashes or periods.
   Only minimal validity checking is done on the date:  February 32 will be
   rejected, but February 31 is accepted as legal.

   It is possible to specify a time for either the starting or ending date.
   Use an @ sign to separate the date and time.  For example, to list only
   files modified between 8:00 AM on December 8, 2003, and 5:00 PM on
   December 12, use:

      LOCATE /D:2003-12-08@8:00,2003-12-12@17:00
   

/D:dowlist    Mask by day-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 day
   names are SUnday, MOnday, TUesday, WEdnesday, THursday, FRiday, SAturday,
   and XX (which matches illegal dates like February 31.)


/T:range    Time range.  The range may contain an optional earliest time,
            optionally followed by a comma and a latest time.  Or, the range
   may be a single time followed by an exclamation point, to find only a
   specific time -- that is, the earliest and latest times are equal.

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

   The seconds value is optional; if not specified, seconds will default to
   00 for the earliest time, 58 for the latest 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.

   The /T: time check is independent of the /D: date check.  If you combine
   /D: and /T:, only items matching both criteria will be listed.  For
   example, the command:

      LOCATE  *.DOC  /D:2003-12-08,2003-12-12  /T:8:00,17:00

   would not list a .DOC file modified at 6:32 PM on the 10th because 6:32 PM
   does not fall between 8:00 AM and 5:00 PM.  To list all .DOC files which
   were modified between 8:00 AM on December 8th and 5:00 PM on the 12th,
   specify the times in the /D: date range:

      LOCATE  *.DOC  /D:2003-12-08@8:00,2003-12-12@17:00


/A:mask    Attributes mask.  Useful if you want to find only items with
           certain attributes set or cleared.  Here are some examples:

      LOCATE C: /A:R+     find only Read-only items on drive C:
      LOCATE /A:DS+       find only Directories with the System attribute
      LOCATE CD: /A:A+    find items with the Archive attribute on C: and D:
      LOCATE /A:D-H+      find Hidden files (but not Directories)
      LOCATE /A:S+H-      find only items which are System but not Hidden

   /A:D+ and /A:D- function the same as /D+ and /D-.  However, /A:H+ is not
   the same as /H.  /A:H+ will find only items with the Hidden attribute.  /H
   will find items with either the System or the Hidden attribute, or both.
   /A:SH+ will find only items with both the System and Hidden attributes.


/T      Search only current directory and search path.  I provide this option
        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 will not be searched twice.  This is
   different from FL's behavior, but similar to the way COMMAND.COM works.
   /T goes nicely with /X.


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


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


/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 share on the file server.  (V: through Z:
   are 'search drives', used to keep the search path short.)  Normally,
   Locate would search only drive F:.  LOCATE /M would search the shared
   drive six times, reporting each found item six times, and taking
   significantly longer to finish.


/E:var    Search subdirectories listed in an environment variable.  Separate
          multiple directories with semicolons, as in PATH.


/P      Peter-style display, with file dates, times, attributes, and sizes.

   Peter-style output is the default for Locate.  You can use /P to override
   other options which alter the display.  For instance, if you have
   SET LOCATE=W in your AUTOEXEC.BAT file, you could type LOCATE C:*.VXD /P
   to see the files displayed with their dates, times and sizes.


/I      Index.  This is a minor variation on the Peter-style display.  It
        shows the index number of each found item, and omits the kilobyte or
   megabyte display of file sizes.

   If you want to use LOCATE /G:n 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 /G:n 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 setting the default.


/W      Wide display.  Displays filenames five to a line.  This option is
        provided for compatibility with Norton FL and the DIR command.


/N      Bare Naked listing.  Prints only fully justified filenames, not file
        info or the final summary.  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 can use file lists; so can recent versions of 4DOS.

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


/B:"command"    Automatic Batch file creator.  Lists all files prefixed by
                a 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 then 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-, so if you happen to have a
   directory named D:\SHOPPING\CHKLIST and type LOCATE CD:CHKLIST /B:"DEL",
   the resulting output will not contain a line DEL D:\SHOPPING\CHKLIST.  If
   you want LOCATE /B to list directories as well as files, or instead of
   files, you must specify /D or /D+ on the command line.


/L      Display Windows 95 Long filenames.  This option will only work under
        an operating system which provides the long-name API.  It will work
   in a DOS box under Windows 95, but not in Win95 DOS mode (MS-DOS 7.x.)
   It will work with DR-DOS only if you have Caldera's long-filename TSR
   installed.

   This option only affects the display!  Locate still searches for files
   using the 8.3 DOS 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 probably 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, try LOCATE *~*


/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           width  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     13   win.com      
   &A     attributes, as for ATTRIB    11   +A -S -H -R
   &B     attribute bits                5   A....
   &W     Windows 95 long filename      -   "C:\Directory\Long Filename.html"
   &Z     long filename only, no path   -   "Long Filename.html"
   &Y     long directory name with \    -   "C:\Directory\"
   &V     long filename base            -   Long Filename
   &K     long filename extension       -   html
   &1     date stamp, local format     11   May 31 1994
   &2     time stamp, local format      9    6:22:00a
   &3     file size                    10   13335
   &4     day of the week               3   Tue
   &5     pretty file size             13   13,335
   &6     file size in KB or MB         9   13.02 K
   &7     date stamp, ISO format       10   1994-05-31
   &8     time stamp, 24-hour format    8   06:22:00
   &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 displayed by &D will not end in a backslash unless it
   is 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, &Y to &P,
   &V to &R, and &K to &X.  If these macros are used when Windows 95 is not
   running, any of the long-filename macros will behave identically to the
   corresponding short-name macro.  Since &V and &K display only part of the
   filename, quotes will not be output; use &Q to show quotes where you wish.

   &J displays the filename petercased (lowercase for filenames, uppercase
   for subdirectories) and right-padded with spaces.  Unlike all the other
   macros, &J will be colorized to indicate subdirectories, hidden items,
   and so on.

   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.  They may contain leading or trailing spaces to make
   them line up neatly.  &7 and &8, on the other hand, are not affected by
   the local country settings and never display leading or trailing 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 pad 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) while &@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'"


/S      Summary info only; don't list the actual names.  Use this option when
        you're only interested in the final counts (not displaying the file-
   names speeds the program up considerably.)
        
      LOCATE C: /H /S        How many Hidden or System items on drive C: ?
      LOCATE C:\DOS\ /S      How many items in C:\DOS or below?
      LOCATE C: /A:A+ /S     How many files on C: need to be backed up?
      LOCATE D: /S           Count the files on my CD-ROM drive.
      LOCATE F: /S           Count the files on a server share.

   In short, 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 may not be
   permitted to 'see' all the files.


/US     Use United States date and time format :  Jul 25 1999   9:32:00p
/UK     Use United Kingdom date and time format:  25 Jul 1999  21:32:00
/UJ     Use Japanese (ISO) date and time format:   1999-07-25  21:32:00

   The /US and /UK formats spell out the month.  This is done to make it easy
   to tell the month from the date.  The /UJ format uses numbers only, which
   is convenient for sorting purposes.

   These options also affect the parsing of dates which follow them on the
   command line.  If /US appears before /D: on the command line, the date(s)
   for /D: must be entered in United States format (or else YYYY-MM-DD.)  If
   /D: comes before /US on the command line, the date(s) for the /D: must be
   entered in the local date format (or YYYY-MM-DD.)  Likewise /UK and /UJ.

   This is as good a place as any to mention a forgotten oddity of DOS:  the
   null date stamp.  It's possible to mark files as having no date.  In the
   /US and /UK formats, this strange stamp will be displayed as a blank,
   which is how the DIR command shows it.  In /UJ mode, however, the null
   stamp will be shown as 1980-00-00.


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


/NP     No paging.  Default is to pause every 24 lines if output is to the
        screen.  Not a terribly useful option.


/G      Go there!  Change 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 change 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+ /F:1 /G (or just LOCATE DOOM2 /D+ /G:1) will go to the
   first directory named DOOM2 which it finds.  LOCATE DOOM2 /D+ /G:3 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 change to a specified directory on your hard drive:

      @echo off
      rem  G.BAT   -- Go to specified directory
      cd .
      locate %1 /d+ /g:1 /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 the directory that was found, not to its parent.  This is
   inconsistent, but 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 deletes files regardless of attributes.  However, if the target file
   is in use by another program then Locate may not be able to delete it.

   /K cannot remove non-empty subdirectories.  If for some strange reason
   you need to locate and remove non-empty subdirectories, you could use
   /C:"DELTREE &F"  However, this is an Extremely Dangerous Idea and probably
   a Very Bad Plan; avoid it if at all possible.

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


/C:"format"    Execute Commands.  This option supports all the same macros as
               /O.  However, instead of simply displaying the output, Locate
   passes each line to the command shell to be executed.  You will be
   prompted first; use /Y to suppress the prompt.

   You can put multiple commands in the string by separating them with the &T
   end-of-line macro.  (You will be prompted for each command.)

   Locate executes each command by starting a copy of the command shell.  It
   uses the environment variable COMSPEC to find the shell.  If COMSPEC is
   not defined, you'll get an error message.  Note that Locate launches a new
   transient *copy* of the shell, which will exit after the command is
   executed.  This fact has subtle implications which you might need to bear
   in mind:  if a batch file is run, any changes it makes to the environment
   will be lost when the child shell exits; a transient copy of 4DOS will
   process any 4START and 4EXIT scripts....

   Locate contains internal code to handle the SET command.  SET is not done
   through the command shell.  It is possible to set environment variables
   this way:  LOCATE C:VBRUN300.DLL /C:"SET VBRUN=&F" /Y /F


/F:n    List only the First n items found.  Again, a Norton FL-like option.
        LOCATE S* /F:12 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 were 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.

   /F:n may appear in the LOCATE variable to provide a default 'finds' limit.
   If so, you may override it by specifying a different /F:n on the command
   line.  Or you can use /F- to disable the limit.


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


/NV     Do Not use the Video BIOS.  Display using DOS only.  This option is
        mainly for debugging purposes, but it's also possible that Locate's
   video calls might be incompatible with some strange system somewhere.
   Redirecting Locate's output automatically disables the video-BIOS use, by
   the way.  You don't need to use /NV for redirection.


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


/NA     Normally, Locate strips off any accent mark from letters before
        comparing them.  The letter E, E-acute, E-circumflex, E-umlaut, and
   so forth are all considered to be the same letter for purposes of filename
   matching.  Use /NA to defeat this behavior.


With the options, as with the filespec, I permit the Unix way of life.
LOCATE -T -X works just as well as LOCATE /T /X.  Only the first option after
the filespec must be preceded by a space:  LOCATE S* /T/X is okay.  If you
don't specify a filespec, the first option must be preceded by either a slash
or a minus.

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

    LOCATE -D-W   will display files, but not directories, in wide format.
    LOCATE -D -W  will display both files and directories, in wide format.

Some of the options use a colon followed by parameters:  /S: /D: /T: /A: /B:
/O: /C: /F:  You may use an equals sign instead of the colon (/S=10K!)

Some of the options use a comma as a range separator:  /S:10,20  You may
instead use a semicolon (/S:10;20) or a tilde (/S:10~20)  It can be difficult
to pass commas and semicolons in arguments to a batch file; if you want to
pass Locate's options via batch arguments, the tilde is a workaround.


                            þþþ  OTHER NOTES  þþþ

Locate is a DOS program.  It was written to work in MS-DOS, in compatible
versions of DOS such as PC DOS and DR DOS, and in DOS-based Windows including
Windows 95 and Windows 98.  In environments which emulate the DOS API, for
instance Windows 2000 and XP, most of Locate's functions should work as
expected, but a few will probably fail.  /G will not be able to change the
current drive and directory; the internal SET handler in /C will not be able
to alter CMD's environment.  There may be other issues of this type.  If you
wish to use Locate in a non-DOS environment, you can probably work around
these problems by using /B or /O to create a subsidiary batch file and
calling it; such an approach will also be compatible with DOS.

If a file or directory does not have any associated DOS-compatible filename,
the traditional DOS FindFirst and FindNext API calls will not report it, and
therefore Locate cannot list it.  Such files might be created, for example,
by a Macintosh user saving files to a Windows NT file server.  Use programs
created for your operating system to find and manipulate such files.
JP Software's shareware command shell 4NT is an excellent Win32 tool and
highly recommended.  Info and download links are at  http://jpsoft.com


                        þþþ  ENVIRONMENT VARIABLE  þþþ

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

Most of Locate's options 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 options with slashes, minuses, spaces, or anything else,
although you can if you really want to.


                 þþþ  REDIRECTION, PAGING, AND SCROLLING  þþþ

Locate is intended both for interactive use at the command line, and as a
batch tool.  Locate's output can usually 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:  the keyboard BIOS is
used to fetch keystrokes, so you cannot pipe into Locate.  Error messages are
sent to stderr, and /G /K and /C may force stdout to the screen.

If Locate's output is not redirected, the program will pause every 24 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.  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.  The the features
described in the previous paragraph 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 options /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 matching items found.
2       Illegal filespec.
3       User abort.  ESC, Control-C, Q, etc.
4       Memory allocation error.  Not enough memory.
5       Invalid operating system (DOS 3.2 or higher required.)
7       Command buffer overflow.
8       No COMSPEC variable.
16      Syntax error.


                          þþþ  DISTRIBUTION  þþþ

Locate is free.  You aren't expected to register it or pay for it.  As with
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; /K or /C:
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.TXT 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.31   2003-12-09   C. Dye   raster@highfiber.com
    Freeware.  Copyright 1995-2003, Charles Dye.  No warranty!
    Recursive DWIM thunking support r1.1 by J. R. Hacker, 2004-04-01

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

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  þþþ

Locate is developed using Eric Isaacson's elegant assembler A86.  Source in,
program out... too simple!  http://eji.com/a86/

I compress the executable using UPX, a freeware executable packer.  The UPX
home page is:   http://upx.sourceforge.net/

Thanks to Yves Bellefeuille for suggesting Polite Tourist enhancements.

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

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 list separator.

Mark Vinten and Dave Cochlin persuaded me to add some new macros, long after
I'd resolved to abandon this Frankenstein's monster forever.

The macros used by /O: and /C: borrow shamelessly from Keith Ledbetter's
file-finder SST (alias Target), which also has /O and /C options with
similar macros.

Much of the basic syntax is borrowed from Norton FL, published by Symantec.
I don't know who wrote it originally; might even have been ol' Peter himself.


                           þþþ  WHAT'S NEW?  þþþ

v1.31   2003-12-09   11,254 bytes                            DE7316B3  9260

Many internal changes to accomodate larger volumes.  The tree buffer is now
dynamically allocated 8K at a time.  File size totals are now 64-bit unsigned
integers.  Tweaks to the internal SET handler to ignore trailing spaces and
to reject variable names beginning with an equals sign.  Changes to /D:  if
the first element in a date is 1980 or greater, the date is assumed to be in
ISO format; also, times may now be specified for the start and/or end of the
date range.  Option /E: from Norton FL is finally implemented.  For /T and
/E:, if a drive letter with no path is listed in the environment variable,
Locate now assumes the current directory on that drive.  Other minor tweaks.


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

