home *** CD-ROM | disk | FTP | other *** search
/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / BEEHIVE / ZCAT / CRUNCH20.LBR / UNCREL.DZC / UNCREL.DOC
Text File  |  2000-06-30  |  6KB  |  108 lines
  1.  
  2.                                 UNCREL v2.0
  3.  
  4.      UNCREL.REL is a Microsoft / DRI compatible .REL file which  makes
  5.      it extremely easy for an application program to "uncrunch" files.
  6.      All  the  programmer need supply is two routines-  one  which  is
  7.      capable of supplying one character at a time in the "A"  register
  8.      and one which will accept one character at a time. A single  call
  9.      to external entrypoint "UNCREL" will do the rest.
  10.  
  11.      This  organization was chosen (ie UNCREL stays "in control",  and
  12.      calls  the  programmer's input and output routines,  rather  than
  13.      vice-versa) because it is more consistent with the nature of  the
  14.      LZW  algorithm.   The algorithm may make 1, 2  or  3  consecutive
  15.      calls  for input without outputting anything, & then  may  output
  16.      any number of characters before needing more input.
  17.  
  18.      Since  an  individual call is made for each byte needed  or  sup-
  19.      plied, the user's routines can refill (or dump out) any input  or
  20.      output  buffers at any appropriate time.  If the  programmer  de-
  21.      cides  to  terminate the uncrunch operation  before  its  natural
  22.      completion, it is simply necessary to reset the stack pointer and
  23.      continue rather than RETurning to UNCREL. More detailed  descrip-
  24.      tion of operation follows:
  25.  
  26.  
  27.      Programmer Supplied Routines, declared "PUBLIC".
  28.  
  29.      1.  One  must  be named "GETBYT".  Each time  this  routine  gets
  30.      called  by UNCREL, it should supply the next sequential  byte  in
  31.      "A".  The routine may make full use of all registers, but  should
  32.      not  assume  that they will be in any particular state  the  next
  33.      time the routine is called. Basically, any pointers, etc., should
  34.      be memory based.  Note, however, that all usage of the  alternate
  35.      Z-80 registers has been eliminated from UNCREL.  Thus an  "alter-
  36.      nate" scheme is to execute an EXX instruction at the beg and  end
  37.      of "GETBYT", in which case the registers will remain intact.
  38.  
  39.      2.  Another routine must be named "OUT".  UNCREL calls this  rou-
  40.      tine each time it has a new character available for output.   The
  41.      character  will be in register "A".  All other conditions are  as
  42.      described above.
  43.  
  44.      What you (the programmer) must do:
  45.  
  46.      Simply  make a single call to "UNCREL", which should be  declared
  47.      "EXTRN".  This will initialize all tables, and then all  activity
  48.      will proceed until the file is completely uncrunched or an  error
  49.      is  encountered. At that point, UNCREL will return to  your  pro-
  50.      gram.   If  the carry flag is set, this was an error  return.  In
  51.      this case reg "A" will contain a [non-zero] code identifying  the
  52.      type  of error, if you are interested. If carry is clear, A  will
  53.      be  zero, and this indicates that the entire operation has  term-
  54.      inated normally.
  55.      
  56.      What else you must do:
  57.  
  58.      BEFORE  you make the call to UNCREL mentioned above,  you  should
  59.      load  "HL" with a pointer to a large block of memory (24k).   The
  60.      rest  of the work is taken care of- UNCREL will figure  the  next
  61.      page boundary and allocate various pointer for various tables  it
  62.      will  build itself. It will also allocate a large stack area  for
  63.      itself within this block, and will initialize all any ram locs it
  64.      needs.  All of this is done at "run time". UNCREL can be  reexec-
  65.      uted  multiple times if desired.  Your stack will be returned  to
  66.      its previous value if UNCREL returns (either due to completion or
  67.      error).   If you decide to interrupt operation by  not  returning
  68.      from  one of its "GETBYT" or "OUT" calls, however, don't   forget
  69.      to reset the stack to your own value.
  70.  
  71.      Another  EXTRN value named "ENDU" is made available for  possible
  72.      use. It is the end of the data area (DSEG) used by UNCREL. If you
  73.      link in such a way that UNCREL is "on top", then this can be used
  74.      as a reference for the beg of available memory after the program.
  75.  
  76.  
  77.      More notes:
  78.  
  79.      Every  byte  of a crunched file, starting with the 76H  and  0FEH
  80.      header  bytes, must be supplied in order. The header  information
  81.      is checked for some validity, although the file name is  ignored.
  82.      UNCREL  will  determine the version# when it gets to it  and  un-
  83.      crunch accordingly, you needn't worry about this. If you need the
  84.      filename,  you must extract it yourself.  The exact format  of  a
  85.      crunched  file  is defined as a  separate  document  LZDEF20.DOC.
  86.      UNCREL  does NOT read or compute the checksum, if that  interests
  87.      you  you can do that yourself too. (Note: CRUNCH.COM  &  UNCR.COM
  88.      v2.0  are  not directly based on UNCREL. They always  create  and
  89.      check the checksum respectively, of course).
  90.  
  91.      More notes:
  92.  
  93.      The  LZW process is a continuously progressing  forward  process.
  94.      You cannot go back.  If you leave out just one byte, you will get
  95.      results  which become stranger and stranger, eventually  becoming
  96.      complete  gibberish.   (This is actually  pretty  interesting  to
  97.      watch, albeit frustrating if its not what you want).
  98.  
  99.      ----------------------------------------------------------------
  100.  
  101.      What is USQREL.REL?
  102.  
  103.      This  is an unsqueezer. Its operation is identical to  UNCREL  in
  104.      every  respect. It actually only needs a memory block  4k  large,
  105.      however, and its size is 393 bytes!  TYPELZ20 now uses these  two
  106.      files for all data decompression.
  107.   
  108.   may  outpu     any number of characters before needing more input     Since  an  individual call