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

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?

  1. How can I tell if an Agenda file is damaged?

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


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:

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.