home *** CD-ROM | disk | FTP | other *** search
/ C!T ROM 2 / ctrom_ii_b.zip / ctrom_ii_b / PROGRAM / PASCAL / TPLZH019 / TPLZH.DOC < prev    next >
Text File  |  1992-12-25  |  18KB  |  471 lines
  1. Merry Christmas everybody! (Almost)
  2. ***********************************************************************
  3. Latest Huffman hacker:  Joe Jared of 1:125/1212@Fidonet.ORG
  4.                         BBS (510) 834-6906 V.32bis/HST 8n1
  5. File request name    :  TPHUF or TPLZH (Magic names only please)
  6. Discription          : (V0.19ß) Huffman Compression Engine w/TP {$O+} interface.
  7.  
  8. α implies that there is a known bug
  9. ß implies that there are no known bugs.
  10.  
  11. Downloadable name    : TPLZH@##.SQZ where @ is the major release number and
  12.                        ## the minor release. The Squeeze-it compression
  13.                        utility is available by file request as SQZ.
  14.                        (Or download as SQZ*.EXE)
  15.  
  16. Topics:
  17. - HELP WANTED
  18. - What's new
  19. - Plans for the fidonet nodelist.
  20. - How to use this utility in your programs
  21. - Legalities and distribution
  22. - Version history: Refer to TPLZH.HST
  23.  
  24. ***********************************************************************
  25. - HELP WANTED  
  26.  
  27.   If you are fluent in another language other than Pascal, please send
  28.   a working unit that would make this engine portable to your language.
  29.   LZHASM.OBJ is a standard Microsoft assembler unit, and if necessary,
  30.   I can compile other variations to make it compatible with your
  31.   prefered language. There are now 2 versions of the assembler object
  32.   file.  LZHASM.OBJ uses pascal calls, and LZHASMC.OBJ uses C calls.
  33.  
  34.   Also, if someone would like to clean up documentation, that would be
  35.   appreciated too.
  36.  
  37. ***********************************************************************
  38.  
  39.  
  40. -New in current release:
  41.  
  42.         The following is a runtime comparison between TPLZH and the
  43.         all pascal version.  Basis of comparison is RA.DOC being
  44.         compressed by the 100% assembler version, which allocates
  45.         a good chunk of itself on the heap, vs. the All pascal version,
  46.         which only places its I/O buffers on the heap. (306k of text)
  47.  
  48.         These numbers were based on:
  49.  
  50.         (FinishtimePas - StarttimePas)/(FinishTimeAsm - StartTimeAsm)
  51.         Accuracy (+- 0.5%)
  52.         OS/2 Compatibility cannot be tested here, but the basis of the
  53.         compatibility has to do with whether or not the FS register is
  54.         used.
  55.  
  56. ***********************************************************************
  57.  
  58.         (HUFFCOMP) (In Streams.Pas) { Copyright D.J. Murdoch, (1992) }
  59.         Input size:                306368 bytes
  60.         Output size:               159706 bytes
  61.         Timings:
  62.         CPU        Compress     Decompress
  63.         386        64.7s        67.62s
  64.         286        222.89s      229.15s
  65.         8086       406.78       406.5s      
  66.  
  67.         Exe size:            12288 bytes
  68. ***********************************************************************
  69.         LHarc 1.13c (By Haruyasu YOSHIZAKI )
  70.         The original designer of huffman compression.
  71.  
  72.         Input size:                306368 bytes
  73.         Output size:               101671 bytes (incl file header info)
  74.         Timings:                            Encode      Decode
  75.         CPU        Compress     Decompress  Speed       Speed
  76.         386        26.15        8.02        468%        181%
  77.         286        85.47        23.78       535%        213%
  78.         8086      164.23        43.66       552%        224%
  79.  
  80. ***********************************************************************
  81.  
  82.         Input size:     306368 bytes
  83.         output size:    101639 bytes
  84.  
  85.                          Original           
  86.         Encode Time:    (LZHUFTP5)      (TPLZH)  
  87.         386             122.48           75.97
  88.         286             457.53          290.34
  89.         8086            907.1           500.87
  90.  
  91.         Decode time:
  92.         386             14.55           7.2
  93.         286             50.76           25.93
  94.         8086            97.93           46.58
  95.  
  96.         (Comparison based on LZHUFTP5 "Out of the box")
  97.         Speed          CPU        Encode       Decode   
  98.         33Mhz          386        161%         202%
  99.         8Mhz           286        158%         196%
  100.         8Mhz          8086        181%         210%
  101.  
  102. ***********************************************************************
  103.         V0.19ß (TPLZH019.SQZ)
  104.         Thanks to Andres Cvitkovich, 2:310/36.9@Fidonet.Org
  105.         for the Object oriented programming interface.
  106.  
  107.         Now, if you don't pre-fill the inputbuffer, the engine will do
  108.         it for you.
  109.  
  110.         Added LZHASMC.OBJ, which uses C Calling convention.
  111.         This has in no way been tested, and might be unnecessary. The
  112.         standard object LZHASM.OBJ should work for all languages.
  113.  
  114.         Basic compatibility issues:
  115.         Removed usage of underscores in all public variables.
  116.         Basic interface is in progress.
  117.  
  118. ***********************************************************************
  119. - Plans for the fidonet nodelist.
  120.  
  121.         Within the next week, there will be a second utility out, that
  122.         will supply the fidonet nodelist as follows:
  123.  
  124.  
  125.         Nodelist.LZ
  126.         Nodlist.LZX
  127.  
  128.         Regions.LZ
  129.         Regions.LZx
  130.  
  131.  
  132.         The structures for these files will be as follows:
  133.  
  134.  
  135.         Type
  136.             NetlistRec  = Record        {Nodelist.LZ}
  137.                         Zone,Net        : Word;
  138.                         NetPointer      : Longint;
  139.                         end;
  140.  
  141.             RegionRec   = Record
  142.                         Zone,Region     : Word;
  143.                         RegionPointer   : Longint;
  144.  
  145.  
  146.         Nodelist.LZ will have seperate segments for each net, which will
  147.         be pointed to by NetlistRec.Netpointer.  To find a specific net,
  148.         all one would have to do is search through the index, and then
  149.         find the appropriate Zone:Net match.
  150.  
  151.         To find an appropriate list of nets in either region or Zone,
  152.         you would use the Region.LZ and Region.LZx
  153.  
  154.         The source code will be provided as an example
  155.         implementation for your friendly neighborhood nodelist compiler.
  156.  
  157.         Although the compression part will be slow, I'm sure someone will
  158.         find a good use for this.  Perhaps even to create a nodediff
  159.         processer that works with the compressed files.  Here is one
  160.         proposal for handling of new nodediffs of a different format:
  161.  
  162.         1> Nodelist.LZ is never sorted. (For nodediff reasons)
  163.            Afer compilation, Nodelist.LZX and Region.LZX will be sorted
  164.            by region and net.
  165.  
  166.         2> All file comments or notes are 'assumed' to belong to the
  167.            current host.
  168.         3> As the nodediff is read in, each net is read into memory,
  169.            (Please use a filemode of 0, as I'm on a network <g>)
  170.  
  171.         4> CRC/LF/CR
  172.            Occurances of the following to be translated to CR/LF
  173.  
  174.            Amiga line feeds only
  175.            Macintosh style Carriage returns without linefeeds.
  176.  
  177.         5> (This and a dozen other spaces intentionally left invisible)
  178.  
  179.         6>  Processing of nodediffs:
  180.             Processing of nodediffs will have little difference between
  181.             how it's done now, and how it would be done on the fly.
  182.             2 procedures would be setup for reads and writes, and for the
  183.             read/modify/write cycle, modifications will be held in another
  184.             heap buffer. (2 allocations of LZHMemSeg^).
  185.             (Specifics to be worked out at a later date)
  186.  
  187.  
  188. ***********************************************************************
  189. - Implementation, and explaination of the interface to turbo pascal.
  190.   
  191.  
  192.   Memory requirements:
  193.          Since this is constantly updated, I wont update it again.
  194.          As of version 0.18ß, memory requirements are as follows:
  195.  
  196.          {$M 1024, 56000, 56000}
  197.          Codespace: 3123 bytes.
  198.          Dataspace: approximately 700 bytes.
  199.  
  200.          The stack is probably higher than necessary, but heap memory
  201.          is definately accurate.
  202.  
  203.          The engine uses approximately 1.2k of data seg as well, although
  204.          these too are 'thrown' onto the heap.
  205.  
  206.          This unit is overlayable.
  207.  
  208.  
  209.   The following system variables are available for your interface to play
  210.   with:
  211. Public    Decode, Encode   ; Encode for compression, Decode for decompression.
  212.  
  213. EXTERN   LZHMemSeg       : WORD      ; Heap pointer to LZH Structure.
  214. EXTERN     WriteFromBuffer : FAR PTR   ; External buffer handling.
  215. EXTERN     ReadToBuffer     : FAR PTR   ; External buffer handling.
  216. EXTERN   LZHERROR        : WORD      ; Errorlevel return {Future use}
  217.  
  218. (Offset into LZHMem^. allocation)
  219. count         equ 0                       ; LongInt = 0;
  220. textsize      Equ count +4                ; LongInt = 0;
  221. codesize      equ textsize +4             ; LongInt = 0;
  222. inptr         equ codesize +4
  223. inend         equ inptr+2   
  224. outptr        equ inend+2                 ; Word
  225. outend        equ outptr+2                ; Word
  226. Ebytes        equ outend+2                ; LongInt = 0;
  227. Inbuf         equ Ebytes+4                ; array[0..N] of word; 8194 bytes
  228. Outbuf        equ Inbuf +2800h            ; array[0..N] of word; 8194 bytes
  229.  
  230. type
  231.     
  232.   IObuf = array[0..$2800-1] of byte; {These buffers are now FIXED!}
  233.  
  234.   LZHRec = Record
  235.          count          : LongInt;
  236.          textsize       : LongInt;
  237.          codesize       : LongInt;
  238.          inptr,inend,outptr,outend    : Word;
  239.          Ebytes         : Longint;
  240.          inbuf,outbuf        : IObuf;
  241.          {Buffersize and position are critical}
  242.          WorkSpace           : Array [0..$8657] of byte;
  243.          {LZHASM work space}
  244.          End;
  245.  
  246.  {$L LZHASM}
  247.  
  248.     
  249.  
  250. var
  251.    StupidAlloc : Boolean;
  252.    StupidPtr    : Pointer;
  253.        These variable is to provide Segment:0 alignment for versions
  254.        of turbo Pascal prior to 6.0.  Refer to notes in InitLzh.
  255.     
  256.    WriteFromBuffer,
  257.    ReadToBuffer: Procedure;
  258.  
  259.    These variables should "point" to your procedures for reading and
  260.    writing of LZH compressed data.  Before calling any LZH Functions,
  261.    you must have the following lines of code in your routine, or some
  262.    function thereof:
  263.    {$F+}
  264.    Myprocwrite
  265.    {$F-}
  266.    begin
  267.    (Your procedure for handling data from LZHMem^.Inbuff)
  268.    end;
  269.  
  270.    Myprocread
  271.    {$F-}
  272.    begin
  273.    (Your procedure for handling data from LZHMem^.Outbuff)
  274.    end;
  275.  
  276.  
  277.    Your startup for your program should have:
  278.  
  279.    Myprocwrite := WriteFromBuffer  
  280.    Myprocread := ReadToBuffer
  281.  
  282.    The actual procedure type MUST be a far Call, but the data within
  283.    the procedure may be near.
  284.  
  285.   IObuf = array[0..$2800-1] of byte; {These buffers are now FIXED!}
  286.  
  287.   For your reference, preceed all variables with LZHMem^. as this
  288.   structure is of heap pointer type.
  289.  
  290.   LZHRec = Record
  291.          count          : LongInt;
  292.         Current position of compression of input data.  This counter
  293.         will continue to count, until you dinit and reinit the engine.
  294.  
  295.          textsize       : LongInt;
  296.          Size of input text data
  297.  
  298.          codesize       : LongInt;
  299.          Size of output code data.
  300.  
  301.         These variables are available to provide user interface for
  302.         ratios.  Since the assembler obj file is external to turbo
  303.         pascal, adding floating point math to your program will have no
  304.         effect on the speed of compression.
  305.  
  306.          inptr,inend,outptr,outend    : Word;
  307.  
  308.         Inptr points to the position of valid data in your input bufferm
  309.         as does outptr for your output buffer.  These are counters to
  310.         determine where in the appropriate buffer to place the next byte
  311.         of data.  (See example LZ.PAS for details of implementation).
  312.  
  313.  
  314.         inend, Outend:
  315.  
  316.         These variables point to the last valid byte in the appropriate
  317.         buffer.  You MUST set these values to the pointer.
  318.         (Again see LZ.PAS for details)
  319.  
  320.  
  321.  
  322.          Ebytes         : Longint;
  323.          EBytes is a count of total bytes to compress.  You MUST set this
  324.          variable to the total number of bytes you wish to compress.
  325.  
  326.  
  327.          inbuf,outbuf        : IObuf;
  328.          These are input/output buffers for the compression engine.
  329.          In previous versions, these were seperate from LZHMem^, but it
  330.          seemed more practical to have one call to allocate memory. If
  331.          someone complains loud enough I'll "Put em back" to seperate
  332.          independent pointers.
  333.  
  334.  
  335.          WorkSpace           : Array [0..$8657] of byte;
  336.          {LZHASM work space}
  337.          This variable array is work space for LZHASM.OBJ.  Please do
  338.          not adjust it or change the data while encode or decode is
  339.          active. If you wish to keep the space active on your heap, you
  340.          can use it in between runs for other things.
  341.  
  342.  
  343.          End;
  344.  
  345.  
  346.    LZHMem: ^LZHRec;
  347.    LZHMemSeg       : WORD;
  348.  
  349.         Notice that there is no offset variable.  This is intentional,
  350.         and the reason is simple:  SPEED!
  351.         In LZH.PAS, there is a sample routine for allocating memory that
  352.         is segment:0 aligned.  The difference in memory allocated using
  353.         this method is up to 32 bytes.
  354.         (For allocations of 55k, who cares!)
  355.                                 
  356.    procedure Encode ; compresses data
  357.    procedure Decode;  decompresses data
  358.    Procedure InitLZH; memory allocation and seg setterupper
  359.    Procedure DInitLZH; Memory de-allocation.
  360.  
  361.         (Pay attention to this section in future versions)
  362.         The proper sequence is as follows:
  363.  
  364.         Set writetobuffer and readfrombuffer to point to your procedures
  365.         for handling of buffer data.  Make sure that at bare minimum,
  366.         that the procedure is of far type;
  367.         {$F+}
  368.          Procedure YourProc;
  369.          {$F-}
  370.  
  371.         InitLzh
  372.  
  373.         Set the following LZHMem^. variables to zero:
  374.         Inptr
  375.         OutPtr
  376.  
  377.         if compressing:
  378.         Set LZHMEM^.Ebytes to the size of the data you wish to compress.
  379.  
  380.         Call encode to compress, or decode to decompress.
  381.  
  382.         The memory buffers will have the decompressed data.
  383.  
  384. ***********************************************************************
  385.  
  386. -Special design notes:
  387.  
  388.         This unit is specifically designed to be a portable unit for all
  389.         versions of Turbo Pascal. (Should work for windows too)
  390.         If this unit is modified in any way,
  391.         please keep backwards compatibility in mind.
  392.  
  393.         The following commands are identical in operations, although the
  394.         first listed command is portable only to turbo pascal 6.0 and
  395.         higher:
  396.  
  397.         AllocmemSeg( PointerToType,Sizeof(PointerToType^));
  398.  
  399.         Getmem(PointerToType,(Sizeof(PointerTotype)AND$FFF0)+16)
  400.  
  401.         If you use this unit, for all memory allocations you must use
  402.         the latter command, or modify your unit to use AllocMemSeg.
  403.  
  404. PLEASE DO NOT DISTRIBUTE THIS UNIT IF YOU MODIFY THE MEMORY ALLOCATION
  405. SECTION. ALLOCMEMSEG IS TP6.0 COMPATIBLE AND ABOVE, WHEREAS THIS UNIT IS
  406. COMPATIBLE WITH ALMOST ALL VERSIONS OF TURBO PASCAL.
  407.  
  408.  
  409. ***********************************************************************
  410. -Legalities:
  411.  
  412. Note:  I hate seeing legal items at the beginnings of files, wading
  413. through tons and tons of used cow food to get to the meat of what the
  414. utility really does.  With this in mind, all legal issues or limitations
  415. are here, at the end of the document.  
  416. -Compression of this archive:
  417.  
  418.         As far as compression type is concerned, I could personally care
  419.         less, as long as the software used to re-compress is freely
  420.         available.  Please to not recompress this archive with
  421.         Lameware, and do not add useless banner files.  
  422.  
  423.         The contents of this archive should contain the following:
  424.  
  425.  
  426.         LZHASMC.OBJ  -=> The C version (Uses C calling conventions.)
  427.                          (Untested and maybe unnecessary)
  428.  
  429.         LZHASM.OBJ   -=> The huffman compression object file (MSC6.0)
  430.                          (Pascal/Basic/Fortran/?)
  431.  
  432.         TPLZH.HST    -=> Version history        
  433.         TPLZH.NEW    -=> This document.
  434.  
  435.         LZ.PAS       -=> Sample TP 5.0+ version
  436.         LZH.PAS      -=> Base unit for all pascal platforms
  437.  
  438.         LZO.PAS      -=> OOPS examples for TP 6.0+
  439.         TESTLZO.PAS  -=> OOPS examples for TP 6.0+
  440.  
  441.         Anything additional shall be considered twit behavior.
  442.  
  443.         If this object is used in any utility you write for public
  444.         or commercial use, please give credit to the following people
  445.         in your documentation as applicable:
  446.  
  447.  
  448.         Haruyasu YOSHIZAKI  : Original concepts and lharc program.
  449.         Kenji RIKITAKE      : English translation to C
  450.         Peter Sawatzki      : Pascal interface(TP 5.0+}
  451.         Wayne Sullivan      : Pascal interface
  452.         Joe Jared           : Assembler optimization {TP 5.0++}               
  453.         Andres Cvitkovich   : Object version (TP 6.0+)
  454.  
  455.         here may be other legal issues, but at this time I'm not aware
  456.         of them.
  457.  
  458. -Distribution
  459.  
  460.         No fee may be charged for distribution of this package, and it
  461.         CANNOT be sold for any reason.
  462.  
  463.         Exception:  The disk this program is on, may be sold for the cost
  464.         of the disk.  (Not to exceed $0.70)+exact mail costs if mailed.
  465.  
  466.         If in a shareware package, no additional charges may be added
  467.         for the use of this "module".  This is a *freeware* implementation
  468.         of huffman compression.
  469.  
  470. ***********************************************************************
  471.