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