Archive Object Beta Release Documentation 10/30/95

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

1. HTML DOCUMENT AVAILABLE, BUT HAS PROBLEMS

    This release includes a set of HTML files (in the tar file only)
    which are derived from the comment blocks in the code. These are
    provided in lieu of a low-level reference manual. The content of
    this documentation will become more robust over time, but for now,
    they hopefully provide a convenient way to navigate around the
    public classes and methods.

    The base page is in the file:

        udfHtml/nsrtoolkit.html

    Note the following bugs:

    - Some methods have very little documentation showing up, or have
      it showing up twice.
    - The primary description of each class has somehow been left out,
      along with any of its public data members.

    Workaround:

    - Find the actual source file and read the comment blocks.

2. REWRITABLE AND WORM FUNCTIONALITY TURNED ON

    In this release, the functionality is fully implemented, and
    turned on but not yet thoroughly tested. Here is what we have
    done:

    - Label volume sets (without writing any file sets)
    - Destroy volume labels and filesets on ewritable
    - Grow volume sets
      - with and without existing file sets
      - on WORM and on MO
    - Write multiple filesets on WORM
    - Read specific filesets on WORM
    

3. INTERFACE HAS CHANGED SINCE ALPHA

    In reviewing the implementation and use constraints presented by
    our current base of potential users and our own implementation,
    several changes have been made to the interface since the Alpha
    release.

    These changes have been outlined and described in the file:

        udfDoc/msDoc/AlphaCh.txt

    Note that we believe these modified interfaces are now stable. The
    two areas which may undergo some change as they come into some
    usage and full implementation are:

    a. The EA interface is likely to change to:
       - offer control over Root EAs.
       - work easily with the EA packing and unpacking tools (to be
         included in the "online objects" in Release 2.0.

    b. Some of the VolumeSet methods which currently require an entire 
       volume set to be loaded may change to work with incomplete
       volume sets.

4. BASIC PORTING AND TESTING

    Portions of the code may be tested independently, as well as
    together. The following list of directories is provided as a
    recommended path to turning on the code.

    udfAncil/descrTst - This contains tests of the innermost guts of
                        the library - the descr directory. These tests
                        should pass before attempting to test the
                        Archive object. The two key tests here are:

        descrTst - tests out most of the descriptors
        attrTest - test out the Attributes class

    udfAncil/devsTest - This contains tests for the device
                        objects. NOTE that implementors are expected
                        to provide their own device objects. Thus,
                        these tests may assist in turning on that
                        code. These tests should pass before
                        attempting to test the Archive object at
                        all. The key tests are:

         ssDevTst - Tests out the abstraction of a drive device. This
                    should be turned on before trying the msDevTst.
         msDevTst - Tests out the surface driver object (MSDevice)


    udfAncil/msTest   - This contains the code which HP has used to
                        test and turn on the Archive object. It is
                        provided mainly for use as example code.

         arcWrite - This is an example application, which writes
                    archives in UDF using the Archive object. It also
                    supports WORM and Rewritable media, and volume set
                    growth, as well as label destroying.
         arcRead  - This is another example application, which reads
                    archives, supporting WORM and rewritable media,
                    etc... It also allows testing of volumeSet growth,
                    and supports comparison between UDF and CMR
                    representations of Metadata.
         udf2cmr  - Reads in an archive and writes a CMR file. This
                    functionality will be required by all users
                    wishing to perform interchange testing. NOTE that
                    this code has been kept largely independent of the
                    other code in this directory, so that it may be
                    ported more easily (by not requiring the port of
                    lots of other code).

    udfAncil/msVerify - This directory contains all of the CMR code,
                        and is mostly provided as an example. There
                        are currently no tests supported which allow
                        separate testing of the CMR code itself.
                        Thus,it should be tried out only after the
                        msTest directory code.
                        
For more information please send complaints and questions to

    udf_eng@gr.hp.com
