home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 298.lha / PowerPacker_v2.3b / packer.doc < prev    next >
Text File  |  1980-11-30  |  36KB  |  800 lines
  1.  
  2.  
  3.  
  4.                         Power Packer 2.3b User Manual
  5.  
  6.                                 Sep 14, 1989
  7.  
  8.  
  9.  
  10. Preface
  11. =======
  12.  
  13.      Congratulations, you have just obtained a copy of PowerPacker 2.3b,
  14. PowerPeak's command and data cruncher for the Amiga.  If you have suggestions
  15. or remarks about this program, or if you find any bugs, please let me know.
  16.      This version of PowerPacker is shareware, this means that if you use it
  17. a lot I would appreciate it if you'd send me a contribution of $10 US or the
  18. same amount in any other currency.  This money will enable me to produce more
  19. programs on the Amiga.  If you send $15 US ($20 US overseas) I will send you
  20. the latest version of PowerPacker.  Please send money by international money
  21. order, EuroCheck (in Belgian Francs (BF) !!!!!) or cash, it's difficult for
  22. me to cash in other checks.  If you send for an update please state your
  23. current version, if there is no higher version at the time I get your letter
  24. I won't reply until I finish the next version, so don't be alarmed if it
  25. takes a while !
  26.      If  you want to use PowerPacker for commercial purposes you need written
  27. permission.
  28.  
  29.      Write to the following address:
  30.  
  31.                                 Nico François
  32.                                 Corbielaan 13
  33.                              3060 Bertem BELGIUM
  34.  
  35.  
  36. Contents
  37. ========
  38.  
  39. 1. The Packer
  40.      1.1 An introduction
  41.      1.2 The file requester
  42.      1.3 The basic menus
  43.           1.3.1 Project
  44.           1.3.2 Prefs
  45.           1.3.3 Crypt
  46.  
  47. 2. Recrunch
  48.      2.1 How ?
  49.      2.2 Why ?
  50.  
  51. 3. The HunkLab
  52.      3.1 Preferences
  53.      3.2 Process file
  54.  
  55. 4. The Script Menu
  56.  
  57. 5. The Supervisor Window
  58.  
  59. 6. A Sample Session
  60.  
  61. 7. PowerPacker 2.3b & the CLI
  62.  
  63. 8. PowerPacker 2.3b & other programs
  64.      8.1 Introduction
  65.      8.2 The function
  66.      8.3 Loading encrypted files
  67.      8.4 Compiling and linking
  68.      8.4 An example
  69.  
  70.  
  71. 1. The Packer
  72. -------------
  73.  
  74. 1.1 An introduction
  75.  
  76.      PowerPacker is a userfriendly command and data cruncher, this means a
  77. menu driven utility that can crunch almost any file on your disks.  It can be
  78. started from the CLI or the WorkBench, just type it's name in the CLI window
  79. or doubleclick it's icon.  PowerPacker will detach itself from the CLI so you
  80. can close the CLI window.  When you use it for the first time it's best to
  81. maintain a certain order in your actions (as we will see in chapter 6 of this
  82. document):
  83.  
  84.   (a) Check the packer options at the beginning of a session (Prefs menu)
  85.   (b) Load the file from disk (Project menu)
  86.   (c) Wait for the file to (de)crunch.
  87.   (d) Save the file back to disk (Project menu)
  88.  
  89.      Apart from crunching, you can also recrunch files that were crunched by
  90. most other crunchers.
  91.      The HunkLab enables you to e.g. force code or data in chip ram.
  92.      The script allows you to e.g. crunch a dozen of files overnight.
  93.  
  94.      Before I demonstrate how to use PowerPacker, let's look at the file
  95. requester and a brief overview of the menus and capabilities.
  96.  
  97.  
  98. 1.2 The file requester
  99.  
  100.     Whenever you are required to enter a filename, the packer sets up a file
  101. requester.  This requester automatically contains all devices connected to
  102. your Amiga and lists all the files (and their length) of a selected
  103. directory.  You don't have to wait for the directory read to end.  You can
  104. select a file or directory the moment you see it, or you can enter it in the
  105. appropriate string gadget.
  106.     However, if you wait for the directory read to end and quit the file
  107. requester, the next time you use it all the files will still be there, so you
  108. don't have to wait for the directory to be read again (This is very useful
  109. when you are recording a script, as you'll see later).  This feature has one
  110. disadvantage :  if files are changed or added to the selected directory they
  111. won't be shown in the list, or they will be shown with the wrong filelength,
  112. the next time the requester appears.  Therefore, if you think anything has
  113. been changed to the selected directory, use the 'GET DIR' gadget to re-read
  114. the directory.  (E.g.  when you save a crunched file on top of the old one,
  115. the old file length will be shown in the requester.)
  116.      When the 'Sort Files' switch in the prefs menu is checked the files will
  117. be alphabetically sorted in the requester.  This switch is present because
  118. some people don't like the files being sorted and jumping up and down the
  119. requester, they think it's annoying to try and catch the file you want. (and
  120. they are right of course :-)
  121.  
  122.  
  123. 1.3 The basic menus
  124.  
  125. 1.3.1 Project
  126.  
  127.     The project menu contains the file manipulation options.  Most of them
  128. speak for themselves:
  129.  
  130.   Load      ->  Load a file from disk and start the (de)crunching.
  131.   Save      ->  Save the (de)crunched or processed file in memory to disk.
  132.   Delete    ->  Delete a file from disk.
  133.   WorkBench ->  Open or close WorkBench if possible. (Adds 42K !)
  134.   Sleep     ->  Put PowerPacker to sleep on the WorkBench Screen, this
  135.                 frees 40-50K.
  136.                 WARNING: All buffers will be deallocated, so you are advised
  137.                          to save things first.
  138.   About...  ->  Show general information and my address.
  139.   Quit      ->  Quit the program.
  140.  
  141. 1.3.2 Prefs
  142.  
  143.      The prefs menu contains all the (de)cruncher settings.  You can select
  144. to (de)crunch command files or a data files.  If you want the crunched
  145. version of your file to be executable, select 'Command file'.  Now
  146. PowerPacker knows it has to add a decrunch header (572 bytes).  If the file
  147. you want to crunch only contains data (e.g. source codes of your programs),
  148. select the 'Data file' option.  This can be handy if you're going to use the
  149. PowerPacker CLI commands.  I'll discuss these commands in chapter 7 of this
  150. document.  Finally you have to choose whether you want to crunch or decrunch
  151. the load file.
  152.  
  153. NOTE: - PowerPacker will automatically decrunch a previously crunched
  154.         file.  You don't have to select crunch or decrunch mode anymore as
  155.         in PowerPacker 2.0a.
  156.  
  157.      The 'Decrunch Color' submenu contains the following options :
  158.  
  159.   Color 0   ->  The background color will change while decrunching
  160.   Color 1   ->  The text color changes
  161.   Pointer   ->  Only the mousepointer's color changes
  162.   Scroll    ->  Handy for decrunching a demo (just try it out !)
  163.   None      ->  If your eyes are wearing out.
  164.  
  165.      These options indicate what color will flash when a file is decrunched.
  166. You can change this option before saving a crunched file, so you can save a
  167. version of your crunched program that flashes in color 1, and one that
  168. flashes in the mouse pointer.  The default value is 'Pointer'.
  169.  
  170.      In the efficiency submenu you will find the following possibilities :
  171.  
  172.   Fast      ->  Use for small files, or for quick crunch.
  173.   Mediocre  ->  Better but slower.
  174.   Good      ->  Default, gains 40-50% in most cases.
  175.   Very Good ->  Also very slow !
  176.   Best      ->  Advised for script use only, ultra slow !!!
  177.  
  178. NOTE: - 'Fast' is approx. 4 times faster than 'Good', 'Very Good' is
  179.         2 times slower and 'Best' 4 times.
  180.       - 'Best' isn't always the best.  Small files crunch best with
  181.         'Very Good' or even 'Good'.
  182.  
  183.      The remaining preference switches:
  184.  
  185.   Data suffix  -> Attach '.pp' suffix to data files after crunching or remove
  186.                   '.pp' after decrunching.  It is advised that you leave this
  187.                   switch on so you can easily spot crunched data files.
  188.   Encrypt Data -> See section 1.3.3 of this manual.
  189.   Color Crunch -> Flash the selected decrunch color when crunching, giving
  190.                   you an idea what the decrunching will look like (provided
  191.                   that you don't change any options just before saving to
  192.                   disk).
  193.   LED Crunch   -> Your power-LED flashes while crunching, just like the
  194.                   screencolors. Now, you can even turn off your monitor and
  195.                   still see when the cruncher has finished.
  196.   Multitask    -> Switch multitasking off to (sligtly) increase the crunching
  197.                   speed.
  198.   Paging       -> Pause and wait for mouse button when supervisor window
  199.                   fills up.
  200.   Overwrite    -> Don't prompt if it's ok to overwrite a file when saving.
  201.   Verify sleep -> When this switch is on you will be prompted if you are sure
  202.                   you want PowerPacker to go to sleep.
  203.   Sort files   -> Sort files in file requester.
  204.  
  205.      Use 'Save prefs' to save the preferences to your boot disk.  The
  206. preferences will be saved in the file 's:PowerPacker.prefs', this file will
  207. be enormous, euh, 6 bytes big.  When PowerPacker 2.3b is first started it
  208. will attempt to load this file and adjust the preferences.
  209.  
  210. NOTE: - While crunching, you can press both mousebuttons at the same
  211.         time to abort.
  212.       - Do *NOT* change disks when you are crunching with the multitasking
  213.         switched off !!!  The Amiga will crash !!!
  214.  
  215. 1.3.3 Crypt
  216.  
  217.      When the 'Encrypt Data' switch is on PowerPacker will not only crunch
  218. data files, it will also encrypt them so nobody else but you can decrunch
  219. them.  Just before crunching a data file PowerPacker will ask you for a
  220. password.  You will be presented with a string gadget with a special feature,
  221. it won't show you what you are typing !  After entering your password you
  222. will be asked to enter it again, this is done to verify that you haven't made
  223. a typing error (unless you make the same error twice :-).
  224.      You can also use the 'Last' gadget to re-enter your last password again,
  225. or the 'Abort' gadget to abort the encryption and just crunch the file.
  226.      When you try to load a crunched encrypted data file PowerPacker will
  227. once again prompt you for your password.  If you enter the correct one the
  228. data file will be decrypted and decrunched.  If you don't know the password,
  229. bad luck, there is no way you can decrunch this file !!
  230.  
  231. NOTE: - Encryption can currently not be used in a script.
  232.       - Your password can be up to 16 characters long, any character is
  233.         accepted, lowercase and uppercase are DIFFERENT !!!!
  234.       - Take care when using the 'Last' gadget, be sure to know what your
  235.         last password was.
  236.       - Don't forget your password !!  It is *IMPOSSIBLE* to decrypt a file
  237.         without the password !!!!!
  238.  
  239.  
  240. 2. Recrunch
  241. -----------
  242.  
  243. 2.1 How ?
  244.  
  245.      This menu is provided for the people who were using another cruncher or
  246. an older version of PowerPacker.  Just select 'Recrunch File' or 'Decrunch
  247. Only' and load the file.  PowerPacker will start the correct decrunch
  248. algorithm.  If you selected 'Recrunch' PowerPacker will start to crunch the
  249. decrunched file.  If PowerPacker doesn't recognize the cruncher it will say
  250. so, no harm is done.  If you select 'Recrunch Always' PowerPacker will always
  251. recrunch, even if the file was crunched with this version of PowerPacker.
  252. Useful for recrunching files using a higher efficiency.  (e.g. recrunch a
  253. 'Fast' crunched file with 'Best')
  254.      Use the 'Change Color' item to change the decrunch color in an already
  255. crunched file to the current decrunch color.  Please note that the file will
  256. be changed on disk, nothing will be loaded into memory.
  257.      Crunchers currently supported are:  'ANC Cruncher', 'TNM Cruncher 1.1',
  258. 'Relokit 1.0', 'HQC Cruncher 2.0', 'MasterCruncher 3.0', 'DragPack 1.0' and
  259. older PowerPacker files.  If you'd like to see other crunchers supported,
  260. send me the cruncher and some programs crunched with it.  (Together with a
  261. contribution I hope).  If it is possible to develop a decrunch algorithm I
  262. will include it in the next version of PowerPacker.
  263.  
  264. 2.2 Why ?
  265.  
  266.      PowerPacker always crunches better than the 'ANC Cruncher', 'TNM
  267. Cruncher' and 'HQC Cruncher'.  It crunches better than 'Relokit' most of the
  268. time, but even if it doesn't, I advise you to recrunch because 'Relokit' has
  269. some serious disadvantages (e.g. while the decrunched file is running, the
  270. crunched version still eats memory).  In contrast PowerPacker only eats about
  271. 530 bytes while your file is running, and (of course) frees it afterwards.
  272.  
  273. NOTE: - If you want to recrunch a PowerPacker 1.1 or 2.0 crunched file,
  274.         PowerPacker just replaces the file header with the improved and
  275.         debugged 2.1+ header. (Unless you've selected 'Recrunch Always')
  276.       - The recrunch menu only supports command files !  You can't recrunch
  277.         data files from e.g. PowerPacker 1.1, sorry.
  278.       - 'Decrunch Only' is not 100% guaranteed for 'Relokit 1.0' files,
  279.         'Recrunch' however is 100% ok ! (It's a strange world ! :-)
  280.       - Several people sent me 'dirty' crunchers, these are crunchers that
  281.         use absolute addresses (an absolute TABOO !!!).  It is impossible
  282.         to develop a decrunch algorithm for these.  (In fact, nothing should
  283.         have been crunched with these crunchers in the first place !)
  284.  
  285.  
  286. 3. The Hunklab
  287. --------------
  288.  
  289. 3.1 Preferences
  290.  
  291.      This menu is not really part of the PowerPacker crunch/decrunch routines
  292. but it wasn't worth writing a separate program for and a HunkLab is after all
  293. a very interesting utility.  You can e.g. use it to remove symbol and debug
  294. hunks from files that wouldn't crunch otherwise.
  295.  
  296.      You can force a program's code, data or BSS (uninitialised data) into
  297. chip ram or you can remove symbol tables and debug information just by
  298. toggling the marker on/off.  So in future, when you want your programs to be
  299. able to run on a one megabyte system, a simple click on the mousebutton will
  300. do.
  301.  
  302. 3.2 Process file
  303.  
  304.      'Process file' reads the file from disk and changes it according to your
  305. preferences.  To save the processed file, use 'Save' from the Project menu.
  306.      'Process & Crunch' will process the file and crunch the file afterwards
  307. (if possible).  To save use 'Save' in the Project menu.
  308.  
  309. NOTE: - Debug and symbol hunks are only used in debuggers, so you can safely
  310.         remove them from a program. (Unless you want to debug the program.)
  311.  
  312.  
  313. 4. The Script Menu
  314. ------------------
  315.  
  316.      The script is something that will save you a lot of time, it allows you
  317. to record 80 different commands to be executed after each other.  It is ideal
  318. for crunching a lot of files overnight.  Menu options are:
  319.  
  320.      'Clear Script' and 'List Script':
  321.           will do just that.
  322.      'Script Log File':
  323.           is used to specify a file to redirect output to.  If you cancel
  324.           the requester no log file is used.
  325.      'Destination Dir':
  326.           is used to specify the directory to save to.  It is ghosted in
  327.           normal use.
  328.      'Start Recording':
  329.           is used to start the recording of the script. If the script was
  330.           empty you will be asked for the destination directory.
  331.               After selecting the destination you can start entering the
  332.           script commands.  Everything that is ghosted is not available as a
  333.           command.  Just enter everything as if you were actually using
  334.           PowerPacker.  When you e.g. choose 'Load' PowerPacker will ask a
  335.           list of files to be (de)crunched. Press 'CANCEL' to exit the
  336.           entry.
  337.           NOTE: - You can still change the source and destination dir while
  338.                   recording.
  339.           Every command you enter will be displayed in the supervisor window.
  340.      'Stop Recording':
  341.           is used to exit the recording mode.
  342.      'Delete Last':
  343.           will delete the last command after a confirmation.
  344.      'Execute Script':
  345.           will start the playback of the script commands.  You will be asked
  346.           if you want files that are already crunched with PowerPacker to be
  347.           skipped.  This way you can select all the files in a directory
  348.           without worrying about crunched files being decrunched.
  349.               If you press the menu button a requester will appear to ask you
  350.           if you want to abort the script execution.  After executing the
  351.           script a request to clear the script will appear.
  352.  
  353. NOTE: - It is advisable to let the filerequester buffer fill before you
  354.         start selecting files.  It is also better not to change the source
  355.         directory too often.
  356.       - The screen turns grey to indicate a script is executing.
  357.       - While executing a script, PowerPacker will always act destructive !
  358.         Files will allways be overwritten and deleted !!!
  359.  
  360.  
  361. 5. The Supervisor Window
  362. ------------------------
  363.  
  364.      This window displays all kind of useful information like the file
  365. status, crunch messages, and error messages.  You can follow all steps, from
  366. the original file that is loaded into memory, to the final crunched version
  367. on disk.  When an executable file is loaded, its hunk information is
  368. displayed.  This information is rather technical, but it can be useful for
  369. programmers.  If you're not interested, just ignore it.
  370.  
  371.      I think it might be useful to give a list of possible error messages:
  372.  
  373. (De)crunch :  Buffer overflow !
  374.                 (Crunched file is getting longer than original file)
  375.               Crunch aborted !
  376.                 (Crunching stopped by user or by buffer overflow)
  377.               No memory for decrunch buffer !
  378.               Out of memory !
  379.                 (Buy some more, try selling your WorkBench :-)
  380.               Sorry, can't crunch !
  381.                 (This is a polite program)
  382.               Can't find hunk_header.
  383.               Hunk not allowed in load file!
  384.               Unknown Hunk !
  385.                 (Not a command file)
  386.               Hunk not supported (yet ?) !
  387.                 (If it's a symbol or debug hunk, try removing it in HunkLab)
  388.               Nothing to save !
  389.                 (Buffer is empty)
  390.               Save Aborted !
  391.               Error reading file !
  392.               Can't open file !
  393.               Error writing data header !
  394.               Error writing buffer !
  395.               File not found !
  396.               Couldn't delete file !
  397.               Can't open file !
  398.                 (Disk errors)
  399.  
  400. Recrunch :    No need to recrunch 'PowerPacker 1.1' command file,
  401.               Replacing 1.1 decrunch header with 2.3 header...
  402.                 (2.1+ header is shorter and bugfree, 1.1 isn't !!)
  403.               No need to recrunch 'PowerPacker 2.0' command file,
  404.               Replacing 2.0 decrunch header with 2.3 header...
  405.                 (There was still a small bug in 2.0 header, so replace it.)
  406.               Not crunched with one of the supported crunchers !!
  407.                 (Or file isn't crunched at all !)
  408.               Sorry, can't recrunch !
  409.                 (Please don't sue me :-)
  410.  
  411. Process :     Sorry, can't process file !
  412.                 (File is probably not a command file)
  413.               Can't crunch file !
  414.                 (File contains unsupported hunks)
  415.  
  416. Script :      Script buffer full !! Please stop recording.
  417.                 (Script is limited to 80 commands, select 'Stop Recording')
  418.  
  419.  
  420. 6. A Sample Session
  421. -------------------
  422.  
  423.      Now that I have explained PowerPacker's capabilities, it's time for
  424. a little demonstation.  Let's say we want to crunch the 'CLI' command in the
  425. System directory on your Workbench 1.2 disk.
  426.  
  427.      Select 'Pointer' in the Prefs/Decrunch Color menu (When I wrote this
  428. text, it was very late and I couldn't stand the other decrunch colors
  429. anymore !)
  430.  
  431.      Set 'Prefs' to 'Command file'.  Now select 'Load' in the Project menu
  432. (the file requester will appear), insert your WorkBench 1.2 disk and choose
  433. the 'CLI' command in the system directory.  Now you'll see a lot of hunk
  434. (or junk ?? :-) information about the CLI command:
  435.  
  436.                                                                              
  437.      Scanning file 'df0:System/CLI'...                                       
  438.      Loading command file...                                                 
  439.                                                                              
  440.      Hunk_header (0x03F3)                                                    
  441.         9 hunks (0 to 8).                                                    
  442.      Hunk  0 : Hunk_code (0x03E9)     (524 bytes)                            
  443.                Hunk_reloc32 (0x03EC)                                         
  444.      Hunk  1 : Hunk_data (0x03EA)     (428 bytes, 0 BSS)                     
  445.      Hunk  2 : Hunk_code (0x03E9)     (472 bytes)                            
  446.                Hunk_reloc32 (0x03EC)                                         
  447.      Hunk  3 : Hunk_data (0x03EA)     (52 bytes, 0 BSS)                      
  448.      Hunk  4 : Hunk_code (0x03E9)     (16 bytes)                             
  449.      Hunk  5 : Hunk_code (0x03E9)     (0 bytes)                              
  450.      Hunk  6 : Hunk_code (0x03E9)     (196 bytes)                            
  451.                Hunk_reloc32 (0x03EC)                                         
  452.      Hunk  7 : Hunk_code (0x03E9)     (68 bytes)                             
  453.                Hunk_reloc32 (0x03EC)                                         
  454.      Hunk  8 : Hunk_data (0x03EA)     (0 bytes, 0 BSS)                       
  455.                                                                              
  456.      Crunching command file...                                               
  457.      Press left and right button to abort.                                   
  458.      Crunching, please wait.                                                 
  459.                                                                              
  461.      The cruncher displays the percentage of the file already crunched and
  462. the gain so far. After some time your screen will look like this:
  463.  
  464.                                                                              
  465.      100% crunched.                                                          
  466.      Done.                                                                   
  467.      Original length : 2356 bytes.                                           
  468.      Crunched length : 1204 (1776) bytes.                                    
  469.      Gained 49% (1152 bytes) !                                               
  470.                                                                              
  472.      The only thing you have to do now is save this back to disk as an
  473. executable file.  Now enjoy the crunched CLI command.
  474.  
  475.  
  476. 7. PowerPacker 2.3b & the CLI
  477. -----------------------------
  478.  
  479.      For your convenience, I have also written two CLI commands, one to
  480. crunch and one to decrunch data files.
  481.      From version 2.3 onwards the CLI commands use the magnificent ARP
  482. library !!!  This means they have been greatly enhanced:  wildcards are fully
  483. supported, options can be entered in any order, directories will be created
  484. when needed, etc...  Make sure the arp.library is in your LIBS:  directory
  485. when you run these commands.
  486.      A usage line is given by typing 'Crunch' or 'Decrunch' without
  487. arguments.  You'll get something like this:
  488. _____________________________________________________________________________
  489.  
  490. 1> Crunch
  491. POWER-PACKER 2.3a Data Cruncher.
  492.   Written by Nico François (POWER PEAK)
  493. Usage : Crunch <source> <destination> [EFFICIENCY 1-5] [COLOR 0-4] [CRYPT]
  494.                                       [NOSUFF] [NOLED] [FORBID] [NOPER]
  495. With:
  496.   EFFICIENCY: 1 = Fast, 2 = Mediocre, 3 = Good (def), 4 = Very Good, 5 = Best
  497.   COLOR     : 0/1 = Color 0/1, 2 = Pointer (def), 3 = Scroll, 4 = None
  498.   CRYPT     : Encrypt file.
  499.   NOSUFFIX  : Don't attach '.pp' suffix to filename.
  500.   NOPER     : Don't print percentage.
  501.   NOLED     : Disable led crunch.
  502. Hit ^C to abort, ^D to abort crunching only.
  503.  
  504. 1> Decrunch
  505. POWER-PACKER 2.3a Data Decruncher.
  506.   Written by Nico François (POWER PEAK)
  507. Usage : Decrunch <source> <destination> [COLOR 0-4] [OPT B|F] [SKIP] [QUIET]
  508. With:
  509.    COLOR: 0/1 = Color 0/1, 2 = Pointer (def), 3 = Scroll, 4 = None
  510.    SKIP : Skip uncrunched files.
  511.    QUIET: Be quiet.
  512. If <destination> is '*' or is omited, files will be typed to Output().
  513. Options effective when typing:
  514.    OPT B will print a banner before and
  515.    OPT F will print a formfeed after each file.
  516. Hit ^C to abort, ^D to abort typing only.
  517.  
  518. 1>
  519. _____________________________________________________________________________
  520.  
  521.      These commands are useful to be included in your startup-sequence or to
  522. read crunched text files quickly.
  523.  
  524.   Some examples:
  525.  
  526.      Crunch df0:source/*.c TO ram:source COL 4 NOLED
  527.  
  528.      This will result in a crunching of every C program in the df0:source
  529. directory.  If the ram:source directory exists the files will be saved there,
  530. if it doesn't it will be created if there is more than one C program in
  531. df0:source.  The '.pp' suffix will be attached to the filenames.  The led
  532. will not flicker, no crunch color is used.
  533.  
  534.      Decrunch >PRT: QUIET dh0:progs/*.asm.pp OPT BF COL 3
  535.  
  536.      Every crunched assembler program will be decrunched and printed, before
  537. each file a banner will be printed, each file will start on a new page.  If
  538. the file is encrypted you will be prompted for a password.  It is very
  539. important that you use the QUIET option here, if you don't the copyright and
  540. information lines will also be printed.  The mouse pointer will flash while
  541. decrunching.
  542.  
  543. NOTE: - These commands only (de)crunch DATA files !!!!  (So to (de)crunch
  544.         executable files, you'll still have to use PowerPacker 2.3b).
  545.  
  546.  
  547. 8. PowerPacker 2.3b & other programs
  548. ------------------------------------
  549.  
  550. 8.1 Introduction
  551.  
  552.      This one is for the programmers among you !
  553.      From release 2.3 onwards the decrunch source is included.  I decided to
  554. do this so other programs could load data files crunched with PowerPacker.
  555. As an example I could refer to one of my other utilities : PPMore, this is a
  556. text viewing utility (like more, hence the name) that can also display ASCII
  557. files crunched with PowerPacker.
  558.      Source is presented as a support function 'PP_LoadData', this function
  559. will load a data file and will decrunch it if necessary.  When the file isn't
  560. crunched it'll just be loaded.  Encrypted files are also supported.
  561.      The source was written for Aztec C 3.6a.  If you want to compile it with
  562. Lattice you will have to seperate C and assembler, compile/assemble them
  563. separatly and link them together.  You can use this code for non-commercial
  564. programs as long as you leave my copyright notice intact.
  565.  
  566. 8.2 The function
  567. _____________________________________________________________________________
  568.  
  569.   error = PP_LoadData (file, color, typeofmem, buffptr, lengthptr, password);
  570.  
  571.   with:
  572.      char *file;         filename of file to be loaded
  573.      UBYTE color;        decrunch color (see ppdata.h)
  574.      ULONG typeofmem;    type of memory to be allocated
  575.      UBYTE **buffptr;    address of buffer pointer variable
  576.      ULONG *lengthptr;   address of length variable
  577.      char *password;     pointer to password string or NULL
  578.  
  579.   Note:
  580.      - error and color codes are defined in <ppdata.h>.
  581.      - memory must be freed by caller after usage : FreeMem (buff, length);
  582. _____________________________________________________________________________
  583.  
  584.      You have the following decrunch colors available:
  585.  
  586.           DECR_COL0      Decrunch in color 0
  587.           DECR_COL1         ''    '' color 1
  588.           DECR_POINTER      ''    '' the mouse pointer
  589.           DECR_SCROLL       ''    '' the scroll register
  590.           DECR_NONE      No decrunch color is used
  591.  
  592.      The following errors can occure:
  593.  
  594.           PP_LOADOK      No error, file loaded succesfully.
  595.           PP_LOCKERR     Couldn't lock file, file probably doesn't exist.
  596.           PP_OPENERR     Couldn't open file.
  597.           PP_READERR     Read error.
  598.           PP_NOMEMORY    No memory to allocate buffer for data file.
  599.           PP_CRYPTED     File is crypted and no password was provided.
  600.           PP_PASSERR     File is crypted and wrong password provided.
  601.  
  602. 8.3 Loading encrypted files
  603.  
  604.      To load encrypted files a password has to be provided to the function.
  605. First of all try to load the file with a NULL pointer for 'password', when
  606. you get the PP_CRYPTED error you know that the file is encrypted.  Then
  607. prompt the user for a password and call the function again with the same
  608. parameters, but now 'password' points to the password string.  If PP_LoadData
  609. returns PP_LOADOK the file was decrypted, if it returns PP_PASSERR the
  610. password was incorrect.  If it returns anything else some sort of error
  611. occured (see <ppdata.h> for the error codes).
  612.  
  613. 8.4 Compiling and linking
  614.  
  615.      - If you use Aztec C you have one module to compile : ppdata.c
  616.  
  617.      cc [options] ppdata.c
  618.  
  619.      Use the same options you use in the other modules of your program.
  620. Compile the other modules of your program and link everything together:
  621.  
  622.      ln +q main.o ... ppdata.o -lc -o myprog
  623.  
  624.      - If you use Lattice C you will have to seperate the C source from the
  625. assembler source and compile/assemble them seperatly.  You will then get two
  626. object files.  When you then link everything together be sure to link with
  627. both these object files.  (I haven't tried it, but it should work)
  628.  
  629. 8.5 An example
  630.  
  631.      This small (incomplete) program shows you how to use the support
  632. function in your programs.
  633.  
  634. /*********
  635. * test.c *
  636. *********/
  637.  
  638. #include <exec/types.h>
  639. ...
  640. #include <ppdata.h>
  641.  
  642. UBYTE *buffer = NULL;
  643. ULONG bufferlength;
  644. UBYTE password[17];
  645.  
  646. main()
  647. {
  648.      int error;
  649.  
  650.      error = PP_LoadData ("df0:doc/Packer.doc.pp", DECR_POINTER, MEMF_PUBLIC,
  651.           &buffer, &bufferlength, NULL);     /* Don't forget the '&' !!!!! */
  652.      if (error != PP_LOADOK) switch (error) {
  653.           case PP_LOCKERR:
  654.                puts ("file not found !!!");
  655.                FreeStuffAndExit();
  656.           case PP_LOADERR:
  657.                puts ("loading error !!!");
  658.                FreeStuffAndExit();
  659.           case PP_NOMEMORY:
  660.                puts ("out of memory !!!");
  661.                FreeStuffAndExit();
  662.           ...
  663.           case PP_CRYPTED:
  664.                /* prompt the user for a password (max 16 chars) */
  665.                ...
  666.                error = PP_LoadData ("df0:docs/Packer.doc.pp", DECR_POINTER,
  667.                     MEMF_PUBLIC, &buffer, &bufferlength, password);
  668.                if (error == PP_PASSERR) {
  669.                     puts ("incorrect password !!!");
  670.                     FreeStuffAndExit();
  671.                     }
  672.                else if (error != PP_LOADOK) {
  673.                     puts ("correct password, but couldn't load !!!");
  674.                     FreeStuffAndExit();
  675.                     }
  676.                break;
  677.           }
  678.      /* now do something with the data file loaded at addr 'buffer' and with
  679.         length 'bufferlength' */
  680.      ...
  681.      /* DO NOT FORGET TO FREE THE MEMORY !! */
  682.      FreeMem (buffer, bufferlength);
  683. }
  684.  
  685. FreeStuffAndExit()
  686. {
  687.      /* free all your resources */
  688.      ...
  689.      exit (0);
  690. }
  691.                                              Enjoy this program !!!
  692.  
  693.  
  694.                               PROGRAM HISTORY:
  695.  
  696. *****************************************************************************
  697. VERSION 1.0a
  698.  
  699.      First release.
  700.  
  701. *****************************************************************************
  702. VERSION 1.1a
  703.  
  704.      Fixed bugs.
  705.      Improved crunch algorithm by about 5%.
  706.      'Delete' and 'Multitask' added.
  707.      Better menu structure.
  708.      Improved the file requester.
  709.      Written CLI commands.
  710.  
  711. *****************************************************************************
  712. VERSION 2.0a
  713.  
  714.      Fixed some more bugs.
  715.      Added buffer and automatic device-list to the file requester.
  716.      Added 'LED Crunch', useful for turning the monitor off while crunching,
  717.      and 'Paging'.
  718.      New header, bug fixed. (1.1 didn't free mem when started from WorkBench)
  719.      Added the hunklab.
  720.      Improved CLI commands.
  721.  
  722. *****************************************************************************
  723. VERSION 2.1a
  724.  
  725.      Fixed last bug in header (2.0 crashed when you were out of memory, oops)
  726.      Added script feature, now possible to crunch files overnight.
  727.      Improved requesters.
  728.      Automatic crunch/decrunch.
  729.      Improved menu structure considerably.
  730.      Intelligent recrunch implemented.
  731.      Automatic crunch/decrunch.
  732.      Added 'Color Crunch' option.
  733.      New efficiency 'Best' added.
  734.  
  735. *****************************************************************************
  736. VERSION 2.1b
  737.  
  738.      Bug fixed in script abort.
  739.      Added ability to open a log file during script execution.
  740.      Now possible to recrunch PowerPacker files with a higher efficiency.
  741.      Recrunch detects unsupported crunchers a lot faster.
  742.      PowerPacker now automatically opens a PAL/NTSC screen.
  743.  
  744. *****************************************************************************
  745. VERSION 2.2a
  746.  
  747.      All known bugs (or better, undocumented features) fixed.
  748.      'Sleep' mode implemented, useful for multitasking freaks.
  749.      While crunching the gain percentage so far is displayed.
  750.      Recrunch now supports 'HQC Cruncher 2.0', 'MasterCruncher 3.0'
  751.        and 'Dragpack 1.0'.
  752.      New graphics in title.
  753.  
  754. *****************************************************************************
  755. VERSION 2.3a
  756.  
  757.      PowerPacker detaches itself from the CLI, so the CLI window can be
  758.        closed or used for other things.
  759.      CLI commands are greatly enhanced, they now use ARP.
  760.      New switch : 'Overwrite' to surpress 'OK to overwrite ?' request.
  761.      File requester now able to sort files, 'Sort files' switch.
  762.      By popular demand: encryption of data files is now possible using the
  763.        new 'Encrypt Data' switch. Encryption should be IMPOSSIBLE to crack !!
  764.      Also by popular demand: Now possible to save preferences to boot disk.
  765.      More memory efficient decrunch and recrunch of PowerPacker files.
  766.      Decrunch source included, so other programs could be written that
  767.        would load data files crunched with PowerPacker.
  768.      'Data Suffix' switch to improve adding/removing of '.pp' suffix.
  769.      Decrunch color default 'Pointer'.
  770.      Improved scanning of files when loading or recrunching.
  771.      Fixed small bug (version 2.2a lost 256 bytes every time it was run).
  772.      More info in about window.
  773.  
  774. *****************************************************************************
  775. VERSION 2.3b
  776.  
  777.      Added 'Change Color' in 'Recrunch' menu to change the decrunch color
  778.        of an already crunched file.
  779.      PowerPacker now starts up a process with priority -1.  It now no longer
  780.        slows down the rest of the system (e.g. a CLI) when crunching.
  781.      New 'Verify sleep' switch to toggle the requester that verifies the
  782.        sleep function on/off.
  783.      Now possible to skip files already crunched with PowerPacker in script.
  784.      Bug fixed in 'Recrunch', ANC files were no longer recognized. Oops :-)
  785.  
  786. *****************************************************************************
  787.  
  788. P.S. This text file crunches to 43% of it's original length. (Gains 57% !)
  789.  
  790. PowerPacker 2.3b written by Nico François (Yes, Nico is my first name :-)
  791. Special thanks go to - Luc Pauwels for the icons and writing the 2.0a manual,
  792.                      - Jorrit Tybergein for the extensive debugging,
  793.                      - everybody who mailed me suggestions or remarks.
  794.  
  795. (c) 1989 Nico François / Power Peak
  796.  
  797.                                    //
  798.                        Thanks to \X/ Amiga for being the best computer ever !
  799.  
  800.