WildCat File Tools Version 4.00 Copyright (C) 1994 Daniel A. Gulkis The Data Center BBS (305-436-5070), 1:369/121 All Rights Reserved INTRODUCTION Thank you for evaluating the WildCat File Tools, a set of utilities designed to help WildCat system operators manage their file database. Presently, this package consists of seven tools. The first four tools are distributed as shareware; the remaining three are included with your registration. The shareware tools are: FILEDESC: A fast and flexible ALLFILES report generator. Very easy to use. Handles an unlimited number of files. FILESUM: Creates a bulletin which shows the number of files, the total size, and the number of downloads for each file category. CDUSAGE: For each CDROM, show the number of files, the total size, and the number of downloads. Quickly reveals which disks are contributing the most to your system. WCTOUCH: Freshens files in the database by updating their date, time, and size. With your registration, you receive printed documentation and the following three tools: MASSDEL: Deletes files from the database. Can use a filter or an explicit list of files. Optionally deletes the actual files from disk. MASSMV: Moves all matching files to a specified file category. CDL: Changes a CDROM's drive letter in the file database. REQUIREMENTS Each utility will be fully described in the following pages. You must use WildCat version 4.0 or later for correct operation. In addition, if you have the single line version, then you must take your board down before running any of these tools. For the multiline version, you must assign a unique node number using the WCNODEID environment variable. Failure to heed these cautions may cause damage to WildCat's databases. Each tool finds MAKEWILD.DAT using the following steps. If an environment variable named WCHOME exists, it should point to the directory containing MAKEWILD.DAT. Otherwise, the tools search the current directory and then every directory on your PATH. Several of the utilities use the current directory for temporary files, so don't run them when logged onto a CDROM or a write protected disk. 2 FILEDESC FILEDESC creates a list of files available for download on your BBS; this list is commonly called an ALLFILES report. Your users can download the list and peruse it at their leisure, rather than tying up your phone line while they look for a certain file. Among the programs which create ALLFILES reports, you will find FILEDESC to be the best! Why? Well, glad you asked: Ease of Use: You create a configuration file using a full screen form. Simply choose the filtering, formatting, and output options you want. No more cryptic command line switches or tempermental ASCII configuration files. If you desire, FILEDESC will compress your report, move it to a download directory, and update the corresponding database entry to reflect the new date and size. Flexibility: You have many filtering options that let you specify which files should appear in a report. You can include files based on file category, the CDROM they reside on, their age, the number of accesses, and more. You also have control over the format of the report. Choose a single line, double line, or single/double line report. Sort alphabetically or by age within each area. Turn subtotals and the grand total on or off. Include your own report header, report footer, and section headers. Speed: FILEDESC makes use of the file database's index to process only the file areas you have chosen to include. The final report is directly generated without intermediate passes. You will typically see several hundred files processed per second. Few Limits: Your reports can contain a virtually unlimited number of files, instead of only the number of files which fit in memory. The file size grand total will accumulate up to 100 gigabytes without overflowing. Using FILEDESC FILEDESC is actually two programs in one. It contains a configuration file editor and a report generator. You create a configuration file detailing exactly which files you want to appear in the report and how the report should look. You only need to do this step once, even if you generate the report every day. If you want to print several 3 different reports, then you will create a configuration file for each one. Next, you actually generate the report. The report generation is fully automatic, and can be started from your nightly processing batch file if desired. To edit a configuration file, type: FILEDESC [filename.cfg] If the file you specified exists, then it will be loaded into the configuration editor. Otherwise, the editor will be initialized with suggested values. If you don't specify the configuration filename, then a default name of FILEDESC.CFG is used. When editing a configuration file, simply enter values into each field. A short description of the current field is displayed on the bottom line. To move between fields, use the Enter key or the arrow keys. When you have finished making changes, press the Return key to accept changes in the current field and the Escape key to exit. You will then be asked if you want to save your changes. To run reports, type: FILEDESC /R [report1.cfg] [report2.cfg] ... You may include one or several configuration files on the command line. Each report will be generated in turn. If you don't list any configuration files, the default FILEDESC.CFG file will be used. As each report is generated, the file category being processed is displayed in the top window on the screen and the actual report being generated shows in the bottom window. You may press the Pause key to temporarily suspend output. If you do this, the bottom window may pause while it is scrolling. This causes a line to appear twice. Don't be alarmed; the report won't contain the duplicate line. To resume report generation, press any key. If you want to halt report generation, press the Escape key. The current report will be terminate immediately. Any other reports specified on the command line will be skipped. Configuration File Editor The configuration file editor is divided into three major sections. The first section, Filters, allows you to select which files will be included on the report. Next, the Formatting Options section lets you fine tune the look of your report. Finally, in the Output Options section, you choose the name for your report, and whether you want the 4 report freshened in the database. Below, each field is described: Filters: Include Areas: Enter the file categories that you want to appear in the report. You may list single categories or ranges, separated by spaces. Or, leave this field blank to include all categories. Example: 1-25 31 36 50-104 45 Exclude Areas: The file categories that you want to omit from the report. Sometimes it is more convenient to choose a large range of categories to include and then just specify a few to exclude. The categories listed here are removed from the list of included file categories. Example: 17 11-14 Drive Letters: This option lets you select the files from any CDROM or the files which are stored on your hard drive. The drive letter of a file can be found by looking at its stored path. If the stored path is empty, then the file is considered to be on drive 0 (zero). If left blank, all drive letters are included. Enter individual drive letters or ranges, separated by spaces. Example: 0 (Selects files without a stored path) Example: S-U (Selects files on drives S, T, or U) Date, From and To: Enter the minimum and maximum age (in days) of files to include. This option lets you include only new files or only old files. Example: 0 to 30 (Select files up to 30 days old) Example: 365 to 9999 (Select files at least one year old) Accesses, From and To: Enter the minimum and maximum access count for files to include. These fields can be used to show your most popular or least popular files. Example: 0 to 0 (Select files which have never been accessed) Example: 10 to 9999 (Select files accessed at least 10 times) 5 Normal Files: Choose Y to include typical files--those which have not failed the virus scan, don't have a password, and aren't offline. Most of the time, this option will be Y. But if you want to see just files which failed the virus scan, for example, then put N here. Failed Scan Files: Enter Y to include files which have failed the virus scan. Password Files: Select Y to include password protected files in the listing. Offline Files: Pick Y to include any offline files in the report. Formatting Options: Sort Order: Enter 1 to sort alphabetically within each area or 2 to sort by date within each area. Show Subtotals: If you want a subtotal showing the number of files and bytes printed after each file category, enter Y. Report Type: Three report types are available. Type 1 is a combined single/dual line report. If the description doesn't fit on a single line, then it wraps to the next line and is indented. Type 2 is a single line report similar to Wildcat's single line format. Type 3 produces a double line report which resembles the Wildcat double line format. Show Total: Entering Y displays a grand total of files and bytes at the bottom of the report. Use Headers: This simple yes/no question is perhaps the most complex configuration item. If you pick N, then the standard file category headers will be used. But if you choose Y, then you can use your own report header, report footer, and file category headers. These headers are entered into ASCII files which are located in the directory where FILEDESC is run. There are two basic strategies: you can create individual 6 files for each specific area or you can create a single file which contains the headers for each area. These methods can be combined. When processing custom headers, FILEDESC first tries to get a header from the single, combined file. If that fails, then it will attempt to get a header from a file which matches the current area. If that also fails, then the standard header will be used. This approach allows you to define custom headers for just a few file categories, instead of requiring every category to have one. The filenames used by the header files consists of the name of your configuration file with a special extension. The filename of the combined header file, which can contain a header for each area is cfgfile.HDR. The format of cfgfile.HDR follows: [HEADER] This is the report header. Use as many lines as you need in any section. A section is terminated by a line which begins with a left bracket. [1] This is the header for file category 1. It is important that each section begins with a left bracket, the section name, and then a right bracket on a line by itself. [] This is ignored, since the line above terminates category 1, but the footer doesn't start until after the line below. [FOOTER] Finally, this footer will be printed at the bottom of the report. This example shows the sections in order, with the header first and the footer last, but that isn't important. You can list sections in any order you want. This last section will be terminated by the end of the file. For individual header file, the filenames are: cfgfile.TOR -- Report Header (Top of Report) cfgfile.nnn -- Individual file category, nnn is 000, 001, ... , 999. The 000 extension indicates category 1000. Note: This method only works for category numbers up to 1000. Otherwise, use the cfgfile.HDR method. cfgfile.BOR -- Report Footer (Bottom of Report) 7 Output Options: Text Filename: Enter the name of the output file. This field must be entered. The report will be generated in the current directory. Freshen Text File: If you select Y, then the text filename will be freshened in the Wildcat file database. For freshening to work, the file must already exist in the database. The text file will be moved from the current directory to the primary area defined by the file category. Then the database date, time, and file size will be updated. Compressed Filename: Enter the name of the compressed output file. This field is used in conjunction with the next field to freshen the ALLFILES report in the Wildcat database. Freshen Compressed File: If you enter Y and the compressed filename already exists in the WildCat file database, then when the report has been generated it will be moved to the file area specified in the database. The database date, time, and file size will be updated. Compression Command: Enter the command needed to create the compressed report from the text report. Leave this field blank if you don't want a compressed report. To keep the text report, use the archiver's add option. Use the move option to delete the text report after it has been compressed. Example: pkzip -m allfiles.zip allfiles.txt (Deletes allfiles.txt) Example: pkzip -a allfiles.zip allfiles.txt (Keeps allfiles.txt) 8 FILESUM The FILESUM utility produces a summary report from the file database. For each file category, the number of files, the total size of the files, and the total downloads are listed. A grand total of files, size, and downloads appears at the bottom of the summary. You don't need to worry about overflowing the capacity of the total size. Up to 100 gigabytes can be accurately reported. You can use this information in several ways. It can tell you which file categories should be split because they are too cluttered. It also shows you the most popular categories. Your callers can see what type of files your board specializes in and can also see just how many files you have. FILESUM is an easy utility to run; no parameters are required. Before generating the reports, the entire file database must be scanned. While hundreds of files are scanned per second, it takes a few minutes if you have a large file database. A bar graph and numerical percentage count keep you informed on the progress. You may press Escape to cancel the scan at any time. When the scan completes (or is cancelled), the program will create two reports in the current directory: a plain ASCII text version which is named FILESUM.TXT and a version with WildCat color codes which is named FILESUM.BBS. You might want to run FILESUM from a nightly processing batch file. After it completes, the batch file can copy FILESUM.BBS to a bulletin for viewing by your users. 9 CDUSAGE CDUSAGE is an interactive tool used to analyze the contributions each CDROM makes to your file database. You can see the number of files, the total size, and the number of downloads for each CDROM in your system. You can easily tell the most popular CDROMs from the least popular. CDUSAGE does not require any command line parameters. You simply run the program and it will begin generating the analysis. Since this program has to scan every record in your file database, it may take a few minutes if your file database is large. You can press Escape at any time to abort the scan and exit the program. When you exit the program, either by pressing Escape or by waiting until the scan finishes, a report called CDUSAGE.TXT is created in the current directory. This report contains the same information found in the on-screen display. Each file is classified as belonging to a specific CDROM by looking at the Path field in the file database. If this field is empty, then the file is assumed to be on your hard drive. Otherwise, the first character of the Path is taken to be the drive letter of the CDROM that holds the file. 10 WCTOUCH WCTOUCH is used to "freshen" files in the WildCat file database. The term freshen means to update a file entry in the database to reflect the current date and time and the file's current size. WCTOUCH will not add a new file entry to the database; it only updates a pre-existing entry. If you have allowed duplicate filenames, WCTOUCH will only update the first matching filename it finds. To run WCTOUCH, enter the program name followed by the filenames that you want to freshen. If you have many files to freshen, a response file can be used. A response file is just a plain ASCII file which contains the filenames to freshen, one per line. To use a response file, list it on the command line preceded by the @ symbol. Wildcards can not be used either on the command line or in response files. To update the files A1.ZIP, ALLFILES.ZIP, and REGISTER.TXT, use the following: WCTOUCH A1.ZIP ALLFILES.ZIP REGISTER.TXT Or, assume that NIGHTLY.WCT contains the filenames WELCOME.ZIP, EMAIL.ZIP, FILES.ZIP, and DOORS.TXT (one per line). You also want to update REGISTER.TXT and ALLFILES.ZIP: WCTOUCH @NIGHTLY.WCT REGISTER.TXT ALLFILES.ZIP 11 MASSDEL With MASSDEL, you can rapidly delete numerous files from the WildCat file database. You can specify which files to delete using one of two methods. Filtering similar to that provided with FILEDESC can be used. Or, an explicit list of files to be deleted may be specified on the command line or in response files. MASSDEL has many uses. For example, you can delete all files on hard drive (but not CDROM) that are older than 180 days and haven't had any downloads. Or if you want to replace a CDROM, you can delete all files on that drive. If you are changing the focus of your BBS, you can delete whole file areas with ease. There are three different ways to invoke MASSDEL. The first two are exactly like FILEDESC. To edit a filter, use: MASSDEL [filter.cfg] To delete files matching a filter (or several filters), enter: MASSDEL /R [filter1.cfg] [filter2.cfg] ... If no file is specified, the default MASSDEL.CFG is used. Finally, you may delete a list of files, including those in response files, by typing: MASSDEL /[I | D] [file | @rspfile] [file | @rspfile] ... If you use the /I option, then MASSDEL will only delete the files from WildCat's file database. The actual files on the disk will be untouched. The /D option deletes the specified files from the database and the disk. At any time during the deletions, you may stop the process by pressing the Escape key. This will not restore any of the files which have already been deleted. 12 MASSMV MASSMV serves two purposes. First, it lets you transfer all the files matching a specified filter to a new file category. Files on CDROM will just have their file category updated. Files on your hard disk will be moved to the path appropriate for the new category. Second, you can transfer files which match a filter from CDROM to your hard drive. Each matching file will be copied to the appropriate directory. Then the stored path will be erased and the On_CDROM flag will be turned off. These two features can be used separately or combined. That is, you can use MASSMV to move a group of files to a single category or use it to move CDROM files to the hard drive without changing the category. Or, you can do both at the same time. Before you can move any files, you must first create a configuration file. The procedure is exactly the same as FILEDESC for the filter section. To edit or create a configuration file, enter: MASSMV [cfgfile.cfg] The bottom section of the configuration editor contains three questions. If you want to move files to a new category, answer Y to that question and enter the new category number. To move files from CDROM to your hard drive, just answer Y to the last question. After you have created a configuration file, move the files by typing: MASSMV /R [cfgfile1.cfg] [cfgfile2.cfg] ... If no configuration file is specified, the default MASSMV.CFG will be used. You can stop moving files at any time by pressing the Escape key. However, this will not replace files which have already been moved. 13 CDL CDL stands for "Change Drive Letter." It searches the entire WildCat file database, changing the drive letter in the file path from a source drive to a target drive that you specify. It ignores files with paths that don't match the source drive letter. You will find two major uses for CDL. First, the drive letter for your CDROM may change due to hardware updates, such as adding a new disk drive. Now your CDROM is drive E, but all the files in the database refer to drive D! CDL will let you fix this problem by changing all the file database entries to reflect the new drive letter. For future reference, you can specify a more distant drive letter (such as drive M) for the CDROM. Just add /L:d to MSCDEX, where d is the drive letter to use for the CDROM. This will make your system less sensitive to subsequent hardware changes. The second major use is if you want to move a CDROM from one drive to another. For example, you may have a six disk CDROM changer and three single disk players. You like to keep the most popular disks in the single disk players to minimize disk switching in the changer. You just used CDUSAGE to find which disks are most popular and now will use CDL to move the disks around. WARNING: If you want to swap the files from two CDROM drives, you must do the following. First, use CDL to change the first drive letter to a temporary, unused drive letter. Then change the second drive letter to the first drive letter. Finally, change the temporary drive letter back to the second drive letter. If you had simply changed the first drive letter to the second drive letter, then CDL would not be able to differentiate between the files that belonged to the first CDROM and those on the second CDROM. You would have a big mess! Invoking CDL is straightforward. The two parameters are source and destination drives, in that order. For example, to change D: to E:, type: CDL D: E: You may press Escape to halt the conversion at any time. However, the files which have already been converted will not be changed back. 14 REGISTRATION The WildCat File Tools are distributed as shareware. You are granted a 30 day trial period to evaluate this package. If you find it useful, then you are obligated to register it, at a cost of $15 plus $3 shipping and handling. Florida residents add $0.90 for tax. When you register, you will receive three additional tools -- MASSDEL, MASSMV, and CDL -- which have already been discussed. You may register the WildCat File Tools using a check, money order, Visa, or MasterCard. For credit card orders, please include the expiration date. Send payment to: Daniel A. Gulkis PO Box 820695 South Florida, FL 33082-0695 If you have any comments on the WildCat File Tools, I can be reached at the address above, at The Data Center BBS (305- 436-5070), or as Dan Gulkis at 1:369/121. WARRANTY The WildCat File Tools are provided without any warranty, expressed or implied. In no event shall the author be liable for damages arising out of the use of this program. While these utilities have been thoroughly tested, it is impossible to try every combination of hardware and software. Therefore, it is highly recommended that you back up your system before using this package. LICENSE The shareware WildCat File Tools package may be distributed to others under the following two conditions. First, no fee, other than a nominal distribution fee, may be charged. Second, all related files must be distributed without modification. The additional tools provided with registration are not shareware and may not be distributed to others. 15