Chapter 1:  Introduction 

1.1  Organization of this Documentaton

Chapter 1 provides an overview of the library and describes its features.

Chapter 2 is a debugging tutorial.  It is shown (a) how the array
functions provided in this library can be used in the development of
text-based windowing system of some complexity and (b) how the debugging
facilities of the library can be used to track down a number of serious
bugs.

Chapter 3 explains installation and use.  It discusses how to unpack the
compressed files on the disk and to set up the files for use in compilation.

Chapter 4 covers the single header file, L_MEM.H, required for use with
this library.  The special types used (Uchar, Far_ptr, etc.) are
explained.  It explains how to use the SHOWFUNC utility to display the
function declarations for Dolphin functions.

Chapter 5 is the main reference section.  It explains the usage of the
functions (grouped according to purpose), gives examples of use and
generally explains the finer points.  It is divided into sections, 5.1
through 5.6.  There is an index of functions in Appendix III, with page
numbers referring to this Chapter.

Chapter 6 contains about a dozen demonstration programs. In order to use
this library to its fullest extent these demos should be reviewed.

1.2  A Quick Outline of What this Library is All About

MS-DOS programmers who have had problems with far memory allocation
can make good use of this library which addresses these difficulties.
It is, in part, a far memory debugging package.  It is also a
replacement for the far memory functions in the Microsoft C and the
Borland/Turbo C++ libraries, and is an extension to them, providing
numerous additional far memory functions and far heap checking
functions.

The library provides a debugging tool in the form of a memory
allocation log, in which details of memory operations can be
recorded as they occur.  Two reports, based on this log can be
output to screen, printer or disk file.  The items in the log may
be output either in chronological order or grouped into oper-
ations on the same block (thus providing an individual block
history).

During the development of a program which uses far memory the program
will terminate when any of the functions in the library detects a
critical memory error (that is, damage to the memory control blocks).
Any of the available reports can be output automatically upon termination,
thus providing a history of far memory operations up to the point at
which the error was detected. A far heap dump function may be called to
give a map of memory blocks allocated in the far heap by the currently
executing process.  A useful hexdump function is provided as well.

Automatic termination upon detection of a critical error can be turned
off if desired.  Alternatively it is possible to arrange for the program
to terminate (with optional reports) when any of twenty-seven errors (or
any subset of them) is detected.  This makes it possible to check for a
particular type of error, for example, a NULL pointer being passed, or a
memory block being freed twice.

Multi-dimensional array allocation functions are provided (arrays of up
to five dimensions are supported) along with functions to free those
arrays.  This makes it easy to allocate memory for arrays (of any type
of data object) in far memory.  These arrays may be as large as avail-
able memory permits (up to a maximum of about 600K).  Array operations
are also recorded in the log, together with the constituent memory block
allocations that make up a multi-dimensional array allocation.

1.3  Description of Features

This library has the following features:

(a)  Reliable far memory allocation:  Microsoft's _fmalloc() causes
excessive heap fragmentation and occasionally fails despite lots of free
memory.  This library relies exclusively on DOS's memory allocation
functions, thus avoiding this problem. Blocks of any size up to
available memory may be allocated, initialized, resized and freed.

(b)  Dynamic allocation of multi-dimensional arrays in far memory:
There are functions to allocate dynamically arrays of any data type up
to five dimensions.  These functions return pointers which can be
subscripted, as in array[2][3][60000].

(c)  Variable array index bases and negative array indices:  Arrays can
have a non-zero base index, which can be negative.  Thus the first
element of a 1-dimensionl array a[] could be a[-32000], a[-1], a[0],
a[1] or a[65000] as desired.  The indices of a 2-dimensional array a[][]
could range from a[-8][-8] to a[8][8], and so on.

(d)  Array bounds checking:  Array indices can be checked during
assignment and retrieval of values from dynamically allocated arrays.
An attempt to write a value outside an array's data space (which is the
same as attempting to use an index outside of the permitted range of
indices) is trapped; no more "off by one" errors!

(e)  Representation of memory areas as 2-D and 3-D Arrays:  Video
RAM and other areas of memory can be represented as arrays, as in
screen[row][column].

(f)  Extensive error checking:  Most of the functions in this library
check for a variety of errors, including: null and invalid pointers, an
attempt to free an already-freed block, parameters with zero value, and
such abstruse errors as an attempt to allocate an array larger than 64K
using an element size which is not a power of 2.

(g)  Diagnostic information in a memory allocation log:  There is a
facility for automatic logging of far memory operations (including
array operations) with program line numbers; errors are also logged.
Sequential and block analysis reports can be sent to screen, printer or
disk file.  A summary report shows how many blocks were allocated and
freed, and how many were not freed.

(h)  Automatic detection of errors with consequent program termination:
It is possible to arrange for the detection of any of twenty-seven
errors, or any subset of them.  When the execution of a statement
generates one of these errors the program will terminate and display a
message identifying the source file and line number of the offending
statement:

(j)  Reports of far heap structure:  Complete information about
the far heap can be obtained at any time with the far heap dump
functions, including a hex dump of as many bytes of each memory
block as you wish.  The report can include all memory blocks or
just those allocated by the currently running process.  The type
of each block is shown.  There is also a variety of other func-
tions pertaining to the far heap.

Copyright 1991 Dolphin Software