þþþ THE PROGRAM þþþ This documentation file covers LOCATE.COM by Charles Dye, version v1.29b, dated 10-31-2001. At present, I can be reached as raster@highfiber.com. LOCATE.COM is a freeware file finder. It works similarly to the FL program included in the Norton Utilities, but may be freely distributed. LOCATE is copyright 1995-2001, 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.TXT 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. FILE_ID.DIZ Descriptions of the archive's contents. Not used by the LOCATE.LSM program, and can be deleted. þþþ 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 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 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 Fri Nov 21 1997 6:52:04p .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 Fri Nov 21 1997 7:08:46p .D.H. C:\WINDOWS\SYSTEM\ toolhelp.dll Mon Nov 1 1993 3:11:00a A.... 14,128 13.80 K 2 items found: 1 file, 1 directory (1 H/S). Total of file sizes: 14,128 bytes 13.80 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:\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, FILE4YOU 12345.TXT, 6, 007.DOC 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. You may specify more than one drive letter before any filespec. 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) 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. þþþ SWITCHES (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 search duplicate network drive Mappings 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 formats /UK use United Kingdom date and time formats /UJ use Japanese (ISO) date and time formats /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 switches: /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 þþþ SWITCHES (IN DEPTH) þþþ /D Finds both files and subdirectories (the normal default behavior) /D- Files only, not subdirectories (default with /B /K /X /S:mask /0) /D+ Finds subdirectories 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, /S:mask, and /0 for details. /H Finds only items 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. If LOCATE is running under 4DOS, .BTM is also considered an executable extension. 4DOS uses .BTM for high-speed, in-memory batch files. 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 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 the COPY command won't copy empty files. This switch implies an automatic /D-. It will only find empty files, not subdirectories. Actually, /0 is just an alternative for /S:0! or /S:,0 /S:mask Size mask. The 'mask' may contain an optional smallest size, optionally followed by a comma and a largest size. Or, the mask may be a single size followed by an exclamation point, to find only one specific size -- that is, the largest and smallest 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:mask Date stamp mask. The 'mask' may contain an optional starting date, optionally followed by a comma and an ending date. Or, the mask may be a single date followed by an exclamation point, to find only a single date -- that is, the starting date and ending date 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 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 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 days- of-the-week are SUnday, MOnday, TUesday, WEdnesday, THursday, FRiday, SAturday, and XX (which matches illegal dates like February 31.) /T:mask Time stamp mask. The 'mask' may contain an optional earliest time, optionally followed by a comma and a latest time. Or, the mask may be a single time followed by an exclamation point, to find only a single time -- that is, the earliest and latest times are equal. 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. /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 files on drive C: LOCATE /A:DS+ find only Directories with the System attribute LOCATE CD: /A:A+ find only item in need of backing up on C: and D: LOCATE /A:D-H+ find Hidden files, but not Hidden 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 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. /NR No recursion. Searches only the specified directory (or the current directory) and not any child subdirectories. /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. /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!) /P Peter-style display, with file dates, times, attributes, and sizes. Peter-style output is now the default for LOCATE. /P remains for compatibility with older versions of the program. You can use it 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:*.VXD /P to see the files displayed with their dates, times and sizes. /I Index. This provides a minor variation on the Peter-style display. It shows the index number of each found item, instead of the kilo- or megabyte display. 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 switch is provided for compatibility with Norton FL, of course. /N Bare 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 /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 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. /L Display Windows 95 Long filenames. This switch 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, but only if you have Caldera's long-filename TSR installed. 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 *~* /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, standard 11 +A -S -H -R &B attribute bits 5 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 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 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. &J displays the filename petercased (lowercase for filenames, uppercase for subdirectory names) and right-padded with spaces. 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 force the number to at least n characters: &# will left-pad with spaces, and &@ will left-pad with zeros. So  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'" /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 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 my file server. 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. 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. 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 commands 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 pausing. Default is to pause if output is to the screen. Not a terribly useful switch. /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+ /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 switch 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 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 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 switch 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 will pass 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 the commands by starting a copy of the command shell. It uses the environment variable COMSPEC to find the shell. If the COMSPEC variable is not present, you'll get an error message. 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, e.g.: LOCATE C:VBRUN300.DLL /C:"SET VBRUN=&F" /Y /F /F:n List only the First n items found. Again, a Norton-alike switch. 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 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. /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 add a /F- to the command line to set the 'finds' count to 'no 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 switch 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 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. Some of the switches 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!) or, in many cases, simply omit it (/F10) I recommend that you use the colon for clarity. Some of the switches 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) The DOS batch-file handler strips commas and semicolons out of batch arguments; if you want to pass LOCATE's switches as batch arguments, use the tilde. þþþ 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. 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: you cannot pipe into it. The keyboard BIOS is used to fetch keystrokes. Error messages are sent to stderr, and /G /K /C 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 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). 6 Tree buffer overflow. Directory structure too complex. 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. 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; /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.29b 10-29-2001 C. Dye raster@highfiber.com Freeware. Copyright 1995-2001, Charles Dye. No warranty! File CRC code r1.1 by J. R. Hacker, 02-29-2002 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... the way it ought to be. I compress the executable using UPX, a freeware executable packer. The UPX home page is: http://wildsau.idv.uni-linz.ac.at/mfx/upx.html 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 delimiter. The macros used by /O: and /C: borrow liberally from Keith Ledbetter's file- finder SST (alias Target), which also has /O and /C switches 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 Peter himself. þþþ WHAT'S NEW? þþþ v1.29b 10-31-2001 10,489 bytes 9B0AB0D4 810F The final file size display did not include the size in K or M if the last item found was a subdirectory; fixed. v1.29a 10-29-2001 10,487 bytes F12347CC 64CD Fix for a nasty little bug which could frag a random chunk of memory if extensions were specified using /X:xxx. v1.29 10-08-2000 10,477 bytes ABE4005D F818 /X changes: When running under 4DOS, .BTM is now considered an 'executable' extension. It is also possible now to specify a list of user extensions to compare against: LOCATE /X:BMP,GIF,JPG,JPE,TIF The tree buffer is now allocated from upper memory if possible. New macros to provide date and time stamps in a consistent format regardless of country settings: &7 file date in ISO format with no leading space; &8 file time in 24-hour format, no leading space. /UI is now a synonym for /UJ. v1.28a 09-16-2000 10,323 bytes F133F4E5 9CB2 Fix for a serious bug pointed out by Bjorn Simonsen: filename canonicalization was stepping on the "character class" definitions, breaking all bracket expressions. v1.28 11-07-1999 10,327 bytes A0BF5DA2 FF7D Bug fix: The super-long "short" filenames allowed under Windows 95 and 98 could overflow internal filename buffers; fixed. Now filenames of up to 260 characters (including the terminal null) are correctly handled. It is now possible to enclose all or part of the filename in quote marks to trap spaces. The name of the starting directory is now canonicalized ("truename") via DOS 21/60 or 21/7160. This has the happy side effect of converting long directory names to short format under Windows 9x, so you can now use long directory names, e.g. LOCATE "C:\PROGRAM FILES\*.EXE" New switch /NC (No Canonicalize) disables this feature. Finally, /Q has been moved to /NA (No Accent stripping.) For a complete version history, see the end of the file LOCATE.S.