Spawn Version 1.3
Public Domain by Albert H. Ariail
Copyright 1990

The following program is a Desqview specific utility to allow you to
execute a more or less arbitrary DOS command in the background. This
program nicely implements what someone has called "the compile in the
background circus trick". The background process inherits the default
directory and the environment that was in effect when spawn was invoked.
Spawn will execute any DOS internal or external command that does not
require operator intervention and is otherwise compatible with Desqview.
Another useful application is to use spawn to force full screen programs
to load into their own windows. This makes working in a small DOS
window much easier.

Hardware/Software requirements:
IBM PC/XT/AT or 100% compatible running DOS 3.x and Desqview 2.x . A 386
processor is not specifically required, but you will certainly get a lot
more out of this program if you have one.

****************************************************************************
* The above paragraph notwithstanding, at this writing, this program has *
* only been tested against DOS 3.3 and Desqview 2.22 . It is hoped that *
* this program will not prove overly version dependent, but if you are *
* having trouble with different versions of DOS and/or Desqview, drop me *
* a line. I will fix it if I can. At the very least, I would like to *
* update the documentation and supply a graceful exit. *
* I can usually be found on the Interlink Desqview conference at a BBS *
* near you, or at Future Technology BBS (617-720-3600). Less frequently, *
* I can be reached on Compuserve through an EazyPlex message to *
* [73510,2562] . *
****************************************************************************

If you are new to Desqview, the following definitions may help make this
documentation more intelligible.
I will use the term "parent process" to refer to the Desqview window from
which you invoke spawn. It is the function of spawn to open a new
Desqview window to execute the supplied command. This will be called the
"child process". A process is in the foreground when it can receive input
from the keyboard, otherwise it is in the background. Foreground windows
are always visible, background windows may or may not be, depending on
whether or not they are behind other windows. The PIF file for a window
is the Desqview Program Information File that is used to tell Desqview
more about the program that is to be executed. When you are manipulating
the "Change Program" menu, you are editing the PIF file for that entry.
Under Desqview, a process that is invoked with the keys "XX" will have
a PIF file of c:\dv\xx-pif.dvp .

Installation Instructions:
This program assumes that the Desqview executables and all of your PIF
files reside in the directory C:\DV . If this is not the case, before
starting Desqview, you should set the environment variable DESQ to point
to the correct pathname, e.g.

c> set desq=e:\desqview

In what follows if I use the directory c:\dv, I will be referring to
either this directory or whatever is in the variable DESQ .

After unpacking the archive file, copy file files sp-pif.dvp and
dvcmd.com to the current Desqview directory. dvcmd.com file must be
present in c:\dv and not renamed. sp-pif.dvp is the Program Information
File that spawn uses to launch the background process. This may be
renamed if you specify the correct (complete) pathname in the environment
variable SP-PIF . SP does not have to be present in your Desqview "Open
Process" menu unless you wish to change the default settings. The program
spawn.com can reside anywhere accessible from you current PATH variable,
however, since it doesn't function outside of Desqview, c:\dv would be
more appropriate.

Basic operation:

To invoke a command in a background window, simply enter:

c>spawn program [arguments]

where program is any valid DOS internal or external command with whatever
arguments it expects, e.g.,

c>spawn copy c:\dv\*.* a:

If you are executing an external command (a .COM or .EXE file) you can save
about 5K of memory in the child process if you specify a complete pathname
for "program" :

c>spawn c:\bin\pkzip.exe -par e:\archive c:\*.*

instead of

c>spawn pkzip -par e:\archive c:\*.*

You can also spawn off pipes and filter programs by enclosing the command
in quotes:

spawn "dir *.* | sort >sort.dat"

Note that spawn "dir *.* >dir.dat"
is completely different from spawn dir *.* >dir.dat
The latter will put the output of spawn in the file dir.dat (usually there
is no output from spawn itself, so dir.dat will be empty).

Environment variables used by spawn:

CMDSWT - Defines text which will be placed on the command line whenever
spawn invokes command.com. This is usually assigned to a string
such as CMDSWT=\e:1500, which for DOS 3.2 or 3.3 will give
some additional free space in the child's environment.

SP-MEM - Defines the amount of memory to be given to the child process
e.g., SP-MEM=256 will grant 256k bytes of free memory. If
specified, this will override the memory allocation defined in
sp-pif.dvp which initially is set to "all you can get".

SP-PIF - Defines the Desqview Program Information file used by spawn.
The default is c:\dv\sp-pif.dvp . You must specify a complete
DOS pathname if this is used (for example: c:\desq\spawn.pif or
c:\dv\xx-pif.dvp).

DESQ - Defines the pathname to the desqview directory. If not
specified, c:\dv is assumed. dvcmd.com must reside in this
directory. If the PIF file name has not been changed as
described above, sp-pif.dvp must also be in this directory.

COMSPEC - This defines the program name which is used to invoke
"command.com" As you probably know, this is generally set by
DOS at boot up and is rarely changed by the operator.

Run time options:
Note: all of the options below must be placed immediately after the command
name "spawn" or they will be assumed to be options for the command being
executed, e.g., spawn/f copy ...

/a - alarm at completion
This options causes the child process to pause at completion. If
running in the background, the child process will be placed in
to the foreground. This allows you to review any exit
conditions from the spawned command. To acknowledge the message,
key ESC or click the mouse.

/s - silent alarm
same as /a but less noisy.

/f - move child to foreground
Normally the child process is executed in the background. This
will force the parent into the background and let the child
continue running in the foreground.

/w - suspend parent until child completes
This will stop the parent until the spawned command completes.
You may manually restart a waiting process by keying ESC .
Normally you will want to use this switch in conjunction with /f.
This option also gives allows you to retrieve a DOS program
return code from the spawned process (see below).

/d - disable background operation in parent
When used with /f, this switch will also suspend the parent
until the child completes. This suspend is softer than /w , the
parent process will restart automatically the first time you
switch to it.

/x - move parent to foreground at exit
This will guarantee that the parent returns to the foreground
after the child exits. This is normally used in the combination
/w/f/x or /d/f/x to insure control returns directly to the
parent and not to some other process.


/p:xx - use alternate pif
This defines the PIF file to be used in lieu of the default file
sp-pif.dvp . This option will also override the environment
setting SP-PIF. This should be used if the program being
spawned requires special Desqview options in order to function.
This switch /p:ab is short for /p:c:\dv\ab-pif.dvp . You may
specify a complete pathname if you wish. The specified file must
be a valid Desqview Program Information File, but does not have
to be present on the Desqview "Open Window" menu.

/m:n - limit memory to n K
This provides another way to control the amount of memory the
spawned process acquires. /m:256 will give the process 256k of
memory. This switch overrides the setting in the specified pif
file as well as the environment variable SP-MEM . (see below)

Notes and Ideas:

1. Watching the spawned process execute.
You can of course use spawn/f, but this sort of defeats the purpose
of using spawn. A more elegant way is to open as small DOS window
such as D1, move it out of the way and enter something like:
spawn/p:d1/f/x copy *.* a:
The function of the switch combination "/f/x" is to keep the parent
process in the foreground and not allow the child's window to be
hidden behind other windows.

3. quoted commands.
spawn implements the "command | command" syntax by starting
command.com and then feeding the command text into its keyboard
followed by and "exit". This works for pipes and filters, but if
any of the programs try to read from the keyboard, they will eat
the "exit" that was intended for command.com .

4. Using script files with spawn.
I recommend that you do not attach a script to sp-pif. If you want
use a script with a spawned process, use /P:XX to specify a PIF
file that has a script file attached to it. The script file used
is not determined by the file name, but rather the field "Keys to
use on open menu" . If this is say, AB, and a script file
c:\dv\ab-scrip.dvs exists, Desqview will play it back in the child
process when spawn starts it.

5. Getting more environment space in the child process.
If you spawn off batch files that manipulate the environment with
the DOS "SET" command, you may get "out of environment space" errors
from command.com . For DOS 3.2 and 3.3, you can fix this by setting
the environment variable CMDSWT=\e:nnnn where nnnn is the number of
bytes you which to allocate to the new environment. This text will
be placed on the command line whenever spawn invokes command.com .
For earlier versions of DOS, you will need to set up some long dummy
environment variables in the parent window (or better, before you
start desqview) such as
set a=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
set b=bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
At the beginning of the batch file that you wish to spawn, clear
these variables with
set a=
set b=
This will generally free up enough space for the batch file to
continue normally.

6. Specifying the memory to be given to the child process.
Initially, the spawn PIF file is configured to allocate as much
process memory as is available for the child process. While this
is the most general, it is usually far too generous. For most of the
programs that you would use will spawn, 256K is more than enough.
You can always modify sp-pif.dvp to scale back it maximum memory
allocation, I recommend that you instead set the environment
variable SP-MEM=256 . This will have the same effect, but can be
changed more readily. The SP-MEM setting is overridden by /m:nnn on
the command line and is ignored when you specify an alternate pif
file with /p:xx . Spawn will modify the "maximum program memory
size" field of the pif file. If the "memory size" is greater than
the "maximum memory" both are set to the specified value. In all
cases, an 10k is added to both fields to help accommodate spawn
overhead.

7. Modifying SP-PIF.DVP
Spawn itself is not very sensitive to the set up of the PIF file (as
long as there is sufficient memory to start the child process). Spawn
will modify the various fields if it needs to. In particular, the
following are always replaced by spawn:
Program name
Program parameters
Directory
Anything placed in these fields will never be used. As I have
mentioned, the process SP does not have to be in the Desqview "Open
Window" in order for spawn to function. So after making whatever
modifications desired, you may delete the menu item "SP". You must
then rename the file sp-pif.bak to sp-pif.dvp in order for spawn to
be able to find it.

8. Getting the DOS return code from a child.
When spawn is used with /w, the normal program return code of the
child process is returned by spawn to the parent. This can be used
with an "if errorlevel" test inside of a batch file. The return code
will correct when following conditions are met:
a. spawn was executed with the /w option
b. a complete pathname was given for the executable command
c. the command was not enclosed in quotes
d. the wait was not aborted with ESC in the parent or a "close window"
command in the child
If (d) fails, or some other error occurs, spawn will return a value
of 255. Otherwise spawn will return a condition code of 0.

9. Using spawn to force a context switch.
Some text editors have the ability to run a compiler or assembler
while the user remains inside the editor environment. Since the
editor is still in memory, the total ram that is available to the
compiler is limited. If the editor can be configured to invoke
the compiler with something like spawn /w/f p:bd c:\cc\tcc.exe ...
then the compiler will run in its own window with a full compliment
of memory. The /w switch is appropriate here since the editor must
wait for the compilation to complete before continuing and may need
the correct return code from tcc.exe .
This sort of thing can also be done from a batch file so that full
screen editors and the like can be conveniently run from a small
Desqview window. For example, if you have an editor say edit.exe, you
can create a one line batch file, say ed.bat, containing
@spawn/d/f/x c:\bin\edit.exe %1 %2 %3 %4 %5 %6 %7 %8 %9
The /d will disable the DOS window while the editor is running, but
unlike /w, /d will allow the DOS window to restart the first time you
select it. The /x will assure that DOS regains control when the editor
finishes. Without the /x, if you were to pull up a third window while
in the editor, control of the keyboard would pass to this window when
you exit the editor.

10. If you do not have a 386 processor.
You can still use spawn for context switching with a non-multitasking
system. In this case, the parent process will swap out when spawn is
invoked. You will generally want to use /f so that the parent isn't
swapped back initially. If the current process is marked non-
swappable and there isn't sufficient conventional memory to load the
child process, then spawn will fail with the message "api error
activating new process".
You want the child process to run concurrently with the parent, you
must lower the "maximum program memory" in the parent window to a value
small enough so that there is sufficient free conventional memory to
hold both processes. The exact amount will vary, but a figure of about
180k will permit one 180k process to spawn.