**************************************
* TPU2OBJ .TPU/.OBJ file converter *
**************************************

(c) 1988 Borland International, Inc. All Rights Reserved.


It is now possible to generate an .OBJ file from a .TPU file by
using the TPU2OBJ converter. The purpose of the TPU2OBJ utility
is specifically to make possible the link between Turbo Pascal and
Turbo Prolog, as described in the "Language Connections" column in
the March/April 1988 issue of TURBO TECHNIX. Other interlanguage
links (i.e., with Turbo C or assembly language) may be possible,
but we have not tested them exhaustively and do not recommend them
at this time.


>>>>>>>READ THIS PARAGRAPH<<<<<<<

Again, TPU2OBJ is NOT a general solution to the problem of linking
Turbo Pascal code to .OBJ modules written in other languages.
Please note that we CANNOT guarantee that this utility will work
in all circumstances, much as we'd like to. Borland International
therefore will NOT provide phone support for problems connected
with TPU2OBJ. Note carefully the warnings provided in the TURBO
TECHNIX article before you begin using TPU2OBJ.

>>>>>>><<<<<<<

The advantages of Turbo Pascal's smart linking are lost by
converting a .TPU file to an .OBJ file. When an .OBJ file is
linked by Turbo Pascal's linker, *all* routines contained in the
.OBJ file are loaded into the Turbo Pascal code file, whether
those routines are referenced or not.

What TPU2OBJ generates
======================

TPU2OBJ takes a file XXX.TPU as input and generates XXX.OBJ.


Segments and Groups
-------------------

The following segments are generated by TPU2OBJ:

* UNITNAME_TEXT Class 'CODE' Alignment PARA
This segment contains the code generated by Turbo Pascal.

* _DATA Class 'DATA' Alignment WORD.
This segment contains the typed constant in the unit.

* _BSS Class 'BSS' Alignment WORD.
This segment contains the variables in the unit.



TPU2OBJ groups _DATA and _BSS together in DGROUP.

It is not possible to change the segment names and the group
name.


Publics
-------

The variables, procedures and functions in a XXX.TPU interface
part are visible in the XXX.OBJ file through the PUBLIC
definitions.

Exceptions:

* absolute variables.

* inline procedures/functions.

For each procedure/function in a unit, a PUBLIC UNITNAME_XXX is
generated in the .OBJ file. These publics are only used
internally by other converted units. If a procedure/function is
declared in the interface section a PUBLIC is also generated.

It is possible to let the UNITNAME be a prefix to the
procedure/function name by using TPU2OBJ with option /P.
For example, the procedure:

procedure Next(I: Integer);

will produce a PUBLIC:

* NEXT or
* UNITNAME_NEXT ( Option /P )

All PUBLICs are in uppercase.


External
--------
For a reference to another unit an EXTERNAL is generated. These
EXTERNALs correspond to the PUBLICs described under the header
Publics, above.


Using TPU2OBJ
=============

To use a Turbo Pascal unit requires that SYSTEM.OBJ
(Turbo Pascal's runtime library generated from SYSTEM.TPU) be
present. The procedure SYSTEM_INIT must be called first in the
program, because this is the intialization and setup code for the
PASCAL module.

SYSTEM_INIT takes over the following interrupts:
* $0 (Divide by 0)
* $2 (Nonmaskeble Interrupt)
* $23 (Ctrl-C)
* $24 (Critical error)
* $75 (AT Math Coprocessor)

When terminating a program it is necessary to reinstall the
original interrupt vectors.

It it possible to call SYSTEM_003 to reinstall the vectors and
terminate to DOS.

SYSTEM_003 always terminates a Turbo Pascal program.


Calling the initialization part of a unit
-----------------------------------------
To use the intialization part of a unit it is necessary to call
the procedure UNITNAME_INIT.



Calling more than one unit
--------------------------

When a unit USES other units, these additional units must also be
converted to .OBJ files and be present at link time.
If a unit A uses a unit B, and B is changed, it is necessary to
recompile both A and B and convert them again.



Limitations of TPU2OBJ
======================

It is only possible to have:

* 1024 internal PUBLICS (the ones of the form UNITNAME_XXX ).
* 2048 EXTERNALS.