The Readme.txt file for documentation directory for the final release
of HP's UDF Object Framework

The files in this directory are as follows:

ErrHandl.txt
    Explains the conventions used in the code regarding error
    handling. This has been done so that ultimately, exceptions may be
    implemented with minimal architectural impact.
HeadTail.txt
    Explains the basics of the LogExtentList chopping methods
    provided: Head, HeadX, Tail, and TailX.
ListBas.txt
    This tries to show how the different lists in the sslib are kept
    similar. For example, they are all built on the RWTools.h++
    Generic classes, but have had value semantics added.
NameConv.txt
    This is the coding naming conventions. They may help to understand
    the source code.
Overview.txt
    Gives a good high-level description of entire Object Framework.
Readme.txt
    This file.

Below are some notes about what has changed in the final release from
before.

1. The ssTest directory has been reorganized.
   It would have been great to have had the time to actually clean all
   of these up as well, but many were left as-is. Upon release, they
   all PASSED.

   The simple tests which simply print out something have been
   separated a little bit, by being named volPrnt, dirPrnt, and
   rootPrnt, where the first two were called volTest and dirTest
   before.

   The most instructive example to look at is the rootPrnt.cpp
   file. It shows the way to follow all of the volume structures down
   to the root directory, and then print it out.
   
2. The README files have been consistently named, and several have
   been added.

   Now, if any directory has a README file in it, it is called,
   "Readme.txt". It typically includes some information about the
   files in the directory and/or the purpose and philosophy of the
   directory.

3. The DirList and DirEntry objects have been substantially changed.

   Prior to this release, the DirEntry CONTAINED a
   FileIdentifierDesc. Because the Descriptors do not fully support
   assignment and passing as arguments, this was changed. DirEntry now
   contains only the parts of the FID that it needs. This has the
   added advantage of making them more lightweight, not carrying
   around the extra fields of the FID.

   It also helps out in getting an icbAddress from it. Before, a
   Partition or LogicalVolume pointer to do it, since a LogExtent was
   being constructed from an Allocation Descriptor. Now, however,
   neither pointer is required, since the information is actually held
   as a LogExtent already. This is an improvement which was long
   overdue.

   WARNING: The largest problem here is that the comments in the
   nsrDir.h and nsrDir.cpp files were never fully changed to reflect
   the change in implementation.
   
4. The LogExtent boundary conditions have been changed.

   When Charley Bay completed his work on the PackedLogExtentList and
   TableSpaceResource objects, he identified a number of areas in
   LogExtent handling where the behavior was unclear. These were
   resolved, and it now all makes sense, we think.

   Fundamentally, the tricky areas were associated with what happened
   when a non-block-multiple extent or extent list was allocated. I
   believer that we now set the length of it properly. However, we
   round up its length when it is added back into a SpaceResource.

   Unfortunately, the best documentation we can provide is that
   embedded in the nsrExt.h, nsrExt.cpp, nsrSpace.h and nsrSpace.cpp
   files.

5. The ImplementationID has changed.

   The code now supports the original idea that all users of the
   toolkit would share the same ImplementationID, but be provided with
   a registration number, to be placed in the EntityID suffix. Now,
   the value that this toolkit writes into the ImplementID field has
   been set to its final value.

   In order to see how all of this works, see the file
   config/nsrStat.cpp. It shows which values can be set by the user,
   and which ones are automatically set by the toolkit.
      
6. srTest, newsrTest, and nodeTest all work with the LELSpaceResource,
   rather than one of the ISOSpaceResources.

   Due to lack of time (my favorite scapegoat), these tests, which
   SHOULD have tested several of the SpaceResources, now only use the
   LELSpaceResource, which is the same one that is at the heart of the
   TableSpacweResource, except it does not go to/fromISO().

   These tests should be tried on the BitmapSpaceResource and
   TableSpaceResource and should go through the to/fromISO() loop to
   prove that those objects work properly.

7. The EAInspector is NOT used. Instead, the SAIEAInspector, located
   in the wrong file has been used in its place. The EAInspector
   itself should be replaced by the SAI implementation, so that it
   will function properly.

-DVM 6/27/96
