UnHPI v1.1  1997-12-12  Barry Pederson <bpederson@geocities.com>

FEATURES:

    UnHPI will attempt to display the contents of, and extract
    files from a .HPI or .UFO file archive.  When extracting, it
    retains long filenames, and can either retain or discard the
    original directory names.

    --- The format of .HPI files isn't documented, use at your own risk ---

    The package also contains full Java source code, and the
    core classes that access the .HPI file are written with
    re-use in mind.  They contain methods for querying the
    contents of a .HPI file, and obtaining java.io.InputStream
    objects for reading the stored data.  These classes could
    perhaps be used for more ambitious programs...maybe a GUI
    HPIExplorer of Java UnitViewer someday?

    As a Java program, it might be little slow, but hopefully Java
    will get faster in the near future.  My main goal was to
    write something that worked correctly, was reusable, and was
    portable - Java seemed like the best way do do all three.

CHANGES
    Ver 1.1
        Faster, Faster, Faster. Ver 1.0 was slow extracting
        large files (ok, pitifully slow). Ver 1.1 does some
        fancy buffering of data, and is twice as fast as
        Ver 1.0 running under the plain Sun JDK, and over
        ten times (!) faster when using the Sun Windows
        Performance Pack.

        As an example, extracting the "Yerrot Mountains.tnt"
        file from the first CDs TOTALA2.HPI file (>13mb) took 
        150 seconds on my machine with Ver 1.0, and now takes 
        only 14 seconds.

ACKNOWLEDGEMENTS:

    Thanks to Eric DeZert (Ericd45@aol.com) - Orleans / France
    for his WriteHPI program, which helped in understanding the
    .HPI format and the algorithm for uncompressing data stored
    within those files.

    I spent quite a bit of time examining his sourcecode..but
    unfortunately I don't speak French and barely speak 8086
    assembler...so it made or an interesting few days. :)

REQUIREMENTS:

    Since this program is written in Java, it requires that you
    have a Java VM (Virtual Machine) installed on your computer.
    The VM that comes in web browsers like Netscape won't work
    with this standalone application, you'll need something like
    Sun's JDK (Java Development Kit) or JRE (Java Runtime
    Environment).  These are available at:

        http://java.sun.com/products/jdk

    The JRE contains just enough Java to be able to run
    applications, the JDK is bigger and contains development
    tools so you can create and compile your own Java programs.

    If you download Sun's JDK or JRE, you might as well also get
    their Win32 Performance Pack - it easily doubles UnHPI's
    extraction speed.

    Since this program is 100% Java, it should work with any
    Java VM, but has only been tested with Sun's Windows JDK
    1.1.4.  (Theoretically, it should be able to run without
    having to be recompiled on OS/2, MacOS, various Unixes, etc,
    maybe even AS/400s and IBM mainframes.   If someone actually
    runs this on an AS/400 or a mainframe, I'd get a kick out of
    hearing about it)

CONTENTS:

    This package contains:

        UnHPI.txt           -  this file

        UnHPI.jar           -  The Java classes that make up the program

        UnHPI.bat           -  A Windows batch file that makes it easier
                               to run the UnHPI program. (You may have to
                               modify this to reflect the directories your
                               copies of Java and UnHPI are installed in)

        UnHPI_Source.zip   -  Full source to the Java classes


INSTALLATION:

    We'll assume you're installing on a Windows machine with
    Sun's JDK installed.  I think the JRE will be very similar, but
    Microsoft's JavaVM will be a bit different

    If you've got Sun's JDK successfully installed, you should be able to 
    open up a command prompt and type "java -version" and see the version 
    of the JDK you have installed.

    Next, extract UnHPI.bat and UnHPI.jar files from this package. The .jar
    file can go anywhere, and the .bat should go to a directory in your path.

    The UnHPI.bat file is just one line long - use a text editor to
    modify it to reflect the directories where your JDK and UnHPI.jar
    are stored.

USAGE:

    The usage of UnHPI is similar to Info-Zip's UNZIP program.

    If you've placed the UnHPI.bat file in a directory in your
    PATH, and updated it correctly, you should be able to type:

        UnHPI

    at a command prompt and see a usage message like:

    ---------------------------------------------
    UnHPI v1.0  1997-12-10  Barry Pederson <bpederson@geocities.com>

    Usage: UnHPI [option] HPI-file [file file file ...]
        -v     View contents
        -j     Junk pathnames and extract files
        -d     Extract with directories (default)

    Wildcards * and ? are permitted when you specify files to extract
    (filenames are case-insensitive)
    ---------------------------------------------

WARNING:

    I had some problems on my WindowsNT machine with the
    Wildcard characters - the command shell would expand them
    before passing the parameters to the java interpreter.  So
    you may have to put file parameters in quotes for it to work
    correctly.  For example, you might have to type:

        unhpi -v r:\totala2.hpi "*.pcx"

    instead of

        unhpi -v r:\totala2.hpi *.pcx

    It all seems to depend on whether you already have files in your current
    directory that match the wildcard sting you're using.  If anyone knows
    how to fix this, let me know.

EXAMPLES:

    Here are some examples to show how the program might be used:

    unhpi -v c:\aflakker.ufo           // View the contents of a unit file
    unhpi -v r:\totala2.hpi "*.pcx"    // View a list of .pcx files on a CD
    unhpi -v r:\totala2.hpi maps\*     // View just files in the maps directory

    unhpi r:\totala2.hpi               // extract all the files, keeping the
                                       // directory structure
    unhpi -d r:\totala2.hpi            // same thing as above

    unhpi -j r:\totala2.hpi            // extract all the files, ignoring the
                                       // original directory names

    unhpi -j r:\totala2.hpi "*.pcx"         // extract just the .pcx files into
                                            // the current directory                    )
    unhpi -j r:\totala2.hpi "*.tnt" "*.ota" // extract all the .tnt and .ota
                                            // files


JAVA NOTES

    The source code is full of comments, so you can run the "javadoc"
    program to get a nice set of HTML files documenting the classes
    and methods.

    The program was written with IBM's VisualAge for Java 1.0 - a great
    program at a great price. (but you have to have 64mb of RAM for it to
    be very usable)


DISCLAIMERS

Copyright (C) 1997 by Barry Pederson <bpederson@geocities.com>. All rights reserved.

 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:

 1. Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.

 2. Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.

 THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 SUCH DAMAGE.

---------------------- That's all folks -----------------------------------
