PROPACK.TXT

            PRO-PACK(tm) Instruction Manual - February 1992

            Copyright (c) 1991,92 Rob Northen Computing, UK

                          All Rights Reserved



    LIST OF CONTENTS

        1.0 OVERVIEW
        2.0 COMMAND LINE
        3.0 COMMANDS
        4.0 FILE TYPES
        5.0 OPTIONS
        6.0 FILE EXTENSION
        7.0 FILE SPECIFICATION
        8.0 ERROR MESSAGES
        9.0 TECHNICAL SUPPORT



    1.0 OVERVIEW

        PRO-PACK is a sophisticated File Compression Utility written and
        designed for programmers. Two methods of compression gives the
        programmer the choice of high performance compression or high speed
        unpacking.

        Besides performance PRO-PACK also features the ability to compress
        executable files and uncompress and relocate them automatically in
        memory. The design of PRO-PACK caters for the often limited memory
        restraints of the program by allowing the packed data to be
        restored to its original unpacked state by unpacking in its own
        memory space.

        The unpack source code provided with PRO-PACK gives the programmer
        full control over unpacking. A packed file may be unpacked 'over
        itself' or an entirely different part of memory. A separate version
        of the unpack code can also be used to validate the integrity of a
        packed file before and after it unpacks. By ensuring the unpacker
        will not unpack corrupted packed data this will prevent further
        memory corruption and a possible system crash.

        An important feature of PRO-PACK packed files is their ability to
        prevent their unauthorised unpacking. This is achieved by packing
        the files with a 16 bit locking key. Unpacking a locked file
        without the correct key would be almost impossible.


    2.0 COMMAND LINE

        PP <command> <file_type> [-|/<option>] [.<ext>] <file(s)>

        Parameters may be specified in upper or lower case and must be
        separated with at least one space. The parameters must occur in the
        command line in the order shown above. Multiple options may occur
        in any order. Each option must be preceded with the option
        character, either "-" or "/" with an optional space between the
        option character and the option. The optional output file extension
        must be preceded with the extension character ".". The default
        output file extension is "RNC". The file specification may include
        the wild card characters "*" and "?".


    3.0 COMMANDS

        p: PACK

        This command is used to create a packed data or executable file
        from an unpacked data or executable file.

        The original file is not overwritten but a new file is created and
        given the file extension "RNC". The original file can be over-
        written by using the "-o" option and the file extension of the
        output file can be changed with the output file extension parameter
        [.<ext>].

        A file will not be packed if the packed file would be equal to or
        larger than the original unpacked file. You cannot pack a file that
        has already been packed.

        Example

        PP p d *.*

        will pack all files in the current directory. The files will be
        packed as data.

        PP p m -k 0x1234 -o *.*

        will pack all files in the current directory. The files expected
        are MC68000 executable binary files. A key of 0x1234 (hex) is used
        to lock them. All the files will be overwritten by their packed
        version.


        u: UNPACK

        This command is used to restore a packed data or executable file to
        its original unpacked state. It is not necessary to specify the
        Method of packing used when the file was packed.

        A file cannot be unpacked if it was packed and locked using the
        lock option "-l".

        A file packed and locked with a key using the "-k" option cannot be
        unpacked unless the same key is used to unpack it.

        NOTE

            Unpacking a PC ".EXE" file may not produce an identical copy of
            the original file. For example, the MS-DOS file compare utility
            "comp" may report some differences when comparing the original
            unpacked file with the PRO-PACK unpacked version. These
            differences occur only in the files relocation table and do not
            make the unpacked version behave or run any differently from
            the original version. These differences occur because PRO-PACK
            optimises the relocation table when packing a PC .EXE file.

            Unpacking an AMIGA file will not restore the symbol or debug
            hunks occuring in the original unpacked file. This is because
            these hunks do not get written to the packed file.

        Example

        PP u p *.*

        will unpack all files in the current directory. The files expected
        are packed PC executable files.

        PP u d -k 0x1234 -o *.*

        will unpack all files in the current directory. The files expected
        are packed data files locked with the key 0x1234. The packed files
        will be overwritten with the unpacked version.


        v: VERIFY

        This command is used to verify the data integrity of a packed data
        or executable file. The integrity of the packed and unpacked data
        is checked.

        Locked files may be verified. Files locked with a key can be
        verified providing the same key used to pack them is used to verify
        them. Executable files packed with a key do not require a key to
        verify them.

        Example

        PP v s *.*

        will verify all files in the current directory. The files expected
        are packed Atari ST files.

        PP v a -k 0x1234 *.*

        will verify all files in the current directory. The files expected
        are Amiga files packed with the key 0x1234.


    4.0 FILE TYPES

        Only one file type may be specified and it must not be omitted. All
        files referred to in the file specification must be of the same
        file type and the same as the file type parameter.

        The file type parameter tells PRO-PACK whether you want to pack a
        data or executable file and the format of the file to expect if it
        is an executable file. The "-d" file type specifies a data file,
        all other file types are executable.

        You cannot pack a data file as an executable file.

        NOTE

            Any type of file (including executable files) may be packed as
            data. A packed data file contains only the PRO-PACK header
            information plus the actual packed data. Executable files are
            packed with a self-extract piece of code added to the file.
            This allows them to automatically unpack (and relocate if
            necessary) when the file is run.

        The current version of PRO-PACK supports the following file types:

        d: Data

        Specifies the file type to be data, eg. game data, graphic data,
        sprite data, music data etc. Any file type can be packed as data.

        p: IBM PC

        Specifies the file type to be an PC ".EXE" or ".COM" file. You
        cannot pack Microsoft Windows or OS/2 executable files.

        s: Atari ST

        Specifies the file type to be an Atari ST ".TOS" format file.

        NOTE

            Any debug information occuring at the end of a ".TOS" format
            file will be packed with the rest of the file.

        a: CBM Amiga

        Specifies the file type to be an AmigaDos load file.

        NOTE

            SYMBOL and DEBUG hunks are not packed and will not appear in
            the packed file. Files containing OVERLAY hunks will not be
            packed.

        m: MC68000

        Specifies the file type to be an executable Motorola 68000 binary
        file containing 68000 instructions (and probably data). The
        execution address of the file is assumed to be the start of the
        file. A different execution address may be specified with the "-x"
        option.

        l: Atari Lynx

        Specifies the file type to be an Epyx .BIN type file. The same type
        of file produced by the ASM assembler.


    5.0 OPTIONS

        -k: Lock/Unlock a file using a 16 bit key

        This option is used by all the commands to specify a 16 bit key
        word. The pack command uses the key to lock the packed file so that
        it can only be unpacked using the same key. The unpack and verify
        commands must use the key same to unpack or verify the packed file.

        At least one space must occur between the "-k" and the key word.
        The key may be specified in decimal or hex.

        Example

        PP p d -k 0x1234 *.*

        will pack all files in the current directory using the key
        0x1234 (hex). The files expected are data files.

        PP u p -k 1234 *.*

        will unpack all files in the current directory using the key
        1234 (decimal). The files expected are PC files.

        PP p s -k -99 *.*

        will pack all files in the current directory using the key -99
        (decimal). The files expected are Atari ST files.


        -l: Lock a packed file

        This option is used by the pack command to lock a file after it has
        been packed. This prevents the file from being unpacked (but not
        verified) by PRO-PACK.

        NOTE

            Data files packed with this option may be unpacked by the
            unpack source code provided in the <source> directory.

        Example

        PP p d -l *.*

        will pack and lock all files in the current directory. The files
        will be packed as data.


        -m: Method of Packing

        This option is used to determine which method of packing is to be
        used to pack a file. Method 1 is designed to pack files as small as
        possible while method 2 is designed so that unpacking packed files
        is as quick as possible. The choice of method is left to the
        programmer and will depend largely on the application it is used
        in. The default method is 1.

        Example

        PP p d -m 2 *.*

        will pack all files in the current directory using Method 2. The
        files will be packed as data.


        -o: Overwrite the input file

        This option is used by the pack command to overwrite the unpacked
        files with the packed version. This option should only be used if
        you have a backup of the original unpacked files.

        NOTE

            If you specify a different output file extension and use the
            "-o" option on the same command line then the output file
            extension parameter overrides the "-o" option and the unpacked
            files will not be overwritten (unless the input file has the
            same extension as the output file extension).


        -p: specify a different pack block size

        This option is used by the pack command to specify the maximum size
        block a file will be packed with. This option can be used to 'fine
        tune' a packed file to save an extra few bytes in size. The default
        pack block size is 0x3000 (hex) bytes.

        Example

        PP p d -p 0x2800 *.*

        will pack all files in the current directory using a pack block
        size of 0x2800 (hex) bytes. The files expected are data files.

        PP p d -p -1 *.*

        will pack all files in the current directory using a pack block
        size of -1 (equivalent to 0xFFFFFFFF in hex), ie the file will be
        packed using just one block.

        NOTE

            data files which will be unpacked by the i8088 unpack source
            code must not be packed with a pack block size larger than
            32752 bytes (0x7FF0 hex).


        -v: verify packed data when run

        This option is used when packing an executable file. It causes a
        version of the unpack code to be written to the packed file which
        will test the data integrity of the packed and unpacked data before
        the unpacked program is run. If there is a CRC error the program is
        aborted.

        Example

        PP p p -v *.exe

        will pack all "EXE" in the current directory. The files expected
        are PC files. The integrity of the data will be checked when the
        packed version of the file is run.


        -x: Execution address

        This option is used to specify a different execution address when
        packing MC68000 executable binary files using the "-m" file type.
        The execution address should be given as a byte offset from the
        start of the file. In other words, the absolute execution address
        will be the load address of the file plus the offset value
        following the "-x". The offset may be given in hex or decimal.

        Example

        PP p m -x 0x1000 prog.bin

        will pack the file MC68000 executable file "prog.bin" and start
        execution of the program at the address it is loaded plus 0x1000
        (hex).


    6.0 FILE EXTENSION

        The output file extension is used by the pack and unpack commands
        to specify a different file extension from the default extension
        "RNC". The file extension must occur on the command line after the
        options (if any) and must be preceded with the file extension
        character ".".

        Example

        PP p d .dat *.*

        will pack all files in the current directory and give the packed
        files the extension ".DAT". The files expected are data files.


    7.0 FILE SPECIFICATION

        The file specification is used by all commands to indicate which
        files to pack, unpack or verify. The file spec. may include one or
        more files, including the wild card characters "*" and "?".
        Multiple files may be specified separated with a space.

        Example

        PP p d *.dat

        will pack all files in the current directory which have the
        extension "DAT". The files will be packed as data.

        PACK p d music.dat sprite.dat graphic.dat

        will pack the data files "music.dat", "sprite.dat" and
        "graphic.dat".


    8.0 ERROR MESSAGES

        CAN'T PACK FILE

        this occurs when you try to pack a file which would result in the
        packed file being larger than or equal to the unpacked file.

        ALREADY PACKED

        this occurs when you try to pack a file that has already been
        packed.

        PACKED DATA CRC ERROR

        this occurs when you verify a packed file and the stored packed
        data CRC is different to the calculated CRC, meaning the packed
        data has been corrupted.

        UNPACKED DATA CRC ERROR

        this occurs when you verify a packed file and the unpacked data CRC
        is different to the calculated CRC, meaning the packed data when
        unpacked would be different to the original unpacked file.

        NOT A PACKED FILE

        this occurs when you unpack or verify a file that is not a packed
        file.

        CAN'T PACK OVERLAY HUNK

        this occurs when you pack an AMIGA load file which contains an
        OVERLAY hunk.

        PACKED FILE LOCKED

        this occurs when you try to unpack a file that was packed and
        locked with the "-l" option.

        KEY REQUIRED

        this occurs when you try to unpack or verify a packed file which
        was locked with a key using the "-k" option and have not supplied a
        key to unlock the file.
         
        WRONG KEY

        this occurs when you try to unpack or verify a packed file which
        was locked with a key using the "-k" option  and have not supplied
        the right key.


    9.0 TECHNICAL SUPPORT

        Technical support for PRO-PACK may be obtained from:

        Rob Northen
        P.O. Box 17
        Bordon
        Hants
        GU35 8DY
        England

        Tel: +44 0428-713635
        Fax: +44 0428-713999