ProfitPress Mega CDROM2 Shareware Freeware (MSDOS)(1992)(Eng)

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

/ ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng) / ProfitPress-MegaCDROM2.B6I / UTILITY / DISK / WSSI501A.ZIP / WSSI501.DOC next >

Wrap

Text File | 1990-06-19 | 239.5 KB | 5,810 lines

Wssindex 5.01 Disk Indexing Software for MS/PC-DOS Programs and documentation copyright (c) 1985-1990 by Robert W. Babcock and WSS Division of DDC All Rights Reserved License Terms The demo version of WSSINDEX and associated files may be freely distributed provided that the entire package is made available and only a reasonable copying fee is charged. The demo version is functional and fully documented, except that WSSINDEX and CUSTPRNT display commercials on start up and WSSINDEX will not save a database with more than 1000 files. Purchasers of the complete package will receive the demo package plus uncrippled replacements for WSSINDEX and CUSTPRNT and instructions for "un- locking" future demo releases. These are licensed for use by a single user, or on one machine at a time, and are not to be dis- tributed. Site license users may, of course, use as many copies as specified in their license. If there is any question about multiple machines or users, the "like-a-book" rule applies: it should be impossible for more than the licensed number of copies to be used simultaneously. 30 Day limited Warranty The software in the complete package is warranted to perform substantially as documented for a period of 30 days from your date of receipt. The media on which either the complete or eval- uation version of this software is provided is warranted to be readable for the same 30 day period. All other warranties relat- ing to this software, whether expressed or implied, are dis- claimed. Determination of the suitability of this software for a particular purpose is the responsibility of the user. In no event shall WSS Division of DDC or Robert W. Babcock be liable for damages exceeding the price paid to license this software. Table of Contents Introduction . . . . . . . . . . . . . . . . . . . . . . . . 1 Installation . . . . . . . . . . . . . . . . . . . . . . . . 1 Unlocking Demo Releases . . . . . . . . . . . . . . . . . . . 2 Overview and Tutorial . . . . . . . . . . . . . . . . . . . . 3 Setup and General Information . . . . . . . . . . . . . . . . 6 Starting up . . . . . . . . . . . . . . . . . . . . . . . . . 7 Command Defaults . . . . . . . . . . . . . . . . . . . . . . 8 Aborting commands . . . . . . . . . . . . . . . . . . . . . . 8 The Dreaded Abort, Retry, Ignore? . . . . . . . . . . . . . . 8 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 Archive Files . . . . . . . . . . . . . . . . . . . . . . . 10 Archive Formats Supported . . . . . . . . . . . . . . . 11 Main Menu . . . . . . . . . . . . . . . . . . . . . . . . . 13 Quick Find . . . . . . . . . . . . . . . . . . . . . . 14 Print and other output menu . . . . . . . . . . . . . . 14 Display statistics . . . . . . . . . . . . . . . . . . 14 Directory . . . . . . . . . . . . . . . . . . . . . . . 14 Push to DOS . . . . . . . . . . . . . . . . . . . . . . 15 Write database on disk . . . . . . . . . . . . . . . . 15 Quit and return to DOS . . . . . . . . . . . . . . . . 15 Quick Quit and return to DOS . . . . . . . . . . . . . 16 Add or label disks . . . . . . . . . . . . . . . . . . 16 Add/modify Comments . . . . . . . . . . . . . . . . . . 16 ReName a disk in the database . . . . . . . . . . . . . 16 ReName a disk with a mixed case label . . . . . . . . . 16 Remove a disk from the database . . . . . . . . . . . . 16 Remove all disks . . . . . . . . . . . . . . . . . . . 16 Get a database from disk . . . . . . . . . . . . . . . 16 Get configuration file and matching database . . . . . 16 Change cOnfiguration . . . . . . . . . . . . . . . . . 17 Print menu . . . . . . . . . . . . . . . . . . . . . . . . 17 Print (and sort) . . . . . . . . . . . . . . . . . . . 17 Find a file in the database . . . . . . . . . . . . . . 21 Quick Find . . . . . . . . . . . . . . . . . . . . . . 21 Zippy find . . . . . . . . . . . . . . . . . . . . . . 21 List Duplicate files . . . . . . . . . . . . . . . . . 21 List Unique files . . . . . . . . . . . . . . . . . . . 21 List files which are not Backed up . . . . . . . . . . 22 Wssindex 5.01 i Table of Contents List Volume names . . . . . . . . . . . . . . . . . . . 22 Quick list of Volume names . . . . . . . . . . . . . . 23 Return to main menu . . . . . . . . . . . . . . . . . . 23 Indexing Menu . . . . . . . . . . . . . . . . . . . . . . . 23 Start Indexing . . . . . . . . . . . . . . . . . . . . 24 Add dummy entries . . . . . . . . . . . . . . . . . . . 25 List directory . . . . . . . . . . . . . . . . . . . . 25 Label a disk on the labeling drive . . . . . . . . . . 25 COnfiguration menu . . . . . . . . . . . . . . . . . . 26 First indexing drive . . . . . . . . . . . . . . . . . 26 Second indexing drive . . . . . . . . . . . . . . . . . 26 LaBeling drive . . . . . . . . . . . . . . . . . . . . 26 Indexing sTarts from . . . . . . . . . . . . . . . . . 26 Auto-category strinG . . . . . . . . . . . . . . . . . 26 Ask before replacing . . . . . . . . . . . . . . . . . 26 Auto-Comment . . . . . . . . . . . . . . . . . . . . . 27 AUto-category . . . . . . . . . . . . . . . . . . . . . 27 Make .ID entries . . . . . . . . . . . . . . . . . . . 27 DummY entries include subdirectory tree . . . . . . . . 27 Query archive extraction . . . . . . . . . . . . . . . 27 Index Hidden files . . . . . . . . . . . . . . . . . . 27 Extract archive comments . . . . . . . . . . . . . . . 27 Primary Configuration Menu . . . . . . . . . . . . . . . . 28 Printer configuration . . . . . . . . . . . . . . . . . 28 SiZe limits . . . . . . . . . . . . . . . . . . . . . . 28 Indexing options . . . . . . . . . . . . . . . . . . . 28 Screen, keyboard and Miscellaneous . . . . . . . . . . 28 Default sorting/selection options . . . . . . . . . . . 28 Keyboard macros . . . . . . . . . . . . . . . . . . . . 28 Configured Exception list . . . . . . . . . . . . . . . 29 Which fields to print . . . . . . . . . . . . . . . . . 29 Output Format . . . . . . . . . . . . . . . . . . . . . 29 Load configuration file . . . . . . . . . . . . . . . . 29 Save configuration file . . . . . . . . . . . . . . . . 29 Return to previous menu . . . . . . . . . . . . . . . . 30 Printer Configuration Menu . . . . . . . . . . . . . . . . 30 Paper Width to right margin . . . . . . . . . . . . . . 30 Paper Length . . . . . . . . . . . . . . . . . . . . . 31 Left Margin . . . . . . . . . . . . . . . . . . . . . . 31 Top margin . . . . . . . . . . . . . . . . . . . . . . 31 Bottom margin . . . . . . . . . . . . . . . . . . . . . 31 Use Form feeds . . . . . . . . . . . . . . . . . . . . 31 Pause at page breaks . . . . . . . . . . . . . . . . . 31 Database Size Limits . . . . . . . . . . . . . . . . . 31 Indexing Configuration Menu . . . . . . . . . . . . . . . . 32 Indexing drive number . . . . . . . . . . . . . . . . . 33 Make .ID entries . . . . . . . . . . . . . . . . . . . 33 Ask Before replacing . . . . . . . . . . . . . . . . . 33 Wssindex 5.01 ii Table of Contents Auto coMment . . . . . . . . . . . . . . . . . . . . . 34 Auto caTegory . . . . . . . . . . . . . . . . . . . . . 34 Ask before eXtracting archive info . . . . . . . . . . 34 Extract comments from archive files . . . . . . . . . . 34 Auto cateGory string . . . . . . . . . . . . . . . . . 34 Extension for extraction . . . . . . . . . . . . . . . 34 Miscellaneous Configuration Menu . . . . . . . . . . . . . 34 Perform automatic inteGrity check . . . . . . . . . . . 35 Function Key layout matching IBM . . . . . . . . . . . 36 Inverted meaning for PgUp/PgDn . . . . . . . . . . . . 36 Create .BAK files . . . . . . . . . . . . . . . . . . . 36 Enable Alarm sound . . . . . . . . . . . . . . . . . . 37 Change Prompt in DOS shell . . . . . . . . . . . . . . 37 Strip High-bit when viewing files . . . . . . . . . . . 37 Use color . . . . . . . . . . . . . . . . . . . . . . . 37 Use Mouse . . . . . . . . . . . . . . . . . . . . . . . 37 Mouse Sensitivity . . . . . . . . . . . . . . . . . . . 37 Set Colors . . . . . . . . . . . . . . . . . . . . . . 37 Video board configuration . . . . . . . . . . . . . . . 37 Return to primary configuration menu . . . . . . . . . 38 Default Sorting and Selection Options Menu . . . . . . . . 38 Selection list . . . . . . . . . . . . . . . . . . . . 38 Sort Keys . . . . . . . . . . . . . . . . . . . . . . . 38 Return to previous menu . . . . . . . . . . . . . . . . 38 Output Fields Configuration Menu . . . . . . . . . . . . . 38 DuPlicate flag . . . . . . . . . . . . . . . . . . . . 39 Size . . . . . . . . . . . . . . . . . . . . . . . . . 39 Date . . . . . . . . . . . . . . . . . . . . . . . . . 39 Time . . . . . . . . . . . . . . . . . . . . . . . . . 39 Seconds . . . . . . . . . . . . . . . . . . . . . . . . 39 Volume . . . . . . . . . . . . . . . . . . . . . . . . 39 SuBdirectory . . . . . . . . . . . . . . . . . . . . . 39 Archive file name . . . . . . . . . . . . . . . . . . . 39 Comment . . . . . . . . . . . . . . . . . . . . . . . . 39 CateGory . . . . . . . . . . . . . . . . . . . . . . . 39 Output Format Configuration Menu . . . . . . . . . . . . . 40 Number of Blank lines between headers . . . . . . . . . 40 Number of blank lines after Headers . . . . . . . . . . 40 File name style . . . . . . . . . . . . . . . . . . . . 40 Date style . . . . . . . . . . . . . . . . . . . . . . 40 Field width for Subdirectories . . . . . . . . . . . . 41 Field width for Archive name . . . . . . . . . . . . . 41 Field width for Comment or category . . . . . . . . . . 41 Archive file delImiter . . . . . . . . . . . . . . . . 41 Category deliMiter . . . . . . . . . . . . . . . . . . 41 Print comments bEfore categories . . . . . . . . . . . 41 Always start New line for comment/category . . . . . . 41 Truncate to fit on one line . . . . . . . . . . . . . . 41 Wssindex 5.01 iii Table of Contents Return to primary configuration menu . . . . . . . . . 41 Video Board Configuration . . . . . . . . . . . . . . . . . 41 Screen writing method . . . . . . . . . . . . . . . . . 42 Suppress snoW on CGA . . . . . . . . . . . . . . . . . 42 Raw Mode on screen output . . . . . . . . . . . . . . . 42 Return to previous menu . . . . . . . . . . . . . . . . 42 Color Selection Menu . . . . . . . . . . . . . . . . . . . 42 The Add-Comments Menu . . . . . . . . . . . . . . . . . . . 44 WSSINDEX Utilities . . . . . . . . . . . . . . . . . . . . 48 CUSTPRNT - Custom Print Utility . . . . . . . . . . . . 48 Multi-column printing . . . . . . . . . . . . . . . 49 List files which are not Backed up . . . . . . . . . 49 Disk Covers . . . . . . . . . . . . . . . . . . . . 49 Display statistics . . . . . . . . . . . . . . . . . 50 Get a database from disk . . . . . . . . . . . . . . 50 Disk Labels . . . . . . . . . . . . . . . . . . . . 50 Change cOnfiguration info . . . . . . . . . . . . . 51 Quit and return to DOS . . . . . . . . . . . . . . . 51 Quick Quit . . . . . . . . . . . . . . . . . . . . . 51 Read a printer definition file . . . . . . . . . . . 51 Push to DOS . . . . . . . . . . . . . . . . . . . . 51 List Volume names . . . . . . . . . . . . . . . . . 51 Quick list of Volume names . . . . . . . . . . . . . 51 Printer Definition Files . . . . . . . . . . . . . . 51 WSIMPORT Comment Import Routine . . . . . . . . . . . . 56 IDADD Conversion Utility . . . . . . . . . . . . . . . 58 WSSMERGE Database Merging Utility . . . . . . . . . . . 59 SPLIT Database Splitting Utility . . . . . . . . . . . 60 Database Conversion Utilities . . . . . . . . . . . . . 61 Problems and Solutions . . . . . . . . . . . . . . . . . . 62 Hard/software requirements . . . . . . . . . . . . . . 62 Known incompatibilities with other software . . . . . . 62 Disk Cache Warning . . . . . . . . . . . . . . . . . 62 Incompatible TSR . . . . . . . . . . . . . . . . . . 62 Answers to Common Questions . . . . . . . . . . . . . . 63 Command Line Parameter Summary . . . . . . . . . . . . . . 66 Support . . . . . . . . . . . . . . . . . . . . . . . . . . 67 The Distribution Package . . . . . . . . . . . . . . . . . 68 Ordering Information . . . . . . . . . . . . . . . . . . . 69 WSSINDEX Price schedule . . . . . . . . . . . . . . . . 69 WSSINDEX ORDER FORM . . . . . . . . . . . . . . . . . . 72 Appendix A - ANSI.SYS screen driver . . . . . . . . . . . . 73 Wssindex 5.01 iv Table of Contents Appendix B - Expanding the DOS Environment . . . . . . . . 75 Appendix C - WSSINDEX Database Format . . . . . . . . . . . 76 Appendix D - Character Code Conversion Table . . . . . . . 78 Appendix E - WSSINDEX for DEC Rainbow . . . . . . . . . . . 79 Appendix F - WSSINDEX for TI Professional . . . . . . . . . 80 Appendix G - WSSINDEX for WANG PC . . . . . . . . . . . . . 81 Wssindex 5.01 v Table of Contents Introduction Have you ever had to search through dozens of disks trying to find a program or data file which you knew you had somewhere? WSSINDEX.EXE is a program designe to help keep track of MS-DOS files stored on floppy or hard disks. A database is created which contains, for all of your disks, the information normally available from the DOS DIR command, as well as optional comments and categories describing each file. The information in the database may be printed with various sorting options, or may be searched for specific file names with wild cards in case you don't remember the exact name of the file you are looking for. Additional functions include listing files without current backup copies and extracting directory information from archive files of various types. The program is menu driven and easy to use with- out referring to the documentation, but please read it once any- way. If you are a new user, you should first read the Overview and Tutorial section. Installation Before you do anything else, make sure that the disk(s) you received are write protected, and then make at least one backup copy. The disks are not copy protected. WSSINDEX and related routines, including this documentation file, are shipped as com- pressed, self-extracting files. This lowers the number of disks required, and also provides an automatic check during the instal- lation that the disk(s) have not been damaged. The steps re- quired for program extraction may vary from release to release; you will find an instruction sheet packaged with the distribution disks. All purchasers receive the evaluation demo version which is com- plete except for limited database size and an opening commercial in the two main programs WSSINDEX and CUSTPRNT. If you purchased the complete package, an additional self-extracting file is in- cluded which contains replacements for the two limited routines. The demo routines have a "D" as the last character of the file name, i.e. WSSI501D.EXE (Note that the file names vary slightly for the non-standard versions. Generally, a single letter is ap- pended, and where this makes the file name longer than 8 charac- ters, another letter is dropped.) The extracted files generally include the version number as part of the file name. For example, the main program WSSINDEX.EXE becomes WSSI501.EXE. To avoid confusion, I suggest that you rename the executable files to WSSINDEX, CUSTPRNT, IDADD, SPLIT, WSSMERGE and WSIMPORT (.EXE in all cases). If you are running DOS 2.x, you must rename the program files this way if you want to use the virus checking code. Of course, you can name them whatever you like, but this is how they will be referred to in Wssindex 5.01 1 Introduction the documentation. This documentation file can be printed and removed from your working disk, or kept online for reference. Unlocking Demo Releases Demo releases sent to various online and disk copying services are compressed using PKWare's PKZIP. These files include an authenticity check which is believed to be extremely difficult to defeat. When such files are extracted using PKZIP, you should see the message "Authentic files Verified! # RLQ256 Software by WSS Division of DDC." If there is any change in this message, particularly in the serial number RLQ256, it means that the file has been modified and should be treated with caution. Various BBS's may add a ZIPfile comment; this will not change the authen- ticity check. The acknowledgement letter sent to full purchasers includes a personal password which can be used to remove the limitations from the evaluation demo. The DOS SET command is used to define two environment variables, WSSUSER and WSSPASS, whenever the demo version is run. The first of these is typically the user name, the second an 8-digit number. For example, John Q. Public might include the lines SET WSSUSER=JPublic SET WSSPASS=12345678 in his AUTOEXEC.BAT file. The program retrieves the value of the WSSUSER variable, does some arithmetic operations on it, and checks to see whether the result matches the value of the WSSPASS variable. If so, the opening commercial screen is suppressed and the database size limit is removed. The WSSUSER variable must be entered exactly as specified in your registration letter; chang- ing the case or including spaces around the equal signs will cause the program to either not recognize the password or will change the expected value of WSSPASS. Purchasers of versions released before the password scheme was implemented may contact WSS/DDC to receive a password. The maximum database size will be slightly reduced by the memory used by the code which checks the password; otherwise an unlocked demo version will be indistin- guishable from the standard release. This password scheme is probably not very hard to defeat; if you do so, please keep the technique to yourself. Wssindex 5.01 2 Introduction Overview and Tutorial This section is an introduction to WSSINDEX for new users. It contains enough information to get you started, but eventually you should read the Setup and Command Reference sections. What is it? WSSINDEX creates and maintains a database with all the information about your disks available from the DIR command, plus optional descriptive comments and categories. You can search the database interactively, or you can print it with vari- ous sorting and selection options. An auxiliary routine allows printing disk labels and disk covers. The most common use of the program is to keep track of files on a collection of floppy disks, but you can index anything which looks like a disk to DOS, including hard disks, RAM disks and some tape cartridges. (Un- fortunately, most tape systems use special formats which Wssindex cannot read.) One option allows hard disk users to make a list- ing of all files on a hard disk which do not have backup copies on another disk. What hardware and software do I need? An IBM-PC or moderately compatible MS-DOS machine (versions for the Dec Rainbow, Texas Instruments Professional, and Wang PC are also available or under development), DOS-2 or higher and either a video board compatible with an IBM monochrome display or color graphics adapter, or sup- port for ANSI escape sequences. If you lack all of these, the screen display will be hopelessly garbled; more details below. The program will run in 256K of memory, but the database size will be limited; 640K is recommended. A mouse may be used. How many disks can I index? There is a hard limit (set by the 64K segment size of the Intel 80x8x series CPU's) of approximate- ly 16K files (or disks, or subdirectories), and a practical limit of 10-12K files if you have 640K of memory. Extended or expanded memory is not used, but DOS memory beyond 640K is used if your system supports it. How do I run the program? Start it up by typing WSSINDEX (or WSSInnn if you haven't renamed the executable file and it still includes the version number). You will get a message that the configuration file was not found; hit return and you will get into the configuration section of the program. "Help! my screen is all messed up. I see funny numbers, square brackets and other garbage mixed in with normal text." Did this happen to you? If so, it means that your system is not config- ured to recognize ANSI escape sequences for highlighting and cursor positioning. Appendix A gives instructions for adding this capability to your system, but for most machines, there's a better (faster) alternative. If you have a monochrome display adapter (MDA) or color graphics adapter (CGA), or another video board (EGA, MCGA, VGA, etc.) which can be made to respond like Wssindex 5.01 3 Setup one of these, you can tell WSSINDEX to do screen output by writ- ing directly to video memory. As part of the standard distribu- tion package, you should find configuration files MDA.CNF and CGA.CNF. Figure out which one is appropriate for your hardware, and invoke WSSINDEX by WSSINDEX CGA or WSSINDEX MDA (note that the extension .CNF is supplied automatically if you leave it off. You can specify a drive or path if necessary.) Alternatively, before starting you can issue the DOS command SET WSSDISP=monochrome or SET WSSDISP=color as appropriate to set the default screen writing method. If you select the wrong display type, you will find yourself "flying blind" and a reboot will likely be necessary. If you did not specify a configuration file on the command line, the program will tell you that it did not find one, and it will initialize with default options. You can change options at this point or later; simply select the change cOnfiguration option on the main menu. If you did not use one of the supplied configura- tion files listed in the previous paragraph, you will probably want to change the video output method to CGA or MDA. This will increase the screen writing speed by a factor of 5 or so, and will enable boxes around the menus. (Drawing the menu boxes with DOS calls would be painfully slow.) To get to the menu screen which sets this option from the primary configuration menu, se- lect M and then V. This menu option is buried several menus deep because you only need to set it once, and you lose your screen display if you accidentally change it to the wrong value. When you exit from the configuration menu, the program will prompt you for the name of an existing database to load. Since you have not yet created a database, just hit escape to bypass this prompt. This brings you to the main menu. Hit A to move to the indexing menu. If necessary, hit F and S to enter the first and second indexing drives. If you have two drives, you can select A and B and use then alternately; otherwise just select the same drive twice. Hit I to start indexing. You will be told to insert a disk and hit the space bar; do so. If the disk was previously labeled (by the /V option of FORMAT or by some other utility), the label will be displayed and the disk directory information will be added to the database. If the disk was not labeled, you will be given the options to write a label on it, enter a label to use (but not write on the disk), list the direc- tory on screen, or return to the menu. WSSINDEX will spend a few seconds reading the disk, and will then prompt you to hit the space bar to index the next disk. Feed in a few disks this way, Wssindex 5.01 4 Setup then hit return instead of space to stop indexing, and then R to return to the main menu. Now you can try some of the program options. Hit D and see how many files and disks you have entered. Hit P to move to the File/volume listing menu, and then P again to print the database. When asked for selection/rejection options, just hit return to select everything. When asked for sorting options, enter 1,2 and hit return. And when asked to select printer, screen, disk or export output, hit S. You should now get a listing of all files in the database, sorted by name and extension. If the list does- n't fit on a single screen, you can page forward and backward with the PgDn and PgUp keys. At the top of the list will be dummy entries for each disk and subdirectory. Later on you will find out how to control whether or not these appear. If you don't want to see the entire listing you can interrupt it by hitting ^C (control-C) while the screen is being painted, or hit Q after the screen fills. When the listing finishes and you return to the menu display, enter ^F for quick find. When prompted for file specs, enter wildcard specifications one per line, ending with an empty line. For example, *.COM and *.EXE will match all executable files. All files which match these specs will be displayed on screen in the same format as before. There are four different types of disk files which can be written by WSSINDEX: (1) configuration files (default name WSSINDEX.CNF) which contain setup information and are short, (2) database files (default name WSSINDEX.DIR) which contain the disk directory information and can be quite large, (3) printer files which con- tain output which could have been sent to the screen or a printer instead, and (4) export files which can be read by database pro- grams. Only the first two of these can be read by WSSINDEX. From the main menu, select option W to write a database file. You will be prompted with a default name of d:\path\WSSINDEX.DIR. You can hit return to accept this default, or you can edit it: use the cursor keys, insert, delete, control-arrow for word tab- bing, etc. Select option Q (or ^Q) and return to DOS. Verify that the data- base file was written where you expected. Restart the program. If you saved a configuration file with the default name (the instructions above didn't tell you to do this, but you might have done so anyway if you were adventurous), no- tice that it is automatically restored and you are prompted for the name of a database file to read. Otherwise, after configur- ing, select the G option to get a database from disk and reload the database you just saved. Use the V option to list the vol- umes in the database, sorted by name, free space, date indexed or unsorted. Wssindex 5.01 5 Setup Now you have a feel for how the program operates and you should read at least up until the detailed menu descriptions. Some important things you will find are instructions for changing the default names for the configuration and database files, detailed explanation of all the program options, and how to use the add- comments section. Also look at the Problems and Solutions chap- ter for the answers to some commonly asked questions, and at the Utilities chapter for descriptions of the various utility rou- tines. If you want to print disk labels or disk covers, see the documentation for the utility CUSTPRNT. Setup and General Information Before running WSSINDEX, there are several DOS environment vari- ables which you may want to set to establish defaults for the configuration file name, the database name, and your video dis- play type. Doing this is optional, but recommended for smooth operation. The DOS environment is just a list of character strings of the form VARIABLE=value You make, view or delete entries in this list with the DOS SET command. Type SET to view your current settings. You should see something like COMSPEC=d:COMMAND.COM, and probably other items used by other software packages or the PROMPT command. You will probably find it convenient to put SET commands in your AUTOEXEC.BAT file. If you get an error message that you have run out of environment space, see appendix B. When issuing SET commands, do not include any blank spaces around the equals signs. The four commands: SET X=Y SET X =Y SET X= Y SET X = Y mean different things. The environment variables used by WSSINDEX are WSSDISP = default display type WSSICNF = default configuration file name WSSIDIR = default database name WSSPRINT = default printer definition file (CUSTPRNT only) WSSINDEX and the utility routines do not make any assumptions about your video card, you must specify what you have. This is a little less convenient than if the video type were automatically Wssindex 5.01 6 Setup sensed, but it prevents confusion on machines with more than one video board or when smart hardware trys to sense what type of video board the software is trying to address. The video type is saved in configuration files, but you can also use WSSDISP to specify this; legal values are D, C or M for DOS calls, color graphics adapter, or monochrome display adapter. (Actually, only the first character is used, so you can be more mnemonic.) Two reasons why you should set WSSDISP: first, if you don't, you may notice an ANSI escape sequence leaking out at start up and on exit, and second, if an error is encountered when reading a con- figuration file, the program will assume the worst and drop back to using the video type specified by WSSDISP, or DOS calls if WSSDISP is not defined. If you do not specify the configuration file or database file names on the command line, they default to WSSINDEX.CNF and WSSINDEX.DIR on the current drive in the current directory. You can change these defaults with the environment variables WSSICNF and WSSIDIR. Even if you use multiple databases and configura- tions, you can still use these variables to specify the drive and path. For example, if you keep the program and configuration files in subdirectory C:\WSSINDEX, and databases in subdirectory C:\WSSINDEX\INDEXES, you might specify SET WSSICNF=C:\WSSINDEX\ SET WSSIDIR=C:\WSSINDEX\INDEXES\ (Remember, no spaces around the equal signs.) The startup code will use the specified paths and fill in the default file names. If WSSICNF is defined, you are assumed to be an experienced user and the opening screen with the copyright message is displayed for a shorter period of time. The WSSPRINT environment variable specifies the name of the printer definition file which is used by CUSTPRNT. See the util- ities chapter for more details. Starting up Type WSSINDEX <config name> <database name> where the angle brackets indicate optional parameters. If the configuration file (first command line argument or default or de- fined by WSSICNF) is read successfully, the program will immedi- ately ask for the name of an existing database to read, and will prompt you with the default name. If you don't want to read a database, you can hit escape to cancel. On the other hand, if you specify the database name as the second command line argu- ment, it is read without confirmation. If the configuration file and database have the same name (but the usual extensions), you Wssindex 5.01 7 Setup can specify = (an equal sign) for the database name. Either command line name can be replaced by an * (asterisk) as an abbre- viation for the default name. Command Defaults In many places, WSSINDEX gives you a default which will be used if you just hit enter. For text input, you can edit the default with normal editing keys: left, right cursor arrows, backspace, insert, delete, control-arrows for word tabbing. File names generally have default drive, subdirectory, name and extension components which are established at program startup and change to match the last user input. Aborting commands At most points you can hit ESCAPE (CANCEL on a Dec Rainbow) to abort a command when you are prompted for text strings such as file name, disk name, etc. ESCAPE will not stop print opera- tions, use control-c instead. If you hit ESCAPE when numeric input is expected, you will still see a "command aborted" mes- sage, but all this means is the the default value has been used. The Dreaded Abort, Retry, Ignore? Certain disk errors will produce a DOS error message, followed by an "Abort, Retry, Ignore?" prompt, possibly in an inappropriate screen location if you are using direct video writes for screen output. To minimize the chance of triggering such a message, WSSINDEX now has an error handler which will intercept such mes- sages, if they are triggered on the first access of a disk, and give you the opportunity to correct the problem or cancel the operation. The usual problems which can be detected this way are disk not ready or not formatted. Disk full errors are handled properly, but at a different level. In future releases the error handling will be extended to catch all disk errors. The current coding will not detect a write protected disk, nor the various failures which can occur in the middle of a file even if the disk is properly loaded. If you do get the "Abort, Retry, Ignore?" message, you must be careful how you respond. If you respond "A", you return to DOS and lose whatever you were working on. But, that's not the worst thing that can happen. If the failure happens on a write operation, say the wrong disk was inserted and it had a write protect tab, and you swap disks be- fore responding "R", DOS will probably write the directory and file access table of the original disk onto the second disk. This is really a design flaw in MS-DOS, not a WSSINDEX problem, and most any program can suffer from it. It is generally safe to fix the problem and retry with the same disk. The result of ignoring an error will depend on exactly what operation failed, Wssindex 5.01 8 Setup but for read operations you can usually recover by ignoring the error, although you may have to do it several times. Acknowledgements WSSINDEX started out as an exercise to learn C for my "real job" and to fill my needs for a disk indexing package, and ended up growing into a major project. Two special software tools which have proved invaluable in producing various releases of this package are OPUS MAKE (D. G. Kneller & J. F. Thomason, Opus Soft- ware, 1032 Irving St. Suite 439, San Francisco, CA 94122) and the PD M4 macro preprocessor (Ozan S. Yigit with modifications by John Levine). Special thanks to Paul St. George, Nate Horowitz, Don Wetzel, and other members of the Sanyo New England Users Group for encouraging me to distribute my early efforts as shareware. Also thanks to those who voluntarily registered the shareware version, and to those who suggested program enhance- ments. And finally, thanks to the countless bulletin board sysops who provide the distribution network for shareware and demo programs. Wssindex 5.01 9 Setup Archive Files The idea of combining files into an archive or library, and pos- sibly compressing them at the same time, is older than MS-DOS. WSSINDEX can peer into certain types of archive files and extract directory information. Note that it is only the directory infor- mation which is extracted; file viewing and extraction are not implemented. Archive files are identified by their file extension. Since it is possible for a non-archive file to have a name which makes it appear to be an archive, you may get warnings when indexing that such files are either not archives or are corrupted. If such a message is given for a file which you think is a archive, you should use the appropriate archive utility to test the integrity of the file. In most but not all cases, extraction of information from an ar- chive file is noticeably slower than reading a directory because the information is scattered throughout the file, rather than being concentrated in one place. You will probably notice a lot of disk activity when extracting archive information. Some of the archive formats may be used on non-MS-DOS systems which allow file names which are illegal under MS-DOS. When WSSINDEX extracts information from such an archive, the two com- ponents of the file name are truncated to 8 and 3 characters but retain their original case. If you transfer archive files from another operating system to MS-DOS, remember that these are bina- ry files and improper character translations can make them un- readable. Some of the archive formats can include subdirectory information; WSSINDEX will ignore this information. Some of the archive formats allow entries to be marked as deleted; WSSINDEX will ignore such entries. If an archive format allows inclusion of comments, and the WSSINDEX configuration selects comment ex- traction, the 64 leading characters of the comment (after remov- ing any leading or trailing blanks, unprintable characters or strings of more than two consecutive blanks) are included in the database. Archive files introduce two complications in the operation of re- placing a commented disk in the database. First, which comment should be used if a comment has been extracted from an archive and the file already had a comment in the database? Current choice is to accept the comment extracted from the archive, but I'm not certain that this is the best choice. Second, what should be done if a member of an archive file matches the name of an ordinary, commented file in the same subdirectory? Quite probably the files are identical, but they could be completely different, and WSSINDEX has no reliable way to tell which is the case. The current program version uses the following algorithm to decide whether to copy a comment after it has found matching Wssindex 5.01 10 Library Files file and subdirectory names: if both files are archive members, the archive file names must match, and if only one of the pair is in an archive file, the size and date must match. I am not com- pletely satisfied with this algorithm and am open to any sugges- tions for a better technique. Archive Formats Supported ARC, ARK, PAK, PKA - As far as WSSINDEX is concerned, these ex- tensions all refer to the same type of archive. An extraction program might not be able to handle all of these because some of them may use unrecognized compression methods, but the header information has the same format in all four. The ARC extension is used with the archive format which is currently the most popu- lar. ARC files may be created by ARC (Systems Enhancement Asso- ciates, 21 New Street, Wayne, NJ 07470) or PKARC/PKPAK (PKWare 7545 N. Port Washington Road, Suite 205, Glendale, WI 53217). ARK is the extension used by a CP/M port of ARC. The PAK exten- sion is used by PAK (NoGate Consulting, P.O. Box 88115, Grand Rapids, MI 49518). When a version of PKARC was introduced which had a compression method not recognized by ARC, some users recom- mended changing the extension to PKA. LBR - This format was defined by Gary Novosielski for use on CP/M and MS-DOS systems and many programs exist which can create this type of archive. Although no longer popular, this format allows quick access to any archive member because the directory informa- tion is all in one place at the beginning of the file. Time stamps stored in a LBR file are relative to 1/1/76, but are con- verted to the MS-DOS standard by WSSINDEX. This means that files dated before 1/1/80 will appear to be dated 1/1/80. There also exist LBR utilities which do not fill in the date and time infor- mation; these will also produce file dates of 1/1/80. LZH, LZS - Files with these extensions are created respectively by the Japanese programs LHARC (Haruyasu Yoshizaki) or LARC (K. Miki, H. Okumura, K. Masuyama). ZIP - ZIP files are created by PKWare's PKZIP (address above). ZIP files extending across multiple volumes are not currently supported by WSSINDEX (or by the current release of PKZIP). ZIP files may be created on non-MS-DOS operating systems; WSSINDEX should be able to handle such files, except for the above men- tioned truncation of file names. A volume name stored by PKZIP will appear as a zero-byte file. ZOO - The ZOO archive utility (by Rahul Dhesi) is available under many different operating systems, and the file format is supposed to be the same on all of them. Wssindex 5.01 11 Library Files Navigating through the menus Wssindex is controlled by a series of menus and data entry screens. The overall structure is shown in the figure below. For the most part, related functions are put on the same menu. A few items which might logically be used in different contexts are repeated on multiple menus. The appearance of the menus depends on whether screen writing is done by DOS calls or direct video writes. In DOS-calls mode, menus are not surrounded by boxes and there is no highlight bar because displaying these in this mode is very time consuming. Operation of the menus is fairly straightforward. A menu item is selected by either hitting a trigger key which is highlighted in the menu, or by hitting return or space when the highlight bar and cursor are positioned on the desired item. The highlight bar can be moved with the cursor keys or with a mouse; HOME and END move the selector bar to the first and last menu items respec- tively; ESCAPE returns to the previous menu, or refreshes the screen if at the top-level menu. The left mouse button is equiv- alent to the space bar, the right button to the return key. If you hit a key which is not the trigger for any displayed menu item, it is assumed that you are entering a value for the current item. The area below a menu box is used for message display and user entry of items such as file names. After a menu item has been selected, and any processing for that item is completed, an attempt is made to make an intelligent choice whether to leave the cursor positioned on the same item or to advance to the next item. The method used to select the menu item affects the decision whether to advance to the next. If a menu item is selected by hitting return or the right mouse but- ton, the cursor will always advance to the next menu item. On the other hand, if a menu item is selected by hitting the trigger key, the space bar or left mouse button, the cursor will only advance to the next menu item if it seems unlikely that the cur- rent item will be reselected. For example, if you have toggled a YES/NO value or typed in a numeric value for a parameter, you probably want to advance to the next item. Wssindex 5.01 12 Main Menu Structure of Wssindex menu tree +---------------------------------------------------+ | Main menu | | Listing menu | | Add disks menu | | Add comments menu | | Primary configuration menu | | Printer configuration | | Database size configuration | | Indexing options menu | | Default sorting/selection options | | Screen, keyboard, miscellaneous | | Video board | | Keyboard macros | | Exceptions list | | Fields to print | | Output format | | | +---------------------------------------------------+ Figure 1 Main Menu The top level menu provides immediate access to some of the more commonly used functions, as well as entry to the output, indexing and configuration menus. +-------------------------------------------------------------+ | Wssindex Main Menu | | | | Output Database maintenance options | | ^F quick find Add or label disks | | Print and other output menu Add/modify Comments | | ReName a disk in database | | Other options ^N rename with mixed case | | Display statistics Remove disks | | ^D - DIR ^R remove all disks | | Push to DOS | | Write database to disk Configuration options | | Get database | | Program termination ^G get database and CNF file | | Quit Change cOnfiguration info | | ^Q quick quit | +-------------------------------------------------------------+ Figure 2 Wssindex 5.01 13 Main Menu ^F - Quick Find (control-f) This is the option to use if you are looking for a particular file by name and want unsorted screen output. You will be prompted to enter one or more wildcard file specifications. This option is duplicated on the Print sub-menu (page 17) where it is discussed in more detail. P - Print and other output menu This option leads to the print sub-menu. D - Display statistics This option displays the number of files, subdirectories and disks in the database, and the amount of contiguous memory remaining for additional entries. There will always be at least one subdirectory listed, since the root directories of all disks are treated as one subdirectory. Also listed is the current database name, either from the last read/write operation or the default name. Some points about the reported memory remaining: this number will only decrease when the number of subdirectories increas- es, or when comments and categories are added. Space for other information is allocated during the initial setup. (This was not true in versions older than 3.30.) It is only the contiguous space remaining which is reported. If a disk with subdirectories or comments is removed or replaced, a "hole" may created in the memory space which will be used for comments, etc. which are added later. Some operations may create fragments of memory too small to be useful, hence the space remaining may change slightly if you save the database on disk and then reload it. You will receive a warning if the available space drops below 4K. The program tries to recover gracefully from out of memory errors, but doing a save to disk is strongly recommend if you get this warning. Also note that opening a file requires at least 2K for buff- ers, so you may not even be able to save your database if there is too little memory free. ^D - Directory (control-d) This command lists the directory of a disk to the screen (file names only). There are two options after hitting ^D: either hit return and the complete subdirectory tree is dis- played for the disk in the first indexing drive, or enter a wildcard file specification including disk and path and see everything which matches that specification. Note, if you enter a file specification without specifying the disk, the default is the currently logged drive, not the indexing drive, and to see all files on a disk (in one subdirectory) you must use the *.* wildcard, not just d:. The listing can be terminated by hitting control-c. You might want to use this option to find out what's on a disk before you label it, Wssindex 5.01 14 Main Menu or to refresh your memory of the names of your databases. This option is duplicated on the Indexing menu (page 23). S - Push to DOS Load a secondary copy of COMMAND.COM (or alternate processor) and temporarily pass control to it. Return to WSSINDEX by typing EXIT at the DOS prompt. To remind you that you are in a secondary shell, the configuration can be set to change the DOS prompt to "EXIT to return>". You can do anything you can normally do at DOS level, but you will have less free memory to work with. It is best not to load a terminate and stay resident program here because it will fragment the memory space. The DOS environment variable COMSPEC is used to lo- cate the command processor, so this option will work even if you have renamed, or are using a replacement for, COMMAND.COM. COMSPEC is normally set up correctly during the boot process and you don't need to worry about it unless you have done something to change it. You must have some free memory to use this option, and insuf- ficient space is the usual cause when this command fails. On my DOS 2.11 system, I need about 17.5K (as reported by the "D" option); later DOS's are larger and will require more. Of course, if you want to run a program in the secondary shell, you must also consider its memory requirements. W - Write database on disk The in-memory database is saved on disk. The default file name is the first of 1. The last file name used in a Get or Write command 2. The second command line argument 3. The DOS environment variable WSSIDIR (DOS command set WSSIDIR=filespec) 4. WSSINDEX.DIR which is defined. The default file name is displayed and may be edited in the usual way. A previously existing file with the same name will either be renamed with a .BAK extension or overwritten (with verification), depending on which configu- ration option you have selected. If creation of .BAK files is enabled, you will not be allowed to use a filename with a .BAK extension. Q - Quit and return to DOS You will be warned if the in-memory database has been changed without being saved, and in any case you must verify that you really want to exit. For your protection, the default option is N (don't quit) if the in-memory database has not been saved. Wssindex 5.01 15 Main Menu ^Q - Quick Quit and return to DOS (control-q) If the in-memory database has not been changed since being saved, this option returns to DOS without asking for verifi- cation, otherwise it's the same as option "Q". A - Add or label disks This option leads to the indexing menu. C - Add/modify Comments This options leads to the add-comments screen. N - ReName a disk in the database You are prompted for old and new names and the disk name in the database is changed. Names are forced to upper case. A carriage return aborts back to the main menu. ^N - ReName a disk with a mixed case label (control-n) This is the same as option "N" except that it accepts lower case characters. R - Remove a disk from the database The volume name to remove may be either typed in or read from disk. When typing in a name, you can either let WSSINDEX force your input to upper case or use mixed case. ^R - Remove all disks (control-r) This option clears the database currently in memory. A warn- ing is given if the database has not been saved since the last modification. G - Get a database from disk Enter the name of a file previously saved with the "W" menu option. The default name is the first of 1. The last file name used in a Get or Write command 2. The second command line argument 3. The DOS environment variable WSSIDIR (DOS command set WSSIDIR=filespec) 4. WSSINDEX.DIR which is defined. The default file name is displayed and may be edited in the usual way. You will be warned and given an opportunity to escape if you have a database in memory which has been changed without being saved. ^G - Get configuration file and matching database (control-g) This option prompts for the name of a configuration file and loads it without displaying the configuration menu. If there are no problems configuring, the default database name is changed to be the same as the configuration file name, but with a DIR extension, and a get-database function is execut- ed. This same function can also be executed from the command Wssindex 5.01 16 Main Menu line when starting up by specifying the configuration file name as the first argument and an equal sign (=) as the sec- ond. O - Change cOnfiguration This option leads to the primary configuration sub-menu. Print menu This is where most text output options are found. +--------------------------+ | File/volume listing Menu | | | | Select/sort/Print | | Find a file | | ^F quick find | | Zippy text search | | Duplicate files | | Unique files | | List files not Backed up | | | | List Volumes | | ^V quick volume list | | | | Return to main menu | +--------------------------+ Figure 3 P - Print (and sort) The print option first allows you to select what files will be listed. Files to be listed may be selected by combina- tions of 1. names and extensions 7. size range 2. subdirectory 8. exclude configured exceptions 3. disk name 9. exclude archive file members 4. comment 10. only archive files and members 5. category 11. zippy search 6. date range or 12. select from previous subset You tell the program which selection criteria to use by en- tering a list of numbers separated by commas. Depending on which options you chose, further prompts will be made for file names, etc. Each file in the database is checked against all of the selection criteria, and is included in the listing only if it passes all tests. This means, for exam- ple, that while you can select files in which are in subdi- rectory \ABCD and match *.DAT, you can not select files which are either in the subdirectory or match the file spec. This restriction does not interfere with most selection requests; Wssindex 5.01 17 Main Menu the occassional odd request can often be built up with multi- ple passes. Files in the database can also be excluded from the listing by the first 5 options in this list. You indicate this by using a negative selection option number. Option -1, rejec- tion by file name, is essentially the same as option 8, ex- clusion of configured exceptions, except that different lists of names are used. The recommended mode of operation is to put the file names which you always want to exclude into the configured exceptions list (which is semi-permanent and awk- ward to revise), and use the option -1 list for special cas- es. For example, depending on the sort order, you may or may not want to see the .ID entries for volumes and subdirec- tories. The option -1 rejection list is the obvious way to get rid of these entries, although you can also do it by selecting only files larger than 0 bytes. Selection option numbers are entered in a comma-delimited list; the order is not significant. All but options 8, 9,10 and 12 lead to prompts for more information. Options -1, 1 and 11 accept multiple items, one per line, ending with a null line. All selection options are case insensitive. The default list of options is configurable, and can be edited in the usual way. When entering a list of wild-card file specifications, you can switch to full-screen editing mode by hitting tab. You can make up to 100 entries (5 columns of 20 specifications). Normal editing commands are available. Any cursor arrow motion off the left or right end of an entry is interpreted as a move to the next column. Hitting HOME moves the cursor to the beginning of the current entry, or if already there, to the first entry in the list. Similarly, hitting END moves to either the end of the current entry or to the last item in the list. If you want archive file members, but not the archive files themselves, include *.ARC, *.LBR, etc. in one of the excep- tion lists. When character string input is required, you can enter two different types of wildcard. The first is similar to what the DOS DIR command accepts: a question mark matches any character and an asterisk matches all characters to the end of the string. A few examples: * or *.* matches any file. *. matches any file with no extension. xy* matches any subdirectory, disk name, comment, or category which begins with the letters xy. ??? matches anything 0 to 3 characters long. Wssindex 5.01 18 Main Menu return matches absence of comment or category. The second type of wildcard allows you to search for charac- ters when you don't know their position in the string. Es- sentially, this is a keyword search, except that parts of words can also be matched. Simply begin the string with an asterisk and put the text immediately after it. The primary use for this type of wildcard is for searching comments, but it also works for other string items. For example: *LOTUS matches any string containing the substring LOTUS. *123.* matches any file name which includes the charac- ters 123. ** matches any string which contains an asterisk ?*123.* doesn't work because the asterisk isn't the first character. 123 will be ignored and this is equiv- alent to *.*. Option 11, the zippy search, is a wildcard search which looks almost everywhere: file name, extension, comment and catego- ry. A leading asterisk is assumed; you must not add another. The more comprehensive search options are slower than just looking at the beginning of each string, but they aren't too bad. The name zippy search is taken from a similar function in the PC Board bulletin board program; it's actually the slowest selection option. Option 12, select from previous subset, is only offered if you have previously selected files and have not done anything to invalidate the selection list. Possible uses include editing the previous selection if it included too many files, printing the same set of files that were just viewed on screen, or re-viewing with different sort keys. The selected files are optionally sorted in ascending or de- scending order by any combination of 1. file name 6. date and time 2. extension 7. category 3. disk name 8. comment 4. subdirectory 9. archive file name 5. size 10. archive file extension When prompted, enter or edit a comma-separated list of sort key numbers, changing the sign of any you want in descending order. (The default list is configurable.) Most of the keys are self-explanatory, but the last two need a little explana- tion. If you have elected to extract information from ar- chive files, the file name and extension used with keys 1 and 2 for members of an archive file are those of the archive file member. Thus, with only keys 1 and 2, the archive file members sort by their own names. Keys 9 and 10 select the Wssindex 5.01 19 Main Menu archive file name for members of an archive file, or the usual name for ordinary files. In addition, there are two special conditions checked: 1. If sort keys 9 and 10 are used and have higher priority than 1 and 2, the archive file itself will sort ahead of any of its members; 2. If keys 1 and 2 have higher priority than 9 and 10, then archive members (and other files) are sorted by their own names. An interleaved list of keys such as 1,9,2,10 will probably not do anything useful. If there are multiple copies of an archive file, you will probably want to have the disk and/or subdirectory as an intermediate key when sorting first by archive file name. To summarize, 9,10,3,4,1,2 will list archive members following the containing archive file, while 1,2 will list all files alphabetically. Sorting by category and comment is case insensitive. Any votes on whether this should also be true for disk name? There is a noticeable time penalty for making the sort case insensitive. The sort is done using the Quicksort algorithm. The sorting time for a randomly ordered file is O(N*logN), typically less than 30 seconds for 2000 files. If, however, you should somehow manage to enter your files in alphabetical order, you will discover one of the quirks of Quicksort: the sorting time for an ordered file is O(N*N), turning a 30 second sort into a 10 minute sort. If you elect not to sort (sort key equal zero or just hit re- turn), the selected files will appear in the order they are found in the database, unless the files were selected from a previously sorted subset, in which case the previous sort order is preserved. When the sort is finished, you can select whether the output goes to your printer, screen, a disk file or export. For disk output you will be given the options of suppressing page headers and margins. Disk output might be massaged by a text editor to change the format, read by another program, printed by a background printing utility while you do something else in the foreground, or transported to another machine for printing; it is not readable by the "G" menu option. For printer or disk output, you will be given the option to in- sert a variable number of blank lines whenever the first sort key changes (for screen output one blank line is inserted). Export output is in "Mailmerge" format, a standard format which can be read by many database programs. Fields are Wssindex 5.01 20 Main Menu separated by a user-selected character, normally a comma, hence this format is often called comma-delimited. Fields which contain the separator character are surrounded by quotes, and fields which contain a quote receive special handling. For some database programs, in particular Lotus 1-2-3, it may be necessary to enclose all fields in quotes; you are given the option to do this. Information in the configuration file is used to select which fields are printed for each file, and to control paging. When screen output is selected, you can page forward and backward with the PgUp and PgDn keys, go to the top of the list with the HOME key (PF1 key for DEC Rainbow) or return to the main menu by hitting Q. Control-s will pause any screen display; control-c will abort printing. For more printing options, see the routine CUSTPRNT in the utilities section. F - Find a file in the database Find is equivalent to Print (described above) to the screen unsorted. ^F - Quick Find Quick find is equivalent to Print with screen output and files selected by name only. Z - Zippy find This option is equivalent to Print, with selection option 11, unsorted, with output to the screen. That is, you are prompted for a list of strings to search for in file names, extensions, comments and categories. D - List Duplicate files This option lists all files which match the selection crite- ria and have duplicates (which also match). Only the file name and extension, and optionally the time stamp, are used to decide whether two files are duplicates. The dummy en- tries for volumes and subdirectories are automatically ex- cluded. U - List Unique files This option lists all files which match the selection crite- ria and do not have duplicates which also match. This is similar to the "B" option, but checks all files in a database rather than just those on a single disk. The dummy entries for volumes and subdirectories are automatically excluded. As with the "D" option, you can optionally require matching time stamps before two files are considered duplicates. Wssindex 5.01 21 Main Menu B - List files which are not Backed up This option is intended primarily for listing files on a hard disk which have not been backed up, but can also be used on floppies. A file is considered to be backed up if another file with the same name and the same or later time tag is found on another disk (possibly in an archive file). Exact time and size matches are not required because some copy programs do not preserve the time stamp, or even the size for files which are not padded to a full disk sector. When you select this option, you are given the usual selec- tion options (described under the "P" option). These are applied to both the disk being checked for backups and to all other files in your database. Thus, selecting by some op- tions, such as disk name, doesn't make much sense. However, to allow checking a subdirectory rather than an entire disk for backups, any subdirectory selection criteria are applied only to files on the disk being checked for backup. On the other hand, subdirectory rejection criteria are applied to all files. Since only files from a single disk will be list- ed, you might as well set the configuration to skip printing the disk name (it will be listed in the title anyway). You will almost certainly want to use an exception list to ex- clude *.BAK (or whatever your favorite word processing pro- gram names its backup files). The dummy .ID entries for volumes and subdirectories are automatically excluded. If you are using the configured exception list, don't forget to request selection option 8 to use the list, otherwise you will have to stop the listing and try again. After selec- tion, the database is sorted using an internally defined set of sort keys. If you have a hard disk which is logically partitioned so that it looks like multiple disks, you probably don't want to consider a file to be backed up just because it appears in two partitions. To avoid this problem you can either load a database with only floppies included, then index a single partition before checking it for backups, or you can use the "R" option to remove all but one partition from your data- base. See also the U option for checking backups on all disks at once. If you use a backup utility which creates special files which only it can read, you probably will not find the "B" option useful. V - List Volume names The volumes in the database are listed to printer, screen or disk, sorted by name, by decreasing free space, backwards by date indexed, or unsorted (which will be about the same as Wssindex 5.01 22 Main Menu forward by date indexed unless the database was created by merging two databases). When sorting by volume name, you can either treat the name as a text string or you can extract any numerical part of the name and use that as the key. As a text string, "DISK 100" would sort before "DISK 2", but if the numerical part is extracted, "DISK 2" sorts first. The printer configuration information is used to control paging for printer output; for screen output, you can page forward and backward with the PgUp and PgDn keys, or hit Q to return to the main menu. The display for each volume in- cludes the volume name, the number of free bytes, the total number of bytes available, the number of files (excluding hidden files), the number of subdirectories other than the root directory, the date the disk was last added to the data- base, whether or not the disk is bootable and optionally any comments entered describing the disk. The disk is assumed bootable if it has a COMMAND.COM file, the presence of the hidden system files is not verified. You may abort printing by hitting control-c. ^V - Quick list of Volume names This option lists the volume names to the screen, sorted by name and without comments. R - Return to main menu Returns to previous menu. Indexing Menu Additions to the database are made from this menu. Many control options are found here, but a few are only available on the con- figuration menus. Wssindex 5.01 23 Main Menu +-------------------------------------------------------------+ | Wssindex Indexing Menu | | | | Start Indexing Ask before replacing NO | | Dummy entry index Auto-Comment NO | | ^D list directory AUto-category NO | | Label disk Make .ID entries YES | | COnfiguration menu DummY Entries inc subdir tree NO | | Return to main menu Query archive extraction NO | | Index Hidden files NO | | First indexing drive A Extract archive comments NO | | Second indexing drive A | | LaBeling drive A | | Indexing sTarts from (none) | | Auto-category strinG (none) | +-------------------------------------------------------------+ Figure 4 I - Start Indexing Insert the first disk to be indexed into the first indexing drive and hit the space bar when ready. The processing time is roughly proportional to the number of files on the disk, and will typically be only a few seconds for a floppy disk. If the disk is not labeled, you will be given the option to either write a label on the disk, enter an 11 character string to be used in place of a label, list the disk directo- ry or abort back to the menu. See the "L" option below for a discussion of "legal" volume names. If the Ask before re- placing option is YES, you will be informed if the volume name matches a volume already in the database and given the option to replace the previous entry or not enter the disk into the database. The informative message "NO FILES IN d:\*.*" will be generated if there are no files in the root directory, along with similar messages for other empty direc- tories. When prompted you may either insert another disk (in the alternate indexing drive if configured to alternate drives) and hit the space bar, or hit any other key to return to the menu. An important feature: if you replace a disk in the database, any comments or categories which have been previously entered are not lost, they are copied over to the new entry if the file and subdirectory names match. Thus you should feel free to re-enter a disk into the database after even small changes have been made. During a replacement operation, the old and new entries are temporarily in memory at the same time, and both count toward the limits on the number of files, disks and subdirectories. There is one circumstance which could make replacing a disk in the database very time consuming. The code which copies Wssindex 5.01 24 Indexing Menu old comments to new entries is a straightforward doubly nest- ed loop, which means that the running time is roughly propor- tional to the square of the number of commented files. This is not a problem with floppy disks which seldom have even 100 files, but on a hard disk with a few thousand files, the processing time could stretch to several minutes. The obvi- ous solution is to sort both sets of names first, which would reduce the processing time for commented disks, at the ex- pense of increasing it for non-commented ones, and I may implement this in a future release. Comments from registered users are solicited. (Does anyone actually comment files on their hard disk?) D - Add dummy entries This option is similar to the "I" option, but does not make a complete database entry. Instead, the database entry will show that there is only the dummy zero-length file named .ID. (The volume name, free space and total disk space will match the actual disk directory.) This allows you to record the existence of a disk when you don't want to include the file names, say for a program master disk which contains driver files for many different printers, graphics cards, etc. The .ID file is a place to hang a descriptive comment and catego- ry. Older versions of WSSINDEX used DUMMY_EN.TRY instead of .ID; the auxiliary routine IDADD will translate such entries. The Make .ID entries option must be set to YES before dummy entries can be made. ^D - List directory (control-d) This option performs the same way on this menu as it does from the main menu (page 14). L - Label a disk on the labeling drive A volume label is an optional entry in a disk directory which looks much like a file name, but is given special treatment by DOS. If present, it can be displayed by the DOS DIR or VOL commands. Labels are usually written when a disk is formatted, but can be added later by various utilities. WSSINDEX uses the volume name to distinguish different disks. This option displays the current volume label, if any, and prompts you for a new label. A carriage return aborts back to the menu without changing anything. The labeling is done by a DOS call, so DOS restrictions on allowed characters apply (in particular, your input will be forced to upper case because lower case letters are not allowed, but blanks are ok). If in doubt, try the label you want to use; an illegal name will be rejected with no harmful consequences. I would suggest that you not trust a copy protected master disk to any disk labeling program; who knows what sort of games they might have played with the directory. I also recommend Wssindex 5.01 25 Indexing Menu against writing on a 360K disk in a 1.2 MB drive since this could make it unreadable on some 360K drives. Note: if you have a disk with a mixed case label (which you can easily create with the Norton Utilities or some other programs), WSSINDEX will not be able to change the label (DOS rename call fails). If you need to change such a label while Wssindex is running, you can use the DOS Shell option from the main menu to run a labeling utility. Disks with labels differing only in case are considered to be different when adding disks to the database, but cannot be distinguished when selecting by volume name. If you use really weird vol- ume labels, such as ANSI cursor positioning commands, you probably deserve whatever happens to you. O - COnfiguration menu This option takes you to the primary configuration menu. From there, you can make changes or save a configuration file including the control settings from the indexing menu. R - Return to main menu This option returns you to the main menu. F - First indexing drive S - Second indexing drive B - LaBeling drive These three options select the drive letters used for index- ing or labeling disks. If you only have one floppy drive, the three drive letters will usually be identical, but they can be changed to index or label hard disk partitions. T - Indexing sTarts from This option allows for partial indexing of a disk. Instead of starting from the root directory and including all files, only files in or below the specified directory are indexed. (The disk volume label is read from the root directory as usual.) The format of the subdirectory specification will be adjusted to canonical form so you need not worry about de- tails like whether a leading or trailing backslash is needed. Making a partial index might be useful as the first step in checking a critical subdirectory for backups, or as a means of indexing a CD ROM or very large disk which contains too many files to fit in a single database. G - Auto-category strinG This is the string which is used for the category if config- ured to add categories automatically. A - Ask before replacing This flag controls the action taken when a volume label is found which matches one already in the database. If YES, you are asked whether to replace the existing database entry; if Wssindex 5.01 26 Indexing Menu NO, the entry is replaced automatically. Generally, this flag should be YES when indexing a collection of disks for the first time since duplicate volume names on different disks are easy to generate. On the other hand, if you have not kept track of which disks have been changed without being re-indexed and are re-indexing disks you know are already in the database, you can set the flag to NO and replace without verification. C - Auto-Comment If YES, you are transferred to the add-comments screen after each disk is indexed. All files on the disk just entered are selected for commenting. U - AUto-category If YES, all files on disks indexed are assigned the category shown in the auto-category string. M - Make .ID entries In order to record the subdirectory structure of a disk, and to allow comments to be assigned to disks and subdirectories, it is necessary to make special database entries for the volume label and each subdirectory. These entries look like files with the (illegal) name .ID. These entries count to- wards the limits on the number of files, so if you don't want to assign comments to disks or subdirectories, you can set this option to NO and decrease the database size slightly. Y - DummY entries include subdirectory tree If this option is set to YES, dummy entry indexing will in- clude the entire subdirectory tree; if set to NO, only one entry will be made for the volume id. Q - Query archive extraction You may want to extract file information only from selected archives. If this option is YES, you are asked before file information is extracted from any file with an extension in the extraction list. H - Index Hidden files Bootable disks have two hidden files which are not shown by the DOS DIR command. If this option is set to YES, these files are included when a disk is indexed, otherwise they are ignored. (Indexing of any other hidden files is also con- trolled by this flag.) E - Extract archive comments Some of the archive formats allow comments for the archive or members. If this option is YES, such comments are extracted, filtered to remove unprintable characters, and assigned to database files. Wssindex 5.01 27 Indexing Menu Primary Configuration Menu Most of the items in this menu lead to sub-menus which are de- scribed in detail below. The exceptions are the options to load or save a configuration file, and, of course, the option to re- turn to the previous menu. When loading or saving a configura- tion file, the prompt shows the file name which will be used by default. You can accept this default by hitting return, or you can edit the file name using cursor keys, insert/delete, etc. +------------------------------------+ | Primary Configuration Menu | | | | Printer configuration | | SiZe limits | | Indexing options | | Screen, keyboard and Miscellaneous | | Default sorting/selection options | | Keyboard macros | | Configured Exception list | | Which fields to print | | Output Format | | | | Load configuration file | | Save configuration file | | | | Return to previous menu | +------------------------------------+ Figure 5 P - Printer configuration Leads to a menu describing printer characteristics. Z - SiZe limits Leads to a menu to set database size limits. I - Indexing options Leads to a menu of options controlling behavior when indexing disks. M - Screen, keyboard and Miscellaneous Leads to a menu of miscellaneous items. D - Default sorting/selection options Leads to a menu for entering default sorting and selection options. K - Keyboard macros This option displays the 26 keyboard macros available by hit- ting Alt-letter in the add-comments section (or anywhere else that multi-character text input is allowed) and allows you to Wssindex 5.01 28 Primary Configuration Menu change them. These macros are stored in the configuration file, not the database file. If you make any changes here, you will be given the option to save a configuration file. (In earlier releases, keyboard macros were called predefined categories and could only be used in the add-comments screen.) E - Configured Exception list The exception list is list of up to 100 special case names which can be excluded from printing. By default, this list consists of only COMMAND.COM, but you might also want to add *.BAK, AUTOEXEC.BAT or anything else you have many copies of. Wild card names are allowed. List entries are made in full- screen mode (the same as is optionally used for entering file specifications when selecting files). This list is only used if you ask for it as one of the selection options. This semi-permanent list serves the same purpose as the one-shot rejection list which you can enter whenever selecting files. W - Which fields to print Leads to a menu for selecting what information to print. F - Output Format Leads to a menu for controlling output format. L - Load configuration file S - Save configuration file Configuration files hold the option settings entered in the various menus, including the keyboard macros. You can save or load a configuration file at any time, but a newly loaded configuration file cannot change the database size limits if a database is currently in memory. If you attempt to do this, you will be given the option to clear the loaded data- base. If you decline, all configuration options except the changed size limits will take effect. If you read or save a configuration file, the default file name is the first of 1. The last configuration file saved or read 2. The first command line argument 3. The DOS environment variable WSSICNF (DOS command set WSSICNF=filespec) 4. WSSINDEX.CNF (with drive and path whatever was current when the program was loaded) which is defined. The default name can be edited in the usual manner. If an error is encountered when reading a configuration file, WSSINDEX will assume the worst and revert to using DOS calls for screen output unless the environment variable WSSDISP is defined. Wssindex 5.01 29 Primary Configuration Menu The format of the configuration file often changes from ver- sion to version; compatibility is not guaranteed. Usually I try to arrange things so that most information can be ex- tracted from an older configuration file before a read error occurs, but major program upgrades always seem to require so many new configuration items that maintaining compatibility with older configuration files is not always possible. Gen- erally, Wssindex will realize that it is reading an obsolete format before very many garbage values have been read. One of the first things you should do with a new version is to review your configurations settings. R - Return to previous menu Returns to either main or indexing menu. Printer Configuration Menu Items in this menu define the characteristics of your printer. They are also used for disk output, but have no effect on screen output. Distances on a printed page are expressed in characters and lines. Proportionally spaced fonts are not supported; they will cause misaligned columns. +---------------------------------------+ | Printer configuration menu | | | | Page Width 80 | | Page Length 66 | | Left Margin 0 | | Top margin 3 | | Bottom margin 8 | | Use Form feeds YES | | Pause at page breaks NO | | | | Return to primary configuration menu | +---------------------------------------+ Figure 6 W - Paper Width to right margin This is the width of the paper, less any desired allowance for a right margin. (The number entered here does not depend on the left margin setting.) If your printer does an auto- matic carriage return and linefeed when a character is print- ed in the rightmost column, you should set the width to pre- vent using this column. Page numbers are right justified to the page width setting. Wssindex 5.01 30 Primary Configuration Menu L - Paper Length This is the length of the paper, typically 66 lines for 11 inch paper at 6 lines per inch, but slightly smaller (60 or 62) for laser printers which can't print on the first or last few lines of a page, or larger for A4 size paper. M - Left Margin T - Top margin B - Bottom margin The number of spaces or lines to leave blank in each margin. Note that a right margin allowance is made by using a smaller paper width specification. F - Use Form feeds Most, but not all, printers respond to a form feed command to eject the current page. For printers which do not recognize form feeds, set this option to NO and page advance will be done by inserting blank lines. The disadvantage of enabling this option is that if some glitch messes up the line count- ing, the error will propagate to following pages, whereas doing a line feed resynchronizes the program and printer line counting. Depending on your printer, if you are printing with zero bottom margin, it may be necessary to set this option to NO to prevent printing every other page blank. P - Pause at page breaks If a manual-feed sheet printer is used, set this option to YES so that output will pause for paper change. Database Size Limits The entire Wssindex database is kept in memory. Thus, the maxi- mum database size depends on available memory, and under MS/PC- DOS, that usually means less than 640K. The overhead for memory management is greatly reduced if space for certain fixed sized items is allocated in a few large chunks rather than in small pieces as a database grows. Also, the DOS Shell option requires some memory which could otherwise be used for the database. These considerations mean that the program must know the maximum database size before the database is loaded. However, these limits can be changed before a database loaded from disk, so numbers entered here do not restrict future database growth. In this menu, the limits on the numbers of files, subdirectories and disks are set. Regardless of available memory, each must be less than 16,384. In practice, it's usually the number of files which is most constricting. 10-12,000 files can usually be accomodated in 640K, provided that a significant amount of memory is not also being used for comments and categories. If there is not enough memory for the requested size limits, an error message will appear when you attempt to exit from the primary configura- Wssindex 5.01 31 Printer Configuration Menu tion menu. Insufficient memory for variable length items (subdi- rectory names, comments and categories) will be detected as a database is read or expanded. A maximum length comment or category takes up more database memo- ry than 3 file entries, so a heavily commented database could run into memory space problems even at 3000 files. +-------------------------------------------+ | Database size limits | | | | Maximum number of Files 3000 | | Maximum number of Subdirectories 600 | | Maximum number of Disks 300 | | | | Return to primary configuration menu | +-------------------------------------------+ Figure 7 Indexing Configuration Menu Items in this menu control program behavior during disk indexing. Many of these items are duplicated on the indexing sub-menu. Wssindex 5.01 32 Database Size Limits +-------------------------------------------------------+ | Indexing configuration menu | | | | Indexing drive number 1 A | | Indexing drive number 2 B | | Make .ID entries (allows disk/subdir comments) YES | | Ask Before replacing NO | | Auto coMment after disk indexed NO | | Auto caTegory for all files NO | | Ask before eXtracting archive info NO | | Extract comments from archive files YES | | | | Auto cateGory string (none) | | | | File extensions for archive information extraction | | | | ARC YES PAK YES | | ARK YES PKA YES | | LBR YES ZIP YES | | LZH YES ZOO YES | | LZS YES | | | | Return to primary configuration menu | +-------------------------------------------------------+ Figure 8 1,2 - Indexing drive number If you have two drives, Wssindex will read from them alter- nately when indexing so that you can be swapping disks in one drive while the other is being used. If you have only one drive (or if you only want to use one drive), just enter the same letter for both drives. I - Make .ID entries In order to record the subdirectory structure of a disk, and to allow comments to be assigned to disks and subdirectories, it is necessary to make special database entries for the volume label and each subdirectory. These entries look like files with the (illegal) name .ID. These entries count to- wards the limits on the number of files, so if you don't want to assign comments to disks or subdirectories, you can set this option to NO and decrease the database size slightly. B - Ask Before replacing If a disk is encountered while indexing which has the same volume label as one already in the database, it could be either a different disk with a duplicate name or the same disk being re-indexed. This option controls whether any warning is given before a duplicate disk is replaced. Wssindex 5.01 33 Indexing Configuration Menu M - Auto coMment If YES, automatically go to the add-comments screen after each disk is indexed, with all files from the disk selected. T - Auto caTegory If YES, assign the auto-category string to all files as disks are indexed. X - Ask before eXtracting archive info You may want to extract file information only from selected archives. If this option is YES, you are asked before file information is extracted from any file with an extension in the extraction list. E - Extract comments from archive files Some of the archive formats allow comments for the archive or members. If this option is YES, such comments are extracted, filtered to remove unprintable characters and excess blanks, and assigned to database files. G - Auto cateGory string This is the string which is used for the category if config- ured to add categories automatically. Extension for extraction Files with extensions marked YES here will be processed as archive files when disks are indexed. Miscellaneous Configuration Menu This menu includes a variety of miscellaneous items, including the paths to the color selection and video board configuration menus. Wssindex 5.01 34 Indexing Configuration Menu +-------------------------------------------------------+ | Screen, keyboard and miscellaneous configuration | | | | Perform automatic inteGrity check NO | | Function Key layout matching IBM YES | | Inverted meaning for PgUp/PgDn NO | | Create .BAK files YES | | Enable Alarm sound YES | | Change Prompt in DOS shell YES | | Strip High-bit when viewing files YES | | Use color YES | | Use Mouse NO | | Mouse Sensitivity 50 | | | | Set Colors | | Video board configuration | | | | Return to primary configuration menu | +-------------------------------------------------------+ Figure 9 G - Perform automatic inteGrity check A disk indexing program infected by a computer virus could spread the infection to every write-enabled disk indexed. To provide partial protection, Wssindex will read its executable file from disk and perform a checksum test. If the expected checksum is not found, a warning will be displayed the first time you enter the main menu. Since this test requires reading the program from disk, it requires about the same amount of time as loading the program. With a fast hard disk, this time is negligible, but on a floppy it could be annoyingly long, hence the option of disabling the test. This type of integrity test is far from foolproof. First, it only tests whether the program itself is infected, not wheth- er a virus from a previously run program is active. Second, a sophisticated virus might well detect that a program was reading its disk image and feed back the uninfected image. Finally, a virus targeted against a specific program could remove the checksumming code entirely. I intend to change the details of the integrity check from release to release in order to make this last attack more difficult. There are now several programs available which attempt to check for virus infections by known viruses, or to block destructive actions. Since I have never actually encountered a virus, I cannot comment on how effective such programs might be. I do know that computer scientists have demonstrated that writing a "universal virus detector" is not possible. In order to perform the checksum test, the program must know its name and where it was loaded from. Under DOS 3.0 or Wssindex 5.01 35 Miscellaneous Configuration higher, this is trivial, and under previous DOS versions it is impossible. When running under DOS 2.x, the program name is assumed to be WSSINDEX.EXE, and the current directory and the PATH are searched for this name. Thus, if you wish to use the integrity check under DOS 2.x, you must change the program name from the distributed name which includes the version number. There are various utilities available which compress an exe- cutable file on disk and automatically decompress when the program is loaded. If such a utility is used, the disk im- age, and hence the checksum, is changed, so the integrity check will fail. However, such a compression utility may provide an equivalent checksum test. Except for this consid- eration, WSSINDEX has been tested and found to be compatible with the program LZEXE version 0.91 (Fabrice Bellard, 451 chemin du mas de Matour, 34790 Grabels, France) and the LZESHELL program (Pete Petrakis, 1236 River Bay Road, Annapo- lis, Maryland 21401) which translates LZEXE's messages into English. LZEXE compresses the unpacked WSSI501.EXE by about 50% and the reduced disk access time more than compensates for the decompression overhead. K - Function Key layout matching IBM The function key help in the add-comments screen is arranged in two columns, just as the function keys on many keyboards. If you have an unusual keyboard which has F2 below F1 rather than beside it, such as is found on your author's old Sanyo 555, set this option to NO and the help screen arrangement will match the key arrangement. If your function keys run across the top of the keyboard, pick whichever arrangement seems best. I - Inverted meaning for PgUp/PgDn Your author became accustomed to an hp terminal long before he ever saw a PC keyboard. The hp keyboard had NEXT SCREEN and PREVIOUS SCREEN keys in the same positions as PgUp and PgDn, but the positions were interchanged relative to meaning most programs assign to the PC keyboard keys. Your author sets this option to YES and goes through contortions to get other programs to do the equivalent translation; probably everyone else will set it to NO. B - Create .BAK files When a database is saved, and an existing file of the same name is found, the old file can be either overwritten or renamed with a .BAK extension. The latter option is obvi- ously safer since the old file remains if the save fails, but the output disk might not have enough room for two databases. If you elect not to create .BAK files, you will be warned that an old file of the same name exists and must confirm that you really want to overwrite it. If creating .BAK Wssindex 5.01 36 Miscellaneous Configuration files, a two generation old .BAK file will be erased so that the previous database file can be renamed. A - Enable Alarm sound Some error messages include a beep. This option allows you do disable all such sounds. P - Change Prompt in DOS shell The prompt when shelled to DOS can be either changed to "EXIT to return>" to remind you that you are in a shell, or left unchanged. H - Strip High-bit when viewing files Files created by WordStar, and possibly other files, have the high-bit set on some characters. When viewing such files from the add-comments screen, it is desirable to turn off the high-bit to make the text readable. On the other hand, lan- guages other than English use characters with the high-bit set. So, generally this option should be set to YES for English language users and NO for other languages. (Ques- tion: are ther non-English versions of WordStar, and if so, what do they do about special characters?) U - Use color By default, the program will run in monchrome. (This does not refer to the type of video board which is a separate selection.) To get color, set this option to YES and also select set Colors to get a color-selection menu. Actually, the setting of this control is only important if using DOS calls for screen output. With direct video writes, you can get colors even if this option is set to NO. M - Use Mouse Set this option to YES to enable the mouse. There are two possible reasons why you might not want to do this: first, the standard method of testing whether a mouse is present causes some non-compatible machines to crash, and second, when the mouse is active, the program sits in a loop alter- nately checking for keyboard or mouse input rather than sim- ply asking DOS to read the next keystroke. In a multi-task- ing environment such as Desqview, this wastes CPU cycles which could be used by tasks in other windows. S - Mouse Sensitivity A smaller number here means less mouse motion is necessary to move the highlight bar. C - Set Colors This option leads to the color selection menu. V - Video board configuration This option leads to the video board selection menu. Wssindex 5.01 37 Miscellaneous Configuration R - Return to primary configuration menu Returns to the previous menu. Default Sorting and Selection Options Menu +-------------------------------------------------+ | Default Sorting and Selection Options | | | | Selection list (none) | | Sort Keys (none) | | | | Return to main menu | +-------------------------------------------------+ Figure 10 S - Selection list K - Sort Keys When listing files with the Find or Print options, you are prompted for selection and sort options. The two menu items here allow you to specify the default selection and sort key lists. If present, each will be a list of numbers, separated by commas. These lists may be edited at the time of use, but such editing does not change the defaults. R - Return to previous menu Returns to the primary configuration menu. Output Fields Configuration Menu This menu is used to select what information is displayed when files are listed. Note that displaying all items requires con- siderably more than 80 characters. The output format menu is used to control how long lines are handled. Wssindex 5.01 38 Miscellaneous Configuration +-------------------------------------------------------+ | Output fields configuration menu | | | | Print File name and extension plus | | | | DuPlicate flag NO Volume YES | | Size YES SuBdirectory YES | | Date YES Archive file name YES | | Time YES Comment YES | | SEconds YES CateGory YES | | | | Return to primary configuration menu | +-------------------------------------------------------+ Figure 11 P - DuPlicate flag An asterisk following the file name if the name is the same as the previous file listed. Note that whether a file is flagged depends on the sort order and selection options. S - Size File size in bytes. D - Date Date of last modification; date format is selected in the output format menu. T - Time Time of last modification; always omitted if date is not printed. S - Seconds Seconds field of modification time; always omitted if time is not printed. Since MS-DOS only stores the file time to the nearest two seconds, this will always be an even number. V - Volume Disk volume label. B - SuBdirectory Subdirectory name or "Root" for root directory. A - Archive file name The name of the containing archive file, if any. C - Comment File comment, if any. G - CateGory File category, if any. Wssindex 5.01 39 Output Fields Configuration Output Format Configuration Menu +------------------------------------------------------------+ | Output format configuration menu | | | | Number of Blank lines between headers 0 | | Number of blank lines after Headers 1 | | | | File name style FN EXT | | Date style mm/dd/yy | | | | Enter 0 width to use variable field size | | | | Field width for Subdirectories 0 | | Field width for Archive name 0 | | Field width for Comment or category 0 | | | | Archive file delImiter none | | Category deliMiter none | | | | Print comments bEfore categories NO | | Always start New line for comment/category info NO | | Truncate to fit on one line NO | | | | Return to primary configuration menu | +------------------------------------------------------------+ Figure 12 B - Number of Blank lines between headers H - Number of blank lines after Headers File and volume listings have two header lines, one with a title, the second with column headings. These options select how many blank lines to insert between header lines, or be- tween the header lines and the data lines. These parameters are ignored for screen output. F - File name style Selection this option will toggle the file name format be- tween FN EXT and FN.EXT. D - Date style Selecting this option will cycle through the various date formats: mm/dd/yy, dd/mm/yy, yy/mm/dd or 01-Jan-80. The day, month, year order selected here is used for both input and output. The date format implied by the COUNTRY= option in CONFIG.SYS is not used. Wssindex 5.01 40 Output Format Configuration S - Field width for Subdirectories A - Field width for Archive name C - Field width for Comment or category Displaying all possible file information on a single line, neatly arranged in columns and allowing for the maximum pos- sible length of all fields, would require require well over 200 print positions. Perhaps some printers can do this, but generally some compromise must be made. The possibilities are to not print everything, limit the field widths, not require columnar alignment for potentially long, variable length items, or print multiple lines. If a field width is specified as 0, as many spaces as needed will be used, sub- ject to line length constraints. Non-zero widths should be specified if neat columns are desired; overly long items will be truncated at the field width. I - Archive file delImiter The name of the archive file containing the listed file can be printed surrounded by (), <> or []; selecting this item cycles through the possible delimiters. One of these markers is recommend to distinguish the archive name from the follow- ing field if a fixed field width is not used. M - Category deliMiter The same sets of delimiters can be used to mark categories as to mark archive files. E - Print comments bEfore categories Either comments of catefories can be printed first. N - Always start New line for comment/category If YES, a new print line will be started for any comment or category. T - Truncate to fit on one line If YES, long print lines will be truncated rather than wrapped (but multiple lines may still be printed if the pre- vious option selects a new line for comments and categories). R - Return to primary configuration menu Return to the previous menu. Video Board Configuration This menu selects the screen output method. This selection is buried in this menu because it only needs to be made once, and because accidentally configuring for the wrong type of video board is likely to cause an immediate crash. Wssindex 5.01 41 Output Format Configuration +-------------------------------------------------------+ | Video board configuration | | | | Screen writing method (changes only on menu exit) CGA | | Suppress snoW on CGA NO | | Raw Mode screen output NO | | | | Return to previous configuration menu | +-------------------------------------------------------+ Figure 13 S - Screen writing method Screen output may be done using either DOS calls or direct video writes. The former is slower, and on most systems re- quires that ANSI.SYS be installed (see Appendix A, page 73). However, if running in a background window, using DOS calls may prevent screen output from bleeding through to the fore- ground window. The direct write methods are CGA for Color Graphics Adaptor and MDA for Monochrome Graphics Adapter. An EGA, VGA, MCGA or just about anything driving a color monitor should be configured as an CGA. A Hercules board should be configured as an MDA. If you don't know which type of video board you have, take a guess but be prepared to reboot if you guess wrong. Auto de- tection of video board type is not attempted because there are too many ways it can fail: auto-switching boards which will say "sure I'm a ..." no matter what you ask them, sys- tems with two video boards, buggy systems which crash when the standard method of checking for an EGA is used, etc. W - Suppress snoW on CGA Older CGA boards cannot display properly while they are being written to. If this option is YES, writes to video memory will be synchronized with the horizontal retrace to minimize screen disruption. This will slow down the updating. M - Raw Mode on screen output Raw mode means do not check for control-c or control-s after every character of screen output. Setting this option to YES will speed DOS calls screen output slightly, but the differ- ence will probably not be noticable. R - Return to previous menu Returns to the miscellaneous configuration menu. Color Selection Menu Use + and - keys to cycle forward and backward through colors, or left mouse button to advance colors. Cursor arrow keys or mouse Wssindex 5.01 42 Video Board Configuration select which item is to be changed. Hit ENTER or the right mouse button when done. A selector bar is not used if using DOS calls for screen output, so this option may not be displayed. The border color control is not functional on all systems, in partic- ular, it will not currently work on a VGA. Also, while there is an ANSI escape sequence for setting the border color, most imple- mentations of ANSI.SYS do not support it, so the border color selection will usually not work in DOS-calls mode. The actual screen colors may not match the labels exactly. For instance, on a monochrome system, blue on black will give underline, and non- bold yellow may display as brown. As you cycle through colors, the labels at the left will change to the selected colors. +-----------------------------------------------------+ | Attribute Foreground Background | | | | Normal text none white blue | | Highlights bold yellow blue | | Status info bold white white | | Selector bar bold yellow magenta | | Border color none blue | +-----------------------------------------------------+ Wssindex 5.01 43 Color Selection Menu The Add-Comments Menu The add-comments menu screen displays each matching file name along with the disk and subdirectory it is found on, as well as the containing archive file for archive file members. Starting with version 3.2, each disk and each subdirectory will cause a dummy database entry to be made with a blank file name and exten- sion of "ID". These entries, which receive special treatment when printing, give you a place to hang comments describing an entire disk or subdirectory. +-------------------------------------------------------------+ | Add comments menu | | | | Disk id: MS-RAMDRIVE File name: .ID | | Subdirectory: Root | | | | Copy buffer: | | | | | | Current file: | | | | | | New comment: | | category: | | | | | | F 1 - copy comment F 2 - delete comment | | F 3 - copy category F 4 - delete category | | F 5 - copy both F 6 - chng srch direction | | F 7 - skip to next F 8 - view file | | F 9 - add comment and advance F10 - return to main menu | | ENTER - comment/category toggle INSERT - insert/overtype | | Alt-F1 - toggle help Ctrl-END - delete to end | | | | | | Searching forward INSERT OFF | +-------------------------------------------------------------+ Figure 14 The ten PF keys, alt-letter keys, plus BACKSPACE, INSERT, DELETE, ENTER, HOME, and the left/right cursor arrows are used to control this part of the program. Two different sets of PF key assign- ments can be selected from the configuration menu to support different keyboard layouts. (A third set of key assignments is used in the Rainbow version.) While it doesn't really matter which arrangement you use, the placement of the functions and the position of the on-screen help are more rational if you select the layout which matches your keyboard. The descriptions below assume that you are using the IBM layout, which is now the de- Wssindex 5.01 44 Add-Comments Menu fault if no configuration file is found (early program releases supported only the alternate layout). Function Key layouts PF1 PF2 PF1 PF6 PF1 F17 PF3 PF4 PF2 PF7 PF2 F18 PF5 PF6 PF3 PF8 PF3 SELECT PF7 PF8 PF4 PF9 NEXT SCREEN FIND PF9 PF10 PF5 PF10 PF4 EXIT IBM Alternate Dec Rainbow (Function keys may be labeled Fn or PFn) A help menu and three sets of information are displayed: Copy buffer - a comment/category pair which can be copied into the new comment field. Current file - the comment/category currently in the database for the displayed file. New comment/category - the comment and category currently being entered. The special functions available are: PF1 - Copy comment: if the file has a comment, copy it to the new comment field; otherwise, copy the comment in the copy buffer. If you want to replace an existing comment with one from the copy buffer, you must first delete the old comment (PF2). Note that this does not actually add a com- ment to the file until you hit PF9. PF2 - Delete comment: any comment for the current file is de- leted immediately. If you have entered something in the new comment field, and decide that you do not want to have any comment associated with the file, just hit PF2 to delete the old comment, followed by PF7 to skip to the next file without adding the contents of the new field to the database. It is not necessary to clear the text en- tered into the new comment field. PF3 - Copy category: if the file has a category, copy it to the new category field; otherwise, copy the category in the copy buffer. As with PF1, this does not actually add a category until PF9 is hit. PF4 - Delete category: any category for the current file is de- leted immediately. Proceed as described under PF2 to de- lete a category after having entered something into the new category field. PF5 - Copy both: the same as hitting both PF1 and PF3. Wssindex 5.01 45 Add-Comments Menu PF6 - Change search direction: toggles the search direction for the next matching file between forward and backward. PF7 - Skip to next: advance to the next file, without changing the current comment and category fields. PF8 - View file: the indexing drive is searched for the current file. The disk volume name must match (an unlabeled disk will be accepted). If the file is found, it is displayed on the bottom half of the screen. Non-printing characters are translated to periods, so there is no problem with viewing a non-ascii file. The configuration may be set to clear the high bit of each character to make WordStar files printable. Lines longer than the screen width are truncated. This function will fail and claim that the file could not be found if there is not enough free memory to open a file. PF9 - Add comment and advance: the new comment and category (if any) are added to the current file and copied to the copy buffer. Blank fields will not be copied and will not change the record for the current file. PF10 - Return to the main menu. BACKSPACE - (or Delete key on Rainbow) Delete character to left of cursor. DELETE - (Remove key on Rainbow) Delete character under the cur- sor. INSERT - (Insert Here on Rainbow) Toggle between insert and overwrite mode. ENTER - Toggle between comment and category. Left/right cursor arrows - Move around in the comment or category strings for editing. Control-left/right cursor arrows - (down/up arrows on Rainbow) Move the cursor in word rather than character steps. HOME - (Prev Screen on Rainbow) Move the cursor to the beginning of the current field. END - Move the cursor to the end of the current field (F19 key on Rainbow). (Hitting return twice will also do this.) Control-END - Delete characters from cursor to end of field (F4 key on Rainbow). Wssindex 5.01 46 Add-Comments Menu Alt-PF1 or Shift-PF1 - toggle help display between PF key de- scriptions and list of keyboard macros (Help key on Rainbow, control-1 on Sanyo 550). ^R - Redraw the entire screen. It shouldn't be necessary to use this key very often, but occasionally a DOS error message or a program problem can scroll or otherwise mess up the parts of the screen which are normally constant. Alt-letter - Append one of the 26 keyboard macros to the category field, along with a comma and a space if anything was pre- viously entered there. (The behavior here is slightly dif- ferent than in other parts of the program where the macro strings are simply appended to any previous input). Note that changing the keyboard macros will not change the cate- gories which have already been assigned to files; it is the actual string which is saved for each file. Also, the macros are stored in the configuration file, not the database. (In the DEC Rainbow version, F20 is used as a substitute for the Alt key. On a 100A, you can also use the Compose key.) When all files which match the selection criteria specified have been processed, you normally return to the main menu. This would make it inconvenient to apply corrections to a previously com- mented database, or otherwise process several groups of files selected by name. So, if the only selection criterion is the filename, you will be prompted for a new list of filespecs when all matching files have been processed, and the selected files will automatically be sorted using the same sort keys (if any). At this point, you can also just hit ESCAPE to return to the main menu. Comments and categories entered for files are limited to 64 char- acters, although if you use the category field as it is named it will usually be one or more relatively short phrases. Some users may want to use this field as a version number. WSSINDEX will not allow control characters in comments, but anything else, including high-bit ascii, is alright. Wssindex 5.01 47 Add-Comments Menu WSSINDEX Utilities All of the utilities read a standard configuration file, although in some cases the only information actually used is the screen writing method and screen colors. CUSTPRNT - Custom Print Utility CUSTPRNT reads a WSSINDEX database and prints the contents using formats not otherwise available. These functions have been put into a separate program to avoid increasing the size of the in- dexing routine. In this release, the print formats available are multi-column printing, disk labels and disk covers. This documentation assumes that you are familiar with WSSINDEX. CUSTPRNT uses much of the same code as WSSINDEX, and uses identi- cal configuration files (even though a few items are ignored). It also reads a special file of printer control commands. The DOS environment variables WSSICNF and WSSIDIR are used, as well as a new variable WSSPRINT. Entry to the main menu is essentially the same as in WSSINDEX. Two optional command line arguments are allowed to specify the configuration file name and database file name. If you want to use the default for the configuration file name, but not for the database name, specify * as the first argument. The database name may be an equal sign if it is the same as the configuration file name. +------------------------------------------------------------+ | Custprnt Main Menu | | | | Output options Configuration options | | | | Multi-column printing Get database | | List files not Backed up ^G get database and CNF file | | Disk Covers Change cOnfiguration info | | Disk Labels Change Keyboard macros | | List Volumes Read printer config file | | ^V quick volume list | | | | Other options Program exit options | | | | Display statistics Quit | | Push to DOS ^Q quick quit | +------------------------------------------------------------+ Figure 15 Wssindex 5.01 Utilities 48 Custprnt The menu items are: M - Multi-column printing Similar to the "P" option in WSSINDEX, but an additional prompt is made for the number of columns used for the printed output. The output page width (from the configuration file) will be divided into the requested number of columns, sepa- rated by at least two spaces. Comments and categories will go to separate lines if necessary and so configured. Note: if the configured print items do not fit in the column width, they will be truncated, probably in the middle of the field. Output may be directed to printer, screen or disk. Screen output, however, will not pause when the screen fills. Control-s may be used to pause screen output. In order to produce columnar output running down rather than across the page, an entire page is formatted in memory before printing anything. This leads to a delay of a few seconds at the start of each page. A hardware or software print spooler may enable you to drive your printer more efficiently. You must have enough memory left after loading the database to hold an entire formatted page (slightly more than page width times page length bytes). You can include a printer initialization command in the printer definition file which will be sent to your printer before multi-column output is started. B - List files which are not Backed up Same as the "B" option of WSSINDEX except that you will be prompted for the number of print columns. C - Disk Covers A disk cover is a listing of all the files on a single disk, small enough to fit into a disk envelope or be pasted on the front of the envelope. (You could even define a small cover format and print it on a label as an alternative to the "L" option format labels.) The edges are marked by a box to make cutting to size easy. You can select which disks to print covers for by volume name (with wildcards) or by date in- dexed. The output format is similar to the multi-column output described above, plus a header with information about the disk. You will be prompted for the desired number of print columns. The fields printed are selected by the usual configuration menu. The disk name and subdirectory names are printed sepa- rately, so you should not include them in the configured print fields. If you use the printer definition in the sup- Wssindex 5.01 Utilities 49 Custprnt plied file GENEPSON.DEF, you can fit file size, date and time in 2 columns, date or size in 3 columns, or file names only in 4 or 5 columns. In a single column, you could even fit comments of moderate length. The characters which are used to form the box around the cover when printing may not look at all like box forming characters on the screen. The sup- plied file SCREEN.DEF has more appropriate box characters, and also sets the width to fit on an 80 column screen (which might not be what you want to do if you are experimenting to see what will fit on a printer). To avoid the necessity of changing the configuration by hand (and the probability of forgetting) whenever you print covers, you will almost cer- tainly want to have a special configuration file to control the printing of disk covers. Note: as with multi-column output, if the configured print items do not fit in the column width, they will be truncated, probably in the middle of the field. When sorting files for disk covers, the disk name and subdi- rectory must be the primary sort keys. CUSTPRNT enforces this requirement and the prompt for sort options shows 3,4 as the first 2 keys in the list. You cannot print covers with- out sorting, so you might as well add file name and extension or other sort options in the order you prefer. If you want to print disk covers for any disks with subdirec- tories, and these disks were added to your database by a ver- sion of WSSINDEX older than 3.2, then you should run the IDADD utility on your database first. If you do not do this, the disk cover will not include subdirectory names. D - Display statistics Exactly the same as the WSSINDEX "D" option. G - Get a database from disk Exactly the same as the WSSINDEX "G" option. L - Disk Labels Disk labels are meant to be printed on small, self adhesive forms and pasted on your disks. Suitable forms are generally 1 by 3 inches or smaller, so there is only room for a limited amount of information. This program prints the disk volume id, total and free space, date indexed, number of files (and subdirectories, if any), descriptive comments for the disk and subdirectories (if found in database), and directory info for as many files as will fit, starting from the largest. You can also specify one line of text in the printer defini- tion file, such as your name, which will be printed at the bottom of every label. You can select which disks to print labels for by a wildcard name or by date indexed. Wssindex 5.01 Utilities 50 Custprnt Blank label forms which are one or several labels wide may be used. You can also direct output to the screen or a disk file. See section below for information on printer defini- tion. O - Change cOnfiguration info Exactly the same as the WSSINDEX "O" option. Q - Quit and return to DOS Same as the WSSINDEX "Q" option except that there is no pos- sibility that the in-memory database has been changed, so the default answer to the "Do you want to quit" question is al- ways yes. ^Q - Quick Quit Immediate return to DOS without verification. R - Read a printer definition file Normally, this file is read automatically the first time you select a print operation, so this option is only needed if you want to use two different configurations in the same session, or if you have used the S option to run an editor to change the definition file. The default name of the printer definition file is the first of 1. The last printer definition file read 2. The DOS environment variable WSSPRINT (DOS command set WSSPRINT=filespec) 3. WSSPRINT.DEF which is defined. The default name may be edited in the usual manner. S - Push to DOS Exactly the same as the WSSINDEX "S" option. One possible use would be to run a text editor to change a printer defini- tion file. V - List Volume names Exactly the same as the WSSINDEX "V" option. ^V - Quick list of Volume names Like the WSSINDEX quick list, except that the volume names are sorted backward by date indexed so you can see which disks have been recently added and may need new labels or covers. Printer Definition Files To run effectively, CUSTPRNT needs to be able to set the print pitch and line spacing on your printer, especially when printing disk covers or labels which require small print. Unfortunately, Wssindex 5.01 Utilities 51 Custprnt there is no standard way to do this; all printers are different. So, CUSTPRNT must be told how to control your printer. You sup- ply this information in a printer definition file. (I'd call it a configuration file, but that leads to confusion with the WSSINDEX configuration file.) The name of the printer definition file is set by the environment variable WSSPRINT, analogous to WSSICNF and WSSIDIR. If not specified, the default name is WSSPRINT.DEF. The file is read the first time a print operation is requested, or when you select "R" from the main menu. The standard distribution package includes definition files for several popular printers. Some of these have been tested on printers available to me, some have been donated by users, and some were created by looking at printer manuals or driver files from word processing programs. The comments at the beginning of each file indicate whether or not the file has been properly tested. If none of the supplied definition files is adequate for your printer, you will need to look up control codes in your printer manual and modify one of the supplied files. I realize that it would be better if I supplied definition files for hun- dreds of different printers, but I don't have the resources to create and test them. Registered users who have problems config- uring should send me a photocopy of the appropriate pages from their printer manual (usually the control codes are summarized in a few pages) and I will try to assist. Of course, it may be that your printer does not accept any commands, in which case you must make any necessary selections manually. The format of the definition files is designed for easy editing with a word processing program. The file begins with as many lines of comments as desired, until a line beginning with ---- is encountered. After this, alternate lines are comments and param- eters. The comment lines are ignored when the file is read, but since they tell you what the parameters mean, the only changes you should make are to add more detail. Printer command strings can be omitted, but other parameters should have a value filled in. Characters in the printer definition (other than the printer name and owner id) are interpreted as a series of tokens optionally separated by blanks or commas. Each token may be an octal, deci- mal, or hex number, an ascii character, or a special abbrevia- tion. Blank or comma delimiters are only necessary to resolve ambiguities about where one token ends and the next begins, but are recommended to improve human readability. Octal numbers - begin with a 0, contain only the digits 0-7, and are not larger than 377. Terminated by a comma, blank or special abbreviation. Wssindex 5.01 Utilities 52 Custprnt Decimal numbers - begin with a non-zero digit and are not larger than 255. Of course, zero is entered as 0. Terminated by a comma, blank or special abbreviation. Hexadecimal numbers - begin with 0x or 0X and are not larger than 0xff. Letters A-F (if used) can be lower or upper case. Termi- nated by a comma, blank or special abbreviation. Ascii characters - any normal character other than a number, comma, blank or backslash. No terminator needed. Special abbreviations (may also be upper case) - \digit - number as a character rather than a binary value \b - backspace \c - comma \e - escape \f - form feed \n - newline (linefeed) \r - carriage return \s - blank (space) \t - tab \\ - \ Be careful of numbers; 1 means the binary value 1 while \1 means the ascii character one which has the binary value 31 hex or 49 decimal. Printer manuals often are unclear about this distinc- tion. To make the entries in the printer definition file more readable, I have adopted the convention that entries which code for a sin- gle output byte are separated by blanks, and the groups of char- acters which make up a single command to the printer are separat- ed by commas. For example: suppose you want to set an Epson printer to 8 lines per inch (command ESC "0") (character 0) 12 characters per inch (command ESC "B" 2) double strike (command ESC "G") The printer definition file entry could be: \e \0,\e B 2,\e G To continue a sequence on the following line, terminate the cur- rent line with a backslash. There is a conversion table in Ap- pendix D which may be useful in creating definition files. Margins, width and length specifications in this file override those found in WSSINDEX.CNF when printing labels or covers. The definable items are: Printer name - echoed to the screen during initialization, but otherwise not used. Wssindex 5.01 Utilities 53 Custprnt Three sets of printer initialization commands - 50 chars max. The first set is used for multi-column printing, the second for disk labels, and the third for disk covers. Typically this would in- clude commands to select the number of characters per inch print- ed and line spacing. You may also be able to get very small characters by selecting subscript or superscript mode, although some printers (like mine) are slow in this mode and do not print characters with descenders very well. You can also include any other necessary initialization commands here, such as bold print- ing or form length. Printer deinitialization command - 10 chars max. This command string is sent to the printer after a print task is completed. It could include a form feed to eject the last page from a laser printer, or could reset default printer options. Left margin for labels - number of print positions to leave blank before printing the first column of labels. Number of columns for labels - the number of blank labels across a row of your forms. Width of labels - The number of characters which will fit across a label (starting from the left margin). This effectively de- fines the right margin. Number of characters between labels - for multi-column forms, this is the number of characters between the right margin of one label and the left margin of the next. Length of label in lines - label size, including top and bottom margin lines which you don't want to print on. Number of usable lines for label - maximum number of lines to print on a label. Left margin for disk covers - number of print positions to leave blank before printing left side of box which surrounds disk cov- ers. Width of paper for disk covers - number of characters which will fit in 5.25 inches (or 3.5 or whatever disk size you use). Length of page in lines for disk covers - number of lines which will fit in 5.25 inches (or 3.75 inches for paste-on size). Position for the next disk cover - 10 characters max. Printer command to position the paper for the next disk cover. This could be a form feed, or a number of line feeds. A 0 (zero) here is interpreted to mean manual positioning, with a pause at the end of each cover. Wssindex 5.01 Utilities 54 Custprnt Command to use for sides of disk cover box - 50 characters max. Disk cover listings have a border drawn around them. The sides of this border could be a vertical stroke, or your printer may have a better graphics character available. If no suitable char- acter is available, or for faster printing, just use a blank (32). Characters which form boxes on a printer may display very differently on screen. Command to use for top and bottom lines - 50 characters max. Probably a hyphen or a graphics character. Command to use for top left corner - 50 characters max. If your printer has box forming characters in its graphics character set, use them for the corner characters, otherwise you can use the same character as the top or sides, or a blank, or a plus, which- ever you think looks best. Command to use for top right corner - 50 characters max. Command to use for bottom left corner - 50 characters max. Command to use for bottom right corner - 50 characters max. End of printer definition file ---------- Additional items may be added to this file in future releases if users report that there are printers which cannot be adequately defined. If you create a definition file for a different print- er, especially a laser printer, I would appreciate receiving a listing so that I will have it when the inevitable cries for help come in from other users. Registered users are encouraged to suggest the custom print for- mats which they would like to see added to CUSTPRNT. Wssindex 5.01 Utilities 55 Custprnt WSIMPORT Comment Import Routine WSIMPORT is a utility for adding comments to an existing WSSINDEX database. It can be used to extract comments from such sources as a listing of files from a bulletin board or the ascii output from another disk indexing program. It does not create a data- base from scratch from an ascii input file, so it is not quite what is normally called an import routine. Features: 1. Filename format may be either FILENAME.EXT or FILENAME EXT (but not a mixture) 2. Filenames may be in mixed case 3. Tabs are expanded 4. Processing speed is around 1000 lines per minute, depend- ing on the database size and your CPU speed 5. Header or other garbage lines are ignored Requirements on the input file: 1. File names must appear before the comments 2. Nothing can appear after the comment 3. File names and comments must begin in fixed columns 4. Comments must be on the same line as the file name. 5. Lines must end with line feeds (if you can type the file, it meets this requirement) Before starting the program, you should examine the comment file, either by typing it or with a text editor, to determine in which columns the file names (and extensions if the format is not FILENAME.EXT) and comments begin. Number the columns starting with one, not zero. This step may not be necessary since WSIMPORT will show you the first 15 lines of the import file with a ruler line before asking you about the file, but if the com- ments start after these lines, you won't see them. In general, it is not necessary to remove headers or other extraneous lines from the input file; they will simply not match any files in the database and will thus be ignored. But if there are any control characters embedded in the comments (such as might be introduced by line noise in a downloaded file) they should be removed or else they will be interpreted as the end of the comment. You can be a little sloppy with the starting column for comments since the program will remove any leading (or trailing) blanks. On the command line you can optionally specify the configuration file name, the database name, and the comment file name. When the program starts up, it goes through the same configuration procedure as WSSINDEX, although the only configurable parameters which matter are the screen output method, size limits on the database and whether or not to create BAK files. The database is read and you are prompted for the name of the comment file and Wssindex 5.01 Utilities 56 Wsimport the format (FILENAME.EXT or FILENAME EXT and starting columns). You will be given the option to override or keep previously ex- isting comments in the database if a new comment is found. You can also specify a category string which will be applied to every file which has a new comment assigned (unless you prohibit re- placing comments and the file had a category but not a comment previously assigned). At most points you can terminate the pro- gram by hitting escape. After initializing, the database is sorted by file name and ex- tension. You already know about how long this will take if you have used any of the sorting options in WSSINDEX. The program remembers the sequence number where each letter first appears, and starts searching for matching files there. A fancier hashing algorithm and a binary search could be used, but my testing indi- cates that the sorting time will typically be as long or longer than the processing time for reasonable sized input files, so not much can be gained here. The comment file is read line-by-line, and lines which appear to contain a filename and a comment are processed. Note that the same comment may be applied to multiple database entries, since disk and subdirectory names are not checked. When the program finishes processing the comment file, it prints out a few statistics (number of input lines, number of comments applied, etc.) and gives you the option of making another pass with a different comment file. When you finally select no fur- ther passes, you specify the output file name and the updated database is saved. As usual, a previously existing database of the same name will be renamed with a BAK extension (if so config- ured). Wssindex 5.01 Utilities 57 Wsimport IDADD Conversion Utility WSSINDEX version 3.2 introduced a new option to assign comments to disks and subdirectories in addition to files. This feature was implemented by making dummy database entries (which look like files with name .ID) for each disk and subdirectory. However, databases created by older versions of the program will not have these entries, and WSSINDEX would only create them if the disks were re-indexed. Also, it is now possible to configure to not generate .ID entries for volume names. IDADD is a utility for adding these dummy entries to a database without re-indexing. It will also insert a .ID entry in place of the DUMMY_EN.TRY file which older versions of WSSINDEX created when a disk was indexed with the control-a option (and will pre- serve any comment associated with the old entry). It will recog- nize disks which already have .ID entries and just copy them, so you can use this utility on any database (except old version 1.x databases which must first be converted by loading and saving with WSSINDEX). IDADD reads a standard configuration file, mostly to get the video output mode and screen colors. As a side effect, memory is allocated for as many files as are specified in the configuration file, even though this memory is not actually used. Normally this is not a problem; the conversion program is much smaller than WSSINDEX, so a configuration file which does not cause memo- ry overflow with WSSINDEX will also work with IDADD. You can specify the configuration and input database file names on the command line, or allow IDADD to prompt you for them. The output database name must be entered interactively. *** Warning *** The name of the output database must not be the same as the input database, else the output will overwrite the input during the up- dating process. One small quirk: if you have a subdirectory with no files in it, IDADD will not create a dummy entry for it, whereas WSSINDEX would if the disk were reindexed. It would be moderately diffi- cult to change this, so I won't do it unless I get complaints. Wssindex 5.01 Utilities 58 Idadd WSSMERGE Database Merging Utility WSSMERGE merges two WSSINDEX databases. Only databases written by WSSINDEX version 2.0 or higher can be merged. Older databases can be converted by loading them into a current version of WSSINDEX and resaving them. WSSMERGE reads a standard configura- tion file, mostly to get the video output mode and screen colors. As a side effect, memory is allocated for as many file as are specified in the configuration file, even though this memory is not actually used. Normally this is not a problem; the merging program is much smaller than WSSINDEX, so a configuration file which does not cause memory overflow with WSSINDEX will also work with WSSMERGE. When merging, you can elect to assign a common category to all files from the first database, and a second category to files from the second database. This might be useful if you had small databases organized by category, and wanted to merge them into a single database. You can suppress either common category by just hitting return when prompted for the category. In any case, previously entered categories are not changed. The names of the configuration file, input and output databases, merged database, and common categories can be entered on the com- mand line (in this order). If some or all are omitted, the pro- gram will prompt you for them. The WSSICNF environment variable is used for the default configuration file name, and if you do not specify file extensions, .CNF or .DIR is assumed, but other- wise there are no defaults for the names. If you want to specify a null category, enter a hyphen. *** Warning *** The name of the output database must not be the same as either of the input databases, else the output will overwrite the input during the merging process. The disk space required for the output file will be approximately the sum of the input sizes, but the entire merged database will not be in core at once, so you may be able to create a database larger than you can restore. In fact, you can exceed the 16K file limit, but you will not be able to read such a file with WSSINDEX on any machine. One error which the program may warn you about after completing the merging operation is duplicate volume names in the database. The duplicate entries are not deleted from the merged database; that task is left to you. Probably you should decide which input database has the most recent information (perhaps by checking the date indexed), and remove the matching entry from the other data- base, then remerge. Or if you have assigned the same name to two disks, use the Label and Rename options in WSSINDEX. Wssindex 5.01 Utilities 59 Wssmerge SPLIT Database Splitting Utility SPLIT takes a WSSINDEX database and splits it into two smaller databases. This function is something you might want to do if a database is pushing against the memory limits. SPLIT accepts 4 optional command line parameters: configuration file name, input database name, and two output database names. If specified, the database names become defaults which must be confirmed by hitting return. After entering the database names, you are shown all the volume names on one or a few screens with volumes which will go to the second database highlighted. (Initially, all volumes are marked as going to the first database.) Move the cursor (allowed mo- tions summarized below) to the volumes which you want to go to the second output database and hit the spacebar. The volume name will be highlighted to indicate that the disk will go to the second database, and the cursor will move to the next volume in the list. If you change your mind, just tag the volume again and it will toggle back. At any time, you can sort the list of volumes by name, date in- dexed, free disk space or numeric part of volume name. (It's not clear how useful some of these sort keys are, but they already existed from other places.) After marking volumes, you can ei- ther abort the program or write the two databases. This is a rather crude utility in that it doesn't give you very much information to help you decide how to divide the disks. However, because it is simple, it can handle large databases in limited memory, hence it can be used to break up a database which is too large to loaded on some machines. Cursor motions Standard keyboard Rainbow keyboard up/down/left/right arrow keys arrow keys first volume shown home Help 1st column ctl left arrow Find last column ctl right arrow Remove bottom of column end Insert Here last volume shown ctl end Select next page PgDn Next Screen previous page PgUp Prev Screen Wssindex 5.01 Utilities 60 Split Database Conversion Utilities There has been surprisingly little demand for utilities to con- vert databases from other disk indexing programs to WSSINDEX format. The following conversion programs, not normally included in the distribution package, can be supplied with any order at no extra charge. Backup Master - not exactly what I had in mind when I first thought about conversion utilities. This is a commercial disk backup program which produces a "history file" listing where backup copies of files are stored. The history file is converted into a WSSINDEX database. Fastback Plus (under development) - Backup Master was sold to Fastback, and the author wrote Fastback Plus. Backup log files similar to those produced by Backup Master can be written, and the Backup Master conversion utility is being revised to handle these files. Dos File Tracker - this is a disk cataloguer sold by IBM; a fair- ly straightforward conversion. Other formats are under consideration for future releases. Wssindex 5.01 Utilities 61 Conversion Problems and Solutions Hard/software requirements You must have MS- or PC-DOS level 2.0 or higher to run WSSINDEX because it uses operating system features not supported by DOS-1. If configured for DOS video output, WSSINDEX requires only a moderate level of IBM compatibility to run, but your system must support ANSI escape sequences for cursor positioning and high- lighting. This support may be an integral part of your system (as is the case for the Sanyo 55x series without the video board option), but is often provided by an installable device driver called ANSI.SYS (ANSI55.SYS for the Sanyo 55x with the video board). If your system does not support ANSI.SYS commands, you will see the control sequences on the screen; they begin with a left arrow and a [. If you find that you are having this prob- lem, read about ANSI.SYS in appendix A. Many MS-DOS machines which are not fully IBM compatible are able to run WSSINDEX, although often only with the slower DOS-calls video option. Such machines often have hardware or software IBM emulators; these may enable WSSINDEX to run. Machines with suf- ficiently incompatible keyboards cannot run the standard version. Versions for the DEC Rainbow, TI Professional and Wang PC exist or are under development and will be released shortly after the IBM version. Known incompatibilities with other software Disk Cache Warning WSSINDEX may not be compatible with the disk cache utility Light- ning, version 4.2 (not to be confused with Borland's Turbo Light- ning). Based on user reports, it appears that if two non- system disks (with labels but no files on them) are indexed in succes- sion, the volume name and directory of the second will appear to be identical to the first. This is not a WSSINDEX bug because it can be reproduced using the DOS VOL and DIR commands when Light- ning is active. I'm not sure exactly what circumstances will trigger the bug, and I don't have a copy of Lightning for test- ing, but it is potentially catastrophic if directory information is improperly buffered when you write to a disk. Similar prob- lems could conceivably also occur with other disk cache utili- ties, although none have been reported. Incompatible TSR A user reports that if the Word Perfect program SHELLDOS is load- ed, the Alt-letter keys are not functional in Wssindex on his Tandy 2000. Wssindex 5.01 62 Problems Answers to Common Questions Q. Help, my screen is filled with garbage, mostly numbers and square brackets, but also some text. A. You are configured to use DOS calls for screen output, but have not installed ANSI.SYS. If your video board is not IBM compatible, see the chapter ANSI.SYS in the appendix, other- wise read about selecting video mode in the introduction. Q. The menus would look better if they were enclosed in a box. A. They are boxed if you configure for direct video writes. The menu boxes are suppressed when using DOS calls because the large number of cursor position calls makes drawing the boxes really slow. Q. I set up a big RAM disk to increase storage capacity, but I'm still getting out of memory errors. A. WSSINDEX keeps a database entirely in memory. A RAM disk in conventional memory will only serve to decrease the memory available to the program. If you are running out of memory, try removing any memory resident programs such as Sidekick. Q. Why don't you support larger databases? A. Handling a database too large to fit into memory is both awk- ward and slow. For example, in a May, 1988 PC Magazine re- view of programmable databases, 13 of 43 commercial programs either could not sort a 50,000 record database, or else could not do so within the 3 hour time limit! Except for the prob- lem of indexing a high capacity storage device such as a CD ROM, there are definite speed advantages to multiple, moder- ate sized databases. As this is being written, a large data- base version of Wssindex, probably using expanded memory, is in the early development stage. Q. When I print my database, I get all the volume names (and subdirectories) first. A. These are the "dummy entries" which give you a place to hang comments about disks and subdirectories. You probably want to exclude them when sorting first by file name, and include them when sorting first by disk name. The easiest way to exclude them is to use selection option -1 to reject file name .ID. Wssindex 5.01 63 Common Questions Q. I don't have any subdirectories on my disks, yet WSSINDEX won't let me configure for 0 subdirectories, and it tells me I have one, even if there are no disks in the database. A. Internally, the root directories of all disks are treated as a single subdirectory, and this pseudo-directory is the one you see. Q. I see what looks like an ANSI escape sequence appearing briefly on the screen when I start up, and again when I exit. A. This will go away if you define the environment variable WSSDISP to set the default video display mode. Otherwise, WSSINDEX assumes that ANSI sequences are allowed until the configuration file is read. Q. After I run WSSINDEX, my color monitor only displays black and white and the color-setting routines I usually use don't work. A. This too should go away if you define the environment vari- able WSSDISP. The problem is that an ANSI escape sequence is setting the default black & white mode, and you are config- ured to not use color, so WSSINDEX doesn't know that it should switch you back to color mode. Q. When I print, every other page is either blank or has only one or a few lines printed on it. A. Check your configuration. The number of lines on the printer is the number of printable lines with no margin allowance. So, if you are using 8.5x11" paper at 6 lines/inch, and ask for 66 print lines, your printer will have just gone to the top of a new page when WSSINDEX sends out a form feed. Q. My laser printer only prints 60 lines/page. How can I print your documentation file which is formatted for 66 lines/page? A. I can supply replacement documentation formatted for differ- ent page lengths, or WordPerfect 5.1 files. Although Word- Perfect will attempt to convert the document to 5.0 or 4.2 format, some of the formating does not survive conversion to 5.0, and even some of the text gets lost converting to 4.2 format. Wssindex 5.01 64 Common Questions Q. Some or all of the environment variables don't seem to work. A. Are you setting them in your AUTOEXEC.BAT file and running out of environment space? Often other programs run in AUTOEXEC will clear the screen before you can read the error message. Q. When I try to make multi-column listings or disk covers, the last item printed for each file is partially cut off. A. CUSTPRNT builds up a print line containing all the items specified in the configuration, and then truncates it to fit in the available number of columns. You need to configure for fewer items printed, wider paper, or fewer columns. Q. Why don't you extract directory information from self-ex- tracting files? A. Because that would require reading every EXE file to see if it was a self-extractor, and would greatly slow indexing. Q. When I print disk covers or multi-column listings for a disk with subdirectories, the separator line which should have the subdirectory name just says "Subdirectory". A. You are configured to print the subdirectory name for each file, so the name is not shown a second time. However, the page is too narrow to display the column of subdirectory names, so it is truncated. The same thing can happen with volume labels. The solution is not to configure to print items which are truncated due to page width. Q. I have an ARC file which PKXARC or PKUNPAK says is ok, but WSSINDEX says it is corrupt. A. The PKWare extraction program will silently skip over any ascii text which is prepended to an ARC file. SEA's ARC will warn you that it is doing this. The one file I have seen with this problem had the text "Ready to send file with XMODEM protocol" prepended. The solution is to extract the files and recreate the archive. Q. My video card can display more than 25 lines of 80 charac- ters. Why don't you support this? A. This is planned for a future release. Wssindex 5.01 65 Common Questions Q. I can't seem to make the push-to-DOS option work, even with lots of memory free. A. Does the COMSPEC environment variable specify a complete path? If COMMAND.COM (or whatever) is in the root, COMSPEC says d:COMMAND.COM rather then d:\COMMAND.COM, and you are logged into a subdirectory, COMMAND.COM will not be found. Command Line Parameter Summary The various programs in the WSSINDEX package accept optional com- mand line parameters. Summarized below are the parameters recog- nized by each program. Names in upper case are the default file names, other abbreviations are: cnf- a configuration file. Default name set by environment vari- able WSSICNF, otherwise WSSINDEX.CNF. dir - a database file, Default name set by environment variable WSSIDIR, otherwise WSSINDEX.DIR. * - use default. = - generate database name from configuration file name by adding .DIR extension. cat1,2 - categories to be assigned to all files from first or second database. Hyphen means none. Multi-word categories should be enclosed in quotes. WSSINDEX cnf dir * *,= CUSTPRNT cnf dir * *,= IDADD cnf dir * * SPLIT cnf dir 1ST_HALF.DIR 2ND_HALF.DIR * *,= * * WSIMPORT cnf dir commentfile * *,= WSSMERGE cnf 1ST_HALF.DIR 2ND_HALF.DIR MERGED.DIR cat1 cat2 * * * * - - Wssindex 5.01 66 Common Questions Support Early releases of WSSINDEX were distributed as shareware with a $25 registration requested. Starting with version 4.0, the free- ly distributable version is a demo which displays a commercial on startup and will not save a database of more than 1000 files unless that database contains only one disk. In most cases, this should be sufficient to allow you to evaluate the program. If not, the merging utility is not crippled so you can create larger databases. If you purchase the complete package, you will re- ceive the demo package which you can distribute, plus replace- ments for the crippled routines and instructions for "unlocking" future demo releases. See page 69 for a fee schedule and order form. Orders and inquiries should be directed to: Robert W. Babcock WSS Division of DDC 4 Reeves Road Bedford, MA 01730 USA 617-275-1183 (you may get an answering machine) or 617-275-9104 (no answering machine on this line) Registered users will be notified immediately if any bugs capable of destroying a database are discovered. I don't mind receiving phone calls, but you will probably only get to leave a short message before my answering machine cuts you off. I do try to respond to all correspondence. If you do call, the best times to try would be early weekday mornings, weekend afternoons, or evenings 8:45-10:00 (Eastern time) any day but Thursday. If you don't get a call back within a few days, it usually means that I called and got no answer. Please try again or send a letter. If you have a bug report, please mention the version number and describe your machine and operating environment in as much detail as seems appropriate. If I am unable to reproduce a reported problem I may ask you to send a copy of your database, but usual- ly this is not required. Reports of incompatibility with partic- ular brands of machine will always be accepted even from unregis- tered users (I can hardly ask you to buy the complete package if the program doesn't work on your machine). This package is written using Turbo-C version 2.0, (but with Turbo C 1.5 memory allocation routines which maximize efficiency of memory usage rather than speed), a few routines adapted from the Computer Innovations C86 source library, and custom screen output routines in assembly language. Wssindex 5.01 67 Support The Distribution Package You should have received the following files, possibly combined in one or more self-extracting or archive files. Version numbers for the various executables (nnn in the names below) may not all be the same. Demo versions of executables will have a D appended to the file name, Rainbow, TI Pro and Wang versions will have respectively an R, T or W appended to the file name (and the name will vary slightly if this would make it longer than 8 charac- ters). BUGLIST.DOC - a list of known bugs in previous versions and a summary of enhancements. CGA.CNF- configuration file selecting CGA (color graphics adapter) video, other options set to default val- ues. CUSTPnnn.EXE - CUSTPRNT, an auxiliary utility for enhanced data- base printing. CUTPAST3.COM,.DOC - a public domain cut and paste utility, re- quires a somewhat higher degree of IBM compatibil- ity than WSSINDEX. RPN.COM substituted with Rain- bow version. DOSCALLS.CNF - configuration file selecting all default options, including DOS calls video output. IDADDnnn.EXE - a utility to modify old WSSINDEX databases so that comments may be assigned to disks and subdirec- tories, not just files. LATEST.VER - list of current version numbers MDA.CNF - configuration file selecting MDA (monochrome dis- play adaptor) video, other options set to default values. PRNDEF.DOC - A description of the included printer definition files. README.DOC - a very brief description of the other files. SCREEN.DEF - printer definition file optimized for screen out- put (used by CUSTPRNT) SPLITnnn.EXE - database splitting utility WSIMPnnn.EXE - WSIMPORT, an auxiliary routine for importing com- ments. WSSInnn.DOC - this documentation file. WSSInnn.EXE - WSSINDEX, the main executable program. WSSMnnn.EXE - WSSMERGE, a utility for merging WSSINDEX databas- es. PRNDEF.DOC - description of the various included printer defi- nition files (used by CUSTPRNT). Wssindex 5.01 68 Distribution Package Ordering Information WSSINDEX Price schedule This fee schedule replaces any previous editions. The basic registration price will increase effective November 1, 1990; old prices will remain in effect until then and other charges listed below will not change. Of course, previously purchased site licenses remain in effect under the old terms. All prices are in US dollars. ---- Registration Level ---- Charge effective 11/1/90 Level 1 Single user/machine $35 Level 2 2-10 users $10 + $25 per user Level 3 11-20 users $60 + $20 per user Level 4 21-50 users $160 + $15 per user Level 5 51-100 users $410 + $10 per user Level 6 101-500 users $910 + $5 per user Level 7 more than 500 users $3410 ---- Registration Level ---- Charge before 11/1/90 Level 1 Single user/machine $25 Level 2 2-10 users $10 + $15 per user Level 3 11-20 users $40 + $12 per user Level 4 21-50 users $100 + $9 per user Level 5 51-100 users $300 + $5 per user Level 6 more than 100 users $800 Evaluation copy (1000 file limit) $5.00 (cost credited towards purchase of complete package) Upgrade $5.00 Printed manuals not currently available Media, shipping and handling USA and Canada $2.50 ($2 evaluation) Other countries $4.50 ($4 evaluation) Check not drawn on US bank Canada $1.00 Elsewhere $15.00 Registration level upgrade price differential between old and new levels plus $10 service charge Software upgrades: your license covers all future versions of WSSINDEX and related utilities. Level 2 registrants will auto- matically be sent one copy of the next release of WSSINDEX. Wssindex 5.01 69 Order Info Level 3, 4, 5, 6 and 7 registrants will be sent one copy of all new releases made, respectively, in the 6 month, 12 month, 18 month, 2 year or 3 year period following purchase. Notes: 1. While early releases were distributed as shareware, WSSINDEX is not and has never been public domain software. If you have received the demonstration version, you are granted a limited license to evaluate it to see if it meets your needs. You may continue to use the demo version as long as you do not attempt to circumvent the built-in limitations. With a paid registration (and postage) you will receive a copy of the current demo release, plus replacements for the limited routines and a personal password for removing the limitations from future demo releases. The demo version may be distrib- uted to other users for their evaluation. 2. Although WSSINDEX is mainly written in Turbo C (with a little assembly language code), it uses a few routines derived with only small modifications from the Computer Innovations C86 source library. This makes it essentially impossible for me to sell source code, although something could probably be worked out if someone had a sufficient need. 3. I recognize that determining the exact number of users is im- possible in a large organization. A good faith estimate is sufficient. When counting users, you may use the "like-a- book" rule: just as a book can only be read by one person at a time, it should not be possible for more than the licensed number of users to use the software simultaneously. 4. This price schedule is continuous at the price breaks. It is never true that the total cost decreases when you add another user, but the marginal cost declines, eventually reaching zero at the highest registration level. 5. The question may arise in this era of multi-national corpora- tions, who can be covered under a single site license? The answer is a single company including wholly owned subsidiar- ies. For more complicated situations, please contact WSS Division of DDC for a price quote. 6. If you have needs which might be met by a special version of WSSINDEX, or a related custom utility, please contact the au- thor at the address below for estimates of feasibility, cost and development time. 7. To register or to upgrade, you may print copies of the order form below or use any convenient form. Please pay by check; I can handle purchase orders, but I cannot take credit cards. Checks may be made payable to Robert W. Babcock or to Wssindex 5.01 70 Order Info WSS Division of DDC. If you have any comments about the program, please attach them and indicate which version they apply to. 8. If you find a significant bug after purchasing the un-crippled package, and you are the first to report it, you qualify for an upgrade for only the shipping and handling fee. 9. If you want to be notified when there is a new release, please include a self addressed post card. Major new releas- es may be announced by a general mailing to all registered users. 10. If you need a receipt for tax or accounting purposes, check the appropriate box. Otherwise, you will receive a letter with your personal password. Wssindex 5.01 71 Order Info WSSINDEX ORDER FORM To: WSS Division of DDC Date: ___/___/___ 4 Reeves Road Bedford, MA 01730 Name _____________________________ Phone ____________ Company _____________________________ Address _____________________________ _____________________________ City _________________ State ________ Zip _________ Check appropriate boxes: Version ___5.01____ __ __ __ |__| Complete package |__| Evaluation copy |__| Upgrade __ |__| Site license registration (see fee schedule) __ |__| Bug report for version ______, please return my upgrade fee if previously unreported __ |__| Please send receipt (in addition to letter with password) Check disk format __ __ __ |__| 5.25", 360K |__| 5.25", 1.2 MB |__| 3.5", 720K Version (Rainbow & Wang may not be immediately available) __ __ |__| IBM PC and most compatibles |__| DEC Rainbow (MS-DOS) __ __ |__| TI Professional |__| Wang Description Price Total ----------- ----- ----- WSSINDEX Registration $35.00 ($25 before 11/1/90) WSSINDEX Upgrade 5.00 Demo evaluation copy 5.00 Disk and mailer 2.50 2.50 ($2.00 demo only) Overseas postage 2.00 Non-US bank check (see fee schedule) Site license for ___ users ----- Amount due: Appendix A - ANSI.SYS screen driver MS/PC-DOS 2 and higher allow you to install software "device drivers" when you boot your computer. These are essentially extensions of the operating system to handle specific pieces of hardware. If WSSINDEX is configured to use DOS calls for screen output, most systems will need to use the screen driver ANSI.SYS, otherwise the control sequences which are supposed to select colors, position the cursor or clear the screen will instead appear as characters on the screen. Even if you configure WSSINDEX to do direct video writes, it will still drop back to using DOS calls if it encounters an error when reading a configu- ration file. Installation of ANSI.SYS is simple: Check your boot disk with the DIR command to see if you have a file called CONFIG.SYS in the root directory. If not, use your favorite word processing program to create such a file, and in- clude in it the line DEVICE=ANSI.SYS Either upper or lower case is allowed, but if you use an editor such as WordStar which can encode formatting information in the text, be sure to specify non-document mode. If you TYPE CONFIG.SYS, you shouldn't see any funny graphics characters. If you already have a CONFIG.SYS file, simply add the above line to it with a word processor, again in non-document mode. Make sure that the file ANSI.SYS is on your boot disk, then re- boot your system. Watch for any error messages during the boot process. The display should now be much more intelligible when you run WSSINDEX in DOS calls mode. Notes: 1. The Dec Rainbow and the Sanyo 555 (without the video board option) don't need ANSI.SYS because these functions are built into the operating system. There are probably other machines for which this is also true. It is verrrrrry obvious if you lack ANSI support. 2. ANSI.SYS is not particularly fast at screen display. There are alternative commercial, shareware and public domain pro- grams with names like FANSI.SYS, NANSI.SYS, which do a some- what better job on IBM-PC compatibles. Also, different ver- sions of ANSI.SYS and replacements support different com- mands. I believe that WSSINDEX now uses only commands sup- ported by all ANSI.SYS variants, but this was not true in previous releases. Wssindex 5.01 73 Appendix A 3. I have one user who complained that ANSI.SYS interferes with some other applications software, but normally having it in- stalled all the time will do nothing worse than use up a little memory. However, ANSI.SYS also supports control se- quences to redefine keys. A rogue program could play games like redefining some key to mean DEL *.* or FORMAT C: with the appropriate confirmation. PC Magazine published an ANSI.SYS replacement which could be configured to not allow key redefinitions; other ANSI.SYS replacements may have simi- lar options. Wssindex 5.01 74 Appendix A Appendix B - Expanding the DOS Environment MS-DOS versions 2.0 and higher reserve an area of memory called the environment space which can be used to hold strings of the form VARIABLE=value You can view the environment variables by typing SET, or you can change them by typing SET something=whatever. DOS puts the PATH, PROMPT and COMSPEC variables here. Wssindex looks in the envi- ronment for WSSICNF, WSSIDIR and WSSDISP, and other programs do similar things. By default, the environment space is only 160 characters long, and if you have more than one or two programs using the environment, you may get an "out of environment space" error from DOS. This message is most likely to occur when the SET commands are in a BAT file because DOS is able to expand the environment beyond 160 bytes only if there is nothing in the way. Running a BAT file (including AUTOEXEC) gets in the way until the BAT file exits, as does loading a terminate-and-stay-resident program. The initial environment size can be increased easily, if you are using DOS 3.0 or higher, by the SHELL directive in your CONFIG.SYS file. The syntax is SHELL = [path]COMMAND.COM /P /E:nnn where nnn specifies the environment size. For DOS 3.0 and 3.1, nnn is in paragraphs (16 bytes); for DOS 3.2 or higher it is in bytes, and is rounded up to a multiple of 16. Don't forget to include the /P or else your AUTOEXEC.BAT file will not be execut- ed (and you will probably get lost in the ozone if you type EX- IT). Any change will not take effect until you reboot. The DOS 2.x SHELL directive does not recognize the /E option, so the only way to increase the default environment size is to patch COMMAND.COM. Also, under any DOS version, if you load a second- ary command processor (S option from Wssindex), the size environ- ment you will have until you exit is the larger of the the cur- rent environment and the 160 byte default. Microsoft supplies a utility called SETENV with some of its compilers to change the default environment size, but it does not recognize COMMAND.COM from all vendors (for example, it doesn't recognize COMMAND.COM for my Sanyo 555). It isn't too difficult to do the patch by hand; details are given in an article by Richard Hale Shaw, PC Magazine, April 14, 1987, page 295. Wssindex 5.01 75 Appendix B Appendix C - WSSINDEX Database Format This is a description of the format of a WSSINDEX database. This information is not needed for normal program operation, but may be useful if you want to write a program to convert an existing database into a WSSINDEX database, read the database with another program to produce a customized listing, or recover a damaged disk file. This description may be easier to follow if you use it as a guide while examining a small database with DEBUG or some other utility. Dates and times are stored in the same format as used in an FCB. Date has 7 bits for years since 1980, 4 bits for month, 5 bits for day. Time has 5 bits for hour, 6 bits for minute, 5 bits for second. The database is stored unsorted. This is done because the time required by the Quicksort algorithm used by WSSINDEX is O(n*log n) for a randomly ordered source, but O(n*n) for an al- ready ordered input. In more concrete terms, storing the data- base in sorted order would turn a 30 second sort into a longer than 10 minute sort. Notation: \n - a newline, that is an ASCII linefeed, hex 0A \EOS - end of string marker, hex 0 * - a field dependent on the WSSINDEX version var - variable length length contents (bytes) Header: 9 "WSSINDEX\n" 4-6* version number\n 2 number of disks in database 2 number of subdirectories (including root) 2 number of files Disk record, repeated for each disk: 11 volume name, blank padded to 11 chars (no \n or EOS) 4 bytes on disk 4 free bytes on disk 2 number of files on disk 2 number of subdirectories on disk (not counting root) 2 date indexed 1 "Y" or "N" for bootable or not Wssindex 5.01 76 Appendix C Subdirectory record, repeated for each subdirectory: 2 disk number, count starts at zero var subdirectory name\n File record, repeated for each file: 9 file name\EOS there may be garbage after the \EOS. \EOS is 1st character if this is a .ID record 4 extension\EOS there may be garbage after the \EOS 2 date 2 time 4 size 2 disk number, high bit set if file is a member of an archive file 2 subdirectory number (root is 0) for ordinary file, file number of containing archive file for archive member 1 "C" (if commented), else blank var comment\n if comments flag is "C" 1* "C" (if categorized), else blank; field only present if written by version 2.00 or later var* category\n if category flag is "C" Note that there is not a control-Z to mark the end of file, and there may be embedded control-Z's in the binary fields (date, time, size, etc.). This information is subject to change in future releases. Howev- er, I do guarantee that WSSINDEX will always be able to read databases written by older versions of the program (possibly with a conversion utility). Note that this guarantee does not apply to configuration files. Wssindex 5.01 77 Appendix C Appendix D - Character Code Conversion Table ascii decimal hex ascii decimal hex ascii decimal hex NUL 0 0 + 43 2B V 86 56 SOH 1 1 , 44 2C W 87 57 STX 2 2 - 45 2D X 88 58 ETX 3 3 . 46 2E Y 89 59 EOT 4 4 / 47 2F Z 90 5A ENQ 5 5 0 48 30 [ 91 5B ACK 6 6 1 49 31 \ 92 5C BEL 7 7 2 50 32 ] 93 5D BS 8 8 3 51 33 ^ 94 5E TAB 9 9 4 52 34 _ 95 5F LF 10 A 5 53 35 ` 96 60 VT 11 B 6 54 36 a 97 61 FF 12 C 7 55 37 b 98 62 CR 13 D 8 56 38 c 99 63 SO 14 E 9 57 39 d 100 64 SI 15 F : 58 3A e 101 65 DLE 16 10 ; 59 3B f 102 66 DC1 17 11 < 60 3C g 103 67 DC2 18 12 = 61 3D h 104 68 DC3 19 13 > 62 3E i 105 69 DC4 20 14 ? 63 3F j 106 6A NAK 21 15 @ 64 40 k 107 6B SYN 22 16 A 65 41 l 108 6C ETB 23 17 B 66 42 m 109 6D CAN 24 18 C 67 43 n 110 6E EM 25 19 D 68 44 o 111 6F SUB 26 1A E 69 45 p 112 70 ESC 27 1B F 70 46 q 113 71 FS 28 1C G 71 47 r 114 72 GS 29 1D H 72 48 s 115 73 RS 30 1E I 73 49 t 116 74 US 31 1F J 74 4A u 117 75 32 20 K 75 4B v 118 76 ! 33 21 L 76 4C w 119 77 " 34 22 M 77 4D x 120 78 # 35 23 N 78 4E y 121 79 $ 36 24 O 79 4F z 122 7A % 37 25 P 80 50 { 123 7B & 38 26 Q 81 51 | 124 7C ' 39 27 R 82 52 } 125 7D ( 40 28 S 83 53 ~ 126 7E ) 41 29 T 84 54 DEL 127 7F * 42 2A U 85 55 Three letter combinations are non-printing control characters. Wssindex 5.01 78 Appendix D In WSSINDEX versions for non-IBM compatible machines, all of the executable files are different, but this documentation file is unchanged. Beware of trying to transfer configuration files be- tween versions of WSSINDEX for different machines. Generally, this is only safe if DOS-calls video is selected, and even then you should examine the transferred configuration for any anoma- lies. Printer definition files and databases are transferable between versions. Appendix E - WSSINDEX for DEC Rainbow Note: release of the Rainbow version may lag the IBM version by a few weeks. Please confirm availability before ordering. Rainbow versions will normally be sent on RX-50 format disks, written on a 1.2 MB drive using a special device driver. The Rainbow version of WSSINDEX is the same as the IBM version with the following exceptions: 1. Color is not supported but fast video display and 132 column screens are supported. Specify SET WSSDISP=M for fast video. 2. The add-comments menu uses a different set of keys, which are shown in the menu. Keyboard macros are triggered by COMPOSE or F20 followed by a letter rather than Alt-letter. For hardware reasons, the COMPOSE key can only be used as a PF key on a 100A, so I have dropped it from the on-screen menus. 3. Use the CANCEL key rather than the ESCAPE key to cancel com- mands. If the screen gets messed up, the MAIN SCREEN key forces a screen reset the next time the screen is cleared. 4. The IBM version uses control plus cursor arrows for word tab- bing when entering comments or categories. The Rainbow ver- sion uses up arrow for word tab right and down arrow for word tab left. HELP, F19 and F4 substitute for Alt-PF1, END and control-END. 5. Line editing uses the delete key rather than the backspace key (actually either can be used). 6. The version number has an "R" appended. A database stored on disk will be one byte longer, but readable by an IBM version of the program (assuming you can get around disk format in- compatibilities). 7. The cut-and-paste program CUTPAST3 doesn't work on a Rainbow, so I instead include RNP.COM which I am told is a similar utility. The author does not have convenient access to a Rainbow for testing, so user reports of bugs or inconvenient key assignments are especially useful. Wssindex 5.01 79 Appendix E79 Appendix F - WSSINDEX for TI Professional I now own a minimally configured TI Pro, so release of Pro ver- sions should coincide with the standard version. The Texas Instruments Professional computer does not have IBM compatible video, so the standard version cannot run using direct video writes. Also, there is a bug in the TI ANSI.SYS support which prevents color selection from working properly. Patches to fix this are available, but they depend on the DOS version being used. They should not be necessary if direct video writes are enabled. (While I have some of the patch files, I do not have one for the version of DOS which came with my TI Pro, so I have not been able to verify that color selection works properly in DOS calls mode.) The differences in the TI Pro version are that the screen output routines know how to access the TI video hardware and adjustments are made for IBM keys not found on the TI keyboard. The built-in default colors are not appropriate for the TI Pro; I suggest usin the included TI.CNF file as a starting point for configuring. Wssindex 5.01 80 Appendix F80 Appendix G - WSSINDEX for WANG PC Note: the Wang version is still under development and a few items marked by <<>> need to be resolved. Please confirm availability before ordering. Due to keyboard differences, the standard version of Wssindex will not run on some Wang PC's without the use of an optional IBM emulation package. The Wang version of Wssindex attempts to recognize both the native mode and emulation mode keystrokes, and where possible, to use the same keys as would be used by the IBM version when running in IBM emulation mode. Only the special function keys cause problems; ordinary ascii characters need no special handling. In the IBM version, these keys are used in three places: (1) the ESCAPE key is used as a general "cancel operation" command, (2) Alt-letter triggers a keyboard macro, and (3) many function keys are used in the add- comments screen. Wssindex Function Wang mode key IBM emulation mode key Cancel operation Cancel, backtab or ^[ Backtab or ^[ Keyboard macro GL then letter 2nd then letter (If system glossaries is enabled, hit GL twice) Copy comment F1 same Copy category F3 same Copy both F5 same Skip to next F7 same Add & advance F9 or EXEC F9 Delete comment F2 same Delete category F4 same Change direction F6 same View file F8 same Exit F10 same Toggle help Help 2nd F1 Insert mode Insert same Delete char Delete same Del to end of line Erase, shift erase <<^End ??>> or delete Cursor move L/R cursor arrows same Cursor word move Shift arrows <<try control>> Beginning of line Home same End of line Shift home End (End may be keypad 1 or Exec depending on model) Wssindex 5.01 81 Appendix G81 Other differences 1. With some DOS versions, the S-option (shell to DOS) does not work in native mode. Any Wang gurus know why this is true? 2. In native mode (not using any form of IBM emulation), screen output must be done with DOS calls. If emulating an IBM monochrome (SYSMODE M) or color (SYSMODE C) system, you can use direct video writes but you must make sure that Wssindex uses the same mode (monochrome or color) as your emulator. If (when using direct video writes) you use the S option to shell to DOS, make sure that you have the same SYSMODE set- ting when you exit back to Wssindex, else the system will crash. The author does not have access to a Wang PC for testing, so user reports of bugs or inconvenient key assignments are especially useful. Wssindex 5.01 82 Appendix G82