Dec 142017
Chain between .EXE files in Turbo Pascal 4.0+. Now works with 6.0.
File CHAIN6.ZIP from The Programmer’s Corner in
Category Pascal Source Code
Chain between .EXE files in Turbo Pascal 4.0+. Now works with 6.0.
File Name File Size Zip Size Zip Type
CHAIN.ASM 14804 3562 deflated
CHAIN.DOC 21181 7494 deflated
CHAIN.OBJ 746 671 deflated
CHAIN.PAS 3724 1222 deflated
DEMO.PAS 1117 540 deflated
GETMEM.ASM 8114 1937 deflated
GETMEM.OBJ 499 443 deflated
GETMEM6.ASM 5905 1506 deflated
GETMEM6.OBJ 452 384 deflated
PTR2STR.ASM 4236 1003 deflated
PTR2STR.OBJ 303 267 deflated
TGETMEM.PAS 1889 721 deflated

Download File CHAIN6.ZIP Here

Contents of the CHAIN.DOC file

Chain Facility for Turbo Pascal
Version 6.0
Kim Kokkonen

Turbo Pascal 4.0, 5.0, 5.5, and 6.0 no longer support two features that many
programmers have come to depend upon: Chain and Execute. The Chain facility
provided here is a reasonable facsimile of the Turbo 3 Chain and Execute
commands. Turbo's smart linker raises some new issues, though: see the
Restrictions and Limitations section below before getting your hopes too high.

The Chain facility is implemented in a small unit that you USE in your
Turbo Pascal 4.0-6.0 program. The unit exports a function called Chain4 which
you call to chain to a new program. You can chain to any other EXE or COM
file. Unlike Turbo 3, there is no restriction that the chained program be
another Turbo Pascal program. The new program overwrites the current program
in memory. Control will not return to the original program unless you chain
back to it.

This version of CHAIN has been updated to work with any version of Turbo
Pascal from 4.0 to 6.0. When you compile CHAIN.PAS with any version, it will
configure itself appropriately.

The source code for a unit named CHAIN is provided. Add this unit near the
beginning of your USES statement. CHAIN depends on no other units, and uses
about 700 bytes of code space. The first time you compile it, you'll need
(depending on whether version 6 of the compiler is used). Thereafter, you'll
just need to have CHAIN.TPU to link into your program.

CHAIN's central function is Chain4. It is declared as follows:

function Chain4(Path, CmdLine : string) : word;

The Path parameter to Chain4 specifies the name of the new program to execute.
Path must be a complete program name, including the extension, and a drive or
directory name if the file is not in the current directory. CmdLine is the
equivalent of a DOS command line to pass to the new program. Due to the way
CHAIN works, the command line is limited to 82 characters maximum. Longer
command lines will be truncated to 82 characters.

If chaining occurs successfully, the function will not return. If an error
occurs, Chain4 returns a DOS error code. The following error codes are those
most likely to occur:

2 File not found
4 Too many open files
8 Insufficient memory
30 Read fault
152 Drive not ready (mapped by Turbo's critical error handler)

Beyond a certain point, Chain4 is committed to chaining and cannot return to
the calling program even if an error occurs. In this case, it will simply halt
and return control to DOS. The only known case is when a read error occurs
while the new executable file is being loaded.

Here are some example calls to Chain4:

Status := Chain4('MENU.EXE', '');

chains to MENU.EXE in the current directory, passing it an empty command line.
Error information, if any, is returned in the word variable Status.

Status := Chain4('C:\BIN\TPC.EXE', 'MYPROG /M /Q /$T+');

chains to the command line Turbo compiler, telling it to compile the program
MYPROG.PAS with various options.

Restrictions and Limitations
CHAIN works by using DOS function 4B, subfunction 03 (load overlay) to
overwrite the current code in memory and transfer control to the new program.
While performing the load overlay call, CHAIN executes a number of steps:

o The new file is opened to check its type and/or size. If the file isn't
found, Chain4 returns with error 2. If the first 28 bytes of the file
cannot be read, Chain4 returns with error 30.
o Available memory is compared to the amount needed by the program. If
sufficient memory is not available, Chain4 returns with error 8.
o All available memory is allocated to the process.
o By default, all file handles except StdIn, StdOut, StdErr, and StdPrn are
closed. You can stop Chain4 from closing files by setting the typed
constant CloseFilesBeforeChaining to False. You shouldn't set it to False
unless you enable data sharing between the original and chained programs
as described below.
o Interrupt vectors taken over by the Turbo SYSTEM unit are restored to
their previous values. Which vectors are restored depends on the compiler
version used to compile CHAIN.
o The new command line is put in place within the program segment prefix.
o FCB's normally initialized by the DOS loader are initialized using the new
command line.
o The machine stack is temporarily moved to the top of available memory, a
step required for the load overlay call to work reliably. The newly loaded
program will move the stack back to wherever it is normally located.
o The DOS load overlay call is made to overwrite the original code with the
o The registers DS, ES, SS, and SP are initialized the same way that the DOS
loader normally would and control is transferred to the entry point of the

CHAIN _cannot_ handle items on the following list. It is your responsibility
to take any needed action (although some helpful procedures for dealing with
these items are described later).

o CHAIN does not close or reset the DOS standard file handles. If standard
input or output is redirected, this will be passed on to the new program.
This may or may not be desirable -- if not, the original program should
reassign these handles before chaining.
o Interrupt vectors grabbed by units other than SYSTEM must be restored. In
particular, the CRT unit in Turbo Pascal 4.0 takes over interrupt 1Bh. You
can restore it by using the DOS unit in your program, and executing the
following statement prior to chaining: SetIntVec($1B, SaveInt1B). (Note
that in Turbo Pascal 5.0 and 5.5, interrupt $1B is managed by the SYSTEM
unit and no additional steps are required on your program's part.)
o Memory allocation changes for the chained-to program (normally handled by
the DOS EXE loader in accordance with the $M directive for the new
program) are not performed. The new process will have all available memory
when it starts up, overriding any {$M } heap settings that you may have
specified. You can call the supplied SetMaxHeap procedure to adjust the
maximum heap when another Turbo Pascal program is started.
o Neither CHAIN nor the operating system can tell that the file you chain to
is a valid executable file. If you chain to a text file or some other
inappropriately formatted file, the system will crash.
o CHAIN does not store the new program's name (at the end of the
environment). It leaves the original program's name there, since it cannot
guarantee that the environment will have space for the new, possibly
longer name. If this limitation is important, see the SetEnvStr function
in Object Professional's OPDOS unit, or in the public domain unit TPENV.

The DOS function call used by CHAIN is not used very often, and it appears
that Microsoft or IBM didn't test it well in the days of DOS 2.X. As a result,
CHAIN may not work with PC-DOS 2.0 and 2.1, or with some OEM versions of
MS-DOS 2.x. We've incorporated a workaround that usually works in these cases,
but there are no guarantees when it comes to DOS 2.x. Test carefully if your
system must run under early versions of DOS.

Many authors of large programs are using the public domain Extend facility to
increase the maximum number of open files. If you are doing so, be warned that
Chain4's automatic file closing feature does not work properly with Extend. In
this case, your program must explicitly close any open files and call
"UnExtend" before chaining.

CHAIN provides a procedure to help solve the problem mentioned in the second
bullet above, that of dangling interrupt vectors and other uncompleted exit

procedure ChainHalt(Path, CmdLine : string);
{-Execute all exit handlers after the CHAIN unit, then chain as specified}

If you call ChainHalt instead of Chain4, all program exit handlers from units
following CHAIN in the program USES list will be executed prior to chaining.
ChainHalt does this by storing Path and CmdLine in global variables, halting
the program, and then actually chaining when its exit handler is reached. For
this technique to be effective, CHAIN must be first, or near the start, of the
program's USES list.

If a chaining error occurs while using ChainHalt, it simply halts the program
with an exit code given by the chain status values described above.

The CHAIN unit interfaces another routine, SetMaxHeap, that allows you to
modify the heap setting of an executing program, and thereby work around the
limitation described in the third bullet above. Here is the declaration for
the routine:

procedure SetMaxHeap(Bytes : LongInt);
{-Set maximum heap and adjust DOS memory allocation block}

If you need this routine (perhaps because the chained-to program must make an
EXEC call), then you should call it immediately after the chained-to program
starts, prior to any heap allocation. The parameter you specify to SetMaxHeap
is the same as the number you would specify as the third parameter in a {$M }
compiler directive. If there isn't sufficient memory to provide the requested
number of bytes, SetMaxHeap doesn't do anything, since Chain4 will have
already allocated all available memory to the process.

Sharing Data
Since the Turbo 4/5/6 runtime library is not completely incorporated into
programs as it was in Turbo 3, it is not so easy to share data between chained
programs. In fact, it is very likely that the new program will overwrite the
data segment of the old. Without playing further tricks, about the only
information that can be passed from the original program to the new program is
the DOS command line. There is no way to directly share a data segment between
two chaining programs, as there was in Turbo 3.

By taking advantage of DOS memory allocation functions, however, there is a
way to accomplish the same goal. The CHAIN unit exports three additional
routines to make this task easy. Here are their declarations:

procedure GetMemDos(var P : Pointer; Bytes : LongInt);
{-Allocate memory from DOS, returning a pointer to the new block.
Shrink Turbo allocation and relocate free list if forced to.
Returns P = nil if unable to allocate space}

function Pointer2String(P : Pointer) : string;
{-Convert a pointer to a string suitable for passing on command line}

function String2Pointer(S : string) : Pointer;
{-Convert a string formatted by Pointer2String to a pointer
Returns nil if S is an invalid string}

We'll show how to use these routines after first describing what they do.

GetMemDos works in a manner analogous to Turbo's own GetMem procedure,
returning a pointer to a region of memory of size Bytes. Unlike GetMem,
GetMemDos uses DOS allocation services rather than Turbo's own heap. By using
DOS services, GetMemDos allocates a region of memory that cannot be
overwritten during chaining. Also note that you can allocate regions larger
than 64K bytes if desired.

GetMemDos first tries to allocate space from DOS's own free area. If your
program has freed memory previously, perhaps by setting the maximum heap size
at compile time, DOS will immediately return a pointer to the free area. If
DOS doesn't succeed, GetMemDos tries again a different way by checking the
free space on Turbo's own heap. If sufficient heap space exists to meet the
request, GetMemDos moves Turbo's free list down in memory, shrinks the current
allocation of the process, and then allocates the freed up space as a separate
DOS block. (The actual process is slightly different under Turbo Pascal 6.) In
either of these cases, GetMemDos returns a pointer to the base of the
allocated block. If neither approach succeeds, GetMemDos returns a nil

Any memory allocated with GetMemDos is automatically deallocated when the
program (or a chained-to program) finally halts and returns to the DOS command

The Pointer2String and String2Pointer functions are used to pass the shared
data area pointer between chaining programs. Pointer2String converts a pointer
into an 8 character ASCII string suitable for passing on the command line to
the chained program. String2Pointer performs the reverse operation. Note that
the intermediate string format is not intended for display.

The best way to show these routines in action is with an example. Let's assume
a simple two program system: MEM1 starts up the action and chains to MEM2,
which can then chain back to MEM1. Here are the programs:

SHARE.INC - holds common data declarations
ShareRec =
{Any shared data declared here as a record field}
Counter : Integer;
SharePtr = ^ShareRec;
ShareData : SharePtr;

MEM1.PAS - the first program
program Mem1;
Status : Word;
if ParamCount = 0 then begin
{First time in, allocate shared memory space}
GetMemDos(pointer(ShareData), sizeof(ShareRec));
{See if we could allocate}
if ShareData = nil then begin
WriteLn('error allocating shared data area');
{Initialize data}
with ShareData^ do begin
Counter := 0;
{Initialize any other fields}
end else begin
{Get sharing pointer}
ShareData := String2Pointer(ParamStr(1));
{Do something with the data}
with ShareData^ do

WriteLn('in mem1 with counter=', ShareData^.Counter);

{Chain to other program}
Status := Chain4('mem2.exe', Pointer2String(ShareData));
{Check for chaining error}

MEM2.PAS - the second program
program Mem2;
Status : Word;
{Get sharing pointer}
ShareData := String2Pointer(ParamStr(1));

{Check if it's ok}
if ShareData = nil then begin
WriteLn('program must be chained to');

{Do something with the data}
with ShareData^ do begin
WriteLn('in mem2 with counter=', Counter);

{Chain back}
Status := Chain4('mem1.exe', ParamStr(1));
{Check for error}

Let's go through this step by step. The SHARE.INC file holds data declarations
to be shared by all programs. The ShareRec record can hold up to 64K worth of
shared data. Turbo limits any given record to 64K bytes, so if more than that
is needed, additional records should be defined. The ShareData variable is
simply a pointer used to access this record type. It is very important that
both MEM1.PAS and MEM2.PAS include the same declaration file to guarantee that
the data is identical.

MEM1.PAS is the program to call first, from the DOS prompt. It uses a simple
scheme to determine whether it has been called directly from DOS or by
chaining from another program. In this example, we assume that no parameters
on the DOS command line means that the program is being called for the first
time. You could use more bullet-proof techniques to make the same decision --
one way would be to have programs chaining to this one send it a special
password as the first parameter on the command line.

In any case, the first time MEM1 starts, it calls the GetMemDos procedure to
allocate a shared data area. Here, GetMemDos allocates the number of bytes
required to hold ShareRec, the shared data declaration. GetMemDos returns a
pointer to this region. Note that GetMemDos returns an untyped pointer.
Because of Pascal's strict data typing, we must _typecast_ the ShareData typed
pointer as an untyped one. If GetMemDos can't allocate the required space, it
returns a nil pointer, which we check for here.

Next, MEM1 initializes the shared data area. Within the statement With
ShareData^ Do Begin, we can refer to any of the shared data fields by name.
Any other programs we chain to will be able to do the same thing.

Let's follow this through assuming that MEM1 chains to MEM2. In MEM1's call to
Chain4, it specifies the executable file name MEM2.EXE, and passes the
ShareData pointer in ASCII format on the DOS command line. If Chain4 is
successful it won't return, but we should check for errors by polling the
Status variable after the call to Chain4.

The next statement executed will be in the main block of MEM2.PAS. (Actually,
any initialization blocks in units of MEM2 would be executed earlier if there
were any. As it stands, these initialization blocks cannot refer to the shared
data area.) MEM2 immediately takes the first command line parameter and
converts it back to a pointer. If there is no command line, or if the first
parameter isn't formatted like Pointer2String does it, String2Pointer will
return nil. MEM2 checks for this and halts if there was an error.

Again, this validation process could be bulletproofed. MEM1 could always pass
MEM2 a password as the first command line parameter. Perhaps better yet, the
MEM2.EXE file could be renamed to a non-executable DOS filename (like
MEM2.CHN) so that it could never be executed unless chained to. The Chain4
routine doesn't care what extension a file has.

MEM2 can then refer to and modify any of the shared data inside of a With
ShareData^ Do Begin statement. Then MEM2 chains back to MEM1, passing the same
ShareData pointer back. MEM1 determines that it is being chained to, and does
_not_ again allocate a shared data area.

In the example, this cycle never stops. Obviously, in a real program certain
actions would stop the program, returning control to DOS. No matter which
program is active, DOS automatically deallocates not only the main memory
block allocated to the program, but also the shared data block allocated

The easiest way to make programs share more than 64K of data is to call
GetMemDos more than once, each time returning a pointer to a sub-64K region.
Two or more pointers can be passed on the command line to other programs.

If your program calls GetMemDos, Pointer2String, or String2Pointer, Turbo's
smart linker will pull in about 300 bytes more code from these routines.

Revision History
Version 1.0 11/17/87
First release.
Version 1.1 11/18/87
Check for sufficient memory before chaining.
Add CloseFilesBeforeChaining constant to control file closing.
Version 1.2 11/22/87
Add routines for data sharing.
Version 5.0 9/29/88
Modified to work with either Turbo 4 or 5.
Version 5.1 10/31/88
Add ChainHalt routine
Version 5.5 1/16/90
Update for Turbo 5.5.
Add dynamic check for DOS 2.x workaround
Version 6.0 10/23/90
Update for Turbo 6.0.
Split GETMEM.OBJ into two files to minimize overlap

Copyright and Acknowledgement
The Chain Facility for Turbo Pascal is copyright (c) 1987 by TurboPower
Software. All rights reserved.

TurboPower Software hereby grants a limited license to use this software as

o The CHAIN unit and its source code may be distributed freely as long as
there is no charge, with the exception of a handling fee not to exceed $10.
o Programs using the CHAIN unit may be distributed without restriction,
commercially or otherwise.
o TurboPower Software's copyright notices must remain in the source code and

TurboPower Software accepts no liability for the use of this software.

Thanks to Ray Lambert, who showed that this function could be done in Turbo
3.0, which buoyed the morale during a few days of machine crashes while trying
to make this one work.

Contact Kim Kokkonen at Compuserve account 76004,2611 with comments regarding
the Chain Facility.

TurboPower Software is in the business of providing powerful tools for the
Turbo Pascal programmer.

Our newest product is Object Professional, a object-oriented library of
routines for Turbo Pascal 5.5. Includes more than 2000 routines for windows,
menus, data entry, help systems, mouse support, swappable TSRs,
object-oriented data, and much more. Also check out B-Tree Filer, a
network-aware database toolbox.

Call TurboPower Software at 408-438-8608 for more information.

 December 14, 2017  Add comments

Leave a Reply