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 / UNARC12A.LBR / UNARC.IZF / UNARC.INF
Text File  |  2000-06-30  |  22KB  |  529 lines
  1. File:     UNARC.INF
  2. Subject:  Technical Information for UNARC Program
  3. Version:  1.2
  4. Date:     June 24, 1986
  5. ------------------------------------------------------------------------------
  6.  
  7.  
  8.                                     UNARC
  9.  
  10.                      CP/M Archive File Extraction Utility
  11.  
  12.  
  13.                     Copyright (C) 1986 by Robert A. Freed
  14.                              All Rights Reserved
  15.  
  16.  
  17.  
  18. This file provides supplementary technical information of interest to 
  19. programmers and advanced users, particularly RCPM (Remote CP/M) system 
  20. operators, relating to UNARC version 1.2, which was released June 24, 1986.
  21.  
  22. Primary user documentation is provided by the associated file UNARC.DOC.  
  23. Refer to the notice in that file regarding rights of use and distribution of 
  24. this program.  The file UNARC12.MSG contains a list of all files distributed 
  25. with the current UNARC release.
  26.  
  27.  
  28.  
  29. MEMORY REQUIREMENTS
  30. -------------------
  31.  
  32. The UNARC.COM file (Z80 version) occupies 4K bytes of disk storage.  A minimum 
  33. TPA size of slightly more than 4K bytes is needed to obtain the directory 
  34. listing of an archive file.  File extraction requires additional TPA space, 
  35. with the exact amount dependent upon the version of the compression method 
  36. used to store an extracted file (reported by the "Ver" column of a directory 
  37. listing), as shown in the following table:
  38.  
  39.              Version  Stowage        Min. TPA Size  Min. CP/M Size
  40.              -------  -------------  -------------  --------------
  41.                1,2    Unpacked             6K             13K
  42.                 3     Packed               6K             13K
  43.                 4     Squeezed             7K             14K
  44.               5,6,7   Crunched (old)      26K             33K
  45.                 8     Crunched (new)      18K             25K
  46.  
  47. The alternate UNARCA.COM file (8080 version) occupies 5K bytes of disk storage 
  48. and requires approximately 1K bytes more TPA space for file extraction than is 
  49. shown above for the standard version.
  50.  
  51. Any additional TPA space is used for buffering the output file, which provides 
  52. better performance in systems with larger memories.  By default UNARC does not 
  53. utilize the upper 2K bytes of TPA space (which it assumes is occupied by the 
  54. CCP), and it returns directly to the CCP instead of forcing a warm boot after 
  55. program execution.  The last column in the above table, which specifies the 
  56. minimum required standard CP/M 2.2 system size, reflects this fact.  For very 
  57. small systems, a patch may be made which allows UNARC to overlay the CCP (and 
  58. hence reduces the minimum required system size by 2K), at the expense of a 
  59. warm boot following each use of the program (see next section).
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67. File:  UNARC.INF                                                   Page 2 of 8
  68. ------------------------------------------------------------------------------
  69.  
  70.  
  71. Note that the worst-case memory requirement is for crunched files created by 
  72. older releases of the MS-DOS ARC program (prior to program version 5.0, dated 
  73. January 1986).  The newer method of generating crunched files not only reduces 
  74. UNARC's memory requirements by 8K bytes, but offers significant speed and 
  75. compression improvements.  As older ARC files are converted to the newer 
  76. compression method, the likelihood of encountering such files should diminish.
  77.  
  78. UNARC always checks the amount of available memory during execution, and it 
  79. will abort gracefully with a "Not enough memory" message if necessary.
  80.  
  81.  
  82.  
  83. OPTIONAL PATCHES
  84. ----------------
  85.  
  86. Several options are provided, primarily to allow safe use of UNARC on RCPM 
  87. systems.  These are specified by data variables at the beginning of the 
  88. program, which simplifies patching with DDT or ZSID (or whatever) without 
  89. requiring re-assembly of the source.  The following table shows the location, 
  90. symbolic name, and default value of each of these options, which are discussed 
  91. in greater detail below:
  92.  
  93. Address   Name    Default   Description
  94. -------   -----   -------   -----------
  95.  103H     CCPSV     08H     No. of high memory pages to preserve (8 = 2K)
  96.  104H     BLKSZ     00H     Default disk allocation block size / 1K
  97.  105H     HIDRV     10H     Highest input file drive no. (1=A, 2=B, .., 10H=P)
  98.  106H     HODRV     10H     Highest output file drive no. (0 = no extracts)
  99.  107H     TYFLG     FFH     Typeout flag (0 = no typeout allowed)
  100.  108H     TYPGS     00H     No. buffer pages for file typeout (0 = maximum)
  101.  109H     TYLIM     00H     Line limit for file typeout (0 = none)
  102.  10AH     WHEEL    0106H    Address of "wheel" byte
  103.  
  104.  10CH     NOTYP    'COM'    Table of typeout-excluded filetypes...
  105.  10FH              'CMD'
  106.  112H              'EXE'
  107.  115H              'OBJ'
  108.  118H              'OV?'
  109.  11BH              'REL'
  110.  11EH              '?RL'
  111.  121H              'INT'
  112.  124H              'SYS'
  113.  127H              'BAD'
  114.  12AH              'LBR'
  115.  12DH              'ARC'
  116.  130H              '?Q?'
  117.  133H              0,0,0    Room for additional filetypes...
  118.  136H              0,0,0
  119.  139H              0,0,0
  120.  13CH              0,0,0
  121.  13FH              0,0,0
  122.  142H              0,0,0
  123.  145H              0,0,0
  124.  148H                0      (End of table marker)
  125.  
  126.  149H     USAGE             Start of help message
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133. File:  UNARC.INF                                                   Page 3 of 8
  134. ------------------------------------------------------------------------------
  135.  
  136.  
  137. CCPSV:  This value specifies the number of (256-byte) pages to reserve at the 
  138.         top of the TPA.  The default value (8) corresponds to a reserved area 
  139.         of 2K bytes, which is appropriate for the CCP size in standard CP/M 
  140.         2.2 systems.  Setting this value to zero yields an additional 2K bytes 
  141.         of buffer space for file extraction, but forces a warm boot system 
  142.         return following program execution, and need be used only with very 
  143.         small systems.  (Setting this byte to zero may also be desirable with 
  144.         CP/M 3.0 or any non-standard system with a permanently-resident CCP.)
  145.  
  146. BLKSZ:  This value provides the default disk allocation block size (as a 
  147.         multiple of 1K bytes) to use in calculating disk space requirements 
  148.         for archive directory listings ("Disk" column), when no output drive 
  149.         is specified.  A zero value (the default) indicates that the block 
  150.         size of the default (CCP) disk drive is to be used for this purpose, 
  151.         unless the wheel byte is zero, in which case a value of 1 is used.  
  152.         (Since 1K is the minimum disk block size in any CP/M system, this 
  153.         provides the widest applicability for all remote users of an RCPM, 
  154.         independent of the system's actual disk block size.)
  155.  
  156. HIDRV:  Specifies the highest allowable drive no. for archive files, where 
  157.         drive A is 1, drive B is 2, etc.  Setting this to zero restricts input 
  158.         to the default drive (i.e. disallows drive names in the archive file 
  159.         parameter).  Most RCPM systems need not alter this byte, since invalid 
  160.         drive accesses are normally intercepted elsewhere.  If this is not the 
  161.         case, this value should be set to the number of available drives 
  162.         (assuming all sequential drives are available, starting with drive A).
  163.  
  164. HODRV:  Specifies the highest allowable output drive no. for file extraction 
  165.         operations (specified as for HIDRV above).  Setting this to zero will 
  166.         disallow any file extraction (which is the obvious setting of 
  167.         importance on RCPM systems).  However, this is necessary only if a 
  168.         wheel byte is not implemented.  If the wheel byte is zero, a zero 
  169.         value for HODRV is automatically assumed.
  170.  
  171. TYFLG:  The default value of this flag (0FFH) enables typeout of a single 
  172.         (unambiguous) file in an archive, if no drive name is specified (and 
  173.         the filetype is not excluded by the NOTYP table).  RCPM systems may 
  174.         set this to zero to disallow file typeout operations.  (However, 
  175.         typeout is always permitted if the wheel byte is non-zero.)
  176.  
  177. TYPGS:  This value specifies the number of (256-byte) pages to buffer an 
  178.         extracted file during typeout operations.  The default zero value 
  179.         provides the maximum possible buffering (the entire TPA space), but 
  180.         may cause a long delay at the start (and in the middle) of typeout of 
  181.         very large files.  Setting this value to 1 will minimize viewing 
  182.         waits, but may cause excessive stop/start of floppy disk drive motors 
  183.         on some systems (e.g. Kaypro).  For RCPM systems, if this value is 
  184.         zero and the wheel byte is zero, a value of 1 is assumed (which 
  185.         minimizes delays for remote users).
  186.  
  187. TYLIM:  This value may be set non-zero to enforce a limit on the number of 
  188.         text lines (up to 255) which may be viewed for file typeout.  This may 
  189.         be desired by some RCPM systems, to discourage excess "browsing" in 
  190.         favor of downloading of files by callers.  If the wheel byte is non- 
  191.         zero, no limit is enforced.
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199. File:  UNARC.INF                                                   Page 4 of 8
  200. ------------------------------------------------------------------------------
  201.  
  202.  
  203. WHEEL:  This word specifies the address of a "wheel" byte in memory.  Most 
  204.         RCPM systems implement such a byte to protect privileged functions 
  205.         from remote callers and to provide greater flexibility for the sysop.  
  206.         If the wheel byte is zero, no file extraction is allowed (as if HODRV 
  207.         value = 0), and the BLKSZ and/or TYPGS values are assumed to be 1 (if 
  208.         these are not changed from their default zero values).  If the wheel 
  209.         byte is non-zero, the TYFLG and TYLIM values are not enforced (i.e. 
  210.         unlimited file typeout is allowed).  Use of this address to specify a 
  211.         wheel byte external to UNARC permits a single copy of the program to 
  212.         be used by both the sysop (wheel byte non-zero) and remote users 
  213.         (wheel byte zero).  (ZCPR3 users should set this to the address of 
  214.         their Z3WHL byte, as determined by running SHOW.COM.)  If no such 
  215.         wheel byte is implemented, a secure version of UNARC may still be 
  216.         created by leaving WHEEL at its default value and setting the HODRV 
  217.         byte to zero.  (In this case, the sysop will require a second version 
  218.         of the program for unrestricted use.)
  219.  
  220. NOTYP:  This is a table of filetypes (3-byte strings) which are disallowed for 
  221.         typeout.  Storage is provided for 20 such filetypes, with 13 types 
  222.         predefined.  Additional filetypes may be added at the end of the 
  223.         table, or existing types may be replaced.  (To remove one of the pre-
  224.         defined types without replacing it, simply set the msb in any byte.)  
  225.         The table must terminate with a zero byte.
  226.  
  227. USAGE:  This is the on-line help message which is displayed when UNARC is run 
  228.         with an empty command line.  No changes should be made to this text.  
  229.         In particular, the author requests that his copyright notice be 
  230.         preserved (despite the ease with which it may be patched out).  Note 
  231.         that the help information relating to file extraction and/or typeout 
  232.         is automatically removed if the corresponding operations are 
  233.         disallowed (i.e. by zero values of HODRV, TYDRV, and/or wheel byte).
  234.  
  235.  
  236.  
  237. RE-RUNNING UNARC
  238. ----------------
  239.  
  240. The UNARC program is completely self-initializing.  Once loaded, it may be 
  241. re-executed multiple times, e.g. by a zero-length COM file or with the "GO" 
  242. command in ZCPR systems.
  243.  
  244.  
  245.  
  246. ARCHIVE FILE FORMAT
  247. -------------------
  248.  
  249. Component files are stored sequentially within an archive.  Each entry is 
  250. preceded by a 29-byte header, which contains the directory information.  There 
  251. is no wasted space between entries.  (This is in contrast to the centralized 
  252. directory used by Novosielski libraries.  Although random access to subfiles 
  253. within an archive can be noticeably slower than with libraries, archives do 
  254. have the advantage of not requiring pre-allocation of directory space.)
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265. File:  UNARC.INF                                                   Page 5 of 8
  266. ------------------------------------------------------------------------------
  267.  
  268.  
  269. Note that UNARC uses CP/M random disk reads (BDOS function 33) to rapidly skip 
  270. through the entries of an archive.  For this reason, the program requires CP/M 
  271. version 2.0 or higher and will reject attempted execution under earlier 
  272. versions of CP/M.  Archive entries are normally maintained in sorted name 
  273. order (although UNARC does not utilize this fact to any advantage).
  274.  
  275. The format of the 29-byte archive header is as follows: 
  276.  
  277. Byte 1:  1A Hex.
  278.          This marks the start of an archive header.  If this byte is not found 
  279.          when expected, UNARC will scan forward in the file (up to 64K bytes) 
  280.          in an attempt to find it (followed by a valid compression version).  
  281.          If a valid header is found in this manner, a warning message is 
  282.          issued and archive file processing continues.  Otherwise, the file is 
  283.          assumed to be an invalid archive and processing is aborted.  (This is 
  284.          compatible with MS-DOS ARC version 5.12).  Note that a special 
  285.          exception is made at the beginning of an archive file, to accomodate 
  286.          "self-unpacking" archives (see below).
  287.  
  288. Byte 2:  Compression version, as follows:
  289.  
  290.          0 = end of file marker (remaining bytes not present)
  291.          1 = unpacked (obsolete)
  292.          2 = unpacked
  293.          3 = packed
  294.          4 = squeezed (after packing)
  295.          5 = crunched (obsolete)
  296.          6 = crunched (after packing) (obsolete)
  297.          7 = crunched (after packing, using faster hash algorithm) (obsolete)
  298.          8 = crunched (after packing, using dynamic LZW variations)
  299.  
  300. Bytes 3-15:  ASCII file name, nul-terminated.
  301.  
  302. (All of the following numeric values are stored low-byte first.)
  303.  
  304. Bytes 16-19:  Compressed file size in bytes.
  305.  
  306. Bytes 20-21:  File date, in 16-bit MS-DOS format:
  307.               Bits 15:9 = year - 1980
  308.               Bits  8:5 = month of year
  309.               Bits  4:0 = day of month
  310.               (All zero means no date.)
  311.  
  312. Bytes 22-23:  File time, in 16-bit MS-DOS format:
  313.               Bits 15:11 = hour (24-hour clock)
  314.               Bits 10:5  = minute
  315.               Bits  4:0  = second/2 (not displayed by UNARC)
  316.  
  317. Bytes 24-25:  Cyclic redundancy check (CRC) value (see below).
  318.  
  319. Bytes 26-29:  Original (uncompressed) file length in bytes.
  320.               (This field is not present for version 1 entries, byte 2 = 1.  
  321.               I.e., in this case the header is only 25 bytes long.  Because 
  322.               version 1 files are uncompressed, the value normally found in 
  323.               this field may be obtained from bytes 16-19.)
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331. File:  UNARC.INF                                                   Page 6 of 8
  332. ------------------------------------------------------------------------------
  333.  
  334.  
  335. SELF-UNPACKING ARCHIVES
  336. -----------------------
  337.  
  338. A "self-unpacking" archive is one which can be renamed to a .COM file and 
  339. executed as a program.  An example of such a file is the MS-DOS program 
  340. ARC512.COM, which is a standard archive file preceded by a three-byte jump 
  341. instruction.  The first entry in this file is a simple "bootstrap" program in 
  342. uncompressed form, which loads the subfile ARC.EXE (also uncompressed) into 
  343. memory and passes control to it.  In anticipation of a similar scheme for 
  344. future distribution of UNARC, the program permits up to three bytes to precede 
  345. the first header in an archive file (with no error message).
  346.  
  347.  
  348.  
  349. CRC COMPUTATION
  350. ---------------
  351.  
  352. Archive files use a 16-bit cyclic redundancy check (CRC) for error control.  
  353. The particular CRC polynomial used is x^16 + x^15 + x^2 + 1, which is commonly 
  354. known as "CRC-16" and is used in many data transmission protocols (e.g. DEC 
  355. DDCMP and IBM BSC), as well as by most floppy disk controllers.  Note that 
  356. this differs from the CCITT polynomial (x^16 + x^12 + x^5 + 1), which is used 
  357. by the XMODEM-CRC protocol and the public domain CHEK program (although these 
  358. do not adhere strictly to the CCITT standard).  The MS-DOS ARC program does 
  359. perform a mathematically sound and accurate CRC calculation.  (We mention this 
  360. because it contrasts with some unfortunately popular public domain programs we 
  361. have witnessed, which from time immemorial have based their calculation on an 
  362. obscure magazine article which contained a typographical error!)
  363.  
  364. Additional note (while we are on the subject of CRC's):  The validity of using 
  365. a 16-bit CRC for checking an entire file is somewhat questionable.  Many 
  366. people quote the statistics related to these functions (e.g. "all two-bit 
  367. errors, all single burst errors of 16 or fewer bits, 99.997% of all single 
  368. 17-bit burst errors, etc."), without realizing that these claims are valid 
  369. only if the total number of bits checked is less than 32767 (which is why they 
  370. are used in small-packet data transmission protocols).  I.e., for file sizes 
  371. in excess of about 4K bytes, a 16-bit CRC is not really as good as what is 
  372. often claimed.  This is not to say that it is bad, but there are more reliable 
  373. methods available (e.g. the 32-bit AUTODIN-II polynomial).  (End of lecture!)
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397. File:  UNARC.INF                                                   Page 7 of 8
  398. ------------------------------------------------------------------------------
  399.  
  400.  
  401. LIMITATIONS
  402. -----------
  403.  
  404. The current release of UNARC contains several minor limitations, which are 
  405. described below.  These suggest obvious areas for improvement, which may be 
  406. addressed in future releases of the program.
  407.  
  408. (1)  ZCPR-style drive/user specifications (du:) are not recognized.  All file 
  409.      operations are performed in the current user area.
  410.  
  411. (2)  No internal support is provided for printer output to the CP/M list 
  412.      device.  However, all console output is generated via BDOS function 2 
  413.      calls, so directory listings may be printed by typing CTRL-P at the CCP 
  414.      command level before executing UNARC.  But this will in general not be 
  415.      suitable for file typeout, as printer control characters such as BS and 
  416.      FF are filtered by the program.  The best way to obtain a printer listing 
  417.      of a file in an archive is to first extract the file to disk and then use 
  418.      PIP (or your favorite printer utility) to generate the listing.
  419.  
  420. (3)  The file typeout facility is admittedly primitive.  This is intentional, 
  421.      as the typeout operation was provided primarily to allow quick previewing 
  422.      of files.  However, if the program achieves any measure of popularity on 
  423.      RCPM systems, a paged mode of typeout (a la the public domain TYPEL 
  424.      program) will most certainly be added.
  425.  
  426. (4)  UNARC will not properly handle archive file sizes in excess of 23 bits 
  427.      (8 Megabytes).  Since this is the limit for file sizes under CP/M 2.2, I 
  428.      do not envision this as being a significant concern for the majority of 
  429.      users.  (Although, if you are a CP/M 3.0 user with a file that large, and 
  430.      you have enough disk space to store it, I suppose you have a real need 
  431.      for UNARC!  Sorry.)
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463. File:  UNARC.INF                                                   Page 8 of 8
  464. ------------------------------------------------------------------------------
  465.  
  466.  
  467. SOURCE CODE (AND AUTHOR'S RAMBLINGS)
  468. ------------------------------------
  469.  
  470. The source program file, UNARC.Z80, uses Zilog mnemonics (my preference) and 
  471. may be assembled with either the M80 (Microsoft) or Z80ASM (SLR Systems) macro 
  472. assemblers.  (Relocatable code features have been avoided, so conversion to 
  473. other assembler formats should be straightforward.)
  474.  
  475. I own a Z80-based machine and prefer not to limit its capabilities or restrict 
  476. my programming options.  However, in an attempt to offer the program to users 
  477. of 8080-based systems (a vocal minority in the world of CP/M public domain 
  478. software), I have modified the source so that an alternate non-Z80 version 
  479. (UNARCA.COM) may be generated by conditional assembly.  This is accomplished 
  480. through use of macro definitions which emulate the extended Z80 instruction 
  481. set on 8080/8085 machines.  No attempt has been made to optimize this 
  482. emulation for either size or speed, but it does work without impacting the 
  483. efficiency of the standard Z80 version.
  484.  
  485. I distribute the source code because I am a firm believer in disseminating 
  486. information to those interested enough to inspect it (and patient enough to 
  487. download it).  I hate to use a publicly-distributed program which I cannot 
  488. personally verify, and it pains me to see authors withhold their source code. 
  489. (For example, I could not have written this program without the availability 
  490. of the C language source for the MS-DOS ARC program.)  However, I have seen 
  491. too many high-quality programs "hacked" to death by untalented (though perhaps 
  492. well-meaning) amateurs, and I do not wish the same fate for my work.  It is 
  493. for this reason that I have placed certain caveats on the distribution of 
  494. modified versions of UNARC (see notice in UNARC.DOC).  This is not meant to 
  495. discourage sincere implementors:  Just drop me a line or give me a call, and I 
  496. will be happy to discuss and sanction any useful program modifications!
  497.  
  498.                            Bob Freed
  499.                            62 Miller Road
  500.                            Newton Centre, MA  02159
  501.                            Telephone (617) 332-3533
  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.