Dec 182017
 
C source code and libraries that will swap current program to EMS or Disk. Works with Microsoft C, Turbo C, and Lattice C.
File XSPAWN33.ZIP from The Programmer’s Corner in
Category C Source Code
C source code and libraries that will swap current program to EMS or Disk. Works with Microsoft C, Turbo C, and Lattice C.
File Name File Size Zip Size Zip Type
DEMO.C 1539 559 deflated
DEMO.EXE 12081 7773 deflated
LICENSE.DOC 2669 1074 deflated
MANUAL.DOC 17814 4883 deflated
MM.ASM 6425 1376 deflated
MM.COM 293 258 deflated
MP.ASM 5009 1245 deflated
MP.COM 163 163 stored
README.DOC 1917 653 deflated
XLATTICE.BAT 680 283 deflated
XMSC.BAT 689 319 deflated
XMSC4.BAT 691 321 deflated
XMSC5.BAT 693 319 deflated
XSPAWN.ASM 51608 7003 deflated
XSPAWN.H 1136 361 deflated
XSPAWNL.C 508 268 deflated
XSPAWNLE.C 594 301 deflated
XSPAWNLP.C 503 264 deflated
XSPAWNP.H 666 215 deflated
XSPAWNV.C 502 268 deflated
XSPAWNVE.C 16490 3601 deflated
XSPAWNVP.C 504 269 deflated
XSPWNLPE.C 596 302 deflated
XSPWNVPE.C 1673 601 deflated
XSYSTEM.C 1023 440 deflated
XTC.BAT 733 303 deflated
XTCPP.BAT 797 343 deflated

Download File XSPAWN33.ZIP Here

Contents of the README.DOC file



XSPAWN, Version 1.33
Saturday May 4, 1991


List of Files
-------------
README.DOC this file
LICENSE.DOC Whitney Software, Inc. license agreement
MANUAL.DOC manual

DEMO.EXE run MM.COM with and without swap
DEMO.C DEMO.EXE source
MM.COM display largest executable program size
MP.COM list parent's captured interrupts

XSPAWN.H include in your program

XSPAWNP.H XSPAWN source
XSPAWN.ASM XSPAWN source
XSPAWNL.C XSPAWN source
XSPAWNLE.C XSPAWN source
XSPAWNLP.C XSPAWN source
XSPAWNV.C XSPAWN source
XSPAWNVE.C XSPAWN source
XSPAWNVP.C XSPAWN source
XSPWNLPE.C XSPAWN source
XSPWNVPE.C XSPAWN source
XSYSTEM.C XSPAWN source

XMSC.BAT create Microsoft C 6.0 libraries
XMSC5.BAT create Microsoft C 5.0 and 5.1 libraries
XMSC4.BAT create Microsoft C 4.0 libraries
XTCPP.BAT create Turbo C++ libraries
XTC.BAT create Turbo C libraries
XLATTICE.BAT create Lattice C libraries

MM.ASM MM.COM source
MP.ASM MP.COM source


History
-------
In XSPAWN version 1.33, FHTSZ (in the file XSPAWN.ASM) is only
compared to the file handle table size field in the PSP (program
segment prefix) if FHTSZ is greater than 20. This was modified
because the file handle table size field in the PSP is not present in
DOS version 2.1 and there is no need to do the comparison unless
FHTSZ is greater than 20. (See the section "File Handle Table Size"
in the manual for more information about FHTSZ.)


Contents of the MANUAL.DOC file



XSPAWN, Version 1.33
Saturday May 4, 1991


List of Files
-------------
README.DOC this file
LICENSE.DOC Whitney Software, Inc. license agreement
MANUAL.DOC manual

DEMO.EXE run MM.COM with and without swap
DEMO.C DEMO.EXE source
MM.COM display largest executable program size
MP.COM list parent's captured interrupts

XSPAWN.H include in your program

XSPAWNP.H XSPAWN source
XSPAWN.ASM XSPAWN source
XSPAWNL.C XSPAWN source
XSPAWNLE.C XSPAWN source
XSPAWNLP.C XSPAWN source
XSPAWNV.C XSPAWN source
XSPAWNVE.C XSPAWN source
XSPAWNVP.C XSPAWN source
XSPWNLPE.C XSPAWN source
XSPWNVPE.C XSPAWN source
XSYSTEM.C XSPAWN source

XMSC.BAT create Microsoft C 6.0 libraries
XMSC5.BAT create Microsoft C 5.0 and 5.1 libraries
XMSC4.BAT create Microsoft C 4.0 libraries
XTCPP.BAT create Turbo C++ libraries
XTC.BAT create Turbo C libraries
XLATTICE.BAT create Lattice C libraries

MM.ASM MM.COM source
MP.ASM MP.COM source


History
-------
In XSPAWN version 1.33, FHTSZ (in the file XSPAWN.ASM) is only
compared to the file handle table size field in the PSP (program
segment prefix) if FHTSZ is greater than 20. This was modified
because the file handle table size field in the PSP is not present in
DOS version 2.1 and there is no need to do the comparison unless
FHTSZ is greater than 20. (See the section "File Handle Table Size"
in the manual for more information about FHTSZ.)














XSPAWN

Version 1.33


(C) Copyright 1990 Whitney Software, Inc.
All Rights Reserved

Microsoft and MS-DOS are registered trademarks of Microsoft
Corporation.

Turbo C is a registered trademark and VROOMM is a trademark of
Borland International.

Lattice is a registered trademark of Lattice, Incorporated.


XSPAWN 1
_____________________________________________________________________


Overview

The XSPAWN functions allow you to run a large program on top of
another program by swapping the underlying program to EMS memory or
to disk. This frees most of the DOS memory occupied by the
underlying program (both code and data segments) and returns it to
DOS for use by other programs or a DOS shell. The "parent" program
is automatically restored upon completion of the "child" program and
execution resumes where the parent program left off. The XSPAWN
functions can be called over and over again from one program to
another.


System Requirements

XSPAWN supports DOS versions 2.1 and later. Programs using the
XSPAWN functions instead of the standard C run-time library spawn
functions (fork functions in Lattice C) require up to 9K additional
DOS memory (4K on average). XSPAWN requires sufficient EMS (3.2+)
memory or sufficient disk space to perform a swap.


XSPAWN Kernel

The XSPAWN code that remains in memory while the child program is
executing is called the "XSPAWN kernel." The XSPAWN kernel is 1021
bytes in size. In addition to the XSPAWN kernel, the parent
program's environment, the parent program's PSP (program segment
prefix), and the environment to be passed to the child program remain
in memory while the child program is executing. The program segment
prefix is 256 bytes in size.


Compilers and Memory Models Supported

XSPAWN supports all standard memory models for Microsoft C (4.0, 5.0,
5.1, and 6.0), Turbo C++ (1.0), Turbo C (2.0), and Lattice C (6.0).
XSPAWN supports Turbo C++'s VROOMM overlay manager (as long as XSPAWN
is in the overlaid application's base).


XSPAWN 2
_____________________________________________________________________


Using the XSPAWN Functions

To use the XSPAWN functions you must include the XSPAWN.H header file
in your program, call the XSPAWN function that is equivalent to the
standard C run-time library spawn function (fork function in Lattice
C) you wish to use, and link with the appropriate XSPAWN library.
The XSPAWN functions have the same name as their standard C
counterparts (for Lattice C change fork to spawn) with the letter x
prefixed. The XSPAWN functions expect the same arguments as their
standard C counterparts (the modeflag argument does not exist in
Lattice C fork functions).

The XSPAWN family consists of the following functions:

int xspawnl( modeflag, path, arg0, arg1..., argn, NULL );

int xspawnle( modeflag, path, arg0, arg1..., argn, NULL, envp );

int xspawnlp( modeflag, path, arg0, arg1..., argn, NULL );

int xspawnlpe( modeflag, path, arg0, arg1..., argn, NULL, envp );

int xspawnv( modeflag, path, argv );

int xspawnve( modeflag, path, argv, envp );

int xspawnvp( modeflag, path, argv );

int xspawnvpe( modeflag, path, argv, envp );

int modeflag; Execution mode for parent process
char *path; File to be executed
char *arg0, *arg1..., *argn; List of pointers to arguments
char *argv[]; Array of pointers to arguments
char *envp[]; Array of pointers to environment
strings

int xsystem( command );
char *command; Command to be passed to COMMAND.COM

The modeflag argument must be P_WAIT. The modeflag argument exists
only for compatibility with the standard C spawn functions. (The
modeflag argument does not exist in Lattice C fork functions.) The
parent process will be suspended while the child process is
executing.


XSPAWN 3
_____________________________________________________________________


The path argument specifies the file to be executed. The path can be
just a file name or it can be a full or partial path (from the
current working directory). If path does not have a filename
extension or end with a period, XSPAWN will try the extension .COM
and then, if necessary, the extension .EXE. The xspawnlp, xspawnlpe,
xspawnvp, and xspawnvpe functions search for path in the directories
specified by the PATH environment variable.

Arguments are passed to the child process by giving one or more
pointers to character strings as arguments in the XSPAWN call. The
combined length of the strings (not including the first string, but
including space characters inserted automatically for separation) may
not exceed 124 bytes. The strings can be passed as separate
arguments (xspawnl, xspawnle, xspawnlp, and xspawnlpe) or as an array
of pointers (xspawnv, xspawnve, xspawnvp, and xspawnvpe). At least
one argument must be passed to the child process. The first argument
is, by convention, a copy of the path argument. (Using a different
value won't produce an error.) The end of the argument list must be
marked with a null pointer.

Files that are open in the parent process remain open in the child
process. With the xspawnl, xspawnlp, xspawnv, and xspawnvp
functions, the child process inherits the parent's environment. With
the xspawnle, xspawnlpe, xspawnve, and xspawnvpe functions, the child
process acquires the environment passed through the envp argument.
The envp argument is an array of pointers to character strings where
each string defines an environment variable. Each string is of the
form

variable=value

where variable is an environment variable and value is its string
value. The final element of the array must be NULL. When envp is
NULL, the child process inherits the parent's environment.

The xsystem function passes command to the file COMMAND.COM for
execution. The COMSPEC and if necessary PATH environment variables
are used to locate the file COMMAND.COM. If command is NULL and if
the function locates COMMAND.COM, it returns 1. If it does not
locate COMMAND.COM, it returns 0 and sets errno to ENOENT.

If the child process is started, the return value is the exit status
of the child process. The return value will be 0 unless either the
child process called the exit function with a nonzero argument or the
child process exited abnormally with an abort call or an interrupt.


XSPAWN 4
_____________________________________________________________________


If the child process is not started, the XSPAWN functions return -1
and set errno to one of the following values:

Value Meaning
---------------------------------------------------------------------
E2BIG The argument list exceeds 124 bytes or the environment
is not less than 32K.

EACCES Access to the swap file was denied, no handle was
available for the swap file, the file handle table size
did not equal FHTSZ in the file XSPAWN.ASM, attempt to
map EMS memory failed, or attempt to restore EMS memory
page-mapping state failed. There may be insufficient
EMS (3.2+) memory and disk space on the specified
paths.

EINVAL The modeflag argument is not P_WAIT.

ENOENT The specified file was not found.

ENOEXEC The specified file is not executable.

ENOMEM Not enough memory is available to execute the child
process or the memory control blocks are corrupted.


Controlling the Swap Operation

There are four global variables defined in XSPAWN.H which allow you
to control the swap operation of all of the XSPAWN functions. The
XSPAWN global variables and their actions are as follows:

_swap

If _swap is 0 (the default), XSPAWN will attempt to swap out the
parent process before executing the child process. Any other value,
and XSPAWN will execute the child process without swapping out the
parent process. In other words, if _swap is not 0, XSPAWN will
behave like the standard C run-time library spawn functions (fork
functions in Lattice C).


XSPAWN 5
_____________________________________________________________________


_swappath

If _swappath is a null pointer (the default), XSPAWN will attempt to
write the swap file (if EMS memory is not used) to the current
directory on the current drive.

You can specify one or more alternate paths for the swap file by
assigning a string to _swappath as follows:

_swappath = "D:\\;C:\\SCRATCH";

Each separate path specifier in the _swappath string (separated by a
😉 can contain a drive, a directory, or both. If you do not specify
a drive, XSPAWN will use the current drive. If the directory is not
specified, XSPAWN will use the directory that is current on the
target drive.

You may be wondering why you would ever want to specify multiple
paths. To illustrate one use of this feature, let us say your system
has a ramdrive called D: and a hard drive called C:. Since writing
to a ramdrive is many times faster than writing to a hard drive, you
would naturally prefer to write the swap file to the ramdrive. The
problem is that there may not be enough space on the ramdrive to hold
the swap file. The _swappath string shown above would cause XSPAWN
to try the ramdrive first and if there is insufficient space, to try
the C: drive next.

If a path does not exist, XSPAWN will skip it. If XSPAWN can't store
the swap file on any of the specified paths, it will return -1 and
set errno to EACCES.


_useems

If _useems is 0 (the default), XSPAWN will check for the existence of
EMS (3.2+) memory and if there is enough EMS memory, will swap the
parent process there instead of to disk. You can disable the use of
EMS memory by assigning a nonzero value to _useems.


_required

If you know the amount of memory required by the child process, you
can assign the amount in kilobytes to _required. Regardless of the
value of the _swap variable, if _required is less than or equal to
the amount of memory that is already free (without swapping out the
parent process), XSPAWN will execute the child process without
swapping out the parent process. If _required is 0 (the default) and
_swap is 0, XSPAWN will attempt to swap out the parent process.


XSPAWN 6
_____________________________________________________________________


Linking XSPAWN Into Your Program

The XSPAWN functions can be linked into your program by including the
XSPAWN library appropriate for your compiler and memory model on your
linker command line.


Interrupt Handlers

Something must be done with captured interrupt vectors that point to
interrupt handlers in your program. This is true for two reasons.
First, if XSPAWN swaps out your program, the interrupt handlers in
your program will no longer be in memory. Second, even if XSPAWN
doesn't swap out your program, it is probably undesirable to have
interrupt handlers in your program invoked in response to interrupts
that occur while the child process is executing. If you capture
interrupts, you should read the following to understand how XSPAWN
handles interrupts.

Before executing the child process, XSPAWN saves the current content
of the vectors listed in a XSPAWN table called the "vector table" and
replaces the content of these vectors with addresses stored in the
table. After executing the child process, XSPAWN restores the
vectors that were saved.

By default, the vector table contains the interrupts: 0, 1, 2, 3,
1BH, and 23H. Associated with the default interrupts is the address
of an interrupt handler in the XSPAWN kernel (the XSPAWN code that
remains in memory while the child process is executing) that consists
of only an IRET (INTERRUPT RETURN) instruction. By default, the
default interrupts will do nothing if invoked while the child process
is executing.

You can add or change entries in the vector table by using the
addvect function.

int addvect( number, opcode );
int number; Interrupt number
int opcode; Operation code

The number argument must be an integer from 0 to FFH.

The opcode argument can be either IRET or CURRENT. If the value is
IRET, the interrupt will point (while the child process is executing)
to the interrupt handler in the XSPAWN kernel that consists of only
an IRET instruction, unless the child process captures the interrupt.
If the value is CURRENT, the interrupt will point to the interrupt
handler that is in effect when the addvect function is called.


XSPAWN 7
_____________________________________________________________________


If the addvect function fails, it returns -1 and sets errno to one of
the following values:

Value Meaning
---------------------------------------------------------------------
EINVAL The opcode argument must be IRET or CURRENT.

ENOMEM The vector table is full. The vector table has space
for 20 entries (6 are used by default). If more
entries are desired, you will have to modify and
compile the file XSPAWNVE.C. Add free records to the
vectab1 array. No other changes are necessary.

It is typical to call addvect with an opcode of CURRENT before you
capture an interrupt. This will cause XSPAWN to set the interrupt to
its original value while the child process is executing.

To find out what interrupt vectors are captured by your program, use
an XSPAWN function other than xsystem (with the _swap variable set to
a nonzero value) to run MP.COM from your program. Remember by
default, XSPAWN captures the interrupts: 0, 1, 2, 3, 1BH, and 23H.
Interrupt 22H will point to your program because DOS uses it to store
the return address from the child process.


File Handle Table Size

If you have increased the file handle table size so that more than 20
files may be open in the parent process, you will have to modify and
assemble the file XSPAWN.ASM. Change the line

FHTSZ EQU 20

so that FHTSZ is set to the new size.

To increase the file handle table size for Microsoft C versions 5.0,
5.1, or 6.0, see the description of the necessary modifications to
the startup code in the README file accompanying the compiler.


XSPAWN 8
_____________________________________________________________________


Fatal Errors

If XSPAWN is unable to restore the parent process upon completion of
the child process, it will display the message "XSPAWN error" and
exit to DOS with an exit status of 1. This can occur for several
reasons:

1. The child process may have made itself permanently resident.

2. The swap file may have been erased or corrupted.

3. There may have occurred a disk read error.

4. There may have occurred an EMS memory management error.


 December 18, 2017  Add comments

Leave a Reply