home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / lambda / misc / lt31.lbr / LT31.DYC / LT31.DYC
Text File  |  1993-10-25  |  48KB  |  1,523 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.            LT (LIBRARY TYPER) VERSION 31 USER MANUAL
  21.  
  22.           Integrated and edited for improved comprehension by
  23.                 Brian C. Murphy
  24.              Vancouver Kaypro Users Group
  25.  
  26.                Mission, British Columbia
  27.                    December 16, 1991
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.                        i
  69.  
  70.  
  71.                    CONTENTS
  72.  
  73. Extracting and Decompressing LT31.LBR . . . . . . . . . . . . . . . . . . .  1
  74.  
  75. New Features of LT Version 29 - 31  . . . . . . . . . . . . . . . . . . . .  1
  76.  
  77. History of Revisions to LT  . . . . . . . . . . . . . . . . . . . . . . . .  2
  78.  
  79. User Directions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
  80.  
  81.    User Specifications    . . . . . . . . . . . . . . . . . . . . . . . . . .  5
  82.  
  83.    User Control Codes . . . . . . . . . . . . . . . . . . . . . . . . . . .  5
  84.  
  85. User Patches for Customizing LT Version 31  . . . . . . . . . . . . . . . .  7
  86.  
  87. Support of LZH Compressed (.?Y?) Files & LT31 Assembly Procedures . . . . .  9
  88.  
  89.    Support of LZH Compressed Files  . . . . . . . . . . . . . . . . . . . .  9
  90.  
  91.    LT31 Assembly Procedures   . . . . . . . . . . . . . . . . . . . . . . . 10
  92.  
  93.        Using LINK.COM    . . . . . . . . . . . . . . . . . . . . . . . . . . 10
  94.  
  95.        Using SLRMAC and SLRNKP    . . . . . . . . . . . . . . . . . . . . . . 10
  96.  
  97.        Using M80 and L80 (or SLRNK, non + version)  . . . . . . . . . . . . 10
  98.  
  99. Steve Greenberg's Original UNC.REL Documentation  . . . . . . . . . . . . . 13
  100.  
  101. UNLZH.REL and CRLZH.REL Documentation    . . . . . . . . . . . . . . . . . . 16
  102.  
  103.    Abstract   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
  104.  
  105.    Version History and Compatibility  . . . . . . . . . . . . . . . . . . . 16
  106.  
  107.    Care and Feeding . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
  108.  
  109.    Standard Header Information    . . . . . . . . . . . . . . . . . . . . . . 19
  110.  
  111.    What LZH Compression Does and How it Compares  . . . . . . . . . . . . . 20
  112.  
  113.    A Small History  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.                        1
  135.  
  136.  
  137.              EXTRACTING AND DECOMPRESSING LT31.LBR
  138.              (from LT31.LBR: -README.1ST)
  139.  
  140.  
  141. The LT31.COM file is left UNCOMPRESSED and should be used to extract/decompress
  142. everyting in this .LBR.  Merely extract the LT31.COM file and enter the
  143. command:
  144.  
  145.    LT31 LT31 x:*.*  (replace x with a drive letter of your choice)
  146.  
  147. LT31.LBR is based on, and corrects a bug in, LT30.LBR released by:
  148. Roger Warren, Sysop, The Elephant's Graveyard (Z-Node#9)
  149. 619-270-3148 (PCP area CASDI)
  150.  
  151. Brian Murphy, Vancouver Kaypro Users' Group
  152. Richmond, B.C. BBS Phone:  271-5934
  153.  
  154.  
  155.  
  156.               NEW FEATURES OF LT VERSIONS 29 - 31
  157.                (From LT31.LBR: LT31.FOR)
  158.  
  159. Version 31 corrects a bug in version 30 (and probably all versions back to 25)
  160. that prevented LT from accepting USER specifications as a SOURCE of data.
  161. (Many thanks to Roger Warren, Sysop, Elephant's Graveyard San Diego,
  162. California for the suggestions for fixing this problem.)
  163.  
  164. Version 31 also changed the 6 labels in the MAC file, which had 7 characters to
  165. 6 character labels.  That was done to make LT31.MAC compatible with an ancient
  166. (about 1979) version of M80 that will not accept labels with more than 6
  167. characters.  This change does not in any way impair the use of LT31.MAC with
  168. any other assembler.
  169.                      Revised by Brian Murphy
  170.                      Vancouver Kaypro Users Group
  171.                      Richmond, British Columbia, Canada
  172.                      BBS phone:  (604) 271-5934
  173.  
  174.  
  175. Version 30 (July '91) incorporated Version 2.0 of LZH Encoding.  Excellent for
  176. TYPE.COM use.  Can type normal, LZH-encoded, crunched or squeezed files -
  177. whether standalone or in a .LBR.  If wheel is on, can also easily extract
  178. any/all files, and uncrunch and/or unsqueeze at the same time.    Most useful
  179. program for either RCP/M use or for individual CP/M systems.
  180.                      Revised by Roger Warren
  181.                      Sysop, Elephant's Graveyard
  182.                      San Diego, California
  183.  
  184. Version 29 LZH-encoded file (.?Y?)  handling capability has been added to Mr.
  185. C. B. Falconer's excellent Library Typer program with this update.  Excellent
  186. for TYPE.COM use.  Can type normal, LZH-encoded, crunched or squeezed files -
  187. whether standalone or in a .LBR.  If wheel is on, can also easily extract
  188. any/all files, and uncrunch and/or unsqueeze at the same time.    (This is the
  189. missing feature in NULU152.)  Most useful program for either RCP/M use or for
  190. individual CP/M systems.
  191.                      Revised by Roger Warren
  192.                      Sysop, Elephant's Graveyard
  193.                      San Diego, California
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.                        2
  202.  
  203.               HISTORY OF REVISIONS TO LT
  204.                (From LT30.LBR: LT30.DOC)
  205.  
  206.            LT v31 Documentation - C.B. Falconer - 15 Dec. 91
  207.  
  208. Changes summary:
  209.  
  210. LT31 - Modified as follows to enable assembly with ancient (about 1979) version
  211.        of M80 by changing the names of the following symbols which exceeded 6
  212.        characters.  (This will not effect assembly with any other assembler.)
  213.  
  214.        OLD LABEL  NEW LABEL   OLD LABEL  NEW LABEL   OLD LABEL    NEW LABEL
  215.        setnam2      setnm2      setfld1     setfd1      setfld2    setfd2
  216.        setfld3      setfd3      setfld4     setfd4      setfld5    setfd5
  217.  
  218.        Also modified routine labelled start: to fix a bug dating from v25 that
  219.        prevented LT from accepting USER specifications as a SOURCE of data.
  220.        (Many thanks to Roger Warren, Sysop, Elephant's Graveyard San Diego,
  221.        California for the suggestions for fixing this problem.)
  222.  
  223.        Also revised User Manual for easier comprehension. - Brian Murphy
  224.  
  225. LT30 - Incorporated version 2.0 of LZH encoding.  This program is necessary to
  226.        decode files encoded with version 2.0 of LZH compression, but will
  227.        AUTOMATICALLY handle files encoded with version 1.x LZH encoding. Added
  228.        appropriate documentation changes. Added instruction to reset MSB in
  229.        output FCBs. Corrected error message pointer for UNC & UNL errors (sent
  230.        garbage to screen). - R. Warren
  231.  
  232. LT29 - Added the capability to handle LZH-encoded files (files with extensions
  233.        of the form ?Y?).  No other functional changes. - R. Warren
  234.  
  235. LT28 - Reworked - all identification of output files had disappeared.
  236.        Documentation attached to LT27 had the wrong patch information.    (but
  237.        LT25 was correct) LT27 was non-fixable, due to reformatting, and thus
  238.        text  comparators gave no useful information.  Basis for LT28  is LT25.
  239.        - C.B. Falconer
  240.  
  241. LT27 - Rewrote display section when  extracting files to disk.    The program was
  242.        triple spacing with no tabulation.  Was unsightly if the library had
  243.        more than 1-2 files.  (Still under 5k.) If the TPA is under 46k might
  244.        need to change  "REC" from 128 to 96 or even 64. - Irv Hoff, Sysop
  245.  
  246. LT26 - When typing a crunched file  with a comment attached, it was running off
  247.        the end    of the screen, to display the  uncrunched file name with
  248.        comment. - Ed Minton
  249.  
  250. LT25 - All options patchable, no need to reassemble for RCPM/ZCPR use.    OPTION
  251.        LOCATIONS CHANGED.  Fixed multi-sector file output buffer
  252.        initialization.    Cleaned up. - C.B. Falconer
  253.  
  254. LT24 - Fixed bug in PARSE1 routine. If no USER AREA specified for disk output
  255.        then it defaulted to input file user area rather than the CURRENT user
  256.        area. Modified to allow abort during disk output. Added    $U  command
  257.        line option to allow disk output of squeezed/crunched files WITHOUT
  258.        unsqueeze/uncrunch. (see the NOUQZ byte added to the patch area at
  259.        103H). Added REC equate to allow more than one sector in the file output
  260.        buffer to reduce wear and tear on floppy drives.  REC is currently set
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.                        3
  268.  
  269.        for 8 sectors (1k). - Tom Head
  270.  
  271. LT23 - FIXES SEVERAL ANNOYING BUGS.  Most notably, it no longer aborts when
  272.        extracting a 0-length file from a library.  Other minor changes, see
  273.        source code. - Howard Goldstein
  274.  
  275. LT22 - adds support for ZCPR/ZCMD page zero maximum user values for a  more
  276.        secure RCP/M environment.  Wheel support  has  been expanded.  When  the
  277.        wheel  is  active  the  line   counter restriction is defeated, allowing
  278.        the sysop (or other  wheel users to display files of any length.  The
  279.        wheel also  over- rides the page zero user value and substitutes the
  280.        hardcoded maximum value. - Gary Inman
  281.  
  282. LT21 - adds the ability to scroll one line at a time with the space bar. - Irv
  283.        Hoff
  284.  
  285. LT20 - was created for two reasons. The first reason is so that only one copy
  286.        of LT will be needed for RCP/M systems.    It may also be handy for
  287.        persons who have a secure "local" system which utilizes the wheel byte
  288.        for security.  Only one byte need be changed in the table of
  289.        configurable items if desired should the wheel byte not be implemented
  290.        on your system.    The wheel byte will enable/disable ability for the
  291.        program to output to a disk file.   The second reason for this version's
  292.        creation was because it wouldn't assemble properly with M80/L80;  the
  293.        value for YES and NO "were" 0FFH and 0, respectively.   Now changed to
  294.        NO equ 0, YES equ NOT NO.  Minor other  changes    were made.  Code is
  295.        still < 4k. - George Reding
  296.  
  297. LT19 - was modified to prevent possible junk characters from being sent to the
  298.        console while displaying a crunched file header.  LT18 was modified to
  299.        allow access to LBR's larger than 512k.  Changes were made in LT17 to
  300.        prevent the  generation of junk file names under certain usage
  301.        conditions.  See  source code modification  history  for  more details
  302.        about these fixes.
  303.  
  304. LT16 - eliminates  all the limitations    related to extraction  of binary files
  305.        to disk (see below).  It will also now uncrunch    when running on 8080,
  306.        8085 and V20 CPUs, besides Z80s.  When  extracting  binary files to
  307.        disk, the program is uninhibited by the "bad types" table or occur-
  308.        rences of 1Ah (EOF) bytes within the file.
  309.  
  310. LT15 - adds the ability to extract files to disk.  There is a limitation of
  311.        only text files (any 01Ah byte is EOF).    No checks are performed so that
  312.        invalid LBR checksums etc. will    not be detected.  To use this ability,
  313.        add a "DU" specification  to the component name.  Don't try to extract
  314.        .COM (.CZM, .CQM) etc. files with LT15.
  315.  
  316.        This ability was  considered necessary since NULU (1.51) cannot expand
  317.        crunched files directly to disk.
  318.  
  319. LT14 - is a revision of LT13 to  include "uncrunch" capability (but only on Z80
  320.        CPUs for uncrunching).  As did LT13, LT14 can expand UCSD style
  321.        indentation coding (DLE, count + 020h).     Customization    etc., remains
  322.        unchanged, although the defaults have been modified.   The  "min" form
  323.        is no longer supplied but you can create it by setting the appropriate
  324.        equates to false (in the source) and re-assembling.
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.                        4
  334.  
  335.                 USER DIRECTIONS
  336.     (Subtantially expanded from LT30.LBR: LT30.DOC by Brian Murphy)
  337.  
  338.    LT (Library Type) displays the contents of .LBR files on the console, or
  339. functions as a pausing replacement for TYPE.
  340.  
  341.    LT was adapted from Steven R. Holtzclaw's LUXTYP of (06/10/83) for use
  342. without the complete LUX system.  As does LUXTYP, LT automatically unsqueezes
  343. any squeezed file components for display.
  344.  
  345.    Two versions of LT are distributed, LTnnMIN is a minimum sized object file
  346. with no security restrictions, nor DU style drive/user specifications.    It is
  347. intended to be mounted in a COMMAND.LBR file on single user systems.  LTnnMAX
  348. implements DU drive/user specification, and various security provisions, for
  349. use on RCPM systems.  In particular LTnnMAX can individually specify drives
  350. available (rather than a simple max value), and expands UCSD style indentation
  351. coding (V. 13 up).  This is useful for compressed PASCALP source files, or
  352. transfers from a UCSD system.  Both versions implement wild card file
  353. specification, and can search an alternate drive for the specified files.
  354.  
  355.    LT executes on 8080 systems (as opposed to LUXTYP on Z80s only).  LT
  356. searches the default and system disks for the files.  Assembly time constants
  357. are available to restore the original LUX limitations on file types and output
  358. line count.  LT has provisions for stopping CRT page pauses during one files
  359. output, and will also pause across file (component) boundaries.
  360.  
  361.    Execution of:
  362.  
  363.      C>LT
  364.  
  365. produces the version number and a minimum syntax explanation as follows:
  366.  
  367. LT31 [d[u]:]lbr/filename [d[u]:][component] [$u]     by C.B. Falconer
  368. ^S pause, ^C abort, ^X next file, ^Z stops paging
  369.  
  370.    Type/uncrunch/unsqueeze/unLZH files or LBR members
  371.    Drive/user after lbr/filename causes file output.
  372.    $U at end disables unsq/uncr/unlzh of compressed files
  373.    (wildcards permitted)
  374.  
  375. Examples:
  376.    B>LT A3:HELLO SOURCE.AZM       [console]     (defaults to HELLO.LBR)
  377.    A>LT LZHENCOD.DYC           [console]     (handles LZH encoding)
  378.    A>LT SQUEEZE.DQC           [console]
  379.    A>LT HELLO *.*           [console, all typable]
  380.    B>LT B:HELLO A4:SOURCE.AQM       [file]
  381.    B>LT B:HELLO A4:SOURCE.AQM $U   [file with no unsqueeze]
  382.    A>LT B:CRUNCH.AZM A:        [file]
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.                        5
  400.  
  401.  
  402.      C>LT drive[user]:LBRFILE ambigfilereference
  403.  
  404. where "lbrfile" is always assumed to have the extension .LBR, and the
  405. "ambigfilereferance" refers to one or more library components.    It may contain
  406. wild cards (* and ?).  The command above will list to the CRT all ASCII (only)
  407. members of the library which were specified in "ambigfilereference".  There
  408. must not be a drive specification preceding "ambigfilereference".  If the
  409. LBRFILE is on the logged on drive, "drive:" before LBRFILE may be omitted.
  410.  
  411.      C>LT drive[user]:LBRFILE drive[user]:AFN
  412.  
  413. will extract all the designated files (including .COM, etc.) from the SPECIFIED
  414. LBRFILE to disk files located on the drive and user specified prior to "AFN:.
  415. Any data after the EOF (01ah) character will be lost, including CCITCRC checks.
  416. There must be a drive specification preceding "AFN".  If the LBRFILE is on the
  417. logged on drive, "drive:" before LBRFILE may be omitted.
  418.  
  419.  
  420. USER SPECIFICATIONS:
  421.  
  422.    The currently assembled distribution copy of LT.COM (LT31.COM) permits USER
  423. specifications for both source of data and destination of data, as a result of
  424. correcting a bug which probably began about version 25.  (The present editor
  425. can personally verify that the bug was present in versions 29 and 30.)
  426.  
  427. For example:
  428.  
  429. LT C0:NULU *.*    is permitted.
  430.  
  431. LT C1:NULU *.*    is permitted.
  432.  
  433. LT C:NULU C1:*.*  is permitted.
  434.  
  435. LT C1:NULU C2:*.* is permitted
  436.  
  437.  
  438. User Control Codes:  (s,S^S, c,C,C^, ^X, ^Z):
  439.  
  440.    The usual CTL-S can pause output, but finishes the current line before
  441. pausing.  (s or S can also be used.)  CTL-C aborts back to CP/M prompt but
  442. again finishes the current line first.    c,C k,K,^K can also be used.  CTL-X (
  443. or X or x) aborts listing of the current file and advances to the next file, if
  444. any.  CTL-Z stops all "[more] page pauses until the next file (component.)
  445.  
  446. NOTE: Use CTL-Z after a pause for continuous scrolling.  Force an initial pause
  447.       via S or CTL-S, then a CTL-Z.  This allows scrolling without stopping
  448.       with [more] pauses (not even the first one).
  449.  
  450. NOTE: For an RCPM version, patch as detailed below.  This allows you to specify
  451.       the exact drives available.
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.                        6
  466.  
  467. Examples:
  468.  
  469.     B>LT LT10 *.D?C
  470.  
  471. lists all components of LT10.LBR, found on either the B or A drives, with the
  472. extensions DOC, DQC, etc.  The B drive is preferred.
  473.  
  474.     B>LT C:LT10 *.D?C
  475.  
  476. is similar, but will only look for LT10.LBR on drive C:
  477.  
  478.     B>LT D:FNAME.FT
  479.  
  480. will display FNAME.FT, unsqueezing it if it is a squeezed file.  This mode
  481. replaces TYPE.    The absence of the second parameter signals that this is not a
  482. library file.
  483.  
  484. (The following for LTnnMAX only, or versions assembled with the "DUSPEC"
  485. assembly time option set to YES.)
  486.  
  487.      B>LT M5:BLAH *.D?C
  488.  
  489. will display all .DOC/DQC/DZC etc. components of BLAH.LBR on drive M, user 5.
  490. The disk specification avoids any drive searches being made.  (As noted above
  491. under "USER SPECIFICATIONS", this usage of user number is not tolerated by the
  492. currently assembled copy of LT.COM.).
  493.  
  494.      B>LT @5:BLAH *.D?C
  495.  
  496. is similar, but drives B and A are searched for BLAH.LBR on user 5.
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.                        7
  532.  
  533.           USER PATCHES FOR CUSTOMIZING LT VERSION 31
  534.                (From LT30.LBR: LT30.DOC)
  535.  
  536.      Address   Default     Purpose
  537.      -------   -------     -------
  538.        0103h         Standard ZCPR environment, unused in LT now.
  539.        010Bh   0000h     Wheel byte implemented for security/remote
  540.              usage.  Set 10bh to 03eh if you use the wheel
  541.     ^^         byte at 03Eh.    Set NO (00h) if you do not
  542.     ** WORD **         use the wheel byte.  The wheel byte will
  543.              enable/disable the ability of this program
  544.              to extract files to disk. THIS IS A WORD and
  545.              allows the wheel to be anywhere in memory.
  546.              0000h eliminates all wheel checking.
  547.        010Dh   14h=20     Lines typed between pauses.  0 for no pauses.
  548.        010Eh   0     Maximum lines allowed before abort
  549.              A value of zero allows any size file to
  550.              be typed.  Cannot be set above 255 (1 byte)
  551.        010Fh   0FFh     Causes file types listed in the inhibition
  552.              table at 0119h to be rejected for typing
  553.        0110h   0     Set 0ffh to check for pause on each output
  554.              character.  Useful for slow Braille terminals. 
  555.        0111h   0FFh     Absorbs all control characters except CR,
  556.              LF, TAB, BELL AND BCKSP.  A 0 value allows
  557.              any control character to be typed.
  558.        0112h   0     Alternate drive to search when no drive
  559.              specification is made, and the file is not
  560.              found on the default drive.  0 for no search,
  561.              1 for A, 2 for B, etc.
  562.        0113h   00Fh =15  Maximum user number accessible (inclusive).
  563.              The SPECIAL VALUE 0ffh causes the value to
  564.              be replaced by that at 03dh (ZCPR mxusr)
  565.        0114h   A,B,M     A one word (2 byte) vector of bits which
  566.         (all)     specifies drives accessible. The most sig-
  567.              nificant bit (in byte 0115h) specifies
  568.              drive A, the next drive B, etc, until
  569.              the least significant bit of byte 0114h
  570.              specifies drive P.
  571.        0116h   00     A one byte flag that is toggled by the $U
  572.              command line option. If set to 0FFh, it
  573.              will disable the uncrunch/unsqueeze of
  574.              files during disk output.
  575.        0117h   0ffh     0 to suppress dle expansion (UCSD style
  576.              indentation codes).  May be useful if output
  577.              of control characters (above) is enabled.
  578.        0118h         Spare, for future use
  579.        0119h   (and up)  Contains a list of 3 byte ASCII characters,
  580.              each of which specifies a file type that may
  581.              not be "typed".  The byte at 010Fh can be set
  582.              to ignore this table.    The space up to, but
  583.              not including, 0155h can be used to add
  584.              installation specific values.    Setting a high
  585.              order bit in any entry will inhibit its use.
  586.              The "?" character matches any character in the
  587.              file type.
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.                        8
  598.  
  599. Security:
  600.  
  601. The customization values above control the security levels.  However, if LT is
  602. executed by a user already logged onto a drive or user number outside the
  603. specified limits, LT allows access to that area also.  The theory is that the
  604. previous login has established the access rights.
  605.                     - C.B. Falconer
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.                        9
  664.  
  665.        SUPPORT OF LZH COMPRESSED (.?Y?) FILES & LT31 ASSEMBLY PROCEDURES
  666.            (EXPANDED from LT30.LBR: READ.ME by Brian Murphy)
  667.  
  668.  
  669.             SUPPORT OF LZH COMPRESSED FILES
  670.  
  671. Updated for use with LT31                     1991 Dec. 15
  672.  
  673. LT version 29 added support for LZH-encoded files (extensions of the form .?Y?)
  674. to Mr. C.B. Falconer's LT program (prior version 28, see below).
  675.  
  676. LT versions 30 and 31 incorporate version 2.0 LZH decoding, which can also
  677. decode version 1.x LZH compression as well.
  678.  
  679. LT31 is ready for non-RCPM use.  Refer to the LT28 docs and to the source code
  680. for modification for RCPM usage.
  681.  
  682. This .LBR includes UNLZH.REL, an 8080/8085/V20/Z80 subroutine file which
  683. contains the code for the LZH-encoded file handling.  That file is copyrighted
  684. (c) 1989, 1991    by Roger Warren.  It may be used or reproducedon a non-profit
  685. basis only.
  686.  
  687. If you assemble your own version, make sure that the LAST file loaded in the
  688. LINK phase is UNC, as the LT program locates the top of the program by a symbol
  689. in that module.
  690.  
  691. FOR THOSE INTERESTED IN PATCHING FOR DATE STAMPS:  In the pre-assembled version
  692. of LT30 in LT30.LBR 128 bytes of patch area were left from 1AA0h thru 1B1Fh,
  693. inclusive.  These were added in the link phase and are not an integral part of
  694. the program.  If you re-link...it goes away (unless you provide your own).
  695.  
  696.  
  697. ----------------------Updated LT28 documentation follows ----------------------
  698.  
  699. Updated for use with LT31                     1991 Dec. 15
  700.  
  701. LT28 is copyrighted  (c) 1986,    1988 by C.B. Falconer.    It may be freely copied
  702. and used for non-commercial purposes.
  703.  
  704. LT28R.COM (not distributed with versions 29 - 31) is ready for RCPM use.
  705. LT28.COM  does not use the wheel byte and, is ready for normal (non-RCPM) use.
  706.  
  707. This revision of LT (Library Typer) includes UNC.REL, a modification of Steve
  708. Greenberg's UNCREL.REL file, to access crunched files and library components
  709. (in addition to squeezed and uncompressed files/components).  This uncruncher
  710. runs on 8080/8085/V20/Z80 processors, and can process the output of CRUNCH23 or
  711. prior.
  712.  
  713. See above for customization patches.  Sysops can now leave EXTRACT set to YES,
  714. as v20 tied this in with the wheel byte.  v25 also allows UZCPR to be replaced
  715. by a MAXUSR value of 0FFh (255).
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.                       10
  730.  
  731.                LT31 ASSEMBLY PROCEDURES
  732.  
  733. USING LINK.COM
  734.  
  735. To link with LINK rather than L80, simply type:
  736.  
  737.     M80 =LT29.ASM/M
  738.     LINK LT29,UNLZH,UNC
  739.  
  740.  
  741. USING SLRMAC AND SLRNKP:
  742.  
  743. To process this with SLRMAC and SLRNKP:
  744. (SLRMAC configured to use .MAC input files, else rename source)
  745.  
  746.     D>SLRMAC LT29/M
  747.     D>SLRNKP LT29/N/A:100/J,LT29,UNLZH,UNC,/E
  748.  
  749. The first step assembles to a .REL file, the second links UNLZH.REL and UNC.REL
  750. and creates LT29.COM, ready to use - no other steps needed.
  751.  
  752.  
  753. USING M80 and L80 (or SLRNK, non + version):
  754.  
  755.    My early 1980's version of M80, at least, will not accept label symbols
  756. exceeding 6 characters.  One of the authors or revisers of previous versions of
  757. LT31.MAC has used six different 7 character labels.  Consequently, each of
  758. those six labels has to be changed to 6 characters to prevent several "fatal"
  759. assembly errors.  In LT31.MAC I have changed all ocurrences of the following
  760. six 7 character labels as noted to correct that deficiency.:
  761.  
  762.  15 Dec 91 Modified to correct error in M80 assembly (symbols > 6 char.)
  763.        OLD LABEL  NEW LABEL   OLD LABEL  NEW LABEL     OLD LABEL  NEW LABEL
  764.        setnam2    setnm2      setfld1    setfd1     setfld2    setfd2
  765.        setfld3    setfd3      setfld4    setfd4     setfld5    setfd5
  766.  v31 - Modified by Brian Murphy Vancouver Kaypro Users Group
  767.  
  768.    Once those corrections were made to each occurrence of each label, LT31
  769. assembled flawlessly with M80.    Those changes, which have no effect on other
  770. assemblers, have now been made to this distribution version of LT31.MAC.
  771.  
  772. To re-assemble with M80/L80 (using a source file named LT31.MAC):
  773.  
  774. C>M80 =LT31/M
  775.  
  776. No  Fatal error(s)
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.  
  788.  
  789.  
  790.  
  791.  
  792.  
  793.  
  794.  
  795.                       11
  796.  
  797. The final linking step is a two-pass operation:
  798.  
  799. C>L80 /P:100,/D:2000,LT31,UNLZH,UNC,/M
  800.  
  801. Link-80  3.43  14-Apr-81  Copyright (c) 1981 Microsoft
  802. Data    2000    3571    < 5489>
  803. Program 0100    1A99    < 6553>  (NOTE that "1A99", which is the end of the
  804.                  programme code in LT31.COM, is needed for the
  805.                  2nd pass and for calculating the amount of
  806.                  space needed for data before removing unneeded
  807.                  bytes with DDT.)
  808.  
  809.  CODES    3557     ENDU    3571     ENDUL    1554    
  810.  GETBYT 03C8     GLZHUN 03C8     OUT    04E4    
  811.  PLZHUN 04E4     TOPOF 1A71    TROOM  356D    
  812.  UNC    1610     UNCREL 15DE     UNL    12D0    
  813.  UNLZH    12D7    
  814.  
  815. 26817 Bytes Free
  816.  
  817. */R  (Reset L80)
  818.  
  819. */P:100,/D:1A99,LT31,UNLZH,UNC,LT31/N  (NOTE that "1A99" from Pass 1 is used
  820.                        here)
  821. Data    1A99    300A    < 5489>
  822. Program 0100    1A99    < 6553>
  823.  
  824. 26817 Bytes Free
  825.  
  826. */E  (Exit L80 now that Linking is complete.)
  827.  
  828. Data    1A99    300A    < 5489>
  829. Program 0100    1A99    < 6553>
  830.  
  831. 26817 Bytes Free
  832. [0100    300A       48]
  833.  
  834.  
  835.    L80 has added many unneeded bytes to the file.  Load it with DDT and SAVE
  836. only the portion up to the last code byte plus about 80h bytes (1A99H + 80H in
  837. this example;  it may be different depending upon assembly options.).  This
  838. extra pad is because there is actually initialized data in the data segment,
  839. but those areas are in the very beginning of the area.    With DDTZ, use "K
  840. 100,1AE5" command to write it back.  You can zero the portion after the end of
  841. code (unmodified L80 and early SLRNK+ junk fill, but SLRNK zero-fills).
  842.  
  843.    As noted above in Pass 1 of the Linking process, the L80 Linker tells you,
  844. in the Program Row of the table printed on the screen when the linkage pass is
  845. complete, both the beginning and ending locations of program code in the
  846. resulting .COM file.  In our example, while linking to generate the final form
  847. of the LT31.COM file, that row (in each of the 3 screen printouts) states that
  848. the beginning of program code is 0100(H) and the end of program  code is
  849. 1A99(H).  Since the end of program code will vary with the version of the
  850. program and the assembly options chosen, you have to look at that table to
  851. determine that location.
  852.  
  853.  
  854.  
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.                       12
  862.  
  863.    Once you know that location, add 80H to it.    (A Public Domain program
  864. variously called HEXDEC11.LBR, HEX-DEC.LBR, or @.LBR facilitates hexidecimal
  865. calculations.)    In our example, 1A99H + 80H = 1B19H.
  866.  
  867.    Subtract the beginning of file address (0100H) from that number.  In our
  868. example, the difference of 1B19H - 100H = 1A19H or 6681D.
  869.  
  870.    Divide that decimal number by the decimal number of bytes in a page (256).
  871. In our example 6681D/256 = 26.098 pages.  Round up to the nearest integer
  872. number (27 pages in our example) and you have the number of pages to SAVE after
  873. loading the COM file with DDT.
  874.  
  875.    Make sure that the calculator you use for this particular calculation does
  876. not truncate the result.  If you do not round up when telling SAVE how many
  877. pages to save, you will cut off a useful portion of the .COM file.
  878.  
  879.    The following illustrates the final steps to be taken using DDT and SAVE to
  880. eliminate the useless final portion of the file.
  881.  
  882. C>DDT LT31.COM
  883.  
  884. DDT VERS 2.2
  885. NEXT  PC
  886. 3080 0100
  887. -G0
  888.  
  889. C>SAVE 27 LT31.COM  (or whatever name you want to use for the final .COM file)
  890. C>
  891.  
  892.                    - enjoy
  893. ------------------------------------- end -------------------------------------
  894.  
  895.  
  896.  
  897.  
  898.  
  899.  
  900.  
  901.  
  902.  
  903.  
  904.  
  905.  
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.                       13
  928.  
  929.            STEVE GREENBERG'S ORIGINAL UNC.REL DOCUMENTATION
  930.                (From LT30.LBR: UNC.DOC)
  931.  
  932.                   UNC v2.1
  933.  
  934. UNC.REL is an adaptation of Steve Greenbergs UNCREL module to:
  935.  
  936. a:  Execute on 8080/8085/V20 processors.
  937.  
  938. b:  Modify error returns.  Returned values are:
  939.       0 (no carry)  No error, as UNCREL
  940.       1 (carry)     Later version needed.
  941.       2 (carry)     File/module is not crunched
  942.       3 (carry)     File is corrupt. Possibly not crunched.
  943.       4 (carry)     Insufficient memory or stack overflow.
  944.  
  945. c:  Added entry point UNC, is used just as UNCREL (described below), except
  946.     that the input file/module has already been processed up to and including
  947.     the initial 0 byte.  This avoids the necessity of rewinding the file, BUT
  948.     an uncrunched file (no initial id stamp) can cause unknown results.
  949.     CAUTION.
  950.  
  951. d:  Added (data relative) entry points CODES and TROOM may be monitored (but
  952.     not modified) by the application to detect "codes assigned" and "codes
  953.     re-assigned" respectively (version 20 crunch format). TROOM monitors codes
  954.     still unassigned for version 10 format.
  955.  
  956. e:  A single byte at UNCREL-1 contains the revision number.
  957.  
  958. The remainder of this file is Mr. Greenbergs original document.
  959.  
  960.                 C. B. Falconer (86/11/24)
  961.                 -------------
  962.  
  963.  
  964. UNCREL.REL is a Microsoft / DRI compatible .REL file which makes it extremely
  965. easy for an application program to "uncrunch" files.  All the programmer need
  966. supply is two routines - one which is capable of supplying one character at a
  967. time in the "A" register and one which will accept one character at a time.  A
  968. single call to external entrypoint "UNCREL" will do the rest.
  969.  
  970. This organization was chosen (ie UNCREL stays "in control", and calls the
  971. programmer's input and output routines, rather than vice-versa) because it is
  972. more consistent with the nature of the LZW algorithm.  The algorithm may make
  973. 1, 2 or 3 consecutive calls for input without outputting anything, & then may
  974. output any number of characters before needing more input.
  975.  
  976. Since an individual call is made for each byte needed or supplied, the user's
  977. routines can refill (or dump out) any input or output buffers at any
  978. appropriate time.  If the programmer decides to terminate the uncrunch
  979. operation before its natural completion, it is simply necessary to reset the
  980. stack pointer and continue rather than RETurning to UNCREL. More detailed
  981. description of operation follows:
  982.  
  983.  
  984.  
  985.  
  986.  
  987.  
  988.  
  989.  
  990.  
  991.  
  992.  
  993.                       14
  994.  
  995. Programmer Supplied Routines, declared "PUBLIC".
  996.  
  997. 1.  One must be named "GETBYT".  Each time this routine gets called by UNCREL,
  998. it should supply the next sequential byte in "A".  The routine may make full
  999. use of all registers, but should not assume that they will be in any particular
  1000. state the next time the routine is called. Basically, any pointers, etc.,
  1001. should be memory based. Note, however, that all usage of the alternate Z-80
  1002. registers has been eliminated from UNCREL.  Thus an "alternate" scheme is to
  1003. execute an EXX instruction at the beg and end of "GETBYT", in which case the
  1004. registers will remain intact.
  1005.  
  1006. 2.  Another routine must be named "OUT".  UNCREL calls this routine each time
  1007. it has a new character available for output.  The character will be in register
  1008. "A".  All other conditions are as described above.
  1009.  
  1010. What you (the programmer) must do:
  1011.  
  1012. Simply make a single call to "UNCREL", which should be declared "EXTRN".  This
  1013. will initialize all tables, and then all activity will proceed until the file
  1014. is completely uncrunched or an error is encountered.  At that point, UNCREL
  1015. will return to your program.  If the carry flag is set, this was an error
  1016. return.  In this case reg "A" will contain a [non-zero] code identifying the
  1017. type of error, if you are interested.  If carry is clear, A will be zero, and
  1018. this indicates that the entire operation has terminated normally.
  1019.  
  1020. What else you must do:
  1021.  
  1022. BEFORE you make the call to UNCREL mentioned above, you should load "HL" with a
  1023. pointer to a large block of memory (24k).  The rest of the work is taken care
  1024. of - UNCREL will figure the next page boundary and allocate various pointer for
  1025. various tables it will build itself.  It will also allocate a large stack area
  1026. for itself within this block, and will initialize all any ram locs it needs.
  1027. All of this is done at "run time".  UNCREL can be reexecuted multiple times if
  1028. desired.  Your stack will be returned to its previous value if UNCREL returns
  1029. (either due to completion or error).  If you decide to interrupt operation by
  1030. not returning from one of its "GETBYT" or "OUT" calls, however, don't forget to
  1031. reset the stack to your own value.
  1032.  
  1033. Another EXTRN value named "ENDU" is made available for possible use. It is the
  1034. end of the data area (DSEG) used by UNCREL.  If you link in such a way that
  1035. UNCREL is "on top", then this can be used as a reference for the beg of
  1036. available memory after the program.
  1037.  
  1038.  
  1039. More notes:
  1040.  
  1041. Every byte of a crunched file, starting with the 76H and 0FEH header bytes,
  1042. must be supplied in order.  The header information is checked for some
  1043. validity, although the file name is ignored.  UNCREL will determine the
  1044. version# when it gets to it and uncrunch accordingly, you needn't worry about
  1045. this. If you need the filename, you must extract it yourself.  The exact format
  1046. of a crunched file is defined as a separate document LZDEF20.DOC.  UNCREL does
  1047. NOT read or compute the checksum, if that interests you you can do that
  1048. yourself too. (Note: CRUNCH.COM & UNCR.COM v2.0 are not directly based on
  1049. UNCREL.  They always create and check the checksum respectively, of course).
  1050.  
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.                       15
  1060.  
  1061. More notes:
  1062.  
  1063. The LZW process is a continuously progressing forward process.    You cannot go
  1064. back.  If you leave out just one byte, you will get results which become
  1065. stranger and stranger, eventually becoming complete gibberish.    (This is
  1066. actually pretty interesting to watch, albeit frustrating if its not what you
  1067. want).
  1068.  
  1069.  
  1070.  
  1071.  
  1072.  
  1073.  
  1074.  
  1075.  
  1076.  
  1077.  
  1078.  
  1079.  
  1080.  
  1081.  
  1082.  
  1083.  
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099.  
  1100.  
  1101.  
  1102.  
  1103.  
  1104.  
  1105.  
  1106.  
  1107.  
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.                       16
  1126.  
  1127.              UNLZH.REL AND CRLZH.REL DOCUMENTATION
  1128.            For Version 2.0 (with RUNTIME buffer allocation)
  1129.               (From LT30.LBR: LZHREL.DOC)
  1130.  
  1131.  
  1132.                   July    1991
  1133.  
  1134.                    Abstract
  1135.  
  1136. UNLZH.REL and CRLZH.REL contain assembly language routines for the decoding and
  1137. generation of LZH-encoded files, respectively.    The routines need only be
  1138. supplied with a pointer to a large scracth area and linkages to character input
  1139. and character output routines to be used.  There are a few easily met
  1140. functional requirements for the calling routine and I/O routine.
  1141.  
  1142. No Z80 opcodes are used, so these routines may be used on 8080/8085/V20/Z80
  1143. based machines.
  1144.  
  1145. The coding contained within UNLZH.REL and CRLZH.REL are Copyright (c) 1989,
  1146. 1991 by Roger Warren and may not be used or reproduced on a for-profit basis.
  1147. Non-profit use is freely permitted.  The author will not be responsible for any
  1148. damage, loss, etc.  caused by the use of these programs.
  1149.  
  1150.  
  1151.                Version History and Compatibility
  1152.  
  1153. Version 1.1 was released in Sept. '89 and was the first public offering of LZH
  1154. encoding for CP/M.
  1155.  
  1156. Version 2.0 (July '91) introduces several improvements/changes:
  1157.     More efficient encoding
  1158.     Greater speed
  1159.     More compact object code
  1160.  
  1161. There are NO interface changes from the 1.x version.
  1162.  
  1163. Of greatest importance is the encoding improvement.  This change, while
  1164. generating even smaller output files, means that files compressed with version
  1165. 2.x programs cannot be decoded by old 1.x programs.
  1166.  
  1167. However, the version 2.x UNLZH module DYNAMICALLY ADJUSTS for 1.x encoded input
  1168. files.    Thus, version 2.x of UNLZH can be used on all LZH-encoded files
  1169. regardless of which algorithm version was used to encode the files.
  1170.  
  1171. By extensive rewriting for size and speed, a 20% improvement in performance was
  1172. achieved.  Since the LZH algorithm is intrinsically slow, this will be of great
  1173. interest to many.  The recoding project allowed the incorporation of version
  1174. 2.x extensions to the original algorithm while not appreciably affecting the
  1175. code module size.
  1176.  
  1177.  
  1178.  
  1179.  
  1180.  
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.                       17
  1192.  
  1193.                    Care and Feeding
  1194.  
  1195. The infomation that follows documents both CRLZH.REL and UNLZH.REL.  One or
  1196. both may be in the library this file is in, depending upon the nature of the
  1197. program(s) it's bundled with...so ignore the superfluous information (if any).
  1198.  
  1199. UNLZH.REL performs LZH decoding.  It's progamming interface is similar to the
  1200. UNCR.REL it was made to mimic.    The programmer must provide the program with 8k
  1201. of buffer space.  If RUNTIME buffer allocation is selected (it IS selected in
  1202. the version supplied with LT, FCRLZH, CRLZH, and UCRLZH), a pointer to the
  1203. buffer must be supplied in the H/L register pair when the routine is invoked.
  1204. If RUNTIME buffer allocation is not selected, the user must supply a PUBLIC
  1205. symbol, UTABLE, which is the base of the provided buffer area.
  1206.  
  1207. Once invoked, the routine allocates its own stack and 'stays in control' until
  1208. the de-compression is completed (or an error is encountered).  The programmer
  1209. must supply two routines GLZHUN and PLZHUN, via which UNLZH 'GETS' bytes from
  1210. the input stream and 'PUTS' bytes to the output stream, respectively.
  1211.  
  1212. UNLZH *DOES NOT* compute/process checksums, etc. on the  input file.  Any
  1213. support of such features must be handled externally.
  1214.  
  1215. GLZHUN and PLZHUN should save all registers except the A register and flags.
  1216. GLZHUN must return the next character from the input stream in the A register.
  1217. GLZHUN should return with the CARRY flag RESET for a valid character, or with
  1218. the CARRY flag SET when the end of the input stream is encountered (the content
  1219. of the A reg should be zero in that case).
  1220.  
  1221. Upon exit (return to the caller), UNLZH returns the following information:
  1222.  
  1223.        Carry reset (or A reg = 0) - Success
  1224.        Carry set,  A reg = 1      - Newer version required
  1225.        Carry set,  A reg = 2      - File not LZH endocoded
  1226.        Carry set,  A reg = 3      - Bad or corrupt file
  1227.        Carry set,  A reg = 4      - Insufficient memory
  1228.  
  1229. UNLZH has 2 entry points, to be used as the programmer needs:
  1230.  
  1231.     UNLZH is the 'normal' entry point which expects the file to be completely
  1232.     REWOUND.  At this entry point, the entire file is processed - the standard
  1233.     header is examined, but not reported or acted upon.  By examining the
  1234.     return code, the programmer can discern if the file was, indeed, an
  1235.     LZH-encoded file and act accordingly.
  1236.  
  1237.     UNL is a secondary entry point which can be used when the programmer needs
  1238.     to process the standard header information (file name and stamp) and cannot
  1239.     (or doesn't want to) rewind the file.  When this entry point is invoked,
  1240.     the header (down to and including the stamps/comment terminating zero) must
  1241.     have been processed (so the next byte in the input stream will be the
  1242.     revision level).
  1243.  
  1244. The revision level of UNLZH.REL performs is at the byte at UNLZH-1.  A hex
  1245. value of 11 indicates version 1.1, etc.
  1246.  
  1247.  
  1248.  
  1249.  
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.                       18
  1258.  
  1259. CRLZH.REL performs LZH encoding.  It's progamming interface is similar to the
  1260. CRUNCH.REL it was made to mimic. The programmer must provide the program with
  1261. 20k of buffer space.  If RUNTIME buffer allocation is selected (it IS selected
  1262. in the version supplied with LT, FCRLZH, CRLZH, and UCRLZH),a pointer to the
  1263. buffer must be supplied in the H/L register pair when the routine is invoked.
  1264. If RUNTIME buffer allocation is not selected, the user must supply a PUBLIC
  1265. symbol, CTABLE, which is the base of the provided buffer area.
  1266.  
  1267. In addition, at invocation time the A register must contain a value for CRLZH
  1268. to install in the 'CHECKSUM FLAG' portion of the file header (see below).  This
  1269. byte, to be semi-compatible with C.B. Falconer's version of CRN for the 8080,
  1270. is a subset of CRN's strategy byte:
  1271.  
  1272. value (hex)   meaning
  1273. 00          Standard modulo 65536 checksum is used
  1274. 10          CRC16 is used
  1275. 20,30          Unassigned
  1276.  
  1277. SUPPORT FOR CHECK INFORMATION MUST BE EXTERNALLY PROVIDED IN THE USER-SUPPLIED
  1278. I/O ROUTINES (see below).  THIS IS ALSO TRUE OF CRN...BUT WAS NOT EMPHASIZED!
  1279. CRLZH merely provides the support for posting the value in the output stream
  1280. since it happens to 'follow' some of the information posted by CRLZH (see the
  1281. header description, below).
  1282.  
  1283. CRLZH supports no other features of the CRN's strategy byte, all other bits are
  1284. ignored.
  1285.  
  1286. Once invoked, the routine allocates its own stack and 'stays in control' until
  1287. the de-compression is completed (or an error is encountered).  The programmer
  1288. must supply two routines GLZHEN and PLZHEN, via which CRLZH 'GETS' bytes from
  1289. the input stream and 'PUTS' bytes to the output stream, respectively.
  1290.  
  1291. CRLZH *DOES NOT* compute/process checksums, etc. on the  input file.  Any
  1292. support of such features must be handled externally.  Specifically, the GLZHEN
  1293. routine must provide for the accumulation of check information and the caller
  1294. must write that check information to the output stream when CRLZH returns to
  1295. the caller.
  1296.  
  1297. GLZHEN and PLZHEN should save all registers except the A register and flags.
  1298. GLZHEN must return the next character from the input stream in the A register.
  1299. GLZHEN should return with the CARRY flag RESET for a valid character, or with
  1300. the CARRY flag SET when the end of the input stream is encountered (the content
  1301. of the A reg should be zero in that case).  As a service to the user's output
  1302. processor, every 256th call to PLZHEN is made with the Z flag set (for
  1303. monitoring).  All other times the Z flag is reset.
  1304.  
  1305. Upon exit (return to the caller), CRLZH returns the following information:
  1306.  
  1307.        Carry reset (or A reg = 0) - Success
  1308.        Carry set,  A reg = 1      - File already LZH-Encoded,CRUNCHed or
  1309.                     SQueezed
  1310.        Carry set,  A reg = 2      - File empty
  1311.        Carry set,  A reg = 3      - Insufficient memory
  1312.  
  1313. CRLZH has a single entry point at the label CRLZH.  The user must have placed
  1314. the standard header information in the output stream and must have the input
  1315. stream REWOUND prior to invoking CRLZH.
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.                       19
  1324.  
  1325. The revision level of CRLZH.REL performs is at the byte at CRLZH-1.  A hex
  1326. value of 11 indicates version 1.1, etc.
  1327.  
  1328. Since CRLZH and UNLZH allocate their own stacks, the user is reminded not to
  1329. make too large a use of that stack in the user-supplied I/O routines.  In
  1330. addition, if the user-supplied I/O routines decide to abort the CRLZH or UNLZH
  1331. operation (due to operator keystrokes, for example), the user must take steps
  1332. to restore his own stack.  Upon a normal (or error) return from CRLZH or UNLZH
  1333. the user's stack is properly restored.
  1334.  
  1335.  
  1336.               STANDARD HEADER information
  1337.  
  1338. LZH encoding follows Steve Greenberg's CRUNCH file format.  The header contains
  1339. information identifying compression format, original file name, etc:
  1340.   field  size      value    Purpose
  1341. ------- --------- -------- -------------------------------------------------
  1342.     1    1 byte      076h       Signifies compressed form
  1343.     2    1 byte      0FDh       Signifies LZH encoding (0ff is for squeezed and
  1344.                0feh is for CRUNCHED)
  1345.     3    variable  User       Original file name in the form name.ext Trailing
  1346.          supplied  blanks on the name portion should be suppressed,
  1347.                but a full 3 characters following the '.' should
  1348.                be used for the extension (i.e. no blank
  1349.                suppression).
  1350.     4    variable  User       OPTIONAL.  Used for file comment/stamp.  If used
  1351.                the convention is that the comment is placed in
  1352.                square brackets [Like this].  Other information
  1353.                may be placed here (e.g., date stamp).  The
  1354.                logical restriction is that a binary zero must
  1355.                not be part of the comment and/or other informa-
  1356.                tion.
  1357.     5    1 byte       00h       Signifies end of STANDARD HEADER
  1358.  
  1359. For use of CRLZH, the user must supply all of the information above.
  1360.  
  1361. For UNLZH, use of the UNLZH entry point causes UNLZH to expect to process the
  1362. above information.  It will discard the file name and optional comment/stamp,
  1363. but will examine the general form (first 2 fields for a match and general form
  1364. of the rest of the header).  If the user chooses to use the UNL entry point,
  1365. UNL will expect to process the first byte following the end of the standard
  1366. header.
  1367.  
  1368. What follows is the following:
  1369.  
  1370.   field  size      value    Purpose
  1371. ------- ------- ---------- --------------------------------------------  
  1372.     6    1 byte    variable   Identifies generating program revision level.
  1373.                (11H signifies program generated by version 1.1
  1374.     7    1 byte    variable   Significant revision level.    Indicates major
  1375.                revision level of algorithm for decoding program
  1376.                compatability. (10h indicates significant
  1377.                revision 1.0)
  1378.     8    1 byte    variable   Check type.    0=checksum, 1=CRC16, others
  1379.                currently undefined.
  1380.     9    1 byte       05h       Currently a SPARE, set to 05H by convention.
  1381.  
  1382. Following this is the compressed file, itself.
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.                       20
  1390.  
  1391.  
  1392.          What LZH compression does and how it compares
  1393.  
  1394. FIRST - It's SLOW.  Much slower than CRUNCH.  About even with the old SQueeze.
  1395. It's the nature of the algorithm, but the current implementation contributes
  1396. somewhat (more on that later).
  1397.  
  1398. The most impressive aspect of the algorithm is that it compresses further than
  1399. CRUNCH.  The nature of material being compressed is important - prose and high
  1400. level language code will compress further.  Since the algorithm depends, in
  1401. part, on patterns within the file being compressed, I was somewhat surprised to
  1402. discover that it does a better job (in general) on .COM files than CRUNCH.
  1403. Personally, I was surprised to discover that LZH compression of CRUNCHed files
  1404. is possible (but I've disabled that ability in this release)!
  1405.  
  1406. Examples:
  1407.  CRUNCH of SLR180.COM    106% ratio   (actually made a larger file)
  1408.  CRLZH    of SLR180.COM     84% ratio
  1409.  CRUNCH of TYPELZ22.Z80  45% ratio
  1410.  CRLZH    of TYPELZ22.Z80  40% ratio
  1411.  CRUNCH of 'C' source     45% ratio   (typical 'C' src selected at random)
  1412.  CRLZH    of 'C' source     33% ratio   (same file as above)
  1413.  
  1414.  
  1415.                 A small history
  1416.  
  1417. I am NOT the originator of the LZH encoding.  The program that started my whole
  1418. involvement in the introduction of this method of compression to the 8-bit
  1419. world bears the following opening comments:
  1420.    /*
  1421.    * LZHUF.C English version 1.0
  1422.    * Based on Japanese version 29-NOV-1988
  1423.    * LZSS coded by Haruhiko OKUMURA
  1424.    * Adaptive Huffman Coding coded by Haruyasu YOSHIZAKI
  1425.    * Edited and translated to English by Kenji RIKITAKE
  1426.    */
  1427.  
  1428. This 'C' program implemented the compression algorithm of the LHARC program
  1429. which arrived on the US scene in the spring of '89.
  1430.  
  1431. Being of a curious nature, I figured I'd play with the algorithm just to
  1432. understand it (the internal comments were, indeed, sparse - leaving MUCH to the
  1433. reader's contemplation/reverse engineering) while 'better minds' than I tackled
  1434. it in earnest.
  1435.  
  1436. Months passed.    I found that I was 'mastering' the algorithm (read that as
  1437. demonstrating to myself that I understood it) by converting it piece-wise to
  1438. assembly language.  After a while, I was left with a 'C' language main program,
  1439. run time library, and I/O with the business end of the compression and
  1440. decompression implemented entirely in assembly language.  Since the expected
  1441. event of one of the 'heavies' in the PD and/or compression world releasing a
  1442. CP/M version of the compression algorithm hadn't come to pass, I set about
  1443. making a version myself.
  1444.  
  1445. The natural choice was to prepare an analog to the CRUNCH.REL and UNCR.REL of
  1446. Mr. Steven Greenberg and Mr. C.B. Falconer and append to/substitute in the
  1447. existing, widely known programs for handling SQueezed and/or CRUNCHed files.
  1448.  
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.                       21
  1456.  
  1457. I saw no reason to tamper with the format CRUNCH uses on the output file.
  1458. Therefore, with the exception of taking the 'next' file type in sequence
  1459. (SQueezed files begin with a 76h,FFh sequence; Crunched files with 76h,FEh; so
  1460. LZH encoded files begin with 076h,FDh) and setting the revision levels in the
  1461. header to appropriate values , there's no difference in the output file format.
  1462. So, you can probably coax your time/date stamping into operating on LZH encoded
  1463. files.
  1464.  
  1465. R. Warren
  1466. Sysop, The Elephant's Graveyard (Z-Node#9)
  1467. 619-270-3148 (PCP area CASDI)
  1468.  
  1469.  
  1470.  
  1471.  
  1472.  
  1473.  
  1474.  
  1475.  
  1476.  
  1477.  
  1478.  
  1479.  
  1480.  
  1481.  
  1482.  
  1483.  
  1484.  
  1485.  
  1486.  
  1487.  
  1488.  
  1489.  
  1490.  
  1491.  
  1492.  
  1493.  
  1494.  
  1495.  
  1496.  
  1497.  
  1498.  
  1499.  
  1500.  
  1501.  
  1502.  
  1503.  
  1504.  
  1505.  
  1506.  
  1507.  
  1508.  
  1509.  
  1510.  
  1511.  
  1512.  
  1513.  
  1514.  
  1515.  
  1516.  
  1517.     5MBHD-C/PDCPM9:LT31.LBR;  LT31.DOC revised BCM 2057 16/12/1991
  1518. 
  1519.  
  1520.  
  1521.  
  1522.  
  1523.