Simtel MSDOS 1992 June

home *** CD-ROM | disk | FTP | other *** search

/ Simtel MSDOS 1992 June / SIMTEL_0692.cdr / msdos / dirutl / sf33.arc / SF.DOC < prev next >

Wrap

Text File | 1989-03-30 | 78.9 KB | 2,179 lines

SF - Subtree Find Version 3.3 Thursday March 30, 1989 Documentation for SF by Howard Kapustein Copyright (c) 1988,1989, All rights reserved Howard Kapustein 1695 Barbara Lane East Meadow, NY 11554 (516) 481-9612 Contents COPYRIGHT AND DISCLAIMER .......................................... 4 LICENSE ........................................................... 4 TRADEMARKS ........................................................ 5 WHAT IS SUBTREE FIND .............................................. 5 FILE ATTRIBUTES ................................................... 6 INVOKING SUBTREE FIND ............................................. 7 SUBTREE FIND OPTIONS .............................................. 8 Attributes: ................................................... 9 ARCHIVE attribute ........................................ 9 HIDDEN attribute ......................................... 9 READ-ONLY attribute ...................................... 9 SYSTEM attribute ......................................... 9 Directory attribute ...................................... 9 Volume Label attribute ................................... 9 EXACT MATCH .............................................. 9 MATCH .................................................... 9 Criteria: ..................................................... 9 FILE STAMP ............................................... 9 Info: ......................................................... 10 FREE DISK SPACE .......................................... 10 ELAPSED TIME .............................................. 10 USED DISK SPACE ........................................... 11 Search: ....................................................... 11 ONE MATCH ................................................ 11 FIFO SEARCH ............................................... 11 NO SUBDIR SEARCH .......................................... 11 SEARCH .ARC FILES ......................................... 11 SEARCH .ZIP FILES ......................................... 11 Output: ....................................................... 12 COLOR ..................................................... 12 PAUSE ..................................................... 12 QUIET ..................................................... 13 BIOS OUTPUT ............................................... 13 REDIRECTABLE OUTPUT ...................................... 13 Other: ........................................................ 13 BATCH MODE: .............................................. 13 JUMP TO SUBDIRECTORY ...................................... 13 KILL (DELETE) FILES ....................................... 13 VERIFY BEFORE KILLING FILES ............................... 13 WAIT FOR KEYPRESS ......................................... 14 SET ATTRIBUTES ............................................ 14 TOUCH .................................................... 14 Special ....................................................... 15 SAVE DEFAULT OPTIONS ...................................... 15 MISCELLANEOUS PARAMETERS .................................. 15 HELP .................................................... 15 EXTENDED HELP ........................................... 15 PAUSING THE DISPLAY ............................................... 16 SF DISPLAY INFORMATION ............................................ 16 DOS VARIABLES ..................................................... 16 REQUIREMENTS ...................................................... 17 OPTIMAL PERFORMANCE ............................................... 18 INFORMATION ....................................................... 18 UPDATES / RELEASES ................................................ 19 FUTURE RELEASES ................................................... 25 ABOUT THE AUTHOR .................................................. 26 OTHER PRODUCTS .................................................... 26 SUPPORT ........................................................... 26 APPENDIX A - MISCELLANEOUS PARAMETER .............................. 28 APPENDIX B - ERROR LEVEL .......................................... 30 APPENDIX C - SEARCHING ARC AND ZIP FILES .......................... 32 COPYRIGHT AND DISCLAIMER This program and documentation are Copyrighted (C) 1988,1989 by Howard Kapustein, All Rights Reserved. Use of this program acknowledges this disclaimer of warranty: "This program is supplied as-is. The author disclaims all warranties, expressed or implied, including, without limitation, the warranties of merchantability and of fitness of this program for any purpose. The author assumes no liability for damages direct or consequential, which may result from the use of this program." LICENSE SF is distributed as "SHAREWARE." This does NOT mean that SF is free. There are several kinds of software, but these three are most popular: Public Domain: not for sale. Public Domain software is free. Programs listed in magazines are usually PD unless otherwise specified. Commercial: exactly what it sounds like, so called 'real' software, like 1-2-3 or dBASE III+. Shareware: similar to Commercial software, but without the inflated price tag. Shareware has 2 big advantages over commercial software: price and reliability. Because I don't have much overhead (I don't spend millions on advertising, packaging, etc.) I can sell my program to you for a reasonable price (I have never seen a shareware product with a list price of $200, and most 'Commercial' software sells for much more than that.) More importantly, you get to test drive the program BEFORE shelling out any money. You are under no obligation to pay for a shareware program during the trial period. After the initial trial period you may either register or stop using it. Very simply it's a limited time money back guarantee. If you like SF, let me know by sending me a picture postcard. If you really like SF, and would like to make a donation to support my continuing work on SF and other products, I suggest $10, but feel free to send me what you think SF is worth. I promise any monies received will go into a computer slush fund and won't be spent on something trivial like food, heat, the rent, etc. All registered owners (those making donations of $10 or more) will receive the next release of Subtree Find when it becomes Page 1 available. All registered owners will be notified when future versions of Subtree Find become available. If you would like a specially compiled version of Subtree Find, I am open to discussion. Please remember that I can not pay for rent, food, auto insurance, or any of life's expenses with registration money (my name isn't Datastorm, PKware or SemWare). Shareware is usually a thankless task, and almost never profitable. If you would like specific changes incorporated into Subtree Find, and I do not add in the change on my own, a modest fee will be requested. SF may not be distributed without this documentation. TRADEMARKS 1-2-3 is a registered trademark of Lotus, Inc. dBASE is a registered trademark of Ashton-Tate Inc. DESQview is a registered trademark of Quarterdeck Office Systems WHAT IS SUBTREE FIND Subtree Find fills a (to me) vital niche missed by DOS and other utilities. I wanted a program to search a subtree of my disk, but alas, DIR only works on one directory (why didn't Microsoft put in a /S option like they did with XCOPY? Then again, why didn't MS write us a real operating system and save us all many hours of grief?) and utilities such as Find File by Peter Norton and Fast File Finder by Keith P. Graham only work on an entire drive. Now don't get me wrong, they all do a great job, just not the job I need. So voila! I wrote Subtree Find. My main goals when writing SF were: - search just a subtree of an entire disk - the same information provided by DIR and more, like attributes and space used by files - search by any information about files (attributes, date, time and size as well as a filespec) - pause during execution for ease of reading - match filenames 100% identically like DIR - search inside .ARC and .ZIP files One of the more important features was that SF should accept wildcarded filenames (*,?) and match them EXACTLY as DIR does. This turned out to be the hardest part to implement. Some filenames are parsed by DIR differently than you would think. Page 2 Subtree Find will accept any filespec that DIR will, and will parse it the same as DIR will, just over multiple directories. Possible uses of SF: - enhanced DIR display - display disk space used by files - find files with certain attributes - find files modified since a certain date - search a subtree of a disk - search an entire disk for a filespec (just specify the root directory and all subdirectories will get searched, thus the entire disk) - an ARC or ZIP viewer/searcher FILE ATTRIBUTES Before going any further I think I should explain what file attributes are. If you already know, just skip this section. DOS keeps information about each file on a disk, such as the file name, size, date and time it was last changed, where the file is located on disk, and other useful tidbits. Every file has what is called an attribute byte. This byte stores all information about the file's attributes as a bit pattern: DECIMAL 128 64 32 16 8 4 2 1 ┌───┬───┬───┬───┬───┬───┬───┬───┐ │ ? │ ? │ A │ D │ L │ S │ H │ R │ └───┴───┴───┴───┴───┴───┴───┴───┘ HEX 80h 40h 20h 10h 08h 04h 02h 01h Archive Directory Label System Hidden Read-Only The ? are not used by DOS (yet). So what does this all mean? If you didn't understand the chart, don't worry. All you have to know is each file has a flag for each attribute. But wait! Didn't I see Directory up there? Sharp eyes. The only way DOS can distinguish between any old file and a subdirectory is by the Directory bit. Remember when I said DOS stores info about each file? Well, it knows where each file is located on the disk, so when you use your handy dandy word processor to edit your boss' memo, DOS knows where on the disk to look for the memo. For Page 3 directories, the location of the 'data' is really just another subdirectory listing. Another interesting item is the Label flag. Every disk can have a volume label (DIR will display the volume label for you). The volume label is just another filename stored in the root directory, except it has the Label flag turned on. Any file can have their Read-Only, Hidden, System and/or Archive (RHSA) bits turned on. Subdirectories have their Directory (D) bit enabled, and there should only be 1 Label (L), in the root directory. INVOKING SUBTREE FIND Subtree Find is invoked from the command line as follows: SF [options] [d:][path][filespec] [options] Options: -option or -option+ turns an option on -option- turns an option off -option* toggles an option Optional drive, path and filespec. Some examples: SF -he -f- c:\turboc searches the C:\TURBOC branch for all files that have only the HIDDEN attribute, and does not display free disk space when done SF -xm \ -u searches the current drive (specifying the root will have SF search the entire disk) for any file (default *.*) that has R, H, S, A and/or no attributes set, and displays space used by files per subdirectory and total space used when finished SF -f-t C:\turboc\*.h searches the c:\turboc branch for all 'normal' files (visible to DIR) matching *.h and displays the total space used by those files upon completion. No disk free space message will appear. Page 4 SUBTREE FIND OPTIONS Here is a list of the options supported by SF: Parm Option ON by default ──── ────── ───────────── Attributes: -a archive * -h hidden -r read-only * -s system -d directory * -l label -x all attributes (rhsa) -e exact match -m matched files only Criteria: (min-max) file size, date and/or time Info: -f free disk space -t elapsed time * -u used disk space * Search: -1 stop after 1st match -n no subdirectory tracing -i FIFO search of subdirectories -y[=] search [only] inside .ARC files -z[=] search [only] inside .ZIP files Output: -c color -p[n] pause every n lines -q quit mode * -$ use BIOS for output -& use redirectable output routines Other: -b batch (unattended) mode -j jump to subdirectory -k kill/delete files, NO PROMPT -v verify before deleting files -w[n] wait for a keypress when done [hrsax] set attributes (x = all) {touch} modify file date/time stamp Special: -g save default options -@n[:v] miscellaneous parameters Help: -? help -?? extended help Page 5 Attributes: ─────────── -a ARCHIVE attribute -h HIDDEN attribute -r READ-ONLY attribute -s SYSTEM attribute -x toggles all 'normal' attributes (the same as -ahrs) -d Directory attribute -l Volume Label attribute -e EXACT MATCH: all files found must have EXACTLY the same attributes as those searched for. The command SF -hrse \turboc will search the subtree for all files that have only the Hidden, Read-Only AND System bits enabled. In this case, if a file has HR (the system attribute is not enabled) it will NOT be displayed. -m MATCH: all files with the matching attributes, regardless of how their other attributes are set, will be displayed. Similar to Exact matching (-e) but less rigorous, match will find all files with the attributes specified (turned on.) Similar to the above example, SF -hrsm \turboc will search the subtree for all files that have Hidden,Read-Only, AND/OR System bits enabled. Unlike exact matching, match will display a file that only has Hidden and Read-Only (HR) bits on for the above example. NOTE: for Match (-m) to work properly, the ARCHIVE flag is turned OFF when match is specified (-m is really -ma-). If you wish to match files with the Archive bit, you must turn it back on in the command line AFTER match is specified (-ma, -mhra+, etc.) Criteria: ───────── (min-max) FILE STAMP: a minimum and/or maximum file size, date and/or time can be specified for matching files. Page 6 The format for this option varies from the other options: ([min][-][max]) The following formats are expected: [prefix]n[suffix] where prefix is an optional prefix forcing the value to be of that type. Acceptable prefixes are S (size), D (Date) and T (Time) n is the value (a number, date or time) suffix is only valid for a Size. Optional suffixes are B (Bytes), K (Kilobytes) and M (Megabytes) SF knows that 10K is 10 kilobytes (10,240 bytes) and 1M is 1 megabyte (1K * 1K). No decimal is allowed ('512' is 512 bytes but 0.5K is not valid). NOTE: The min and max parameters MUST be separated by a dash. If a date is given, it MUST be delimited with slashes. NOTE: DOS stores file times as hours (0-23), minutes (0-59) and seconds divided by 2 (0-28). SF accepts normal time (10:5:21) and converts it to DOS' format. Because of the way DOS stores the time, 10:5:21 and 10:5:20 are the same. Info: ───── -f FREE DISK SPACE: displays free disk space upon completion -t ELAPSED TIME: the time it took SF to perform the search will be displayed in hh:mm:ss:uu format (hours:minutes:seconds:hundreths of seconds) Page 7 -u USED DISK SPACE: each subdirectory with files matched will have the total size of those files listed. Directory entries have a size of zero. Upon completion, the total size of all matched files will be displayed. If ARC or ZIP files are searched, totals for ARCs and ZIPs may be displayed also. See Appendix A for more details Search: ─────── -1 JUST ONE MATCH: stops after 1st match -i FIFO SEARCH: SF keeps a list of all subdirectories to search and updates this list as new ones are found. If FIFO (first-in-first-out) is not enabled the list will be updated in alphabetical order. Thus, SF will search the disk a branch at a time. With FIFO search turned on, new directories are appended to the list as they are found. Since the list is traversed in order, front to back, with FIFO search turned on the disk will be searched in a level by level order. In the example SF C:\*.DOC first the root would be searched, then all subdirectories of the root, then all subdirectories of all subdirectories of the root, etc. -n NO SUBDIR SEARCH: this option limits the search to just the subdirectory specified. Using this option makes SF perform as a DIR substitute. -y[=] SEARCH .ARC FILES: looks inside .ARC files for the filespec. If = follows the y parameter, only ARC files will be searched (normal files will be ignored.) See Appendix C for more details. -z[=] SEARCH .ZIP FILES: looks inside .ZIP files for the filespec. If = follows the z parameter, only ZIP files will be searched (normal files will be ignored.) See Appendix C for more details. Page 8 Output: ─────── -c COLOR: output will be in color. To change the default colors, use: SF -c[[item:color],[item:color]...] where item is the item you want to change and color is the new color you want it displayed in. Multiple entries can be specified, but they must be separated by a comma. A list of items: # Item ─ ──── 1 Heading 2 Directory 3 Directory name 4 Volume Label 5 Files 6 Directory totals 7 Post info - Heading 8 Post info - 1 9 Post info - 2 10 Post info - 3 11 Post info - 4 12 Post info - 5 13 Post info - 6 14 Post info - 7 15 Post info - 8 16 Post info - 9 17 Pause message 18 Delete message 19 Jump message 20 Wait message 21 Null - used to 'turn off' color 22 Error - for error messages 23 ARC file 24 ARC warning 25 Quit message 26 ZIP file 27 ZIP warning SF requires color values to be 0-255, entered in decimal (base 10) format. Hex format is in the works. -p[n] PAUSE: like the DOS dir/p option, n lines (default 23 lines) of information will be displayed and SF will pause until a key is pressed. See PAUSING THE DISPLAY for more details. Page 9 -q QUIET: only subdirectories with matches in them will be displayed. Helps keep the screen less cluttered. -$ BIOS OUTPUT: normally, output is done by writing directly to the screen memory. Using the BIOS for writes is slightly slower, but sometimes necessary, esp. in multi-tasking environments. -& REDIRECTABLE OUTPUT: if you want to redirect output with DOS' redirection facilities (i.e. SF >dirlist) you must use this flag. DOS cannot redirect what it cannot see, and without this flag DOS is totally bypassed. SF will run significantly slower with this option, but such is the price of using DOS. Other: ────── -b BATCH MODE: while in batch mode, SF is designed to operate without user intervention. Any prompts (with one exception) are automatically answered according to the appropriate miscellaneous setting or, by default, positively. The only exception is the -v option. For now, I decided to leave the -v and -k options alone, due to the extreme potential for hazard. If you with to kill files in 'batch' (unattended) mode, use -k. If you want to be prompted, use -v. -j JUMP TO SUBDIRECTORY: after each match, you will be presented with the option to continue searching, jump to the drive/subdirectory of the file found, or stop SF immediately. -k KILL (DELETE) FILES: with Kill enabled, all matching files found will be deleted. Be warned, you could easily delete many files in a flash. See -v (Verify) for a similar option. -v VERIFY BEFORE KILLING FILES: similar to the -k option, except you will be prompted before each file to confirm the deletion. Page 10 -w[n] WAIT FOR KEYPRESS: SF will pause after completion until a key is pressed. If a number is specified, SF will wait until that key is pressed. Ex: -w32 waits for a space and then quits (space is ASCII code 32). Extended keys are supported (Alt, function keys, etc.) To determine the wait code, use this formula: 256 * scan + ascii where scan is 0 for a normal key and 1 for an extended key. Useful for operating SF with DESQview (tm). If the number entered is prefixed with a 0 (i.e. -w032) no message will be displayed when waiting for a key [hrsax] SET ATTRIBUTES: this option will actually change the attributes of matched files. In addition to the - and + modifiers, the * (toggle) modifier can be used. Be warned, this can do nasty damage since you could potentially change the attributes of every file on you hard drive. Volume label and Subdirectory entries are not affected. {touch} TOUCH: modify the date/time stamp. The format expected is: {[prefix]n} where prefix is an optional prefix forcing the value to be of that type. Acceptable prefixes are D (Date) and T (Time) n is the value (a date or time or special, see below) NOTE: If a date is given, it MUST be delimited with slashes. NOTE: DOS stores file times as hours (0-23), minutes (0-59) and seconds divided by 2 (0-28). SF accepts normal time (10:5:21) and converts it to DOS' format. Because of the way DOS stores the time, 10:5:21 and 10:5:20 are the same. Page 11 SPECIAL: @ If a '@' is given as a value, SF will use the current date and/or time to touch files. The prefixes can be used with the @, so {d@} only touch date {t@} only touch time {@} touch date AND time All files will be touched with the same values during the same execution. So if you use {@} on you entire disk (why you would do such a thing is beyond me, but it illustrates the point), all files will have the same date and time stamps, even though SF may have spent several minutes running. Special ────── -g SAVE DEFAULT OPTIONS: the default options can be permanently changed. The defaults are stored in the .EXE file and are modified with this option. Optional suffixes: - Off (don't save options) + On (same as -g) * Reset defaults Needless to say, the -g option cannot be set on as a default NOTE: -g* does NOT toggle save defaults. This is an exception to the modifier * -@n[:v]: MISCELLANEOUS PARAMETERS: Due to the limited keys available, the -@ parameter was created to handle numerous small options. See Appendix A for the current @ parameter settings -? HELP: oh come on, it's kind of obvious, isn't it? -?? EXTENDED HELP: more help Page 12 PAUSING THE DISPLAY Before each subdirectory is searched, and after each line displayed is output, these keys are looked for: ESC - immediately quit SF any other key - pause the display, wait for a key When paused, the message "Program paused; press any key to continue... " is displayed. Action taken is based on the key pressed: ESC - immediately quit SF ENTER - display 1 more line, then pause P - toggles Pause on/off any other key - reset the pause counter and resume program SF DISPLAY INFORMATION SF will display DIR-like information (name, date, size, etc.) as well as attributes and the disk space allocated to a file. Under DOS, a file is allocated a disk block, regardless whether all of it is used. If you have 100 files, each about 5 bytes long, DOS will still allocate 100 blocks. Not bad, you say. Well, the disk block sizes are 4K for DOS 2.x and 2K for DOS 3.x. Now those puny 5 byte files are each taking up 2K or more! So instead of 100 files using 500 bytes, they're actually using 200K! The total K allocated is a measure of the disk space allocated to files, while the byte count (as per DIR) is merely a total of the bytes used. DOS VARIABLES SF uses the following DOS variables: SF= used to locate SF.EXE. This should contain the explicit pathname of SF.EXE (i.e. SET SF=c:\util\sf.exe) Should only be needed under DOS 2.x and possibly networks. Try running SF without this variable, and if SF will not run, try setting it. If problems still persist, let me know. (See Information/Requirements for further information). Page 13 SFOPT= used to set options. Options are parsed in the following order: defaults (saved in file) DOS environment variable SFOPT command line For example, SET SFOPT=/p50n will force SF to pause every 50 lines and only display a single directory, unless overruled at the command line. REQUIREMENTS SF needs a minimum of 55K of RAM and DOS 3.x, given the following provisions: SF can probably run under DOS 2.x, if the SET SF= is used. In earlier versions, I heard some faint rumors about difficulties running under a network, but never could get a solid answer. I'm going to get a bit technical, so if you don't understand what I'm talking about, don't worry. Just skip ahead and if you have any problems let me know. I save the default parameters at the end of the .EXE file, and read them at the start of execution. To find the .EXE file, I use argv[0], which, so I hear, is not available under DOS 2.x. To prevent this problem, I have included the DOS variable SF= which is used before referring to argv. Theoretically, if argv[0] is not available, using the SF= should allow execution. If this 'problem' persists, let me know and I'll see what I can do. SF needs a minimum of 55K of RAM, but... Using DESQview I have determined that 55K is the minimum the program can run with. Depending on the size of the tree being searched, or certain options, SF might require more. Again, I'm going to get technical to explain the problem. SF needs a little over 55K to load into memory. During a search, every directory found is added to a list of directories to scan. If your root directory has 10 subdirectories, when SF has finished searching your root directory its list of directories to search will have 11 items (root plus 10 subdirs). Each directory in the list uses 82 bytes of RAM. The problem arises if you search a large tree structure. When searching my hard drive with only 53K of RAM available, SF bombs out when trying to add a 29th directory to the list, due to insufficient memory. What this means is if SF exits because of memory shortages, try running SF with some more RAM. I'm currently working on a memory management scheme that will not impair performance. Page 14 As of version 3.3, a new memory management scheme has been implemented. After a directory has been searched and is no longer needed, the memory used is de-allocated. This drastically reduces the amount of RAM needed for SF to search an entire drive. Under DESQview with 55K allocated, SF searches the entire disk without a problem. If the RAM allocated is changed to 54K, the program will not run (Abnormal program termination). The only other time SF needs more memory is during a search inside .ARC and .ZIP files. Because SF has to look inside the files, the open and search functions may require a little bit of memory for buffering, etc. Unlike the memory problem with directories, this memory is allocated when opeing a file and returned to DOS after closing the file. Since only one file is open at a time, the overhead is negligible. I'm not sure exactly how much memory is used, but it's measured in bytes, not Kbytes. OPTIMAL PERFORMANCE SF uses 2 separate search routines, depending on certain options. I found that one generic search function was too slow for most uses, so I 'cheated'. If you just do searching (no modifying files or funky options like jumping or deleting) a slightly faster search routine is used. The following options MUST be off for the optimized search routine to be used: -e Exact -m Match -j Jump to subdir -k Kill/delete -v Kill/delete with verify -y Search inside .ARC files -z Search inside .ZIP files -1 Stop after 1st match [] Modify attributes {} Touch INFORMATION SF was compiled with the interactive version of Turbo C 2.0 in the SMALL memory model, optimized on SPEED, with all optimizations and MERGE DUPLICATE STRINGS turned on. Many of the routines were linked in from TCHK, a Turbo C library for TC 2.0 I have released as shareware. I have tested SF on my system rather thoroughly, although this does not guarantee you won't have problems. If you have difficulties, feel free to contact me. Page 15 My system: - IBM PC - DOS 3.2 - 640K RAM - 2 Seagate ST225 20MB hard drives - NEC V20 cpu - PC Sprint (dandy little speed up plug in. No slot, hardware switch for normal (4.77) and fast (~7) MHz speeds and reboot. Between the board and the NEC my machine plods along almost 2x as fast as a normal PC. At only $95, I highly recommend it. Call these guys for more info: Product: PC Sprint and/or NEC V20 Exec-PC, Inc. PO BOX 11268 Shorewood, WI 53211 VOICE: (414) 963-2880 MODEM: (414) 964-5160 UPDATES / RELEASES Version 1.0 - 4/29/88 - Initial release Version 2.0 - 5/18/88 - changed: old -t now covered by -u - new: -t option, elapsed time - new: -b option, break/keyboard pausing (for speed) - new: # subdirectories searched displayed at end - new: -1 option (stop after 1st match) - changed: text output cleaned up (1 File, 20 Files) - new: -c option, ANSI color - new: -i option - new: -! option - new: (min-max) filesize option - new: -q option, quiet - new: -k option, kill (delete) files found - new: -v option, verify before kill (delete) files found - new: -j option, jump to subdirectory - new: -w[0n] option, if leading zero, suppress 'waiting for key' message - new: [rhsax] option, set attributes (off/on/toggle) (-+*) Version 2.1 - 5/26/88 - new: -g option, make permanent defaults (-+*) - changed: previously kill file would automatically turn off the Read-Only attribute if necessary to delete. Not the safest of practices, it now will give error msg and not delete - new: added ERROR color for error messages - changed: any prompts (Jump, Delete, etc.) now clear the Page 16 typeahead buffer first - new: -?? extended help option - fixed: unnecessary returns were being output for files that didn't match, changed method of output/displaying - fixed: wouldn't display .. entry in some cases (SF *.) Version 2.2 - 6/9/88 - new: touch date/time stamp {touch} - new: (min-max) now handles file date and time also - fixed: the b- option wouldn't always work, due to change in code for 2.1 - fixed: added checking for no more available memory during search of large branches (SF uses dynamic memory allocation to keep track of its search tree) - changed: added ESC (quit) option during extended help pause - fixed: occasionally the cursor would change to a full block with the cursor control option (-!). I fixed the hide cursor routine - changed: I used the Merge Duplicate Strings Option in Turbo C to reduce the .EXE size by a few K - changed: most output has been speeded up - fixed: if the -w option was used with the message "Press key # to end", the key code was wrong - changed: during "Save Options (Y/N)", ESC will be accepted as No - changed: only - is a valid min/max separator - fixed: If a filespec ended with a 1 letter filename (i.e. C:\COMM\Z where Z is a filename) SF would think it was part of the path and not find any matches. The code to check directories had a bug in it which is now corrected. - fixed: in the output, the file date was missing 80 years (i.e. a file with the date 4-1-88 was being displayed as 04-01-08). All DOS dates are stored as the year since 1980 and I forgot to add the 80 years back on. Now fixed - "fixed": extended help erroneously said "file size, date and/or time" because date and time were not supported until now. I "fixed" this by supporting date and time - changed: earlier versions would modify files (i.e. attributes) before displaying them. If you wanted to change all found files to Hidden, when a matching file was found it would be changed to Hidden, and then it would be output. Now I display the file as it was before SF gets its hands on it. Version 2.21 - 8/6/88 - fixed: when calling SF from the root directory, to operate on the root directory, no files would be found unless you explicitly gave it the path (i.e. \s*.* c:\ c:\*.bak etc.) Works properly now (I didn't notice this because I hardly ever use it in the root directory) - changed: if you try to delete a Read-Only file, you can now try to change the attribute before deleting it Page 17 Version 2.3 - 10/24/88 - changed: compiled under Turbo C 2.0 - fixed: touch feature works (current year, not year+60). Forgot filestamp and DOS date years are not stored the same (year-1980 and year, respectively) - changed: all output now uses console i/o unless explicitly told to use redirectable output (-&). Using console i/o increases SF speed immensely (i/o was the major bottleneck) - new: output via BIOS (-*) if using console i/o - new: SET SF=pathname to find SF.EXE - new: SET SFOPT=options - new: displays logical size (allocated disk space) as well as physical size (bytes) - changed: the command line may have options before and/or after a filespec (SF [options] [filespec] [options]) - changed: internal coding has been rearranged. Benefits include easier processing of the command line, faster throughput, color/redirectable output, and easier to upgrade to handle multiple filespecs - fixed: bug in -T option (would automatically turn pause mode on) - fixed(?): bug(?) in earlier versions - would not delete - fixed: pause after n lines (p[n] pause after n lines) now works properly (accomplished as a byproduct of console i/o / redirectable output). Problem: n must be greater than 3 or else unpredicable results may occur (not a bug, just imperfect) - fixed: bug in earlier versions - {@} would not accept modifiers ({d@} and {t@} would not work) Version 3.01 - 10/26/88 - new: any option followed by a * is toggled (except the Save defaults option. If Save defaults is followed by a *, they are reset.) To accomodate this, the BIOS option (previously *) has been changed to a dollar sign ($). The following options do NOT yet support the * modifier: k(ill) p(ause) t(ime elaped) v(erify deletes) w(ait for key) - changed: the documentation has been updated. In 2.3, several references were made to a version 3.0, which does not exist. Originally intended to be released as 3.0, there were not enough substantive changes to warrant an increase by a whole version number, so I titled it 2.3. Sorry if this caused you any confusion. Version 3.10 - 12/27/88 - new: -y and -z options search inside .ARC files (-y also searches inside .ARCS, -z only searches inside .ARCs) - new: -# option confirms execution if the filespec *.* is being used. Page 18 - new: the option -# will now warn the user if the filespec *.* is about to be used. After accidentally deleting part of a hard drive, this option was requested. Sorry Marc. As the documentation clearly warns, using the /k option can potentially WIPE YOUR ENTIRE HARD DRIVE! - new: SF is now more DESQview aware. During keyboard waits, SF will now free its time slice - changed: the extended help information (-??) once again displays the current color settings, in true color if the redirectable option (-&) is not hard coded. In addition, the Compuserve id is no longer listed (sorry, but CIS costs a fortune, well beyond a poor college student's meager means) - fixed: touch {} and set attributes [] no longer modify directories or labels. It can be done, but I'm not quite sure how yet. Look for this in a future release - fixed: Jump now allows you to jump to the directory containing a match, regardless of what type of file it is (older versions wouldn't jump if a subdirectory or label was found) - changed/fixed: all options now support the toggle suffix (*). In version 3.01, the cpkvw options did not allow the * suffix - changed: tweaking of code for speed and .ARC file handling - fixed: in the middle of a scan, esp. in color mode, hitting ESC would cause SF to end, but leave the color set to blank on black, without a cursor, until a CLS was done. A typo in the code was referencing one too many elements of an array, and the next byte just happened to be zero (the attribute of black on black). - fixed: the Error color was accidentally not defined, so a random byte was being used instead. This was especially noticeable in Kill Read-Only files - fixed: a command line of SF /k/b was giving an error due to the extra slash in the middle. In scanning an option string, any extraneous slashes are ignored Version 3.20 - 2/26/89 - new: support for ZIP files (-z now searches ZIP files, no longer ARC files) To support ZIP as well as ARC, I have had to temporarily remove the search only ARCs option. Look for more variety with these options in future version - new: limited support for PAK compression "Crushed" files (type 10). PAK files, as long as their header structure remains the same as .ARC's, and the extension is .ARC, will be handled the same as .ARC files. Adding support for the .PAK extension will decrease performance, and with Phil Katz's new ZIP format, I doubt PAK will be an important force. Besides, I don't use PAK - new: during Pause prompt, hitting P will toggle pause on/off - new: @n parameter for miscellaneous trivial options. supports all setting modifiers (+-*). See Appendix A for more details. Page 19 - changed: redirection turns off color. With redirection there is no color output, but variables were still being set. Should be faster - changed: minor tweaking of code, improve speed and cleanliness - changed: warns unexpected End-of-Archive mark only if flag is set on (-@1). See Appendix A for more details - fixed: still getting problem with color not being reset upon abort by ESC during list, but I think I finally squashed this bug - changed: cleaned up output/display a little. After D to Delete, Jump, etc. messages, internally counts 1 line but does 2 CR/LF - changed: exit code 32 now displays the string "Insufficient memory" - fixed (finally): /k/b used to skip the letter after the '/' inside the parameter list (the 'b'). I accidentally incremented a counter and forgot to decrement it - new: exit codes 70, 71 and 72. See Appendix B for more details - changed: previous versions of Subtree Find used Turbo C's floating point emulation to do 2 calcualtions. Linking in their math library added 16K+ to the .EXE file and more to RAM requirements. I wrote my own math emulation routines (I only needed accuracy to 4 decimal places) and saved substantial amounts of RAM. See Information/Requirements for more details) - fixed: if time rolls over midnight during execution, the elpased time is now correct - new: SF286.EXE, a specially compiled version for 286/386 machines, distributed with Subtree Find Version 3.21 - 3/2/89 - fixed: the /z and /y options would always display the ARC/ZIP file being searched, whether or not the ARC/ZIP matched the filespec or contained any files matching the filespec - changed/fixed: if Jump (-j) and Stop after 1st match (-1) were used together, SF would prompt the user about jumping first (the -j option), and then stop because a match was found (the -1 option). Now the -1 option is checked before the -j option - changed/fixed: if [r] and {anything} were used in the same run, first the file is made Read-Only, then the touch fails because Read-Only files can't be modified. Now any touch is made, followed by modifying attributes - fixed: a couple of the color outputs while inside .ZIP files had typos, referencing the wrong color - fixed: minor modifications to color outputs for cleaner display (I think) - changed/fixed: some of the miscellaneous files distributed with SF 3.20 had typos which are now corrected. SF.DOC is unchanged since 3.20, but most of the other files have been modified Page 20 - changed: the SFOPT= environment setting requires options be specified as if they were on the command line. Where you could say SFOPT=c in earlier versions you must now say SFOPT=/c Version 3.3 - 3/30/89 - new: /z= and /y= restrict searching to inside ZIP/ARC files only, respectively - changed: the file handling functions used to access ARC and ZIP files and to save the configuration have been changed to lower-level functions for two reasons: they require less memory and SF is now network compatible - new: files inside ARC/ZIP must match all search parameters (name, attrib, size, date, time) with one exception: attributes. Attributes are not supported in ARC versions prior to 6.x, and I do not fully understand where they are stored in ZIP files. On the "to do" list. You can force SF to match files inside ARCs/ZIPs by filename only via the -@5 and -@6 parameters - new: automatic detection of redirection (sf ... >...) turns on redirected output (-&). Added -@3 parameter to control auto redirection - new: batch mode (-b). The keyboard break parameter (previously -b) is now -@7 - new: automatic batch if redirection detected (-@4) - changed: keyboard break (-b) now -@7 - changed: cursor control (-!) now -@8 - changed: verify *.* (-#) now -@9 - new: post info also has ARC and ZIP summaries (totals and used space). Optional via -@10, -@11, -@12 and -@13 - new: in batch mode, -@14 will remove ReadOnly attribute if necessary during kill (-@14- will not kill any ReadOnly files during kill in batch mode) - new: -@15 sets DOS BREAK setting ON during run, then resets BREAK to original setting before SF started. I had a request to add in some Ctrl-Break support. This is not a full featured break routine, it just allows a cheap and dirty method to enable Ctrl-Break. If you have problems with this, let me know and I'll look further into putting in my own Ctrl-Break handler <ick>. Right now it's simply not worth the effort. - fixed: cleaned up output display, especially color - fixed: if two sets of parenthesis next to each other, SF would not properly parse it ( i.e. SF (10k)(3/30/89) ) - changed: file time and date fields in ZIP files were incorrectly processed as a signed int, rather than unsigned int, potentially inaccurately displayed - changed: warning messages "Not a .ZIP file" changed to ".ZIP file corrupted" if the ZIP file is valid (signature ok) - fixed: previously, any file not matching attributes was skipped, even ARC/ZIP files (so they were not processed if /zy was given) - fixed: wait before exit (-w) used to come before the Page 21 Quitting with Errorlevel message, negating its effectiveness under DESQview. Now the -w option is the last input/output done by SF. Errorlevel 6 is no longer used - new: the default filename.ext is displayed in extended help (SF -??) - new: errorlevels 73 and 74 added (batch mode incompatibilities and searching the directory \..) - fixed: \. is now properly interpreted as \ - fixed: \.. does not exist, and causes DIR to give an error message. SF will exit with errorlevel 74 if this invalid path is specified - changed: a 286 specific version is no longer distributed. It's a great inconvenience to generate a 286 specific version, and nobody seems to care. It's now by request only FUTURE RELEASES I've got some features I'll be adding in the immediate future, and some that are no more than twinklings of ideas. They're listed in roughly the order I plan to implement them in. - ARC/ZIP attribute match: add comparison of attributes of files inside ARC/ZIP. The complexity of the ARC 6.x format and my lack of time to puzzle out how ZIP stores attributes is holding me back - Redirected input: add support for redirected input (SF <filename.ext does not currently work) - ARC 6.x: add support for ARC 6.x extra information. The only problem is there is very little information about it, and what I can find is not simple. Time time time... - ARC/ZIP comments: add support for displaying comments in ARC and ZIP files - Output: I'd like to have optional forms of output (i.e. only filenames, no attributes, etc.) but how to do this without sacrificing speed is a problem. If I were to muck around with that routine, the performance would most likely suffer. I'll have to see what can be done Multiple filespecs: SF could search multiple branches during a single run Exclude: SF could search all filespecs EXCEPT those that are explicitly excluded (i.e. search for all files matching C:\TURBOC\S*.* and exclude those files matching *.OBJ) Page 22 ABOUT THE AUTHOR I am a senior at Rensselaer Polytechnic Institute majoring in Computer Science. Since I don't graduate until May '89, my main source of income is my savings account. If you are in the Long Island, New York City, and/or Troy/Albany area, I do micro consulting and custom program design. If you're interested, I can be reached at the addresses below. Of course, I am open to all job offers. OTHER PRODUCTS Here's a list of some other shareware products I have written: COOKIE 1.2 - Fortune cookie, gives you a random fortune from a cookie file. Lots of options and distributed with 2800 cookies of mixed content (rated G - X) DCOUNT 1.2 - Document/Text file info, find out all kinds of information like # words, lines, pages, control characters, etc. Many options. FREE 1.61 - Free disk space, with options, including network compatibility and search multiple drives. Distributed with full Turbo C source. TCHK 2.00 - a Turbo C library for Turbo C 2.0 sporting over 200 functions. Featuring date, time and string manipulations, keyboard and video routines,hardware and software identification, ANSI, printer, multitasking, math, financial, DOS, and menu functions, and much more. Source code is available. Many of the functions in Subtree Find are linked from TCHK 2.1b, the beta version of the next release. SUPPORT Thanks to the graciousness of the sysop at The BOSS, I now have easier access to his BBS. The latest versions of my software can be found there. If there are some features you would like to see implemented, or you have any questions or comments, please contact me. I can be reached at the following: Page 23 HOME COLLEGE ──── ─────── Howard Kapustein Howard Kapustein 1695 Barbara Lane 404 Davison Hall East Meadow, NY 11554 Rensselaer Polytechnic Institute Phone: (516) 481-9612 Troy, NY 12180 Phone: (518) 276-7381 or at the following electronic services/bulletin boards: The Boss dBBS (201) 568-7293 *** Support BBS *** Software Society (201) 729-7410 Distribution BBS Computer Connection (202) 547-2008 Distribution BBS GEnie Howard S. Kapustein These are the places I can be reached by modem. SF (and all other software I release) is supported through The BOSS. If you try to get in touch with me during the school year (roughly Sep 1 - May 10, not counting winter break) PLEASE try to reach me at college. If you call my home odds are you won't get much information. My parents aren't exactly what you would call computer people. Page 24 APPENDIX A - MISCELLANEOUS PARAMETER The Miscellaneous parameter (-@) has the following options: -@1 Warn of End-Of-Archive Mark: during a search inside an .ARC file, the data is terminated with a Ctrl-Z (Ascii character number 26). In pre-3.20 versions, if this EOA mark was found before the actual End-of-File, a warning message was displayed. This commonly occurs when using non-batch protocols to transfer files, since non-batch protocols (Xmodem, Xmodem-1K, etc.) have a fixed size for their packets, and they pad the end of a file with nulls (Ascii char 0) to fill out the packet. These extra characters are not harmful, but earlier versions considered it important enough to warrant a message. I've looked into this further and it seems PKPAK, PKUNPAK, ARC and other .ARC file handlers stop processing when they hit the EOA mark. So the warning message is now optional. Usually there is no need to have this option on -@2 Display Error level: when quitting SF, if this option is on the message "Quitting with Error level = #" will be displayed, showing the error level SF quits with. The errorlevel can be detected with batch files -@3 Autodetect DOS redirection: if output is redirected by DOS (i.e. SF >dumpfile) SF will internally set options according to the following command: /&p-@7-@8- and, if -@4 is on (auto batch if output redirected) /b -@4 Auto batch: if output is redirected by DOS and detected by SF, batch mode is turned on (/b) -@5 Ignore match criteria in .ARC: files inside .ARCs are only matched by filename (size, date and time are ignored) -@6 Ignore match criteria in .ZIP: files inside .ZIPs are only matched by filename (size, date and time are ignored) -@7 Keyboard interruption: during execution the keyboard will be checked after every line displayed on the screen and when between subdirectories. See Pausing The Display for more details -@8 Hide cursor: SF will turn off the cursor during execution and when done, restore the cursor to its previous shape -@9 Verify *.* runs: if the search spec for filename is *.* a warning message will ask you to confirm the run. Useful if you are forgetful and use the -k option Page 25 -@10 Used space inside .ARC files: if the -u parameter is on, the summary information will include a total of the compressed and uncompressed size of files found inside .ARC files -@11 Used space inside .ZIP files: if the -u parameter is on, the summary information will include a total of the compressed and uncompressed size of files found inside .ZIP files -@12 Always show used .ARC space: if this option is off, the space used by files inside .ARC files will be displayed only if it is non-zero. With this option on, the total sizes used will be displayed, even if there were no matches inside .ARC files -@13 Always show used .ZIP space: if this option is off, the space used by files inside .ZIP files will be displayed only if it is non-zero. With this option on, the total sizes used will be displayed, even if there were no matches inside .ZIP files -@14 Remove Read-Only in batch: during batch mode execution while killing files (-k), if a file is protected by Read-Only attribute, this option determines whether or not the Read-Only status should be removed before trying to delete the file -@15 Set BREAK: if this option is on, the DOS BREAK setting will be saved, BREAK will be set ON, SF will run, and when finished, the BREAK setting will be restored Page 26 APPENDIX B - ERROR LEVEL Here's a list of the errorlevel settings SF can exit with: 0: Normal end of execution, no errors 1: End after 1st match 2: Error, Unknown parameter 3: Help (-?) 4: SF aborted by user via ESC during file list 5: SF aborted by user via ESC during pause 6: NOT USED 7: Error, Missing closing parenthesis 8: Error, Missing parameter in parenthesis 9: Error, Unknown parameter in parenthesis 10: Error, Invalid parameter in parenthesis 11: Error, Invalid filesize range specified 12: Extended help (-??) 13: SF aborted by user via ESC during delete 14: Error, Invalid parameters: can't delete subdirectories 15: Error, Invalid parameters: can't delete volume labels 16: SF aborted by user via ESC during jump 17: SF end of execution by Jump (-j) 18: Error, Missing closing bracket 19: Error, error changing attribs 20: Error, Invalid parameter in -c, missing : 21: Error, Invalid parameter in -c, missing color 22: Error, Invalid paramter in -c, only color settings 1-24 may be selected 23: Error, Invalid paramter in -c, color values must be 0-255 24: Error, can't get handle to SF file to read options 25: Error, Error reading options: file possibly damaged 26: Error, Can't initialize options 27: Error, can't get handle to SF file to write options 28: Error, Can't save options 29: Error, can't save options 30: Error, Options not saved 31: Error, can't get access to initialize options 32: Error, No more available memory. Disk too big 33: SF aborted by user via ESC during extended help pause 34: Error, Missing closing brace 35: Error, Invalid time format for touch 36: Error, Invalid date format for touch 37: Error, Invalid time format for touch 38: Error, Invalid date format for touch 39: Error, Error: braces but no touch paramter 40: Error, Invalid time separator in touch 41: Error, Invalid date separator in touch 42: Error, Invalid touch format, unknown touch date or time 43: Error, Invalid date touch parameter. Must be dd/mm/yy 44: Error, Invalid time touch parameter. Must be hh:mm:ss 45: Error, Invalid touch date (month must be 1-12) 46: Error, Invalid touch time (hour must be 0-23) 47: Error, Invalid touch time (minutes must be 0-59) 48: Error, Invalid touch time (seconds must be 0-59) Page 27 49: Error, can't get access to initialize options 50: Error, Invalid min date parameter. Must be dd/mm/yy 51: Error, Invalid min time parameter. Must be hh:mm:ss 52: Error, Invalid min date (month must be 1-12) 53: Error, Invalid min time (hour must be 0-23) 54: Error, Invalid min time (minutes must be 0-59) 55: Error, Invalid min time (seconds must be 0-59) 56: Error, Invalid max date parameter. Must be dd/mm/yy 57: Error, Invalid max time parameter. Must be hh:mm:ss 58: Error, Invalid max date (month must be 1-12) 59: Error, Invalid max time (hour must be 0-23) 60: Error, Invalid max time (minutes must be 0-59) 61: Error, Invalid max time (seconds must be 0-59) 62: Error, Invalid filedate range specified 63: Error, Invalid filetime range specified 64: SF aborted by user via ESC during delete Read-Only file prompt 65: Error, Can't find SF.EXE 66: Error, SF only supports 1 filespec 67: Error, Error: parameter delimiter ('/') missing paramter command 68: Error, SF aborted by user during *.* warning prompt 69: Error, Invalid parameters: can't delete files from .ARC or .ZIP files 70: Error: @ parameter must be followed by a number 71: Error, unknown @ parameter 72: Error: Insufficient memory. SF aborting. 73: Error: Batch mode can NOT be mixed with v or # parameters 74: Error: Invalid directory Page 28 APPENDIX C - SEARCHING ARC AND ZIP FILES Subtree Find can search inside ARC and ZIP files. The format used to display the contents of ARCs and ZIPs conforms to the formats used by ARC and PKPAK/PKUNPAK (.ARC files) and PKZIP/PKUNZIP (.ZIP files). The .ARC format is: Filename.ext compressed_size method(#) real_size date time CRC where Filename.ext = the file found compressed_size = the compressed size of the file, in bytes method(#) = the compression method (and equivalent method number) real_size = the uncompressed size of the file, in bytes date, time = the date/time stamp of the file CRC = the 16-bit CRC for the file (in hexadecimal) The .ZIP format is: Filename.ext real_size method compressed_size date time CRC where Filename.ext = the file found real_size = the uncompressed size of the file, in bytes method = the compression method compressed_size = the compressed size of the file, in bytes date, time = the date/time stamp of the file CRC = the 32-bit CRC for the file (in hexadecimal) NOTE: The Compressed and Uncompressed sizes of files in .ARCs are displayed in reversed order as in .ZIPs. Please keep this in mind when viewing a list of files inside .ARCs and .ZIPs NOTE: Matching files inside ARCs and ZIPs by size works with the Uncompressed size NOTE: The ONLY subclause (/z= or /y=) will force SF to only search insize ARC and/or ZIP files. Page 29