BFIND - Basic File Finder Users Manual For Shareware Version 1.00.00 Written By: JEMC Systems Copyright (c) JEMC Systems, 1991 Table of Contents 1 Copyright and Distribution ................................... 1 2 Disclaimer ................................................... 2 3 Introduction ................................................. 3 4 Hardware Requirements ........................................ 3 5 Installation ................................................. 4 6 Basic Operation .............................................. 4 6.1 Filename Wild Cards ................................. 4 6.2 Search Action ....................................... 5 7 Option Switches .............................................. 6 7.1 General Options ..................................... 7 7.2 Qualifier Options ................................... 8 7.2.1 Qualifier Modifiers ....................... 9 7.3 Operation Options .................................. 10 8 Help Screen ................................................. 12 9 Program Return Messages ..................................... 12 10 Version Notes .............................................. 14 11 In Closing ................................................. 15 12 BFIND Registration ......................................... 16 BFIND Registration Form ....................................... 18 BFIND Copyright (C) JEMC Systems, 1991 BFIND.TXT Page 1 1 Copyright And Distribution This document and the BFIND program are Copyright (c) JEMC Systems, 1991. BFIND is copyright material and is not in the public domain. BFIND is not Freeware. If you wish to use BFIND past the 1 month test drive period, you must register your copy by sending in the registration form and fee. This manual is for the Shareware version of BFIND. The Shareware version of BFIND introduces itself as: BFIND - Basic File Find, Shareware Version: 01.00.00 Copyright (c) JEMC Systems, 1991 The Shareware version contains an advertisement and may be distributed as outlined below. A registered version of BFIND introduces itself as a "Registered Version". The registered version is not for distribution or use by anyone other than to whom it was registered or licensed. The Shareware BFIND program and documentation can be freely copied and shared as long as the following restrictions are observed: o The Shareware program (BFIND.EXE) and its documentation (BFIND.TXT) are distributed together in their original unmodified forms. o No fee is charged for the program and documentation except to cover media and reasonable preparation costs. o You do not sell the program or attempt to make any money from it or any modified version of it without JEMC Systems' authorization. o Arrangements for business, corporate, and LAN use must be made with JEMC Systems, See section 12. o You may try the program for 1 month before registering it. If you find the BFIND program useful and wish to continue using it past the 1 month trial date, you must register your copy of the program by sending in the registration form and fee. See section 12 on becoming a registered user and the benefits provided by registration. BFIND Copyright (C) JEMC Systems, 1991 BFIND.TXT Page 2 2 Disclaimer An honest attempt has been made to assure that the documentation is complete and accurate and that the BFIND program functions as described; but bugs can crawl in from anywhere at anytime so . . .. JEMC Systems does not warrant that the documentation is completely accurate or that the BFIND program will operate as described, or on a particular system. The program is provided "AS IS" without warranty of any kind. The entire risk as to the results and performance of the program is assumed by you, the user. JEMC Systems will not be held liable for any loss or damage or loss of business caused directly or indirectly by this program. By using this program you agree to these terms. The program and documentation are subject to change without notice. Registered users will be informed of updates to the BFIND program and will be provided with support for the BFIND product. BFIND Copyright (C) JEMC Systems, 1991 BFIND.TXT Page 3 3 Introduction The BFIND program searches for files regardless of where they may reside on a disk. BFIND searches across subdirectories and inside ZIP files created by PKZIP from PKWARE Inc.. BFIND also searches in hidden subdirectories and can find hidden and system files. BFIND can find files based on a variety of search options. The filename to search for may be wildcarded. BFIND contains its own wildcard parser and therefore can accept a wider variety of wildcarding (See section 6.1). Other search options are date, time, size, and attribute. The options may be specified as greater than, less than, equal to, or not equal to. Multiple search options may be given for a search. Please see section 7 for more information on supplying options. When files are found they may be displayed by pathname only or displayed in detail (pathname, date, time, size, and attribute). 4 Hardware Requirements To use BFIND you must have a IBM PC/XT/AT, PS/2, PS/1, or 100% compatible clone. DOS 3.3 or higher is required. BFIND Copyright (C) JEMC Systems, 1991 BFIND.TXT Page 4 5 Installation BFIND may be installed to a hard drive or run from floppy. To run BFIND it must be in the current directory or accessible by way of the 'PATH' environment variable. Please refer to your DOS Manual for more information on running programs and the use of the 'PATH' environment variable. 6 Basic Operation This section covers how to use BFIND and the basics of how it operates. It is assumed that you understand the components of a pathname as it pertains to DOS. If not, then please refer to your DOS manual for more information on pathnames. For a full description of all the available BFIND options please see section 7. The syntax to use BFIND is as follows: BFIND {/h} FindFile {/ADPSTZbdprstlz}{arg arg ...} If requesting BFIND help, the '/h' must be the first argument following the BFIND program name. If '/h' is found then the rest of the command line is ignored and help is displayed. 'FindFile' is the name of the file that you want BFIND to find. It must be a valid DOS pathname and therefore, may specify a drive and directory. Wildcards are permitted. Only the filename portion of 'FindFile' may be wildcarded, the path portion may not. 'FindFile' must be the first argument following the BFIND program name, unless requesting help. 6.1 Filename Wild Cards BFIND contains its own wildcard parser. This allows for greater flexibility in wildcarded filenames. The wildcard characters are: ? - Used to represent 1 character of filename. * - Used to represent 0 or more characters of filename. The wildcard characters perform exactly as they do under DOS, except you may now use wildcarded names of the form "*i?d*.*c". This wildcarded name would cause BFIND to find any file that had an "i" and a "d" in it with one character between the "i" and the "d". The extension would need to have a "c" as the last character, any number of characters may be in the extension as long as "c" was the last one. Examples of filenames that would be found: BFIND.C, IXD.GFC, INDU.TC. A filename of "*" implies "*.*" as it does under DOS. To find all files without extensions you would need to enter a filename of "*.". BFIND Copyright (C) JEMC Systems, 1991 BFIND.TXT Page 5 6.2 Search Action Normally BFIND begins the search for 'FindFile' from the root directory of the current drive regardless of the current directory. If 'FindFile' contains a drive and/or directory, then the search starts on the drive and/or directory specified by 'FindFile'. The following are examples of BFIND and the effects of 'FindFile' on the search: 1) This example finds all occurrences of 'foo.*' starting from the root directory of the current drive. As matching files are found they are printed out using their complete pathname. BFIND foo.* /p 2) This search finds all occurrences of 'foo.*' in the current directory and all directories below the current directory. When a match is found then the matching file is printed out as a complete pathname. BFIND .\foo.* /p 3) This search states that the search will be on drive 'd:' and should start in the directory '\source\devel'. The file to find is 'foo.*'. Note that only '\source\devel' and all directories below it are searched. BFIND d:\source\devel\foo.* /p By supplying additional command line options, a file that matches 'FindFile' may be further qualified as matching by checking its size, date, time, and attribute. It is also possible to search the contents of ZIP files for files that match 'FindFile' and to qualify matches further by checking its uncompressed size, date, time, or attributes. If BFIND is instructed to search ZIP files, then ZIP files are searched as they are encountered. The ZIPs actual filename does not need to match the 'FindFile' argument. The files stored in the ZIP file are searched for a name that matches 'FindFile'. ZIP files are searched for matching filenames only. No check is done on the path portion, if present, of a ZIP file entry. When a ZIP file entry is displayed, any path portion also will be displayed. ZIP files that contain errors in their internal structure are reported whether or not the ZIP contains matching files. BFIND Copyright (C) JEMC Systems, 1991 BFIND.TXT Page 6 7 Option Switches Program options are single character flags that cause BFIND to perform certain actions. Options are introduced with the switch character "/". A single switch character may introduce a single option or a group of options. For example: "/PDz" and "/P /D /z" have the same meaning. The BFIND program is sensitive to the case of options, "/P" is not the same as "/p". Options, such as the one used to search for a date, require an argument. Options and arguments may be intermixed. The first option that requires an argument on the command line is matched up with the first encountered argument. The difference between an option and an argument is that options are introduced by the switch character and arguments are not. For example: "/DT 11/16/58 23:30". The "/D" requires a date as an argument and "/T" requires a time. In the example, "11/16/58" is the argument for the "/D" option and "23:30" is the argument for the "/T" option. Arguments are dependent on position. The first option found that requires an argument, is matched to the first argument found, and so on. If the option order was reversed in the preceding example, the argument order would also have to be reversed; as in "/TD 23:30 11/16/58". To prevent confusion the options may be entered as two single options with arguments: "/D 11/16/58 /T 23:30". The BFIND options are separated into three groups based on their function. The first group is General Options. These options affect the overall operation of BFIND, such as searching inside of ZIP files. The second group is the Qualifier Options. These options qualify a file matching the filename portion of 'FindFile'. The options include checking the files size, date, time, and attributes. The final group is the Operation Options. These display the found and qualified file on your monitor in either a simple single line pathname or a two line pathname, size, date, time, and attribute format. A search status, reporting the number of files searched and found may also be requested. Any number of options may be specified in searching for a file, but individual options may be used only once on a command line. If any option is used more than once, it will override the previous. BFIND Copyright (C) JEMC Systems, 1991 BFIND.TXT Page 7 7.1 General Options These options affect the overall operation of BFIND for the search. They specify how to carry out the search. Any combination of these options can be used except for 'z' and 'Z'. If both 'z' and 'Z' are specified, the last one to appear takes precedence and overrides the other. Switch Description b Batch mode operation. This switch suppresses the program copyright notice. It useful for redirecting output to a file. The shareware advertisement will still be displayed on the screen, it will not follow the redirection. l Level control. This switch requires a number argument. The argument specifies how deep to go into sub-directories. A level of 0 indicates that no sub-directories should be searched. A level of 1 indicates the search should include any sub-directory off the directory where the search begins, but no deeper. If this switch is not used, then all sub-directories will be traversed to the end or the maximum allowed by DOS. r Searches will begin from a sub-directory at the lowest level and proceed up. Lowest level sub-directories will be searched first. Higher level directories will not be returned until all lower level directories have been searched. It is not guaranteed that the deepest directory of all the directories will be returned first, only that the search will always start at an end of a directory branch. z Includes searching ZIP archive files for 'FindFile'. ZIP files must have the default extension of ".ZIP" in order to be searched. The name of the ZIP file being searched will be output only if matching files are found in the ZIP. Z Searches only ZIP archive files for 'FindFile'. ZIP files must have the default extension of ".ZIP" in order to be searched. The name of the ZIP file being searched will be output only if matching files are found in the ZIP. d Return directories that match 'FindFile'. Normally directory names are not returned even if they match 'FindFile'. BFIND Copyright (C) JEMC Systems, 1991 BFIND.TXT Page 8 7.2 Qualifier Options These switches serve to further qualify a file matching 'FindFile'. If any of these options are supplied, the file matching 'FindFile' must also meet the requirements established by these option(s) to be considered a match. Multiple options may be specified for a search but each individual option can be specified only once. Options that require arguments have a default action using the supplied argument, please see section 7.2.1 for details on how to change the default action. Switch Description D Date option. This option requires a date as an argument. By default the date option looks for dates greater than or equal to the supplied date argument. The date argument can be any of the following forms: MM/DD/YY, MM-DD-YY, MM DD YY May 1, 1988, May 01, 88 [Defaults to current year] MM/DD, MM-DD, MM DD [Defaults to current day] MM/YYYY, MM-YYYY, MM YYYY May 1, May 1988 [Defaults to current month & year] DD 1, 02, . . . NOTE: If spaces are used in the date argument, the date must be enclosed in quotes. T Time option. This option requires a time as an argument. The default action of this option is to match all files with the time specified and those that are after the time specified. The time argument can be in any of the following forms and must be specified in 24 hour format: HH:MM:SS, HH-MM-SS, HH MM SS [Default secs equal 0] HH:MM, HH-MM, HH MM [Default mins & secs equal 0] HH NOTE: If spaces are used in the time argument, the time must be enclosed in quotes. BFIND Copyright (C) JEMC Systems, 1991 BFIND.TXT Page 9 S Size option. This option requires a size argument. The argument specifies the size in bytes. The default action of this option is to match all files with the size specified and those that are larger than the size specified. A Attribute option. This option requires an attribute argument to specify the attribute to find. The following are the valid attribute arguments and their meaning: A : Archive attribute. L : Volume label. S : System attribute. H : Hidden attribute. R : Read only attribute. D : Directory attribute. The default search action is to match files whose attributes contain those that are specified plus any others not specified. A files attributes must contain at least those specified to be considered a match. The attribute arguments may be combined as in "BFIND *.SYS /A HS /P". This command would cause all files named "*.SYS" with at least the Hidden and System attributes to be found and displayed. t Today option. Specifies a default search for all files with todays date as read from the PCs clock. 7.2.1 Qualifier Modifiers The Qualifier Options in section 7.2 have a default action. The modifiers detailed here allow that default action to be changed. Modifiers are placed in front of the options argument. If you wanted to search for files with a date of 04/17/92 and display their names, the command would look like: BFIND *.* /Dp =04/17/92 Only a single modifier can be used on an options argument. The following are the available modifiers and their action. Modifier Description + For the arguments of options D,T,and S this is the default action. It indicates a date, time, or size equal to or greater than the found files date, time, or size. For the attribute argument this is also the default action. It specifies that the file found must have at least the attribute(s) specified. = For the arguments of options D,T,and S this modifier indicates that date, time, or size must equal the found files date, time, or size in order to qualify as a match. BFIND Copyright (C) JEMC Systems, 1991 BFIND.TXT Page 10 For the attribute argument this modifier indicates that the found files attributes must exactly match the attribute argument. - For the arguments of options D,T,and S it indicates a date, time, or size less than or equal a found files date, time, or size. For attribute, this modifier indicates that the found files attributes must not contain the attributes specified by the attribute argument. An example is if the attribute argument was 'RD' (read only and directory). All files with either attribute would be considered a match. Any file containing both attributes would not be considered a match. ! For the arguments of options D,T,and S it indicates a date, time, or size not equal to a found files date, time, or size. For attribute, this modifier indicates that the found files attributes must not contain any of the attributes specified by the attribute argument. An example is if the attribute argument was 'RD' (read only and directory). All files with either attribute or both would not be considered a match. 7.3 Operation Options Once a file matching 'FindFile' has been found and qualified by any qualifier options, any of the following operations may be performed on it. In this version of BFIND the operation options are limited to output display and stats gathering only. Both 'p' and 'P' may not appear on the command line at the same time. If they do then the last one typed takes precedence. The stats option may appear alone or with the 'p' or 'P' options. Switch Description p Display 'FindFile' as a complete pathname including drive. If ZIP archives are being searched, the ZIPs filename will be printed only if the ZIP archive contains files matching 'FindFile'. The ZIP filename is preceded by "->" to indicate that this ZIP archive contains files matching 'FindFile'. All matching files from the archive are indented two spaces and preceded by "++" under the archive filename. BFIND Copyright (C) JEMC Systems, 1991 BFIND.TXT Page 11 P This produces a two line output for each matching file. The first line is identical to that produced by the 'p' option above. The second line contains the files date, time, size, and attributes. The second line for matching files in a ZIP archive contain the files size in compressed and uncompressed bytes. The attributes of the matching file are displayed as single letter flags. The letter flags and their meanings are as follows: A : Archive attribute. L : Volume label. S : System attribute. H : Hidden attribute. R : Read only attribute. D : Directory attribute. s Generate Stats report. This option generates a report of the number of directories searched, number of files found, number matching the supplied filename and the total number of bytes and actual bytes occupied on disk by the matching files. If ZIP files are included in the search, the report will contain the total number of ZIPs with matching files and the total number of files in ZIPS matching the supplied filename. The compressed and uncompressed sizes and the percentage of compression. The compression percentage is an average of all matching files. NOTE: The count of directories includes the root directory or starting directory of the search. BFIND Copyright (C) JEMC Systems, 1991 BFIND.TXT Page 12 8 Help Screen The following is the help screen from the BFIND program: BFIND - Basic File Find, Shareware Version Help Screen Copyright (c) JEMC Systems, 1991. All Rights Reserved. Program Version: x.xx.xx Compiled: Mmm dd yyyy hh:mm:ss Syntax: BFIND {/h} PathName {/ADPSTZbdprstlz}{arg arg ...} Search for PathName and further qualify match using Qualifier Options and then perform the Operation Options Specified. PathName must be the first item following the command name unless requesting help (/h). General Options: (b)atch Mode Operation. (l)evel Control. (r)everse Search. (z)ip Files Included. (Z)ip Files Only Searched. (d)irectories Included. PathName Qualifier Options: (D)ate, (T)ime, (S)ize, (A)ttribute - Require Argument, "+-=!" Are Modifiers (t)oday - Acts on Current Date Operation Options: (p)rint Found Files Path. (P)rint Detailed Pathname Info (s)tatus Display. Please Refer To The BFIND Documentation For More Detailed Information. 9 Program Return Messages The following are the information/error messages the BFIND program may return along with their meaning and possible cause. The return codes may be retrieved using ERRORLEVEL in batch file processing or by other programs that may call BFIND. Invalid Option On Command Line - An option was supplied that BFIND does not understand. Reenter the command and verify that the options are all correct and that the case, upper or lower, is correct. BFIND is case sensitive to the option switches. The return code for this error is 1. Missing Option Argument - For an option supplied there was an argument missing. Reenter the command and ensure that you have arguments supplied for all options that require them. The return code for this error is 2. BFIND Copyright (C) JEMC Systems, 1991 BFIND.TXT Page 13 Invalid Attribute Specified - For the attribute option, an invalid attribute character flag was supplied. Reenter the command and verify that the attribute flags of the attribute argument are valid. The return code for this error is 3. Invalid File Size Argument - For the size option an invalid size argument was supplied. Reenter the command and verify that the size argument contains only numbers 0-9. The return code for this error is 4. Invalid Date Argument - For the date option an invalid date argument was supplied. Reenter the command and verify the date argument as valid, refer to section 7.2 for the formats of the date option argument. The return code for this error is 5. Invalid Time Argument - For the time option an invalid time argument was supplied. Reenter the command and verify the time argument as valid, refer to section 7.2 for the formats of the time option argument. The return code for this error is 6. Out Of Memory - Indicates that the BFIND program ran out of memory. BFIND dynamically allocates and frees memory once the program begins. To run BFIND, you must free up additional memory. The return code for this error is 7. Internal Error! - Indicates that an error internal to the BFIND program occurred. Please report this error to JEMC Systems along with the command line used. It is recommended that the PC be rebooted after an error of this type. It is not anticipated that this error will ever come up, but it is there to catch unexpected events. The return code for this error is 252. BFIND Copyright (C) JEMC Systems, 1991 BFIND.TXT Page 14 Directory Engine Fault - This error indicates a failure of the directory search engine used in BFIND. Please report this error to JEMC Systems along with the command line used. Under normal circumstances this error should never occur. The error return code is 253. Help - No message is actually displayed; a return code of 254 is returned to indicate that the BFIND help screen was displayed. 10 Version Notes The following is a list of released versions of BFIND. Version 1.00.00, August 1992. Initial release of BFIND. BFIND Copyright (C) JEMC Systems, 1991 BFIND.TXT Page 15 11 In Closing JEMC Systems will attempt to support this program as best it can. Please report any problems/bugs to JEMC Systems. JEMC Systems would appreciate any feedback, comments and requests for features. Customized versions of this program may also be requested. If this software is of use to you and wish to continue using it past the 1 month trial date, you MUST register your copy. Please see section 12 on becoming a registered user. The BFIND program is written in C++ and compiled using the Borland C++ Compiler. Portions are written in assembler and assembled using the Borland Turbo Assembler. Please note that this program is copyrighted. You may not sell unmodified or modified versions of this program. For registration, problems, questions, or comments, JEMC Systems can be reached at: JEMC Systems PO Box 822 Crown Point, In 46307 ** Brand and product names mentioned are trademarks or registered trademarks of their respective holders. BFIND Copyright (C) JEMC Systems, 1991 BFIND.TXT Page 16 12 BFIND Registration This registration form is for individual users. The cost to register individual BFIND programs is $8.00 U.S. for each copy. Businesses, corporations and LAN users should contact JEMC Systems at the address below for registration and site license pricing information. Please include a fax number for a quicker response. JEMC Systems does not require that you register one copy of BFIND for each machine that you use, as long as there is no chance of BFIND being run simultaneously on the machines that it is loaded on. The program may be loaded on multiple machines, but must be active on only one at a time. If BFIND will be running on more than one machine at a time, then you must register as many copies as will be running. This makes it convenient to use at home and work on the PC that YOU use. When you mail in your registration form and fee you will receive a registered copy of the most current version of the BFIND program and documentation. The registered copy will not display the advertisement present in the Shareware version. You also will receive an unbound users manual. JEMC Systems will support registered copies of the BFIND program for a period of 90 days from the date shipped. All support is initiated by mail at this time. If JEMC Systems is supplied with a phone number along with a problem description, JEMC Systems will respond by phone. During the 90 day support period of registered versions of BFIND, JEMC Systems will provide the following: o JEMC Systems will attempt to correct program bugs within a reasonable time frame and to the satisfaction of the user. JEMC Systems reserves the right to determine what is a true program bug. If a program bug cannot be corrected or be corrected within a reasonable time frame, JEMC Systems will refund the cost of registration. o If there is a software/hardware incompatibility that cannot be overcome to the satisfaction of the user, JEMC Systems will refund the cost of registration. NOTE: If the cost of registration is refunded, the user agrees to cease the use of the registered and Shareware versions of BFIND. The user must erase/destroy all copies of the registered version of BFIND and its associated documentation. After the 90 day support period, JEMC Systems will still attempt to correct all reported bugs and provide fixes. Support for BFIND is free to registered users. After the initial 90 day support period JEMC Systems will make no refunds on the registration fee. BFIND Copyright (C) JEMC Systems, 1991 BFIND.TXT Page 17 Registered users will be informed of updates and bug fixes to the program. Major bug fixes to the program will be offered to registered users for only the cost of shipping. Registered users also will be informed of new products. Please make checks payable to "JEMC Systems" and mail registration form and fee (credit cards not accepted) to: JEMC Systems PO Box 822 Crown Point, In 46307 BFIND Copyright (C) JEMC Systems, 1991 BFIND REGISTRATION FORM, Version 1.00.00 (Please Print) NAME:_____________________________________________________________ Last First MI ADDRESS:__________________________________________________________ __________________________________________________________ __________________________________________________________ PHONE (Optional): ____-____-____________ Registration Cost: $8.00/ea Quantity : ________ @ $8.00/ea Amount Enclosed: $________ (Please Make checks payable to JEMC Systems) Floppy Type: ___ 360k ___ 1.2m ___720k ================================================================== Optional Information (Not required to register): PC Type (Make and CPU, ISA, EISA):________________________________ __________________________________________________________________ Video Adapter (Make and Type):____________________________________ __________________________________________________________________ COMMENTS:_________________________________________________________ __________________________________________________________________ __________________________________________________________________ __________________________________________________________________ __________________________________________________________________ __________________________________________________________________ BFIND Copyright (C) JEMC Systems, 1991 1 Copyright and Distribution ................................... 1 2 Disclaimer ................................................... 2 3 Introduction ................................................. 3 4 Hardware Requirements ........................................ 3 5 Installation ................................................. 4 6 Basic Operation .............................................. 4 6.1 Filename Wild Cards ................................. 4 6.2 Search Action ....................................... 5 7 Option Switches .............................................. 6 7.1 General Options ..................................... 7 7.2 Qualifier Options ................................... 8 7.2.1 Qualifier Modifiers ....................... 9 7.3 Operation Options .................................. 10 8 Help Screen ................................................. 12 9 Program Return Messages ..................................... 12 10 Version Notes .............................................. 14 11 In Closing ................................................. 15 12 BFIND Registration ......................................... 16 BFIND Registration Form ....................................... 18 BFIND Copyright (C) JEMC Systems, 1991