Readme.txt file for the msDoc/Alpha directory

Readme.txt
    This file
arcRW.txt
    This describes the arcRead and arcWrite programs (at this phase in
    their development).
arcTree.txt
    This describes the core technology employed by these, the "tree".

The rest of this file is the release documentation, as stated below:

---------------------------------------------------
Alpha2 Release Documentation 8/02/95

This file is the primary piece of documentation for the Alpha release
of the HP OSTA library.

First THE BAD NEWS:

    LIMITED FUNCTIONALITY

    The code has been turned on for rewritable, and MAY work on WORM,
    although it has not been tested. See the msTest directory for more
    on which portions of the functionality are in use, and thus are
    expected to work today.

    LIMITED DOCUMENTATION

    Unfortunately, the documentation for this release is very
    sparse. Essentially, the best documentation for the actual
    interface is in comments inside the nsrArc.C file. 

Next, THE GOOD NEWS

    IT WORKS

    We have turned on the code for the rewritable media case, and
    it works.

    THE PROTOTYPES ARE "FINAL"

    The key deliverable of the Alpha code was that all the interface
    changes would at least be stubbed, so that users could begin
    designing and/or coding to something real. We believe that the
    interface in this code is robust and much improved from prior
    versions, and will make changes to it ONLY to fix significant
    problems that users find in using it.

    Thus, you can begin design with confidence that it is not in a
    state of flux, and about to change.

Key Improvements since the Interface Review

    LABELING SUPPORT

    We now support the labeling of OSTA-UDF volume sets independently
    from the export and import interfaces. This allows users to, among
    other things, use the OSTA-UDF volume labeling scheme on their
    disks as their primary labeling structure, if desired.

    This also provides much greater enforcement of the ISO and OSTA
    volume set requirements.

    In addition, this change consolidates and brings clearly to the
    surface the differences between WORM and Rewritable to the
    following two items:

    1. WORM volume labels cannot be removed, while Rewritable labels
       may be explicitly removed.
    2. WORM media allows multiple file sets, while Rewritable requires
       that a prior file set be removed before a file set may be
       exported.

    This is by far the most far-reaching interface change.

    ATTRIBUTES CHANGES

    The Attributes struct has changed:

    1. It will no longer contain the linkCount field. Although this
       field still exists, it is ignored, and will disappear
       altogether by Beta.

       This was a hazard, in that it had to be set by the user on
       export, but was of (very) limited value to the user on
       import. The linkCount will be automatically generated by the
       archive object, but the user will need to provide the number of
       subDirectories to write[Next/Root]ICB().

    2. It will no longer contain the fileSize field. Although this
       field still exists, it is ignored, and will disappear
       altogether by Beta.

       This field was ignored on exports, since the length is also
       held in the extentList, in the totalBytes() method. This
       second, ambiguous path for this information has been
       eliminated.

    3. It has grown to support DOS attributes, specifically SYS and
       ARC.

    4. It will become user-definable by Beta.

       We have prototyped a scheme by which users may define their own
       "struct" for their attributes, and will need only to implement
       some standard methods to supply and/or request attribute
       information. Our tests show so far that this may indeed be
       filled out and inspected by C code as a struct, while our
       library will interface with it via the required methods.

       Much more detail will be available by Beta, but for now,
       suffice it to say that users will be able to tailor their
       attributes struct to meet their OWN needs without breaking
       their interface to the archive object at all.

    DIRECTORIES SUPPORT DOS AND OS/2 NEEDS

    DirectoryEntry types now support a hidden bit.

    VARIOUS ASYMMETRIES ADDRESSED

    1. Parent directory entries are automatically generated by the
       archive object on export, and will no longer be supplied on
       import.

       The original version of the code returned parent entries along
       with the rest, which required users to throw it out. The only
       way they could identify it was by its name length being
       zero. This kludge has been removed.

    2. Several Volume-related pieces of information were (in the past)
       supplied on export, but unavailable on import. As much as
       possible, this has been corrected.

       The user is directed to examine the public methods of the
       Archive object to see the new information paths.

    3. MediaType and SectorSize are now required on import as well as
       export. They are used in enforcing the OSTA rules about volume
       sets. Errors are indicated if any of the media does not match
       what is specified, and the error occurs when the volumes are
       added to the volume set.

    4. AccessType has been eliminated, and replaced by an
       independently settable and readable writeProtect type. This
       better conforms to the OSTA and ISO specifications.

    EXTENDED ATTRIBUTES INTERFACE DEFINED

    The EA interface has been brought to the surface, and the whole
    model of how these are supported has changed significantly.

    1. EAs may be treated as DATA, rather than being embedded in the
       ICBTable, so that there is no requirement to import and
       re-export foreign EAs.

    2. Formatting (i.e., packing and unpacking) of EAs will be done by
       the same code which will be used in the second release of the
       toolkit (the "online objects").

    Thus, EA extent lists need to supplied to write[Root/Next]ICB()
    and are supplied back from read[Root/Next]ICB().

    IMPLEMENATATION INFORMATION PROVIDED

    Information about who has written a specific fileset is now
    available via the getImplementInfo() method, which may be called
    just before beginImport(). This will allow users to be picky about
    whose filesets they try to read.

    METADATA SPACE AVAILABLE ON IMPORT

    A method was added to allow reclaiming the space used by the
    ICBTable after import. Directory space must be reclaimed manually,
    but this space is provided on beginImport().

For more information please send complaints and questions to

David Van Maren                  
Hewlett-Packard SSO             Email: davev@gr.hp.com
700 71st Avenue                 Voice: (970) 350-4543 
Greeley, CO 80634               Fax:   (970) 350-4675 
