POPDOS -- A Swapping TSR DOS Shell

Copyright (c) 1990 TurboPower Software
May 1990

------- Overview -----------------------------------------------------------

POPDOS is a TSR that can activate a DOS shell while almost any application is
running, hence providing the ability to run DOS commands and even other
applications within programs that didn't originally allow it. POPDOS keeps
only about 6K of normal DOS memory when it goes resident, but can provide up
to about 600K of free DOS space when it pops to DOS. Besides being a useful
utility in its own right, POPDOS demonstrates how to incorporate the same
capability in other TSRs written using Object Professional, TurboPower's
class library for Turbo Pascal 5.5.

POPDOS uses two forms of swapping technology to maximize the amount of memory
available to the DOS shell. First, POPDOS is a swappable TSR: when its hot key
is pressed, POPDOS swaps out the applications loaded after it and swaps itself
in. Most of the memory area that it reclaims in this way isn't used directly
by POPDOS. Besides the code, data, and stack space that POPDOS actually uses,
it retains a variable amount of heap space that provides the free RAM for the
DOS shell itself. Second, POPDOS uses a swapping DOS shell: after the
swappable TSR takes control, it swaps the TSR's code and data back out,
shrinks its memory allocation to the minimum, and calls the DOS EXEC function
to activate a DOS command line. The amount of memory free at this command line
can range from 30K to over 600K depending on when and how POPDOS was loaded.
After you type "Exit" at the command line, the sequence is reversed and the
original application regains control.

For reasons that aren't clear at this time, POPDOS does not work with PC-DOS
2.0 or 2.1. Either piece of swapping technology -- swappable TSR's or swapping
exec -- works fine by itself, but the two don't combine. Interestingly, AT&T
DOS version 2.11 works with POPDOS, which suggests the presence of a bug in
the earlier DOS versions. POPDOS.EXE as supplied will not load for any DOS
version prior to 3.00.

POPDOS requires Object Professional version 1.02 or later to compile. Download
POPDSE.LZH from LIB 6 of the PCVENB forum on CompuServe if you'd like just the
precompiled EXE file.


------- Installing POPDOS --------------------------------------------------

POPDOS will use either EMS (expanded memory), XMS (extended memory), or disk
space for its swapping medium. When using EMS, it consumes about X+45
kilobytes of EMS space (rounded up to the nearest 16K boundary), where X is
the amount of RAM to be free when the DOS shell starts. When using XMS or
disk, it uses about n*(X+15)+30 kilobytes of space, where n is either 1 or 2
depending on whether single or double file swapping is used. The single file
swapping option is described in more detail below.

You can install POPDOS simply by typing its name at the DOS command line. It
provides the following default behavior:

- all RAM that is free at the time POPDOS is loaded, less about 20K, will
be available to the DOS shell
- EMS, if available, will be used for swap space
- dual swap files located in the root directory of drive C: will be used
if EMS is not available
- swap files will be marked hidden
- hot key will be
- the mouse state will be saved and restored if the mouse driver allows

All of these defaults may be modified by using the command line options
described below.

Unload POPDOS from memory by typing POPDOS /U from the DOS command line. The
unload will succeed only if no TSRs that grab interrupt vectors have been
loaded after POPDOS. POPDOS will also refuse to unload if you try to do so
from within its own DOS shell.

The following table summarizes the POPDOS command line options:

/1 single swap file
/A visible attribute for swap files
/D force disk swapping even if EMS available
/F kbytes specify approx. kbytes free within DOS shell
/H hexkey specify TSR hot key in hex
/K kill mouse management code
/M disable swap message
/S path specify drive and directory for swap files
/U unload TSR
/X use XMS memory for swap
/? show the command line options

When disk space is used for swapping, POPDOS normally uses three swap files.
Two of the files are used to activate the swappable TSR. The first such file
holds the POPDOS code and data and the other one holds the memory contents
that POPDOS overwrites. The third file is used for the DOS shell itself and
consumes about 30K bytes, which is typically much smaller than the first two.
When the /1 option is specified, POPDOS uses a small intermediate buffer which
removes the need for one of the first two files and thus cuts its disk space
requirement by up to a factor of two (see the formula above). However, the
intermediate buffer slows swapping since the swap file is read in smaller (2K
byte vs. 64K byte) blocks and since an extra memory-to-memory move is
required. Nevertheless, the single swap file option is advantageous if it
allows the swap files to fit entirely on a RAM disk. Note that the
intermediate buffer increases the size of the POPDOS resident core by 2K bytes
as well.

The /1 option has an analogous effect on the XMS swapping option. When /X /1
is specified, POPDOS uses half as much XMS memory, swaps somewhat slower, and
consumes 2K bytes more normal RAM.

When the /A option is specified, POPDOS leaves its swap files visible and
unprotected. Don't delete or overwrite the swap files (which are named
!POPDOS1.SWP, !POPDOS2.SWP, and !POPDOS3.SWP) while POPDOS is loaded. Note
that POPDOS deletes its own swap files when it is unloaded. Although POPDOS
cannot delete the swap files if you turn the machine off while POPDOS is
still loaded, it will correctly overwrite them the next time it's loaded
again.

The /D option forces POPDOS to use disk space for swapping even if sufficient
EMS or XMS space is available. You'd specify this option if you have other
applications that will need the EMS or XMS space, or if you have an extended
memory RAM disk that you prefer to use for swapping. Note that POPDOS
allocates space for the TSR-swapping requirement when it goes resident. At the
time it pops up, it allocates another 30K bytes of EMS, XMS, or disk space for
the shell itself.

/F lets you specify how many kilobytes of RAM space you'd like to remain free
within your DOS shell. The larger this number, the larger your swap space
requirements will be. The smallest allowed parameter is 30, since DOS itself
won't do much with less than 30KB free. If you don't specify a /F option, the
free space within the shell will be the amount of memory that was free when
POPDOS was loaded, less about 20K.

/H allows you to specify a hot key other than the default . The
parameter following /H must be in hexadecimal, where the high byte specifies
the shift key combination and the low byte specifies the scan code of the
trigger key. The shift key codes are:

None - 00
RightShift - 01
LeftShift - 02
Ctrl - 04
Alt - 08

Valid scan codes (in hexadecimal) are:

A - 1E N - 31 0 - 0B F1 - 3B [ - 1A
B - 30 O - 18 1 - 02 F2 - 3C ; - 27
C - 2E P - 19 2 - 03 F3 - 3D , - 33
D - 20 Q - 10 3 - 04 F4 - 3E / - 35
E - 12 R - 13 4 - 05 F5 - 3F \ - 2B
F - 21 S - 1F 5 - 06 F6 - 40 ] - 1B
G - 22 T - 14 6 - 07 F7 - 41 ' - 28
H - 23 U - 16 7 - 08 F8 - 42 . - 34
I - 17 V - 2F 8 - 09 F9 - 43 ` - 29
J - 24 W - 11 9 - 0A F10- 44
K - 25 X - 2D F11- 57
L - 26 Y - 15 F12- 58
M - 32 Z - 2C

For example, 0244 means , 0820 means , 0517 means
.


When /K is specified, POPDOS doesn't execute its mouse management code. This
option does nothing unless a mouse is installed. By default, POPDOS saves and
reinitializes the mouse state before it starts the DOS shell and restores the
mouse before returning control to the underlying application. For some mouse
drivers, notably recent versions of Microsoft MOUSE.COM and MOUSE.SYS, the
call to reinitialize the mouse takes an annoyingly long time (a second or so).
/K removes this delay, but if you run a program that enables the mouse within
your DOS shell, you may see a phantom mouse cursor when you return to the
interrupted application.

/M disables the swapping message, which POPDOS normally displays whenever it
is swapping to disk or to EMS or XMS when it judges that the swap delay would
be noticeable. /M is particularly useful when you're swapping to a RAM disk.

/S specifies an alternate drive and directory for the swap files. The default
location is C:\. All three swap files go to the same place. Note that the
parameter to /S should specify a complete path name, including a drive and
directory but no filename.

/X enables the use of XMS memory for swapping. Note that in order to use the
XMS option, you must have an XMS-compatible driver installed. Microsoft
distributes the HIMEM.SYS driver for free (it's available on CompuServe) and
also with some of their products like Windows. Other XMS-compatible drivers
include QEXT.SYS and QEMM.SYS from Quarterdeck and 386MAX.SYS from Qualitas.
The amount of XMS memory required is affected by the /1 option, described
above.

Here are some examples of POPDOS command line options:

POPDOS /F 200
Installs POPDOS to support a DOS shell with about 200K bytes free. The
actual amount will vary slightly depending on the version of DOS. POPDOS
will need about 256K bytes of EMS space, or 450KB of disk space with dual
file swap, or 245KB of disk space with single file swap.

POPDOS /D /1 /A /M /S G:\
Forces POPDOS to swap to disk, using single file swapping, leaving the swap
file visible, turning off the swap message, and locating the swap file in
the root directory of drive G (which is presumably a RAM disk).

POPDOS /X /1 /F 200
Installs POPDOS to use XMS memory in "single file swap" mode. POPDOS will
use about 245KB of XMS space and will retain about 9K of normal DOS RAM.
About 200KB of RAM space will be free when the DOS shell is activated.

POPDOS /H 0858
POPDOS will activate when is pressed.

POPDOS /U
Unloads POPDOS.

POPDOS /?
Displays the POPDOS command line options.


------- Using POPDOS -------------------------------------------------------

Once POPDOS has been installed, just press its hot key. After a short swapping
delay, the screen will clear and the DOS prompt will appear. Execute one or
more DOS commands, then type EXIT to return to the interrupted application.

If POPDOS cannot shell to DOS when you request it, it will beep and return to
the current application.


------- Restrictions -------------------------------------------------------

POPDOS may not be loaded "high" using such utilities as QEMM, QRAM, or
386MAX. POPDOS requires a large amount of contiguous RAM space that must
immediately follow its kernel in memory.

Like any swappable TSR, POPDOS should not be loaded before programs or TSRs
that contain hardware interrupt handlers. Examples include network shells,
asynchronous communications programs, and multitasking operating systems.

You may not pop to a DOS shell when you're already at the DOS command line.
(This is not a critical restriction, of course, but it's the first thing that
most people try.) POPDOS protects itself against such a request and just
beeps and returns to the command line. The limitation arises because of the
way DOS manages its internal stacks. For related reasons, you may not shell to
DOS while you're at the DEBUG or EDLIN command line. Similarly, you may not
shell to DOS when you're within another TSR that was popped up at the DOS
command line. The techniques POPDOS uses to detect that it was popped up at
the command line may be fooled by multitasking operating systems such as
DesqView; use POPDOS carefully in these situations.

You may not pop to DOS from within a program operating in graphics mode. This
is not a limitation of the swappable TSR itself; POPDOS simply doesn't know
how to save and restore the state of a graphics screen.

Do not install another TSR while within a POPDOS shell. The most likely result
will be a system hang when you return from the shell.

As mentioned above, POPDOS can't be used with DOS 2.x.


------- Providing a DOS Shell in your TSRs -----------------------------------

This section assumes that you have the POPDOS source code. The hardest things
that POPDOS does are handled by the OPSWAP and OPEXEC units from Object
Professional. POPDOS itself has been kept simple so that you can see how it
works, extend it, or incorporate the same capabilities in your own programs.

The following rules summarize what your program must and must not do. Refer to
POPDOS.PAS (the main program source file) and PDMAIN.PAS (the main unit) for
additional details. In most ways, POPDOS is organized just like any other
swappable TSR, so you should be sure to understand that first.

1. ONLY the main program itself should use the OPEXEC and OPSWAP units. OPSWAP
should be the last unit in the USES statement, and OPEXEC should immediately
precede it.

2. As with other swappable TSRs, the main program consists primarily of just a
call to the installation procedure of the main unit. In this case, the program
must also initialize a few variables in the main unit so that the main unit
can access the routines in OPEXEC. The most essential one is a function
variable, ExecDosSwap, whose declaration mirrors that of the actual
ExecDosSwap function in OPEXEC. In this way, the main unit can call
ExecDosSwap even though it doesn't explicitly use OPEXEC.

POPDOS.PAS also stores the address of OPEXEC's UseEmsIfAvailable and
UseXmsIfAvailable flags so that PDMAIN can toggle the flags' values depending
on command line options. POPDOS always turns off the OPEXEC swapping message
since the size of the swap region is never more than about 30K bytes.

3. POPDOS stores two independent flags in the UserData field of the TSR's
external interface record. One of the flags is the typical one: a
success/failure flag that indicates whether the TSR was successfully unloaded
from the DOS command line. The other flag indicates whether the POPDOS shell
is currently active, in which case it's unsafe to unload the TSR. See
procedure TryToUnload for details.

4. Procedure ParseCommandLine shows how to handle all of the common
installation options for a swappable TSR: single swap file, visible swap
files, forced swap to disk, XMS support, etc. It also shows the calculations
required to obtain a specified amount of memory free within the DOS shell
(although these calculations may not be appropriate when the DOS shell is part
of a larger TSR program).

5. Before actually shelling to DOS, the popup routine must check the
DosBusyFlag and WasCommandActive functions of OPSWAP1:

if (DosBusyFlag <> 0) or WasCommandActive then
{DO NOT shell to DOS} ;

The TSR itself will pop up and can perform almost any action under these same
conditions. However, it CANNOT safely shell to DOS if either condition is met.
As previously noted, refusing to shell under these conditions doesn't really
give away much functionality.

6. The popup routine must deal with the video system and the possibility that
the user may switch video modes while in the DOS shell. POPDOS refuses to
shell out if the system is not in a text mode when the request occurs. If the
system is in a text mode, POPDOS saves the contents of the screen, the video
mode, the cursor shape and position, and the mouse state before it clears the
screen and calls ExecDosSwap. On return from the shell, it switches back to
the original video mode if necessary, restores the screen contents, the
cursor, and the mouse state. Note that POPDOS calls WhereXYDirect to get the
initial cursor position; this is necessary to get accurate values when POPDOS
is activated over SideKick, Lotus 1-2-3, or another program that doesn't
position the cursor using BIOS calls.

7. It's deadly for the user to install another TSR while within the POPDOS
shell. POPDOS has no effective way to protect itself against this possibility,
so you must warn your users against it. The typical result of doing so will be
an immediate system crash upon returning from the shell.

8. In order to provide XMS support, you must assure that Object Professional
is correctly configured. Assure that OPDEFINE.INC, OPEXEC.ASM, and OPSWAP.ASM
all enable the SupportXms define and that you've reassembled OPEXEC and OPSWAP
with these defines in place.


------- POPDOS License Information -------------------------------------------

POPDOS.EXE and its source code, unmodified, may be used freely by individuals
in a home or business environment. You may use POPDOS yourself, give it to
your friends or co-workers, or distribute it for a cost-based fee ($10 or
less) as part of a user's group or bulletin board service. If you wish to
distribute POPDOS as part of a commercial software package, please contact
TurboPower Software for a license agreement.

You may incorporate the ideas embodied by POPDOS into programs of your own
design with no additional licenses, subject to the terms of the Object
Professional license agreement.

TurboPower Software assumes no liability for the use or abuse of POPDOS.EXE or
the program code it contains.

To report problems or suggestions regarding POPDOS, or for more information
about TurboPower's line of programmer's tools, contact Kim Kokkonen at
TurboPower Software:

TurboPower Software
P.O. Box 66747
Scotts Valley, CA 95067-0747

408-438-8608 (voice only, Monday-Friday 9AM-5PM)
CompuServe: 76004,2611


------- POPDOS Version History -----------------------------------------------

Version 1.02 6/04/90
Initial release (synchronized with Object Professional 1.02)

Version 1.03 7/24/90
Add support for swapping to XMS