

	How to use Swallow v1.0
	-----------------------



Information, how to use with Pascal/C and the most important problems to
adapt a program to Swallow:


How to use with Borland/Turbo Pascal 6.0/7.0
--------------------------------------------

The Pascal-compilers of Borland create completely Protected Mode-compatible code, even those of TP 6.0. There will only be problems with assembler modules or own memory managers. The most important drop of bitterness is the unit Graph: it disregards the rules of Protected Mode so heavily that I didn't found a simply and fast way to let it fit. Overlays aren't supported by the Pascal-adapter because you normally have enough memory within Protected Mode, and in case of need you can let simulate virtual memory by the Pager additionally. The HLL(High Level Language)-adapter is saved as Swallow.Pas.

To use Swallow in your program you have to do the following steps:
- link (by "uses Swallow") the unit Swallow into your primary file as the
  first one, even before the CRT-unit and all the other standard units
- if you want to use Turbo Vision, link "SwaTV1", for Turbo Vision 1, or
  "SwaTV2", for Turbo Vision 2, as the second file into your primary file,
  directly after "Swallow"
- instruct the linker to create a simple map file (within the IDE at
  Options|Linker... Map File: Segments)
- compile your primary file
- call the enclosed convert program SEGREG after each linking; as the only one
  parameter it expects the name of your program

Your program is now ready to run. Make sure the files "Programname.Seg" and
"Swallow.Drv" are in the directory of the exe-file at run time. The latter is
searched within the "PATH"-directories too.

!!! Attention !!!
Call the program SEGREG after each linking. Otherwise your program will be
loaded into extended memory erroneously!




How to use with Turbo C++ 1.0/ Borland C++ 3.1
----------------------------------------------

The C++-compilers of program create nearly Protected Mode-compatible code.
The DOS/BIOS-Emulator takes care that incompatible commands work under Swallow
too. But if you include assembler code and use system-hacking libraries,
like special Critical Error-handlers you have to expect problems. The most
important drop of bitterness is the unit Graph: it disregards the rules of
Protected Mode so heavily that I didn't found a simply and fast way to let it
fit. Overlays aren't supported by the Pascal-adapter because you normally have
enough memory within Protected Mode and in case of need you can let simulate
virtual memory by the Pager additionally. The HLL-adapter is saved as c0?.asm
and replaces the original c0?.obj. These are linked automatically and have to
start the program even before executing the function main (the names are
c0l.obj for memory model large, c0m.obj for medium and so on). The functions
provided by this unit are exported via Swallow.H. If you want to debug the
program you have to link Swallow.C additionally.

To use Swallow in your program following steps must be done:
- instruct the linker to search for object files first in the directory where
  Swallow's c0?.obj-files are stored. Else you don't get an error message,
  because the standard c0?.obj are linked, but your program will still run in
  real mode. You don't need to add a c0?.obj-file to the project.
- instruct the linker to create a simple map-file (within the IDE you find it
  under Options|Linker... Map File: Segments)
- link your program
- call the enclosed convert program SEGREG after each linking; as the only one
  parameter it expects the name of your program

Your program is now ready to run. Make sure the files "Programname.Seg" and
"Swallow.Drv" are in the directory of the exe-file at run time. The latter is
searched within the "PATH"-directories too.

!!! Attention !!!
Call the program SEGREG after each linking. Otherwise your program will be
loaded into extended memory erroneously!




Problems adapting a Program
---------------------------

Following parts of your program must be checked or replaced:
- The memory management:
    Swallow exchanges the memory management of the run time library with an
    own by patching. In this way all standard procedures/functions are executed
    correctly. Special commands of the C-memory management aren't emulated (for
    instance heap-checks) and have not to be called. Own memory managers work
    incorrectly under Protected Mode with guarantee. So if your program uses
    an own you have to replace it by Swallow-calls.

- Assembler-Code:
    Assembler code normally is Protected Mode-incompatible, because many
    programmers write directly into the code segments or even stores their
    variables there. This kinds of errors will be visible at least at runtime
    by getting a "General Protection Fault". With this knowledge you have to
    revise your assembler parts.

- Access to system data:
    Many programs directly access system data, like the BIOS segment or the
    video memory. This is forbidden in Protected Mode. A loophole is the
    function Seg2Selector: it expects a real mode segment as the parameter and
    returns an adequate selector. This selector can or better: have not to be
    freed, because the same selector will be returned by multiple calls with
    the same segment. There are 4 selectors of the most important segments
    defined in the HLL-adapters: SEG0040, SegA000, SegB000 and SegB800.

- Overlays:
    They aren't supported by the HLL-adapters, because memory shortage
    shouldn't exist in Protected Mode. All extended memory can be used and
    you can add virtual memory too.

- Unit Graph:
    This unit cannot be used under Swallow. The old one of TP 6.0 is too
    incompatible with Protected Mode and I hadn't enough time to adapt the
    new one of TP 7.0 up to now. (Borland knew, why they created a new
    BGI-format)
- Turbo Vision:
    There are patches for Turbo Vision 1 and 2 for Turbo Pascal: they must be
    linked into your primary program by uses, directly after "Swallow", i.e.
    "uses Swallow, SwaTV1" for Turbo Vision 1 and "uses Swallow, SwaTV2" for
    Turbo Vision 2. Up to now there is feature to use Turbo Vision with
    Turbo/Borland C++

- Use of unsupported DOS/BIOS functions:
    though the DOS/BIOS-Emulator simulates most of the functions, there are
    some seldom and undocumented it don't support. In this case the program
    will be stopped at run time with the message: "Unsupported Interrupt xx".
