Agenda 2.0 Hot Topics
What Version am I Using?
All Agenda 2.0 customers should check to make sure that they are using the most current version of the Agenda program files. These files were introduced in the Update B kit, and are now included in every new package of Agenda. The latest version of the Agenda code can be identified by checking the version of the A.EXE file. The original version of Agenda 2.0 had the dates 8/17/90 on its .EXE files. The Update Kit had dates of 10/15/91. The Update B Kit had dates of 4/29/91. The version which can currently be purchased has dates of 10/1/91 on all of the .EXE files, and includes the checker (AG_CHK.EXE) for verifying and restoring the integrity of Agenda databases that was introduced in Update B. Customers using anything but the latest build or the Update B kit should obtain the Update B kit from Lotus Customer Service at 1-800-343-5414. The Update B kit is free of charge.
File Damage
There are a number of things which can contribute to errors in agenda databases. These are outlined in an attached technote. Following these guidelines, regularly checking databases for corruption, and fixing that corruption with AG_CHK/F can help to minimize instances of data loss in Agenda data files.
The Agenda 2.0 HP Driver and Icon Disk
Lotus now provides customers with support for an HP LaserJet III or an IBM Laserprinter with Agenda 2.0. Customers needing this driver, or who want .PIF and .ICO files for use with Microsoft Windows 3.0 may order the Agenda 2.0 HP Driver and Icon Disk. These diskettes can be obtained free of charge from Lotus Customer Service by calling 1-800-343-5414. These drivers and files are also available on CDPROMPT, and come with the latest version of Agenda.
Damaged Print Markers
Sometimes an error message will appear when printing through Agenda which says "Out of Virtual Memory When Printing", which usually means exactly that. An explanation of Agenda's use of Virtual memory can be found in Appendix E of the Agenda 2.0 User's Guide. There are, however, other things which can cause this message, namely damaged print markers.
If attempts to rectify a virtual memory shortage (page E-5 of the User's Guide) do not resolve the problem, then an attempt to clean up the file should be made. Print markers should be cleared, and the file saved. AG_CHK/F should be run on the file, and any damage should be fixed. The file should then be retrieved, and another print attempt should be made. If the error is due to damaged print markers, this should fix the problem.
Slow Performance
Lotus Technical Support gets lots of questions regarding slow performance under Agenda 2.0. There are several reasons that performance can drop, but there are three that are most common.
The first is file size. The larger the file, the slower Agenda will be. This is true primarily because as a file grows, so does the number of categorization links which must be maintained and updated. The reality of this maintenance process is that it takes time. To help alleviate this, done items can be exported to an archive file, freeing up the resources calculating non-current items. This reason for slow performance ties in with the second reason, low memory resources.
Agenda likes to have lots of available conventional and expanded memory. The more room it has to work, the faster it will be. As RAM resources increase, it will have to swap to the hard drive less, and performance will increase accordingly. Because of the comparatively slow speeds involved with accessing a disk drive as opposed to RAM, and because of the mechanics involved in creating and maintaining virtual memory, swapping to the hard drive is much slower than accessing RAM.
The third is file damage. If a file has become damaged, the ability to update the categorization links can be compromised. If the links themselves are damaged, then they may never be able to update completely. If they cannot update, Agenda will waste time and resources trying to perform a task which it cannot complete, slowing the product down considerably. If a file becomes damaged, the Checker should be run on it, and the damage should be corrected. If the damage cannot be corrected with the Checker, then DB2STF should be run as outlined in Appendix I of the Agenda 2.0 User's Guide. DB2STF should be able to recover the items and categories from an Agenda database, and that information can be imported into a new file.
What Can be done about Damaged Agenda 2.0 Files?
Problem: Damaged Agenda 2.0 Files. Recovery and Troubleshooting Information.
Solution: In an ideal world, computers and software would work flawlessly, and Agenda files would never become damaged. Many Agenda users appear to live in that world now, and their files never break. However, some users find that their files seem to suffer damage repeatedly. This document will attempt to cover several topics:
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 stating that the file is damaged. The second way is to run the AG_CHK utility, which will analyze the database's integrity and indicate whether anything is wrong. If the file AG_CHK.EXE is not present in the customer's Agenda directory, they should order the latest version of Agenda. (To determine whether the version of Agenda 2.0 is up-to-date, check the file size and date of the 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 the Agenda 2.0 Update B Kit. The update can also be downloaded from the LOTUSB forum on CompuServe.)
2. When an Agenda file is "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?
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, enter the command:
AG_CHK /F PLANNER
AG_CHK will attempt to repair the database, and will report whether or not it succeeded. AG_CHK can repair most sorts of minor damage. In fact, the original PLANNER.AG file that shipped with Agenda 2.0, which was written even before the AG_CHK utility was, has some stray information in it that AG_CHK will report as damage (though it won't actually hurt the file), and AG_CHK /F will correct it.
There are two special cases which should be mentioned here.
AG_CHK, then, should always be the first step. However, AG_CHK can only do so much. If extremely severe damage to an Agenda 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, use DB2STF to recover the Agenda database. Instructions for running DB2STF are in Appendix I of the Agenda 2.0 User's Guide. DB2STF will attempt to rescue the items, categories, and category assignments, and can usually recover all of the actual data. What DB2STF cannot do is recover the views, so if DB2STF is used to recover the database, the views will have to be reconstructed. For information on how to avoid this in the future, see the "What can be done to make recovering from damage easier if it does happen?" section, later on in this document. If DB2STF does not recover all of the data, the missing data is probably not in the file any more.
4. What causes an Agenda file to become damaged and how can it be prevented?
Once the Agenda file has been recovered, the above question will almost certainly be foremost in the customer's mind. Verify that the customer is using the most recent version of Agenda 2.0. Refer to section 1 of this document and follow the instructions there for checking the 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 the most recent update of Agenda 2.0, Update B, there are no known problems within Agenda that cause it to damage its own files. Agenda is a very complicated program, and it is certainly possible that there are problems somewhere in it that have yet to be discovered, which cause it to damage its own files. However, in all the cases of damage that Lotus has seen since shipping Update B in January 1991, there have been only a few for which the cause has never been determined, and in no case was the cause found to be Agenda itself
.If a series of actions within an Agenda file cause the file to become damaged, and if after the file has been recovered and AG_CHK reports that it is intact, those same actions cause it to become damaged again, then call Lotus Technical Support (1-800-223-1662) and have a technician walk through these steps to recreate the problem. If the same sequence of steps produce damage on the technician's database as well, then there may be a problem with Agenda. If they don't, try those same steps with the same data file on another computer, and see if damage occurs on the new machine. If the problems cannot be reproduced here, or if the problem occurs on only 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:
The most common cause of damage is "routine" system failure. Power failures, tripping over the power cord, shutting the machine off without quitting out of Agenda, Windows crashing, the network crashing, the machine locking up without any explanation, are all examples of routine system failures. If any of these things happen while working in Agenda, use AG_CHK to check the database. If AG_CHK says the file is okay then continue to work with the file. If AG_CHK says the file is damaged, immediately take the steps described in the previous section to recover the file. Keep in mind that a damaged Agenda file may not cause the DMGD! indicator to come up right away, because the damage may be in a part of the file that Agenda hasn't had to look at since the damage occurred, like an old item or another view. If AG_CHK says it's damaged, repair it before attempting to use the file
"Routine" problems are relatively easy to deal with, because when one happens, it is easy to determine what has occurred and 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 it is discovered, 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 that is running at the same time as Agenda. If Agenda is being run 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 the problems go away. If they do, contact the manufacturer of the multitasker or task-swapper and have them help check the system's configuration. It may be that the multitasker is conflicting with some other element of the system, and that making a few setup changes will correct the 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 known 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 customers' configurations, but it is certainly something to be aware of if Desqview is used.
Beyond multitaskers and task-swappers, another critical piece of software is the expanded memory manager. New memory managers such as QEMM, 386MAX, and DOS 5.0's EMM386.SYS allow customers 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 the "loadhigh" and/or "devicehigh" features of a memory manager are being used, disable them for a while and see if the 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 a particular hard drive, or a memory manager, for instance, then every time information is read from or written to the hard drive it is in danger. If a customer is running a disk cache and notices repeated damage to Agenda files, disable the cache and run without it for a while to see if that eliminates the problems. If it does, contact the manufacturer of the disk cache to see if they can help identify the source of the conflict.
Lotus has had no reports that indicate that any of the popular disk cache programs are inherently incompatible with Agenda. Lotus has, however, had a number of reports of problems with various disk caches if the cache is set up to use expanded memory. Lotus recommends, then, that disk caches be set up to run in extended memory, not expanded. The documentation for a disk cache program should have instructions on how to do this. The configuration of the expanded memory manager may need to be changed 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 repeated damage to Agenda files occurs, and TSRs are present, 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 the TSR available.
If multitaskers, task-swappers, expanded memory managers, disk caches and TSRs all don't seem to be the cause (that is, they either are not being used, or they are disabled and good Agenda files continue to become damaged) if the file is 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, assume that the machine currently being used is okay, and that the problems lie either with the network, or with one of the other machines Agenda is run 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 the damage may not be apparent. Again, the simplest test for whether the network is at fault is to try Agenda on each individual machine, running stand-alone. If there are no damaged database problems with PCs A, B or C, for instance, but when they are connected to the network damaged database problems occur on all three, then it's quite likely that network problems are the cause of the damage. Obviously, this test is less practical if there are 70 PCs connected to the network, not just three, so in these cases, proceed directly from the single, stand-alone test to hardware diagnostics and/or calling the network vendor.
The last factor, but the most important of all, is to make sure that the hardware is not malfunctioning. The set of components that have been mentioned as links but haven't been covered yet -- the hard drive, RAM, diskette drives and the modem if there is one -- combine to cause an overwhelming majority of mysteriously damaged Agenda files (i.e., those not caused by rebooting while Agenda is saving the file). The kinds of cursory checks that the system does automatically, like the RAM check that counts up in the top left corner when the machine is turned on, are only good enough to detect components that do not work at all. Much more dangerous are the problems where the hard drive or RAM chips suffer occasional, sporadic data loss. To locate these problems, "stress" diagnostics are required. 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. A computer dealer will probably have diagnostic programs that are specific to the PC, and if they do, those are the best choice. If they don't, see if the PC manufacturer recommends any particular third-party diagnostic package, and use that.
If the hard drive checks out okay, keep in mind that if the computer has more than 640K, memory failures can be isolated 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 the problems occur, the harder it will be to pinpoint the cause of them, simply because a longer time will have to elapse without the problem before it appears that it has actually been corrected. So, while it can be easy to know that the problem has not been found (e.g., if the disk cache is disabled and damage still occurs, then it can be determined that the 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.
5. What can be done to make recovering from damage easier if it does happen?
In order to prepare for future damage recovery, a customer must have a clean file to begin with, so refer to the section on fixing damaged databases if necessary. 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 can be used for importing the Structured Text File (STF) that DB2STF puts recovered items, notes, categories and assignments in.
AG_CHK should be run as part of the normal maintenance routine and if AG_CHK reports that one of the databases is damaged, it should be fixed immediately, even if the damage hasn't shown up in Agenda yet.
The blank copy of the structure is called a "template", and this can be created by selecting [F10] File Transfer Template within Agenda. Information on using this command is on page 23-26 in the User's Guide. Once a template has been created, use AG_CHK to make sure that it is intact, and then put it in a safe place. If the Agenda database is later damaged, even if AG_CHK can't fix the problem, run DB2STF, copy the template back into the Agenda directory, and import the recovered STF file into the blank template. This saves having to rebuild the views, which can make a big difference.
Lastly, make frequent backups of important Agenda databases.