4DOS Critical Error Handler Version 2.00 by Niels Jensen Copenhagen 1992 -------------------------- This file is the documentation of the 4DOS Critical Error Handler (4DOS24H2.COM). Generel Rules ~~~~~~~~~~~~~ The program(s), the source code and this documentation file is given free to the PUBLIC DOMAIN. Hence nobody is allowed to charge any amount of money for the files included in this package, and everybody can use the programs without paying for it. Feel free to modify the code to fit your own needs but please don't put my name under a modified version if redistributed. Disclaimer ~~~~~~~~~~ Usage of 4DOS24H1.COM or 4DOS24H2.COM is done fully at your own risk and I am not to be held responsible for any kind of damage caused by using any of the programs in this archive. Contents of this documentation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Contents of the Archive - A list of the files included in the arhive with a short description of each About This Documentation - Things concerning how this documentation is written About 4DOS24H2 - A short introduction Highlights - A list of the most important features Installation - How to install the critical error handler Usage - How to operate 4DOS24H2 Unloading - How to unload 4DOS24H2 Trouble Shooting - Look here if you encounter problems with 4DOS24H2 Contents of the archive ~~~~~~~~~~~~~~~~~~~~~~~ Originally the archive includes the following files: 4DOS24H2.COM - The new critical error handler. 4DOS24H2.ASM - Assembler source code for 4DOS24H2.COM. 4DOS24H2.DOC - This documentation file. 4DOS24H1.COM - A special version of the handler which uses only 40 columns across the screen. This is necessary if you use any of the old standard 40 columns text modes and you don't want your display garbled. README - This file contains a short description of the program and a quick-installation guide. Also any last minute information which could not be integrated in this documentation file can be found here. About this documentation ~~~~~~~~~~~~~~~~~~~~~~~~ When refering to the handler in the text the name "4DOS24H2" is used to mean "either 4DOS24H1 or 4DOS24H2." The functionality of the programs are identical and both will be treated alike. The only difference is the number of character columns used in their pop-up message windows when a critical error occurs. 4DOS24H1 uses only 40 character columns while 4DOS24H2 uses 41 columns to show the message window. About 4DOS24H2 ~~~~~~~~~~~~~~ 4DOS24H2.COM is a critical error handler to replace the one build into the otherwise excellent 4DOS command interpreter. The critical error handler is the piece of code displaying the notorious "Abort, Retry, Ignore" message when you have forgotten to put a disk in the disk drive. Due to the nice behaviour of 4DOS it is possible to replace this piece of code with an external handler. This is not possible when using COMMAND.COM and therefore this program will not work with COMMAND.COM. More specifically 4DOS24H2.COM is a RAM-resident routine that remains in the computers storage until you either reboot your computer or turn off the power (see also the TECHNICAL DETAILS in the README file). It is written purely in assembler for maximum efficiency and is optimized for space efficiency (speed isn't very crucial in this context!). The source code is included in 4DOS24H2.ASM and can be modified and reassembled to satisfy individual needs. A Special Thanks... This program is written on the basis of Patrick Philippot's excellent 4DOS24H released to the public domain in 1990. A special thanks therefore goes to Patrick Philippot for the original idea, source code and program. Without the inspiration and basis from this work it would have been impossible to write 4DOS24H2. Highlights ~~~~~~~~~~ * Gives a clear explanation of the error, it's locus and type and shows how to react. * Restores the screen after an error. * Handles all standard text modes. * Handles extended text modes as well (e.g. Tseng ET4000 132x44 character mode). * Written in assembler and optimized to use minimum amount of memory. * Can be loaded high using 4DOS version 4.00 or later. * Source code with comments included. Installation ~~~~~~~~~~~~ To install the handler you just need to run 4DOS24H2.COM by putting the following line in your 4START.BTM (or 4START.BAT) file: [d:path]4DOS24H2.COM were [d:path] is the (optional) drive and path to the directory in which 4DOS24H2 resides. Drive and path can be omitted only if you keep 4DOS24H2 in the root directory of your boot drive. If you don't have a 4START file consult your 4DOS documentation for details about how to create one. Remember to replace 4DOS24H2 with the actual version of the handler (4DOS24H1.COM or 4DOS24H2.COM). If you are using 4DOS version 4.0 or later and DOS 5.0 or later you can load 4DOS24H2 into high memory (provided you have enough free memory of this type) by using the following lines in 4START.BTM: IFF "%_SHELL"=="0" THEN LOADHIGH [d:path]4DOS24H2.COM ELSE [d:path]4DOS24H2.COM ENDIFF If you have 4DOS version 3.x or earlier it is not possible to load 4DOS24H2.COM high (well, I haven't found a safe way of doing it yet!). If you are using 4DOS version 4.0 or later and a DOS version prior to DOS 5.0 it should still be possible to load 4DOS24H2 high using a memory manager capable of doing this (QEMM, 386Max etc.). In that case you just need to replace the LOADHIGH command with the equivalent command supported by the memory manager. IMPORTANT ! Do NOT run this program from AUTOEXEC.BAT. If you load 4DOS24H2.COM from AUTOEXEC.BAT you will not benefit from the handler during shells (when you start a new copy of the 4DOS command interpreter). The 4DOS command interpreter loads its own critical error handler every time a new shell is started. Hence 4DOS24H2.COM need to be reinstalled when starting a new shell. Because 4DOS executes 4START.BTM every time a new command interpreter is started (including the first one) the reinstallation can be done automatically from 4START.BTM. Note: The handler does NOT actually load a new copy of itself in memory but merely reinstalls the one already present without using any additional memory. Usage ~~~~~ At best you will never see 4DOS24H2. If 4DOS24H2 pops up a message window you have a critical error. The following are examples of (well known) situations all leading to a critical error: - You forgot to insert a diskette or to close the diskette drive door before selecting the diskette drive. This is harmless and you can recover by pressing the 'A' key to abort the operation (if you are a 4DOS user!) or by inserting a diskette and/or close the drive door before pressing the 'R' key to retry the operation. - Your diskette is damaged in some way. This is often a *REAL* critical error and can be difficult to recover from. You will probably have to use a disk oriented tool to resque your data on the diskette if possible at all. - Your printer is offline or out of paper when you try to print something. This is normally harmless and typically you can recover by switching on the power or setting your printer online or by inserting paper. There are more rare situations which will also lead to critical errors but hopefully you will not see them too often. When a critical error occurs 4DOS24H2 will pop up a window showing the following information: +---------------- 4DOS Critical Error Handler -----------------+ | Version 2.00 | | | | A description of the error type (read or write error) | | and where it occured (e.g. the drive letter or port). | | | | If possible a somewhat more specific error description. | | | | Which possibilities you have to react and how to respond. | | | +--------------------------------------------------------------+ You may or may not have all of the four respond possibilities: Abort, Retry, Ignore, Fail -- this depends on the kind of error. Aborting will normally stop the program/command that caused the error and return you to the 4DOS command line. Choosing to retry will repeat the operation that caused the error and only if no errors occur this time the program/command will continue normally. Choosing ignore will let the program/command continue as if no error ever occurred, while the fail respond will try to inform the program/command that an error has occurred. You can respond by pressing the first letter of the action, e.g. an 'a' to (a)bort the current operation, an 'i' to (i)gnore the error, an 'r' to (r)etry the operation and an 'f' to (f)ail the operation. The actual case of the letter is unimportant and will be ignored. As a special feature of 4DOS24H2 you can also press Esc, 'q', 'x' or ^C (Ctrl-C) instead of 'a' to abort. These keys are often used to quit or exit other applications and for some users they seem more natural. Likewise you can press Spacebar or Enter to retry the operation as an alternative to 'r'. There are no alternative keys for the Ignore operation as I could not find any better than 'i'. Any other keys will be ignored by the handler. When the critical error situation is properly handled the original user screen is restored upon exit. Unloading ~~~~~~~~~ If you for some reason should need to unload 4DOS24H2 you will either have to reboot your computer or use the TSR utilities from TurboPower Software (Public Domain package available on many BBS-systems) to remove 4DOS24H2.COM from memory. To keep memory usage at a minimum this feature is not implemented. Note: If you want to remove the handler by rebooting your computer remember to edit your 4START.BTM file and remove the line(s) responsible for loading 4DOS24H2.COM or put a REM command in front of it/them. Otherwise the handler will be loaded before you are given control. Trouble Shooting ~~~~~~~~~~~~~~~~ 4DOS24H2 is very easy to install and use and should not cause trouble. In some rare situations, however, you might experience a problem covered in this section. More than one copy of 4DOS24H2 in memory ... If 4DOS24H2 seems to load a new copy of itself into memory every time you make a shell (and thereby wasting useful memory) you may have loaded a resident program (TSR) which interferes with 4DOS24H2. If you can identify the TSR causing the trouble you can sometimes recover by installing your TSR before 4DOS24H2 (e.g. in CONFIG.SYS using INSTALL under DOS 4.0 or later). If this is not possible or does not seem to solve the problem you may try to edit the source code and reassemble it. The trouble might be that for some purpose your TSR uses interrupt 61h. 4DOS24H2 itself uses interrupt vector 61h to see if it is already installed and can not identify itself in memory if this interrupt is hooked by some TSR after installation of 4DOS24H2. To solve the problem you can change the vector used by 4DOS24H2 by editing the EQU directive in line 96 of the source code: IDvector EQU 61h to reflect another vector number. Suitable numbers are vector numbers between 60h and 66h which are user defineable interrupt vectors. After editing you must reassemble according to the directives in the source code. 4DOS24H2 seems to dissapear after a critical error ... When you have had a critical error and have recovered the next time you may see the original critical error handler responding. This problem could be caused by two reasons. Either you have started a new shell and forgotten to reinstall 4DOS24H2 or you may be trying to load 4DOS24H2 high using 4DOS version 3.x. In the first case you may be loading 4DOS24H2 from AUTOEXEC.BAT or may otherwise exclude 4DOS24H2 from reloading when a new shell is started. Load 4DOS24H2 from 4START.BAT if you are not already doing this -- refer to the Installation section for the correct installation procedure. If you are using 4DOS version 3.x you may be trying to load 4DOS24H2 high using something like: COMMAND /C LH 4DOS24H2.COM You must either upgrade 4DOS or use conventional memory in order to keep the contact with 4DOS24H2. Refer to the Installation section for details about loading 4DOS24H2 into conventional memory. "Divide overflow" error when loaded high ... If you get a "Divide overflow" error during a shell you may be trying to reload 4DOS24H2 using the LOADHIGH command but without having enough free high memory. This is not a bug in 4DOS24H2 but the error is sometimes reported by 4DOS. Normally this situation does not lead to an error since 4DOS auto- matically uses conventional memory when no upper memory is available. However, the problem occurs while the excellent public domain ANSI driver NNANSI.COM version 9.92 by Tom Almy is loaded into high memory. At the moment I do not know of any other programs causing the same problems; neither do I know if this is a bug in the ANSI driver or in 4DOS version 4.01, rev. B which I used for testing 4DOS24H2 in high memory. The solution is to load 4DOS24H2 high only when it is first installed. Reloading (when shelling) should be done using conventional memory only. This can be accomplished by exploiting the special 4DOS environment variable "%_SHELL" and use the IFF construction shown in the Installation section. Refer to this section for more information. Epilogue ~~~~~~~~ It took quite a long time to create 4DOS24H2 but the time spent was really funny and certainly not wasted. I learned the 8088 assembler and some new tricks on how to optimize assembler code and somehow it became an obsession to see how much the code could be squeezed. I don't think it is possible to "squeeze" the memory consumption of the code much more than a few bytes but I would be happy to hear from every- body who succeeds in optimizing the code further without losing its features. You can reach me through Internet at the following adress: ehlig@ask.diku.dk Please use subject: 4DOS24H2 Enjoy and have fun Niels Jensen, Copenhagen August 1992 (last revised May 1993)