README.TXT file for NEWTEST code
================================

Thank you for using my code. The following notes should help
you build the sample program successfully.

You should create a sub-directory RES, and move the 3 files
NEWTEST.ICO, NEWTDOC.ICO, and NEWTEST.RC2 to this sub-directory.
(If you used PKUNZIP with the option -d, this will already have
been done for you.)

You should move the file COUT.ZIP to another directory, and
PKUNZIP it there. This file contains the code and makefiles
needed to build the cout libraries that NEWTEST uses. My code
assumes that this other directory is called COUT and is located
at the same level as the directory into which you have unpacked
the NEWTEST code (NTDIR in the diagram below):

parent_directory ----|
|
|---- NTDIR
|
|---- COUT

If you use any other directory structure, you will need to edit
NEWTEST.H so that the #include references for CSTRWND.H and
WINSTRM.H are correct. You will also need to use the MSVC Project
Options menu command to ensure that MSVC correctly picks up the
reference to the COUT libraries in your particular directory
structure.

----

The main test routines are in maintest.cpp. I took two approaches to
testing the MemoryObject and FarHeapBlock classes. Firstly, I wanted to
use MemoryObjects for a realistic test while at the same time thrashing
the deallocation of memory. I needed to allocate a large number of
objects and then deallocate them in a different order. I therefore
implemented a simple tree-sorting routine that read a set of random
numbers in from a file and sorted them into order. I created the
sort_node class, derived from MemoryObject, for this. You will see that
it is declared as FAR. This is essential. As MemoryObjects and their
derived classes are created in Windows global memory, all pointers to
them must be far pointers. I wanted to fill a lot of FarHeapBlocks, to
exercise things properly. I therefore made each sort_node much bigger
than it would normally need to be by including an array char filler
[1000] in it.

I also decided to implement a string handling class like CString,
provided as part of MFC. Fortunately, Microsoft provide MFC source code
with Visual C++. Further, the MFC licensing conditions include the
following phrase:

Microsoft grants you a non-exclusive royalty-free right to use and
modify the source code contained in any Microsoft Foundation Classes
source code file for purposes of creating a software product. However,
you may not include this code in source form (or any modified version of
it) within any software product.

Thus, as the owner of a licensed version of Visual C++, I was able to
take the majority of the MFC code that implements CString and modify it
to work as a derived class of MemoryObject. The new class is CMOString.
The code for it is provided in the files cmostr.h and cmostr.cpp,
included within the files that you can get from CUJ to support this
article. Please remember that you should have a legal copy of MFC to
use the CMOString code and that the above licensing conditions apply to
it. (If you use the Symantec C++ compiler, you will have a legal copy


of MFC, as Symantec license MFC from Microsoft.) Microsoft has kindly
given permission for me to include the code as part of this article.

The required modifications to CString were fairly straightforward. All
pointers needed to be explicitly declared as far pointers. I had to
modify the function CString::AllocBuffer so that it used
CMemoryObject::AllocateBlock rather than the global new operator.
Similarly, I had to modify SafeDelete to use CMemoryObject::ReturnBlock
rather that the global delete operator.

The CComdtestApp::DoTest function, which does most of the testing,
deliberately does not return all of the CMemoryObjects when it exits.
This is to illustrate the handling of memory leakage. I surround the
call to DoTest with exception handling code, to trap any memory
allocation errors (such as shortage of memory) identified by the
program.

----

Although I cannot guarantee support for my code, I would like
you to feel that you should ask me if you have any problems with
it.

You can contact me via Compuserve. My address there is
100265,3625.

My postal address is:

David Singleton
30 The Albany
Sunset Avenue
Woodford Green
Essex
IG8 0TJ
United Kingdom

Good luck

David Singleton