1 Introduction March 2, 1987 Hello, I'm Jerry Shifrin, SYSOP of the East Coast Forth Board. This board has been in operation since January, 1986. If you're a PCBoard SYSOP then I'm sure you appreciate all the great features in PCBoard, as well as all the useful utilities other SYSOPs and friends have been kind enough to contribute to the growing pool of PCBoard support utilities. Since this is my first humble attempt at a PCBoard utility, you may notice that it's missing a few of the niceties we've all grown used to. Mainly the lack of reasonable colors and windows. Still, PCBMsg does the job it was designed for, and if there's any reasonable amount of interest in it (outside of my own), I'll get around to adding the appropriate ornamentation. Also, you should be aware that, at the moment, it's only been tested in a limited environment. I've tried it on the three machines I have access to (IBM PC/XT, IBM PC/AT, and a 6 MHz PC clone). I've used it with color and monochrome monitors, and the only difference I've discovered is, as you'd expect, the operating speed. This utility was written in UR/Forth from Laboratory Microsystems Inc., P.O. Box 10430, Marina del Rey, CA 90295, (213) 306-7412. This is a fine package and I recommend it highly. The basic processor was written in about 2 days of semi-intensive work. A few little enhancements were added over a couple of days afterwards. It's about 500 lines of high-level Forth code. While this program is something more than a "hack", it's not what I think of as "commercial quality". If you're interested, the source code is available for downloading from the ECFB. Note that the code is maintained in Forth "screen" format and as such will not be viewable by most edit/browse utilities. The ECFB has another utility, FSL.ARC, which allows you to view Forth screen files. If you're curious, you should download both. I hope you find this useful (it certainly was for me). I'd like to hear any problem reports you may discover. You can leave me messages on the ECFB: 703-442-8695. Please note that the ECFB isn't a general purpose board; it's primarily dedicated to technical discussions of the Forth programming language. Thanks for your cooperation. 2 Warnings, cautions, and general bogeymen You are probably aware by now that any time you download software from a BBS (or buy it in a store, for that matter), you are taking a bit of a chance. You may end up simply wasting a few dollars on long-distance charges, or, at worst, you may end up with a corrupted hard disk. I've tested this software to the best of my ability, but I can't be sure that it will work for you. I can tell you that in my environment it works fine. Also, I have only tested it with PCBoard version 11.7D. I believe it will work with previous PCBoard releases (seems to me that there haven't been any changes in the message base for quite a while), but it's difficult to predict how it might work with future PCBoard releases. If you follow the directions, this program will NEVER write to a current PCBoard message file. Finally, for the sake of my wife, daughter, and home, the standard cop-out: License ------- Copyright (c) 1986 Gerald A. Shifrin. All Rights Reserved. You are free to use, copy and distribute PCBMsg providing that: NO FEE IS CHARGED FOR USE, COPYING OR DISTRIBUTION. IT IS NOT MODIFIED IN ANY WAY. This program is provided AS IS without any warranty, expressed or implied, including but not limited to fitness for a particular purpose. 3 What does this program do Finally, we get to the meat... PCBMsg is designed to recover the valid messages from within a PCBoard message base. It will detect messages with invalid message header information, allow you to view the junk, and decide whether to save it or go on to the next message. PCBMsg is primarily menu-driven. When the system is initialized, you are presented with a set of initial choices which allow you to do the following: 1. Specify and open an input file 2. Specify and create/initialize an output file 3. Display messages in the currently selected message base 4. Copy valid messages to the specified output file 5. Validate that an existing message base has no errors. 6. Fix the message base without operator interaction. 7. Display the header information in the currently selected message base. During the course of processing, if errors are discovered in the message base, you will be given other choices depending on your current mode (Display, Copy, or Validate): 1. Display the raw message header (the actual text PCBoard saves as the header information). 2. Display the message this program thinks is invalid. 3. Find the next valid header. 4. Copy the potentially invalid message anyway. 4 Why did I write this The East Coast Forth Board contains a number of highly active conferences, where people discuss such things as Forth standards, help for new Forth programmers, experimental language extensions, etc. The various message bases are a critical component of this BBS. I take great pains to manage the message bases: protect or delete the zero-content messages; create files of useful message threads; and for two of the important conferences, I keep the entire public message history on-line. As such, problems in the message base are of crucial importance. Recently, I've had a run of problems (still of unknown origin). One or two messages in each of the conferences became garbled. In one case, this caused PCBoard to hang when a caller tried to join the conference which had a bad message in the message base. In other cases, callers simply saw a run of garbled messages - various text units appeared in the message header fields. Naturally, my first attempt to handle this was to invoke PCBoard message pack/purify/renumber function. Unfortunately, this wasn't possible for the conference which caused PCBoard to hang. For the other conferences, this seemed to work ok, but PCBoard would not get rid of the garbled messages. Rather than give up and start brand new message bases, I wrote this utility. It was able to recover all but the one or two bad messages in each conference. I don't know that it was necessary, but after running the utility, I went ahead and packed each of the restored message bases. I felt better seeing that proceed properly. 5 How do I use PCBMsg 5.1 Invoking PCBMsg You should copy PCBMSG.EXE to whichever hard disk directory you use for your various PCBoard utilities. I.e. one which appears in your DOS PATH list. Once installed, you may invoke it from whichever directory you wish to use for message processing. I'd suggest that until PCBMsg has proved its reliability in your environment, that you only work with copies of the message bases you wish to process. E.g.: CD\PCBUTIL (move to your utility directory) COPY A:PCBMSG.EXE (copy PCBMsg to this directory) CD\ MD\TEMPMSG (set up temporary directory) CD\TEMPMSG (move to it) COPY \MAIN\MSGS (get a copy of your message file) PCBMSG (invoke PCBMsg) You may specify a message file and an output file if you desire on the command line: PCBMSG \MAIN\MSGS MSGS.NEW If you don't, you will be prompted to specify them (or accept the defaults) during processing. 5.2 PCBMsg Functions 5.2.1 Introduction PCBMsg will initially greet you with a little menu of available functions. This menu shows the current version number of this program and the currently selected input and output files. From this point, you may select any of the options (described below) or exit the program. Any time you are prompted, you may respond in either upper or lower case. In most places in this program, the Escape key is recognized as synonymous with quit, exit, or other similar option. During the course of processing, you may see some action or error messages. These are displayed on the bottom two lines of your screen in intensified mode. You will also hear a short, friendly beep. 5.2.2 Set input file If you specified a file name in the PCBMSG command line (e.g. PCBMSG TEMPMSGS), that name will be displayed as the current input file. You may change to any other input file by selecting the "I" option. PCBMsg will prompt you to enter a new file name. You may hit the enter key to default to the file named MSGS. PCBMsg will then attempt to open this file and read in the file header information (you may display this with the "B" option described below). Naturally, if there is a problem with this, you will receive an appropriate error message. 5.2.3 Set output file If you specified two file names in the PCBMSG command line (e.g. PCBMSG TEMPMSGS NEWMSGS), the second name will be displayed as the current output file. You may change to any other output file by selecting the "O" option. PCBMsg will prompt you to enter a new file name. You may hit the enter key to default to the file named MSGS.NEW. PCBMsg will then determine if this file already exists. If so, you will be prompted to confirm that you wish to overwrite this file. Once PCBMsg has a valid output file, it will initialize it - you now have an empty file by the specified name. DO NOT SPECIFY YOUR ORIGINAL PCBOARD MSGS FILE AS THE OUTPUT FILE! THAT IS THE ONLY WAY THIS PROGRAM CAN DESTROY YOUR MESSAGE BASE. If any problems occur (e.g. no more disk space), you will receive an appropriate error message. 5.2.4 Display message base This option allows you to scan through the message base. For each valid message or full screen of text, PCBMsg will prompt you as follows: Hit Esc to quit, C for continuous, or any other key to continue Esc returns you to the main menu C displays messages continuously (non-stop) until either an error is found or the end-of-file is reached. other key goes on to the next part of the current message or clears the screen and goes to the next message. This continues until either an error is found or the end-of-file is reached. If an error in the message base is detected, you will be shown a new menu with the following options: R Show raw header - allows you to see the actual text which was incorrectly stored as a message header. F Find next message - allows you to skip until the next valid head or end-of-file is found. S Show current message - allows you to view the currently assembled message. X Return to previous menu - allows you to return to displaying messages. 5.2.5 Copy message base This option allows you to copy your input message base to the specified output file. For each valid message or full screen of text, PCBMsg will prompt you as follows: Hit Esc to quit, C for continuous, or any other key to continue Esc returns you to the main menu C displays and copies messages continuously (non-stop) until either an error is found or the end-of-file is reached. other key copies the message and goes on to the next part of the current message or clears the screen and goes to the next message. This continues until either an error is found or the end-of-file is reached. If an error in the message base is detected, you will be shown a new menu with the following options: R Show raw header - allows you to see the actual text which was incorrectly stored as a message header. F Find next message - allows you to skip until the next valid head or end-of-file is found. S Show current message - allows you to view the currently assembled message. C Copy current message - allows you to copy the currently assembled message. You should [F]ind the next valid message before copying it. You will then be returned to copying messages. X Return to previous menu - allows you to return to displaying messages. 5.2.6 Validate message base This option allows you to search for errors in your input message base. PCBMsg will read messages until it finds one which appears to be invalid. If an error in the message base is detected, you will be shown a new menu with the following options: R Show raw header - allows you to see the actual text which was incorrectly stored as a message header. F Find next message - allows you to skip until the next valid head or end-of-file is found. S Show current message - allows you to view the currently assembled message. X Return to previous menu - allows you to return to validating messages. 5.2.7 Fix message base This option allows you to go ahead and build an entire new message base without further prompts or displays. PCBMsg will read and copy all valid messages to the current output file. Any messages with invalid header information will simply be skipped. 5.2.8 Show message base information The first block in each PCBoard message file contains some information about its contents. This option will display the following information: Number of the last message left in this message base Number of the last caller on the system An indication of whether or not this message base is currently being updated. This information is not currently used at all by PCBMsg. I'd suggest that if the message base is currently being updated, then either you're running under a network and that you should not be using this program with a live message base; or else the message base is hopelessly fouled up. 5.2.9 Exit program The Exit option simply closes all files and returns to the operating system 6 Known problems The only problem I'm currently aware of is that the message header is not properly displayed. Don't worry! It's copied without modification to the output file. As soon as I get some better documentation on the message formats (or bite the bullet and figure it out the hard way), I'll go ahead and fix up the message header display. I'd appreciate hearing any new problem reports. I'd be amazed if there are none. 7 What's next There are a number of things I plan to add to this program to meet my own needs: 1. Allow selective copying of messages to either the output message base or to a text file. This is to allow me to more easily add message archives. 2. Allow specification of a range of message numbers to be copied. Also allow non-selection of private and/or deleted messages. 3. Allow concatenation of message bases. 4. If I have more free time than I expect, I'd like to provide the ability to edit messages. Some of the messages I've left after a few drinks are a bit embarrassing (at least with respect to spelling and grammar). 5. Provide a nice, fast message base display, with full use of the scroll, home, and end keys. I'm sure you can think of other niceties. Please let me know if you have some suggestions. 8 Non-plea for money As much as I'd like all PCBoard users to send me a few hundred dollars each, I have to admit that that's (1) unlikely, and (2) not really necessary. I wrote this program for my own needs (but did the documentation just for you). As reliable as PCBoard is, you'll probably have little need of this utility's capabilities. But if you do manage to save a critical message base, I'd appreciate hearing about it. If you still can't save it with this program, I'd also like to hear about whatever problems you had - I'll probably run into them eventually. If you do care to reciprocate in some way, I'd appreciate copies of your PCBoard utilities, doors, whatever. You may reach me at: Jerry Shifrin 6212 Loch Raven Dr. McLean, VA 22101 ECFB: 703-442-8695 Good luck!