JDOS Documentation Richard B. Johnson PROGRAM EXCHANGE March 15, 1989 Forward. JDOS is a terminate and stay resident program (TSR) that uses VERY LITTLE MEMORY! The resident portion is only about 3 kb. When installed, JDOS allows the user to activate a copy of the DOS command-processor by typing ^\ (control-backslash) while within a program. The command-processor will be acti- vated for the user if the following conditions are met: (1) The program in use has not acquired ALL of the system memory. (2) The program in use has followed DOS's rules for memory management. (3) There is sufficient disk-space on the default drive to write two files totaling about 700 kb in size. These files are deleted as soon as JDOS returns to the inter- rupted program. Usage: JDOS Note: You should see a signon-message on your screen. If you do not see this message, your base-board switches or CMOS are not set properly to define the screen-card that you are us- ing. In this case, the screen contents will not be restored after you exit the JDOS window. You might be able to fix this with the proper DOS "MODE" command in your AUTOEXEC.BAT file. If you hit ^\ while at the DOS prompt, the console bell will sound but nothing else will happen until you execute a tran- sient program. That program will then be interrupted as soon as JDOS finds a safe time to interrupt. If you accidentally interrupt a program, you just wait until the JDOS window ap- pears then type EXIT to return to your interrupted program. Depending upon how fast your hard-disk drive operates, it may take several seconds to activate the JDOS window and several seconds to get back to your interrupted task. This may seem like a long time, but once you get to the JDOS window, you will have MOST of the system memory available for another application program! Other TSR programs of this type permanently acquire large amounts of system memory when installed. They then allow only very small programs to be activated within the "window". JDOS saves most of the system memory contents to disk so it can be used for applications programs. - 1 - How it works. When invoked at the DOS command-line, JDOS installs itself and leaves about 3 kb resident in memory. JDOS continually monitors the keyboard, waiting for the control-function, ^\ to be typed by the user. If the control-function is typed, JDOS sets a flag that tells it to become active as soon as possible. The system clock provides an interrupt about 18 times every second. When this interrupt is activated, JDOS checks to see if the flag has been set, requesting that it become active. If the flag has been set, JDOS checks to see if the interrupted program lies above JDOS in memory and below the DOS BIOS services. If this is true, JDOS does the following: (1) Saves the current screen mode. (2) Saves all the characters on the screen in a hidden file called SCREEN.$$$. (3) Saves the cursor type and position. (4) Saves the contents of the interrupt table. (5) Saves the state of four possible UARTs for communi- cations adapters, COM1 through COM4, then disables interrupt control on all of them. (6) Masks off interrupts IRQ3 and IRQ4 that communica- tions programs use. (7) Sets the timer-tick interrupt that the interrupted program might be using to a dummy routine. (8) Sets the system-timer interrupt, that the inter- rupted program might be (dishonorably) using back to the correct vector. (9) Saves the user's data-transfer area. (10) Saves the default directory and disk. (11) Saves the contents of memory in a hidden file called VIRTUAL.MEM. (12) Releases memory to load and execute the DOS command processor. (13) Loads the command processor. (14) At this time, the user may execute DOS commands - 2 - and may also execute other programs. Since most of the memory contents will have been saved in a file, the user will have most of the system memory available for application programs. After the user types EXIT at the DOS command line, the following things occur: (15) The command-processor returns to JDOS. (16) The default disk and directory are restored. (17) The memory released is reacquired. (18) The saved memory contents from the file are written back to memory. (19) The memory-file is deleted (VIRTUAL.MEM). (20) The screen mode, cursor type, and position is restored. (21) The screen contents are restored from a file. (22) The screen file is deleted (SCREEN.$$$). (23) The data-transfer area is restored. (24) The contents of the interrupt table is restored. (25) The interrupt-controller mask is restored to enable the interrupted program's interrupts. (26) The state of the four possible UARTS for the communications adapter ports COM1 through COM4 are restored including any interrupt-enable bits. (27) JDOS returns to the interrupted program. If everything went according to plan, the user continues with his work. JDOS may again be activated at any time. Possible problems: There are several things that could go wrong that would prevent JDOS from performing correctly. Much care has been taken to help prevent a system crash in the event that everything didn't go according to plan. Usually, in the event of an error, JDOS simply refuses to load the command processor and returns to the interrupted task. There are a few things you MUST NOT DO when operating in the JDOS "window". - 3 - (1) Do NOT load a TSR program! JDOS needs the memory that the TSR would use and has absolutely no way of returning to the interrupted program if this memory gets taken away by the TSR program. (2) Do NOT run CHKDSK with the /F option! There may be many open files who's buffers haven't been written to disk when JDOS interrupts the task. CHKDSK will assume these files are bad and truncate them to zero-length! (3) Do NOT activate another TSR like Sidekick(tm) or Superkey(tm) while inside the JDOS window! Usually you can get away with this, but not always. You can improve your chances by loading JDOS last. (4) Do NOT run a program that alters your disk struc- ture (like Peter Norton's SD)! This could cause the same problems as DOS's CHKDSK. (5) If operating from a floppy disk, do not remove the default disk from the drive! If JDOS can't open the virtual-memory file, it will abort so you can't get back to the interrupted program. (6) JDOS creates then deletes two files, VIRTUAL.MEM and SCREEN.$$$. These files will reside in the top directory of the default disk. They are normally hid- den. Should you delete them while in the JDOS window, you'll be up the creek without a paddle once you exit the JDOS window. If you follow these rules, JDOS should be a useful addition to your utilities. ERROR MESSAGES  Need DOS version 3.00 or higher to execute! Some versions of DOS 2.XX do not always work. You really need DOS 3.XX for all modern applications.  JDOS is already installed! You tried to load JDOS again. It won't let you.  Can't load command processor The program that was interrupted had acquired ALL of the system memory and won't release any! Just hit the and JDOS will return to the interrupted task. If this message occurs immediately upon loading JDOS, it - 4 - means that the command interpreter, COMMAND.COM can't be located because of a corrupt environment. Type SET at the DOS prompt and verify that the "COMSPEC=" parameter points to a valid filename. This should be the COMMAND.COM file that DOS loaded at boot-time.  Can't create file \VIRTUAL.MEM Not enough directory space in your top directory or not enough file "handles" available. Put FILES=30 in your CONFIG.SYS file then reboot.  Can't write file \VIRTUAL.MEM You are out of disk space. JDOS needs about 700 kb. This single file can be as large as 620 kb.  Can't close file \VIRTUAL.MEM A disk allocation error prevents updating the directory.  Can't open file \VIRTUAL.MEM File was not created because of a previous error.  Can't delete file \VIRTUAL.MEM File was not created because of a previous error.  Can't read file \VIRTUAL.MEM File was not closed properly because of a previous error.  Can't create file \SCREEN.$$$ Not enough directory space in your top directory or not enough file "handles" available. Put FILES=30 in your CONFIG.SYS file then reboot.  Can't write file \SCREEN.$$$ You are out of disk space. JDOS needs about 700 kb. This file is 64 kb in size.  Can't close file \SCREEN.$$$ Disk allocation error prevents updating the directory.  Can't open file \SCREEN.$$$ File was not created because of a previous error.  Can't delete file \SCREEN.$$$ File was not created because of a previous error.  Can't read file \SCREEN.$$$ File was not closed properly because of a previous error. If you want to laugh, please read the following message stolen from a software instruction manual. WARRANTY - 5 - This material, hereunder referred to as software, whether or not in machine-readable form, or existing in the manner re- ferred to as source-code, whether or not in a compiler- usable form, or existing as a memory image either as object- code or binary controls to microprocessor modalities and instructions, has neither express nor implied warranties of any kind including, but not limited to, merchantability, fitness for any particular purpose, or non-infringement of patents, copyrights or other proprietary rights of others, or any liability or responsibility for damages of any kind, including special, indirect or consequential damages, arising out of or resulting from the use of same made available hereunder, or the use or modification thereof, the sole remedy of which is limited, at our option, to the replacement of this notice should it become defective in normal use for a period not to exceed an unspecified time. Some countries, states and principalities do not allow limited warranties so this notice may not apply to you. In other words, "you usa da program, you taka you chances"! The source-code is provided so that users may determine for themselves if this program may serve a useful purpose. I attempted to follow good standards of engineering practice so you should not have too many problems. Cheers, Richard B. Johnson - 6 -