TPCLONE - Routines for cloning typed constants into a program
-------------------------------------------------------------
TurboPower Software
10/88
Version 1.0
Released to the public domain

Overview
------------------------------------------------------------------------------
TPCLONE is designed to assist in the writing of installation programs:
programs that configure other programs by modifying their contents. The key to
writing such programs is to store all data that is to be modified in one or
more typed constants, organized into a contiguous block or a single record
structure, and to precede them with an ID string that can be located by the
installation program.

Here's an example of what we mean:

const
{--- ID string at the beginning of the block ---}
MyIdString : string[28] = 'My installation area follows';
{--- beginning of installation area ---}
MyInstallationOption1 : Byte = 1;
MyInstallationOption2 : Word = 2;
MyInstallationOption3 : LongInt = 3;
{--- end of installation area ---}

The installation program would have a corresponding block of typed constants
or variables that matches the original exactly in terms of size, type, and
number of constants:

const
IdString : string[28] = 'My installation area follows';
InstallationOption1 : Byte = 1;
InstallationOption2 : Word = 2;
InstallationOption3 : LongInt = 3;

Using the facilities provided in TPCLONE, the installation program can then
take the following steps: 1) locate the ID string in the target program's EXE
file; 2) read the current contents of the installation area into its local
copy; 3) allow the user to somehow modify or accept the current installation
options; and then 4) write the modified contents of the installation area back
to disk.

Using TPCLONE
------------------------------------------------------------------------------
TPCLONE interfaces the types, variables, and routines described below. For an
example of how to use them in a program, see TPCONFIG.PAS.

type ClonePack =
record
CloneF : File;
CloneT : LongInt;
end;

A ClonePack contains all information needed by TPCLONE about a file being
modified.

type DateUpdateType = (UpdateNone, UpdateDate, UpdateAll);
const DateUpdate : DateUpdateType = UpdateDate;

DateUpdate affects the behavior of the CloseForCloning procedure. If it is
set to UpdateNone, the closed file will have the same date and time stamp
that it had when it was opened. If it is set to UpdateDate, the date of the
file will be changed, but not the time. (We prefer this option because, like
Borland, we use the time stamp as a version number: 05:00 am = version
5.00.) If it is set to UpdateAll, both the date and time of the file will be
updated normally.

var CloneError : Word;

This variable, much like the DosError variable in the DOS unit, contains the
code for any I/O errors that occur in TPCLONE. After calling any of the
routines in the unit, you should therefore check CloneError to determine if
there was an error.

procedure OpenForCloning(FName : string; var CP : ClonePack);

This routine opens the specified file for cloning. If the file cannot be
opened, CloneError will contain the error code. This routine must be called
either directly or indirectly (by InitForCloning) before any of the other
routines in the unit may be called.

function FindDefaultsEnd(var CP : ClonePack;
var ID; IdSize : Word;
Skip : LongInt) : LongInt;

FindDefaultsEnd searches the file to be cloned, starting at the end of the
file and working backward, for the specified ID value. Normally ID is a
string, and IdSize is equal to SizeOf(IdString). If ID is found, its
offset in the clone file is returned as the function result. If it is not
found, the result will be 0, and CloneError will contain the I/O error code
if there was one. Skip is the number of bytes at the end of the file to be
skipped before starting the search.

function FindDefaultsStart(var CP : ClonePack;
var ID; IdSize : Word;
Skip : LongInt) : LongInt;

FindDefaultsStart searches the file to be cloned, starting at the beginning
of the file and working forward, for the specified ID value. Normally ID is
a string, and IdSize is equal to SizeOf(IdString). If ID is found, its
offset in the clone file is returned as the function result. If it is not
found, the result will be 0, and CloneError will contain the I/O error code
if there was one. Skip is the number of bytes at the beginning of the file
to be skipped before starting the search.

function InitForCloning(FName : string; var CP : ClonePack;
var ID; IdSize : Word) : LongInt;

This routine simply calls OpenForCloning to open the clone file, and
FindDefaultsEnd to search for the ID. Normally ID is a string, and IdSize is
equal to SizeOf(IdString). If ID is found, its offset in the clone file is
returned as the function result. If it is not found, the result will be 0,
and CloneError will contain the I/O error code if there was one.

procedure LoadDefaults(var CP : ClonePack; FileOfs : LongInt; var Defaults; Bytes : Word);

This routine moves the file pointer for the clone file to the specified
offset (FileOfs), and reads Bytes bytes of data into Defaults. CloneError
will contain the I/O error code if there was one, or 100 if the number of
bytes actually read in were less than the number requested.

procedure StoreDefaults(var CP : ClonePack; FileOfs : LongInt; var Defaults; Bytes : Word);

This routine moves the file pointer for the clone file to the specified
offset (FileOfs), and writes Bytes bytes of data from Defaults to disk.
CloneError will contain the I/O error code if there was one, or 101 if the
number of bytes actually written were less than the number requested.

procedure CloseForCloning(var CP : ClonePack);

This routine alters the date/time stamp for the clone file in the manner
specified by DateUpdate, then closes it. CloneError will contain the error
code if an I/O error occurs.

Warning
------------------------------------------------------------------------------
Special precautions need to be taken when using the techniques we've been
describing with Turbo Pascal 5.0. First, you need to insure that Turbo 5's
word alignment option is off--{$A-}--at least in the program(s) or unit(s)
containing the typed constants in question. Second, when declaring a block of
typed constants, you should be sure that the word "const" does not appear
anywhere in the middle of the block. The following declarations could cause
problems, for example:

const
IdString : string[17] = 'Installation area';
const
ConfigOption1 : Byte = 1;
const
FutureConfigOption : Byte = 0;
const
ConfigOption2 : Byte = 2;

Since "IdString" will probably never be used in the program to be installed,
Turbo 5's linker (which "smart links" data as well as code) would not include
it in the EXE file. Result: the installation program will fail when it tries
to find it.

Assuming that FutureConfigOption is also unused, the smart linker would remove
it as well. Result: when the block of typed constants is read in,
ConfigOption2 would be read into the area where FutureConfigOption is supposed
to be.