=== THE PROGRAM ===
This documentation file covers LOCATE.COM by Charles Dye, version v1.24a,
dated 02-11-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...
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.
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.
/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"
&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
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. If these
macros are used when Windows 95 is not running, &W is identical to &F,
and &Z is identical to &N.
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 '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.24a 02-11-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-1999
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.
Thanks to Howard Schwartz for pointing out that my wildcards were too tame.
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.
=== WHAT'S NEW ===
Version 1.24 introduces several new features. Unix-like character-class
wildcards allow for more flexible filename testing. /D: now searches by Date
(you can still use the older /U syntax.) The date parser now allows
subtracting a number of days, weeks, months, or years from today's date.
Also, /D: now supports searching by day-of-the-week. New switch /T: to
search by Time stamp. New switches /UK and /UJ to force U.K. and Japanese
date formats. New macro &G prints the canonical directory name, like &D,
only without the drive letter. /Y is no longer permitted in the variable.
Fixes for two reasonably obscure bugs: STDERR is no longer assumed to be the
console -- 4DOS can redirect it, causing /G and /K to (appear to) crash. Now
LOCATE will specifically open the console device if output must go there.
Also, Control-P is now disabled. Pressing it with no printer attached would
generate a critical error, allowing the user to abort the program with the
INT 15 handler still installed.
Version 1.24a makes one very trivial change. The tilde sign is now accepted
as a list separator, along with comma and semicolon. So /D:MON~WED~FRI is
now equivalent to /D:MON,WED,FRI. (Batch files don't like parameters with
commas or semicolons.)
For a complete version history, see the end of the file LOCATE.S.