MAG Disk (Jun 1989) : Packerdocs



                        Power Packer 2.2a User Manual

                                 May 8, 1989



Preface
=======

     Congratulations, you have just obtained a copy of the PowerPacker 2.2a,
Power Peak's command and data cruncher for the Amiga.
     If you have suggestions or remarks about this program, or if you find
any bugs, please let me know.
     This version of the PowerPacker is shareware, this means that if you use
it a lot I would appreciate it if you'd send me a contribution of $10 or the
same amount in any other currency.  This money will enable me to produce more
programs on the Amiga.  If you send $15 I will send you the latest version of
the PowerPacker.
     Write to the following address:

                                Nico François
                                Corbielaan 13
                             3060 Bertem BELGIUM


Contents
========

1. The Packer
     1.1 An introduction
     1.2 The file requester
     1.3 The basic menus
          1.3.1 Project
          1.3.2 Prefs

2. Recrunch
     2.1 How ?
     2.2 Why ?

3. The HunkLab
     3.1 Preferences
     3.2 Process file

4. The Script Menu

5. The Supervisor Window

6. A Sample Session

7. PowerPacker 2.2a & the CLI


1. The Packer
-------------

1.1 An introduction

     The PowerPacker is a userfriendly command and data cruncher, this means
a menu driven utility that can crunch almost any file on your disks.  When
you use it for the first time it's best to maintain a certain order in your
actions (as we will see in chapter 6 of this document):

  (a) Set the packer options at the beginning of a session (Prefs menu)
  (b) Load the file from disk (Project menu)
  (c) Wait for the file to (de)crunch.
  (d) Save the file back to disk (Project menu)

     Apart from crunching, you can also recrunch files that were crunched by
most other crunchers.
     The HunkLab enables you to e.g. force code or data in chip ram.
     The script allows you to e.g. crunch a dozen of files overnight.

     Before I demonstrate how to use the PowerPacker, let's look at the file
requester and a brief overview of the menus and capabilities.


1.2 The file requester

    Whenever you are required to enter a filename, the packer sets up a file
requester.  This requester automatically contains all devices connected to
your Amiga and lists all the files (and their length) of a selected
directory.  You don't have to wait for the directory read to end.  You can
select a file or directory the moment you see it, or you can enter it in the
appropriate string gadget.

    However, if you wait for the directory read to end and quit the file
requester, the next time you use it all the files will still be there, so you
don't have to wait for the directory to be read again (This is very useful
when you are recording a script, as you'll see later).  This feature has one
disadvantage :  if files are changed or added to the selected directory they
won't be shown in the list, or they will be shown with the wrong filelength,
the next time the requester appears.  Therefore, if you think anything has
been changed to the selected directory, use the 'GET DIR' gadget to re-read
the directory.  (E.g.  when you save a crunched file on top of the old one,
the old file length will be shown in the requester.)


1.3 The basic menus

1.3.1 Project

    The project menu contains the file manipulation options.  Most of them
speak for themselves:

  Load      ->  Load a file from disk and start the (de)crunching.
  Save      ->  Save the (de)crunched or processed file in memory to disk.
  Delete    ->  Delete a file from disk.
  WorkBench ->  Open or close WorkBench if possible. (Adds 42K !)
  Sleep     ->  Put the PowerPacker to sleep on the WorkBench Screen, this
                frees 40-50K.
                WARNING: All buffers will be deallocated, so you are advised
                         to save things first.
  About...  ->  Show general information and my address.
  Quit      ->  Quit the program.

1.3.2 Prefs

     The prefs menu contains all the (de)cruncher settings.  You can select
to (de)crunch command files or a data files.  If you want the crunched
version of your file to be executable, select 'Command file'.  Now the
PowerPacker knows it has to add a decrunch header (572 bytes).  If the file
you want to crunch only contains data (e.g. Source codes of your own
programs), select the 'Data file' option.  This can be handy if you're going
to use the PowerPacker CLI commands.  I'll discuss these commands in chapter
5 of this document.  Finally you have to choose whether you want to crunch or
decrunch the load file.

Note: - The PowerPacker will automatically decrunch a previously crunched
        file.  You don't have to select crunch or decrunch mode anymore as
        in PowerPacker 2.0a.

     The 'Decrunch Color' submenu contains the following options :

  Color 0   ->  The background color will change while decrunching
  Color 1   ->  The text color changes
  Pointer   ->  Only the mousepointer's color changes
  Scroll    ->  Handy for decrunching a demo (just try it out !)
  None      ->  If your eyes are wearing out.

     These options indicate what color will flash when a file is decrunched.
You can change this option before saving a crunched file, so you can save a
version of your crunched program that flashes in color 1, and one that
flashes in the mouse pointer.
     If the 'Color Crunch' option is selected, the PowerPacker will use the
same color while crunching the file, giving you an idea what the decrunching
will look like (provided that you don't change any options just before saving
to disk).  The default value is 'Color 1'.

     In the efficiency submenu you will find the following possibilities :

  Fast      ->  Use for small files, or for quick crunch.
  Mediocre  ->  Better but slower.
  Good      ->  Default, gains 40-50% in most cases.
  Very Good ->  Also very slow !
  Best      ->  Advised for script use only, ultra slow !!!

Note: - 'Fast' is approx. 4 times faster than 'Good', 'Very Good' is
        2 times slower and 'Best' 4 times.
      - 'Best' isn't always the best.  Small files crunch best with
        'Very Good' or even 'Good'.

     You can set Amiga's multitasking off to increase the crunching speed
(slightly).  The default setting is on.  When you want to use the PowerPacker
in a multitasking environment, you'll probably start a crunching job and at
the same time continue your work.  In that case, it might be interesting to
set the 'LED Crunch' option on.  Now your power-LED flashes while crunching,
just like the screencolors.  (but I presume they're already turned off
because editing a file with flashing text really gets on your nerves.)
     You can even turn off your monitor and still see when the cruncher has
finished.

     Finally, you can set 'Paging' in the supervisor window on so you can
read the crunch and hunk information, without everything racing off the
screen before you've had a chance to see it.

Note: - While crunching, you can press both mousebuttons at the same
        time to abort.
      - Do *NOT* change disks when you are crunching with the multitasking
        switched off !!!  The Amiga will crash !!!

2. Recrunch
-----------

2.1 How ?

     This menu is provided for the people who were using another cruncher or
an older version of the PowerPacker.  Just select 'Recrunch File' or
'Decrunch Only' and load the file.  The PowerPacker will start the correct
decrunch algorithm.  If you selected 'Recrunch' the PowerPacker will start to
crunch the decrunched file.  If the PowerPacker doesn't recognize the
cruncher it will say so, no harm is done.  If you select 'Recrunch Always'
the PowerPacker will always recrunch, even if the file was crunched with this
version of the PowerPacker.  Useful for recrunching files using a higher
efficiency.  (E.g. recrunch a 'Fast' crunched file with 'Best')

     Crunchers currently supported are:  'ANC Cruncher', 'TNM Cruncher 1.1',
'Relokit 1.0', 'HQC Cruncher 2.0', 'MasterCruncher 3.0', 'DragPack 1.0' and
older PowerPacker files.  If you'd like to see other crunchers supported,
send me the cruncher and some programs crunched with it.  (Together with a
contribution I hope).  If it is possible to develop a decrunch algorithm I
will include it in the next version of the PowerPacker.

2.2 Why ?

     The PowerPacker always crunches better than the 'ANC Cruncher',
'TNM Cruncher' and 'HQC Cruncher'.  It crunches better than 'Relokit' most of
the time, but even if it doesn't, I advise you to recrunch because 'Relokit'
has some serious disadvantages (e.g.  while the decrunched file is running,
the crunched version still eats memory).  In contrast the PowerPacker only
eats about 580 bytes while your file is running, and (of course) frees it
afterwards.

Note: - If you want to recrunch a PowerPacker 1.1 or 2.0 crunched file, the
        PowerPacker just replaces the file header with the improved and
        debugged 2.2 header. (Unless you've selected 'Recrunch Always')
      - The recrunch menu only supports command files !  You can't recrunch
        data files from e.g. PowerPacker 1.0, sorry.

2. The Hunklab
--------------

2.1 Preferences

     This menu is not really part of the PowerPacker crunch/decrunch routines
but it wasn't worth writing a separate program for and a HunkLab is after all
a very interesting utility.  You can e.g. use it to remove symbol and debug
hunks from files that wouldn't crunch otherwise.

     You can force a program's code, data or BSS (uninitialised data) into
chip ram or you can remove symbol tables and debug information just by
toggling the marker on/off.  So in future, when you want your programs to be
able to run on a one megabyte system, a simple click on the mousebutton will
do.

2.2 Process file

     'Process file' reads the file from disk and changes it according to your
preferences.  To save the processed file, use 'Save' from the Project menu.
     'Process & Crunch' will process the file and crunch the file afterwards
(if possible).  To save use 'Save' in the Project menu.

Note: - Debug and symbol hunks are only used in debuggers, so you can safely
        remove them from a program. (Unless you want to debug the program.)

3. The Script Menu
------------------

     The script is something that will save you a lot of time, it allows you
to record 80 different commands to be executed after each other.  It is ideal
for crunching a lot of files overnight.  Menu options are:

     'Clear Script' and 'List Script':
          will do just that.
     'Script Log File':
          is used to specify a file to redirect output to.  If you cancel
          the requester no log file is used.
     'Destination Dir':
          is used to specify the directory to save to.  It is ghosted in
          normal use.
     'Start Recording':
          is used to start the recording of the script. If the script was
          empty you will be asked for the destination directory.  You will
          also be asked whether to append '.pp22' to the destination file.
          You're advised to do this for data files.
              After selecting the destination you can start entering the
          script commands.  Everything that is ghosted is not available as a
          command.  Just enter everything as if you were actually using the
          PowerPacker.  When you e.g. choose 'Load' the PowerPacker will
          ask a list of files to be (de)crunched. Press 'CANCEL' to exit the
          entry.
          Note: - You can still change the source and destination dir while
                  recording.
          Every command you enter will be displayed in the supervisor window.
     'Stop Recording':
          is used to exit the recording mode.
     'Delete Last':
          will delete the last command after a confirmation.
     'Execute Script':
          will start the playback of the script commands.  If you press the
          menu button a requester will appear to ask you if you want to abort
          the script execution.
              After executing the script a request to clear the script will
          appear.

Note: - It is advisable to let the filerequester buffer fill before you
        start selecting files.  It is also better not to change the source
        directory too often.
      - The screen turns grey to indicate a script is executing.
      - While executing a script, the PowerPacker will always act
        destructive !  Files will allways be overwritten and deleted !!!

4. The Supervisor Window
------------------------

     This window displays all kind of useful information like the file
status, crunch messages, and error messages.  You can follow all steps, from
the original file that is loaded into memory, to the final crunched version
on disk.  When an executable file is loaded, its hunk information is
displayed.  This information is rather technical, but it can be useful for
programmers.  If you're not interested, just ignore it.

     I think it might be useful to give a list of possible error messages:

(De)crunch :  Buffer overflow !
                (Crunched file is getting longer than original file)
              Crunch aborted !
                (Crunching stopped by user or by buffer overflow)
              No memory for decrunch buffer !
              Out of memory !
                (Buy some more, try selling your WorkBench :-)
              Sorry, can't crunch !
                (This is a polite program)
              Can't find hunk_header.
              Hunk not allowed in load file!
              Unknown Hunk !
                (Not a command file)
              Hunk not supported (yet ?) !
                (If it's a symbol or debug hunk, try removing it in HunkLab)
              Nothing to save !
                (Buffer is empty)
              Save Aborted !
              Error reading file !
              Can't open file !
              Error writing data header !
              Error writing buffer !
              File not found !
              Couldn't delete file !
              Can't open file !
                (Disk errors)

Recrunch :    No need to recrunch 'PowerPacker 1.1' command file,
              Replacing 1.1 decrunch header with 2.2 header...
                (2.2 header is shorter and bugfree, 1.1 isn't !!)
              No need to recrunch 'PowerPacker 2.0' command file,
              Replacing 2.0 decrunch header with 2.2 header...
                (There was still a small bug in 2.0 header, so replace it.)
              Not crunched with one of the supported crunchers !!
                (Or file isn't crunched at all !)
              Sorry, can't recrunch !
                (Please don't sue me :-)

Process :     Sorry, can't process file !
                (File is probably not a command file)
              Can't crunch file !
                (File contains unsupported hunks)

Script :      Script buffer full !! Please stop recording.
                (Script is limited to 80 commands, select 'Stop Recording')

5. A Sample Session
-------------------

     Now that I have explained the PowerPacker's capabilities, it's time for
a little demonstation.  Let's say we want to crunch the 'CLI' command in the
System directory on your Workbench 1.2 disk.

     Select 'Pointer' in the Prefs/Decrunch Color menu (When I wrote this
text, it was very late and I couldn't stand the other decrunch colors
anymore !)

     Set 'Prefs' to 'Command file'.  Now select 'Load' in the Project menu
(a file requester will appear), insert your WorkBench 1.2 disk and choose the
'CLI' command in the system directory.  Now you'll see a lot of hunk
information about the CLI command:

                                                                             
     Loading command file 'df0:System/CLI'...                                
                                                                             
     Hunk_header (0x03F3)                                                    
        9 hunks (0 to 8).                                                    
     Hunk  0 : Hunk_code (0x03E9)     (524 bytes)                            
               Hunk_reloc32 (0x03EC)                                         
     Hunk  1 : Hunk_data (0x03EA)     (428 bytes, 0 BSS)                     
     Hunk  2 : Hunk_code (0x03E9)     (472 bytes)                            
               Hunk_reloc32 (0x03EC)                                         
     Hunk  3 : Hunk_data (0x03EA)     (52 bytes, 0 BSS)                      
     Hunk  4 : Hunk_code (0x03E9)     (16 bytes)                             
     Hunk  5 : Hunk_code (0x03E9)     (0 bytes)                              
     Hunk  6 : Hunk_code (0x03E9)     (196 bytes)                            
               Hunk_reloc32 (0x03EC)                                         
     Hunk  7 : Hunk_code (0x03E9)     (68 bytes)                             
               Hunk_reloc32 (0x03EC)                                         
     Hunk  8 : Hunk_data (0x03EA)     (0 bytes, 0 BSS)                       
                                                                             
     Crunching command file...                                                  
     Press left and right button to abort.                                   
     Crunching, please wait.                                                 


     The cruncher displays the percentage of the file already crunched and
the gain so far. After some time your screen will look like this:

                                                                             
     100% crunched.                                                          
     Done.                                                                   
     Original length : 2356 bytes.                                           
     Crunched length : 1204 (1776) bytes.                                    
     Gained 49% (1152 bytes) !                                               


     The only thing you have to do now is save this back to disk as an
executable file.  Now enjoy the crunched CLI command.


6. PowerPacker 2.2a & the CLI
-----------------------------

     For your convenience, I have also written two CLI commands, one to
crunch and one to decrunch.
     Attention:  These commands only (de)crunch DATA files !!!!  (So to
crunch executable files, you'll still have to use the PowerPacker 2.2a).
     A usage line is given by typing 'Crunch' or 'Decrunch' without
arguments.  You'll get something like this:

1>
1> crunch
POWER-PACKER 2.2a Data Cruncher.
  Written by Nico François (POWER PEAK)
USAGE : Crunch <source> <destination> [efficiency (1-5) default 3] [P] [F]
        Where P stands for no percentage, F for Forbid() crunching.
1>
1> decrunch
POWER-PACKER 2.2a Data Decruncher.
  Written by Nico François (POWER PEAK)
USAGE : Decrunch <source> <destination> [decrunch color (0-4)]
   With decrunch color 0/1 -> Color 0/1, 2 -> Pointer, 3 -> Scroll, 4 -> None
   If <destination> is a * the file will be typed to Output().
1>

     These commands are useful to be included in your startup-sequence or to
read crunched text files quickly.

     I don't think these commands need any further explanation.  They work
just like the CLI Copy command.  Just try them out and you'll see what
happens.  E.g. when you have a crunched source file of a program on your
disk, typing

     Decrunch filename.c *

will display the file as if you were using the 'Type' command for textfiles.

                                                   Enjoy !!!


                              PROGRAM HISTORY:

*****************************************************************************
VERSION 1.0a

     First release.

*****************************************************************************
VERSION 1.1a

     Fixed bugs.
     Improved crunch algorithm by about 5%.
     'Delete' and 'Multitask' added.
     Better menu structure.
     Improved the file requester.
     Written CLI commands.

*****************************************************************************
VERSION 2.0a

     Fixed some more bugs.
     Added buffer and automatic device-list to the file requester.
     Added 'LED Crunch', useful for turning the monitor off while crunching,
     and 'Paging'.
     New header, bug fixed. (1.1 didn't free mem when started from WorkBench)
     Added the hunklab.
     Improved CLI commands.

*****************************************************************************
VERSION 2.1a

     Fixed last bug in header (2.0 crashed when you were out of memory, oops)
     Added script feature, now possible to crunch files overnight.
     Improved requesters.
     Automatic crunch/decrunch.
     Improved menu structure considerably.
     Intelligent recrunch implemented.
     Automatic crunch/decrunch.
     Added 'Color Crunch' option.
     New efficiency 'Best' added.

*****************************************************************************
VERSION 2.1b

     Bug fixed in script abort.
     Added ability to open a log file during script execute.
     Now possible to recrunch PowerPacker files with a higher efficiency.
     Recrunch detects unsupported crunchers a lot faster.
     The PowerPacker now automatically opens a PAL/NTSC screen.

*****************************************************************************
VERSION 2.2a

     All known bugs (or better, undocumented features) fixed.
     'Sleep' mode implemented, useful for multitasking freaks.
     While crunching the gain percentage so far is displayed.
     Recrunch now supports 'HQC Cruncher 2.0', 'MasterCruncher 3.0'
       and 'Dragpack 1.0'.
     New graphics in title.

*****************************************************************************


P.S. This text file crunches to 42% of it's original length. (Gains 58% !)

The PowerPacker 2.2a written by Nico François. (Yes, Nico is my first name)
Special thanks to Pauwels Luc for the icons and writing the 2.0a manual,
                  Tybergein Jorrit for the extensive debugging.

(c) 1989 Nico François / Power Peak

                                   //
                       Thanks to \X/ Amiga for being the best computer ever !