In an ideal world, computers and software would work flawlessly, and your Agenda files would never become damaged. Many Agenda users appear to live in that world now, and their files never break. Some users (you, perhaps, if you're reading this), find that their files seem to suffer damage repeatedly. This document will attempt to cover several topics:
How can I tell if an Agenda file is damaged? When an Agenda file gets "damaged", what does that mean? Once an Agenda file becomes damaged, what can be done to fix
it?
What causes an Agenda file to become damaged and how can I
stop it?
What can I do to make recovering from damage easier if it
does happen?
There are two ways to tell if a file is damaged. The simplest is if Agenda puts up the DMGD! indicator and an error box telling you that your file is damaged. The second way is to run the AG_CHK utility, which will analyze your database's integrity and tell you if anything is wrong. If you do not have an AG_CHK.EXE file in your Agenda directory, you may not have the latest version of Agenda. (To find out if your copy of Agenda 2.0 is up-to-date, check the file size and date of your A.EXE file. The file size should be 677,282, and the date should be some time in 1991. If it is not, call Lotus Technical Support at 1-800-223-1662 and request "Update B". The update can also be downloaded from the LOTUSB forum on CompuServe.)
2. When an Agenda file gets "damaged", what does that mean?
"Damage" simply means that Agenda cannot interpret some of the information in the current Agenda file. It most likely means that the current Agenda file has been modified by something other than Agenda itself.
The structure of an Agenda database is extremely complex, due to the high number of complicated relationships between items and categories, items and notes, views and items, conditions and actions, etc., that Agenda must keep track of. Each item, category, view, section, etc. is linked to many other items, views, dates, etc. So, where changing one byte of a word processor document would most likely do nothing worse than putting in a strange character, and changing one byte of a spreadsheet would probably affect no more than one cell, changing one byte of an Agenda file might affect not only the item that got changed, but all the categories, views and sections that are linked to it, and potentially all the things that are linked to each of them. Thus, although Agenda files are technically no more likely to become damaged than any other types of files, the consequences of an Agenda file becoming damaged are potentially much more severe than with other kinds of data files.
3. Once an Agenda file becomes damaged, what can be done to fix
it?
If you have a damaged file, the first thing you will want to know is how to fix it. The easiest way to fix a damaged file is to run the AG_CHK utility, with the /F parameter. To fix a file called PLANNER.AG, for instance, you would type:
ag_chk /f planner
AG_CHK will attempt to repair your database, and will report whether it succeeded or not. AG_CHK can repair most sorts of minor damage. In fact, the original PLANNER.AG file that shipped with Agenda 2.0, which we created even before we had AG_CHK ourselves, has some stray information in it that AG_CHK will report as damage (though it won't actually hurt you), and AG_CHK /F will correct.
(There are two special cases which should be mentioned here. 1) AG_CHK will erroneously report your file to be damaged if you have the Empty trash: setting (under F10 File Properties) set to "When item is discarded". Change the setting to any of the three other choices, such as "When file is closed", to prevent this. 2) On some machines, AG_CHK will report ALL Agenda databases as being damaged. If AG_CHK has ever reported a file to be okay on your system, you can skip to the next paragraph. If AG_CHK always comes up damaged, check your CONFIG.SYS file for the line STACKS=0,0, and remove it. This line, on some machines with older ROM BIOSes, interferes with the functioning of AG_CHK in a way which is not entirely clear to us. Removing it solves the problem, at the expense of a very small (i.e. less than 5K) reduction of available memory. In at least two cases, users with very old Zenith ROM BIOSes have reported that removing STACKS=0,0 still did not allow AG_CHK to function correctly. If you find that AG_CHK still shows every Agenda file to be damaged after removing STACKS=0,0, contact your computer dealer or manufacturer and see if a more recent version of your ROM BIOS is available.)
AG_CHK, then, should always be your first step. However, AG_CHK can only do so much. If extremely severe damage to your file has occurred, there may not be enough of the structure remaining for AG_CHK to simply repair the database. If this is the case, you must use DB2STF to recover your database. Instructions for running DB2STF are in Appendix I of the Agenda 2.0 User's Guide. DB2STF will attempt to rescue your items, categories, and category assignments, and can usually recover all your actual data. What DB2STF cannot do is recover your views, so if you have to use DB2STF to recover your database, you will have to reconstruct your views. For information on how to avoid this in the future, see the "What can I do to make recovering from damage easier if it does happen?" section, later on in this document. If DB2STF does not recover all your data, the data you do not see is probably not in the file any more.
(This seems like an appropriate time to remind you that using computers for important work without making frequent, regular backups is extremely foolish. When you put your life in a car, wear a seat belt. When you put your life in a computer, make backups. End of sermon.)
4. What causes an Agenda file to become damaged and how can I
stop it?
Once you have recovered both your file and your composure, the above question will almost certainly be foremost on your mind. The first thing to make sure of is that you have the most recent version of Agenda 2.0. If you haven't done so already, go back to section 1 of this document and follow the instructions there for checking your A.EXE file's size and date.
Generally speaking, there are only two ways for an Agenda file to become damaged. The first is for Agenda itself to do something wrong to the file. The second is for some other factor (software or hardware) to cause Agenda's data to change without Agenda being aware of it.
As of today (February 24, 1992) and the most recent update of Agenda 2.0, Update B, there is only one known problem within Agenda that causes it to damage its own files. If you use F10 Utilities Show Schedule twice in a row, one of the links that Agenda uses to sort the schedule view will not get properly deleted, and the database will become damaged. This problem is simple to avoid, and simple to correct. To avoid it, delete the Show view manually (by hitting F8, highlighting Show view, hitting Delete and choosing Yes) before using F10 Utilities Show Schedule a second time. You can correct the problem in existing files by running the AG_CHK utility with the /F switch.
Agenda is a very complicated program, and it is certainly possible that there are other problems somewhere in it that nobody has discovered yet, which cause it to damage its own files. However, in all the cases of damage that we have seen since shipping Update B in January 1991, there have been only a handful that we have never discovered the cause of, and none of the causes we have found were Agenda itself.
If you find a series of actions within Agenda that cause your file to become damaged, and if you find that after you recover your file and AG_CHK reports that it is intact, those same actions cause it to become damaged again, then you should call Lotus Technical Support (1-800-223-1662) and have a technician walk through the steps you are doing with you. If your steps produce damage on the technician's database as well, then you have probably found a problem with Agenda. If they don't, you should try those same steps with the same data file on another computer, and see if they happen there, as well (if you don't have access to another computer, the technician may ask you to send in the file and we will try your steps on our own machines).
If we can't reproduce the problems here, or you find that the problem happens only on one computer, then Agenda is almost certainly not the cause.
That said, there are a number of external factors that can damage an Agenda file. Conceptually, any part of the Agenda "signal path" could be at fault. Here are the important links in that path:
"Routine" problems are relatively easy to deal with, because when one happens, you know it just happened, and you can take action. The harder problems are the ones that don't announce themselves, because there may be a substantial delay between when the damage occurs and when you actually discover it, and this makes it difficult or impossible to know what the cause was.
The easiest of these things to check for are conflicts with other software you are running at the same time as Agenda. If you are running Agenda under a multitasker or task swapper like Windows, Desqview or Software Carousel, try using Agenda for a while just from a DOS prompt, and see if your problems go away. If they do, contact the manufacturer of the multitasker/task-swapper and have them help you check your configuration. It may be that your multitasker is conflicting with some other element of your system, and that making a few setup changes will correct your problem.
There are a couple of known problems in this area. The first one involves the MS DOS 5.0 Task Swapper. The initial release of the DOS 5.0 Task Swapper has serious problems swapping applications that use expanded memory. As of this writing (11/27/91), a fix from Microsoft has not been announced, so until one is, do not use the Task Swapper to run any application that uses expanded memory.
The other reported problem is that using Agenda's Alarm feature has caused problems for some people who run Agenda in the background under Desqview. It isn't clear whether this problem is universal, or whether it was caused by other elements of the users' configurations, but it is certainly something to be aware of if you use Desqview.
Beyond multitaskers and task-swappers, another critical piece of software is your expanded memory manager. New memory managers such as QEMM, 386MAX, and DOS 5.0's EMM386.SYS allow you to do interesting things like relocate the EMS page frame and load device drivers and TSRs into upper memory. While there are no inherent problems with doing these things and running Agenda, the potential for causing memory conflicts when loading things into upper memory is high, and any problem that interferes with expanded memory access is very bad for Agenda. If you are using the "loadhigh" and/or "devicehigh" features of your memory manager, you should disable them for a while and see if your problems go away. If they do, contact the manufacturer of the memory manager for assistance in identifying and avoiding possible memory conflicts.
Another component that is in a position to do a lot of damage if it fails is a disk cache. Disk caches, such as Smartdrive, PC-Cache or PC-Kwik, can speed up disk access enormously, but at the expense of adding another level of vulnerability to all disk accesses. If a disk cache runs into a conflict with your particular hard drive, or your memory manager, for instance, then every time information is read from or written to the hard drive it is in danger. If you are running a disk cache and you suffer repeated damage to Agenda files, disable the cache and run without it for a while to see if that eliminates your problems. If it does, contact the manufacturer of the disk cache to see if they can help you identify the source of the conflict. We have had no reports that indicate that any of the popular disk cache programs are inherently incompatible with Agenda. We have, however, had a number of reports of problems with various disk caches if the cache is set up to use expanded memory. We recommend, then, that you setup disk caches to run in extended memory, not expanded. The documentation for your disk cache program should have instructions on how to do this. You may need to change the configuration of your expanded memory manager to make more extended memory free.
The last software-based source of potential problems is TSRs. TSRs, or Terminate and Stay Resident programs, like Sidekick, Metro or Norton Anti-virus, are utility programs that stay loaded at all times and can usually be activated with a certain key-combination. It used to be that TSR conflicts were a huge source of strange problems with all sorts of software applications, but most popular TSR programs have been cleaned up in the past few years, and these problems are now relatively rare. Still, if you suffer repeated damage problems, and you run TSRs, try deactivating them for a while and see if the problems go away. If they do, see if there is a more recent version of your TSR available.
If multitaskers, task-swappers, expanded memory managers, disk caches and TSRs all don't seem to be the cause (that is, you either aren't using them to begin with, or you disable them and clean files continue to become damaged), then it is time to begin examining your hardware.
If you use the file on a network or on more than one machine, a good first step would be, as a test, to run Agenda only on a single, stand-alone machine for a while and see if the problems go away. If they do, you can assume with some degree of confidence that the machine you are currently working on is okay, and that the problems lie either with the network, or with one of the other machines you use Agenda on.
Network problems can involve defective network adapters, transmission failures, or problems with the network server. Because other types of files do not react as obviously to damage as Agenda files do, it may appear that Agenda is the only program suffering data loss, while in fact in other data files you may simply not notice the damage. Again, the simplest test for whether the network is at fault is to try Agenda on each individual machine, running stand-alone. If you experience no damage problems with PCs A, B or C, for instance, but when you connect them to the network you have damage problems on all three, then it's quite likely that network problems are the cause of your damage. Obviously, this test is less practical if you have 70 PCs connected to the network, not just three, so in these cases you may want to proceed directly from the single, stand-alone test to hardware diagnostics and/or calling your network vendor.
The last factor, but the most important of all, is to make sure that your own hardware is not malfunctioning. The set of components that I mentioned as links but haven't covered yet -- your hard drive, RAM, diskette drives and your modem if you use one -- combine to cause an overwhelming majority of mysteriously damged Agenda files (i.e., those not caused by rebooting while Agenda is saving the file). The kinds of cursory checks that your system does automatically, like the RAM check that counts up in the top left corner when you turn the machine on, are only good enough to detect components that do not work at all. Much more dangerous are the problems where your hard drive or RAM chips suffer occasional, sporadic data loss. To locate these problems, you need to acquire "stress" diagnostics. These are programs that perform a given operation, like writing data to the hard drive and reading it back again, over and over and over again, waiting to see if anything will ever go wrong. These are best left running overnight or over a weekend, because a sporadic failure may only occur every 2,000,000 writes, for instance, and that many writes may take a while to do. Your dealer will probably have diagnostic programs that are specific to your PC, and if they do, those are your best choice. If they don't, see if your PC manufacturer recommends any particular third-party diagnostic package, and use that.
If your hard drive checks out okay, keep in mind that if you have more than 640K in your computer you can check for memory failures by simply removing the additional memory and seeing if the problems persist.
The last thing to know about diagnosis and correction is that the more infrequently you have problems to being with, the harder it will be to pinpoint the cause of them, simply because you will have to go longer without the problem to be convinced that you've actually corrected it. So, while it can be easy to know that you haven't found the problem (e.g., if you disable your disk cache and damage still occurs, then you know your disk cache was, if not blameless, then at least not the sole culprit), it can be hard knowing whether a long spell without damage is the result of having actually identified the problem, or is just luck. The only comforting advice I can give in these situations is, again, make backups.
Which leads me to the last section. 5. What can I do to make recovering from damage easier if it
does happen?
In order to prepare for future damage recovery, you must have a clean file to being with, so go back to the section on fixing your database if you need to. The keys to quick recovery are running AG_CHK regularly, and having a blank copy of the structure (i.e., the views, the macros and the category hierarchy) that you can use for importing the Structured Text File (STF) that DB2STF puts your recovered items, notes, categories and assignments in.
You should run AG_CHK as part of your normal maintenance routine (and if you don't have a normal maintenance routine, you should), and if AG_CHK reports that one of your databases is damaged, you should fix it immediately, even if the damage hasn't shown up in Agenda yet.
The blank copy of the structure is called a "template", and you create one by doing F10 File Transfer Template within Agenda. Information on using this command is on page 23-26 in the User's Guide. Once you have made a template, use AG_CHK to make sure that it is intact, and then put it in a safe place. Now, if anything happens to your database, even if AG_CHK can't fix the problem, you can run DB2STF, copy the template back into your Agenda directory, and import the recovered STF file into your blank template. This saves having to rebuild your views, which can make a big difference.
And, lastly, at the risk of repeating myself, if you do not make frequent backups of your important files, no matter what program they come from, you are not acting wisely. Make backups; we will both sleep easier.