EXECWSWP - Exec a windowed command with optional minimal-memory mode
--------------------------------------------------------------------
TurboPower Software
11/90
Version 1.5
Released to the public domain

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

EXECWSWP combines the features of two existing utilities: EXECWIN and EXECSWAP.
Specifically, this is a replacement for EXECWIN. Like EXECWIN, it attempts to
limit a child process's video ouput to a specified region of the screen. This
unit, however, will optionally swap the majority of the parent process to EMS
or disk before calling the child process.

The "window" effect is produced by taking over interrupt 21h and controlling
all writes to standard output and error devices. All such writes are rerouted
to the screen, within the specified window. Note that this technique will not
work for programs that write directly to video memory, through the BIOS, or
through some other file handle assigned to the console. It does work with
standard DOS commands, with the TPC.EXE compiler, and with other command line
utilities like ARCX.COM.

The swapping technology used here was extracted directly from the existing
EXECSWAP unit and is nearly identical to the ExecWithSwap function in Object
Professional's OpExec. Refer to that documentation for more information on the
swapping process.

Using EXECWSWP
------------------------------------------------------------------------------
EXECWSWP interfaces the following constants and routines:

const
UseEmsIfAvailable : Boolean = True;

This constant determines where swapping will occur. The default is to
attempt to swap to EMS. Set this to False to force swapping to disk.

const
EmsAllocated : Boolean = False;
FileAllocated : Boolean = False;

These constants are set to true after the swap space has been allocated (one
or the other will be True).

function ExecWinWithSwap(Path, CmdLine : String;
Xlo, Ylo, Xhi, Yhi : Byte;
Attr : Byte) : Word;
{-Windowed DOS EXEC supporting swap to EMS or disk}

This function spawns a child process, forces the output to the specified
window, and swaps most of the parent program to EMS (or disk) during the
spawn.

Path is the _complete_ pathname of the program to run. CmdLine should
contain the command line parameters to be passed to that program. Xlo, Ylo,
Xh and Yhi define the upper-left and lower-right corners of the window. Attr
specifies the video attribute for all "windowed" writes.

ExecWinWithSwap will return one of the following status codes:

0 Success
1 Swap error (no swap storage, disk error, EMS error)
2 File not found
3 Path not found
8 Insufficient memory

function InitExecSwap(LastToSave : Pointer; SwapFileName : String) : Boolean;
{-Initialize for swapping, returning TRUE if successful}

This function prepares for swapping by allocating the swap space (in EMS or
disk).

LastToSave contains the address of the last byte of the region to be swapped
to disk (the start to the swapped region is within the EXECWSWP unit
itself). There are three reasonable values for LastToSave. Passing the
System variable HeapOrg tells ExecSwap not to save any part of the heap;
this is the correct option for programs that make no use of the heap.
Passing HeapPtr causes ExecSwap to save all allocated portions of the heap.
Only the free list is ignored, so this is a good choice for programs that
don't fragment the heap. Passing the expression Ptr(Seg(FreePtr^)+$1000, 0)
tells ExecSwap to save the entire heap, including the free list. This is the
most conservative option, but it may lead to swap files approaching 640K
bytes in size.

SwapFileName specifies the name and location of the swap file. If EMS memory
is available this name won't be used, otherwise InitExecSwap will create a
new file. InitExecSwap assures that sufficient EMS or disk space exists for
the swap, otherwise it returns False. It's a good idea, of course, to put
the swap file on the fastest drive that will hold it, to minimize swap
times. It's also prudent to avoid a floppy drive, since the user may change
disks while the child process is active. The swap file remains open, using a
file handle, until ShutdownExecSwap is called or the program ends.
InitExecSwap marks the file with the Hidden and System attributes so that
the user of the child process won't be tempted to delete it.

procedure ShutdownExecSwap;
{-Deallocate swap area}

Deallocates the swap area (either frees EMS memory or closes and deletes the
swap file).

function ExecWindow(Command : string; UseSecond : Boolean;
Xlo, Ylo, Xhi, Yhi : Byte;
Attr : Byte) : Integer;
{-Exec a program in a window}

This function performs a simple EXEC and attempts to keep the child
process's output to the specified portion of the screen. No swapping is
done.

Command is the complete program name the desired command line
parameters for that program. UseSecond determines whether a second copy of
COMMAND.COM will be loaded. Xlo, Ylo, Xhi and Yhi specify the upper-right
and lower-left corners of the window. Attr specifies the video attribute of
the windowed output.

Since this eventual results in a call to Object Professional's ExecDos
routine, refer to that documentation for more information about controlling
the EXEC process.

This function can return the following status codes (from ExecDos):

0 : Success
1 : Insufficient memory to store free list
2 : DOS setblock error before EXEC call
3 : DOS setblock error after EXEC call -- critical error!
4 : Insufficient memory to run DOS command
else a DOS error code