;
                                 UNARCZ.COM                                   

             Size (recs) CRC   Version    Author/Latest Issue      Disk
               5k (40)   3786  1.0        Gene Pizzetta 3/90       Z3COM14

  1- Syntax  2- Options  3- Functions  4- Configuration  5- Examples of Use   


   UNARCZ is a ZCPR3 archive file extractor.   It allows the listing, typeout, 
printing,  checking,  and extraction of member files contained in  ARK and ARC 
"archive" library files.   These are commonly used for compressed file storage 
on remote access bulletin boards.   UNARCZ requires  a version  of  ZCPR3  for 
command line parsing and wheel byte detection,  so it will not run properly on 
vanilla CP/M systems.  A Z80 CPU or compatible is required.

   UNARCZ requires  at least 30K of  free memory (TPA) for full support of all 
archive file formats,  but  smaller  systems  may be  able to  use some of the 
program's capabilities.
:1
    Syntax   UNARCZ {dir:}arcfile{.typ} {dir:}{afn.aft} {{/}N|P|C}
             UNARCZ or UNARCZ //   -->  help message

   If a DIR or DU specification is not given for the archive file, the current
drive/user is assumed.  The second filename, which can be ambiguous, refers to
a member file or files in the archive.

   If a  DU or DIR specification is provided for the member file,  it  will be
extracted to  that  directory.   To extract to the current directory,  only  a
colon is required.   If a directory specification is given without a filename,
all files (*.*) are assumed.

   If no DU or DIR specification is given,  UNARCZ  acts differently depending
on whether the  member  name  is  ambiguous  or  not.   If the member  name is
unambiguous, and the filetype is not restricted, the file will be typed to the
screen.   If the member name is  ambiguous,  or if no  member name is given at
all, a directory of the ARK will be displayed.

   If no filetype is given  for the archive file,  UNARCZ first tries  ARK and
then ARC.
:2
 Options - 1/2 

   The actions of UNARCZ are also affected by three  available options,  which
may or may not be preceded  by  a slash,  but  which  must  be the third token
(element) on the command line.  Only a single option may be used at a time.

     C    Check the validity of the archive and the given member files.

     N    Turn off console paging.   This  can  be especially handy it you are 
          extracting a large number of member files whose names fill more than 
          a single screen.   If you use  this option,  you  will  not  get the 
          "[more]" message and have to  hit  a  key  before  UNARCZ continues.  
          It's primary use, however,  is  when  you  want to scroll through an 
          ARK'ed text  file  using ^S to pause at the points you're interested 
          in.

     P    Sends  a member file to the  printer (LST device).   The member name 
          cannot be  ambiguous.   The file will be printed continuously,  with 
          any sort of formating or paging.
 Options - 2/2 


   UNARCZ can be aborted at any time with ^C or ^K.
 
   When UNARCZ pauses after 23 lines  of  console  output, the listing  may be 
resumed by typing any key other than ^S, ^C, or ^K.  The space bar may be used
to display one more line of console output  (overwriting the "[more]" message) 
and the program will again pause.   For hard copy terminals,  line feed may be 
used to  prevent  overprinting of the  "[more]"  line.   Screen  pauses can be 
turned off by using the "N" command line option (see above).
:3
 Functions:                                 Listing an Archive Directory - 1/5

   UNARC always produces a detailed console listing of all the member files of
an archive, or of those members which match the second file specification,  if 
one is given.  If no member name is given, or if the member name is ambiguous, 
then UNARCZ only lists the directory, without doing anything else.   (That is, 
unless the C option is included.)

A sample directory listing:

A0>UNARCZ CODES

Archive File = A0:CODES.ARK

Name           Length  Disk   Method  Ver  Stored Saved    Date    Time   CRC
============  =======  ====  ======== === ======= ===== ========= ======  ====
ABLE    .DOC    24320   24k  Crunched  8    11777  52%  30 Apr 86 10:50a  42C0
BRAVO   .COM    17152   17k  Squeezed  4    14750  14%   2 May 86  4:11p  8CBD
CHARLIE .TXT      234    1k   Packed   3       99  58%   2 May 86  4:11p  8927
        ====  =======  ====               =======  ===                    ====
Total      3    41706   42k                 26626  36%                    58A4
 Functions:                                 Listing an Archive Directory - 2/5
 
The listing is equivalent to the "verbose" listing of the  MS-DOS ARC program, 
with the addition of the "Disk" and  "Ver" fields,  which are unique to UNARCZ 
and  previous UNARC versions.   The  listing  requires  78-columns of terminal 
width.

"Name" is the  filename  which  will be generated if the  file is extracted by 
UNARCZ.   This is not necessarily the same as the name recorded in the archive 
file.   Although CP/M and MS-DOS file naming  conventions  are identical,  two 
conversions are made to guarantee filename validity:   Lower-case letters  are 
converted to upper-case and  non-printing  characters are  converted to dollar 
signs ("$").   Archive  entries  are  usually  maintained  and  so  listed  in 
alphabetical order.

"Length" is the uncompressed file length,  i.e.,  the number of bytes the file 
will occupy if extracted to  disk,  exclusive of any additional length imposed 
by the file system.   MS-DOS permits  files  of  arbitrary  lengths,  but CP/M 
restricts files to multiples of 128 bytes.
 Functions:                                 Listing an Archive Directory - 3/5

"Disk" is the  actual amount of space  required  to extract the file to a CP/M 
disk, expressed as a multiple of 1K (1024) bytes.   The number is dependent on 
the output  drive's allocation  block  size,  which can range  from  1K to 16K 
bytes.   Typically, 1K is used for single-density floppy disks, 2K for double-
density floppies, and 4K for hard disks.  In the absence of an explicit output 
drive, UNARCZ uses the block size of the currently logged drive.

"Method" is the  compression  method  used:  "Unpacked", "Packed", "Squeezed", 
"Crunched", "Squashed", or "Unknown!".   If the method "Unknown!" appears,  it 
likely indicates  a faulty archive file or  a newer compression method not yet 
supported by UNARCZ.

"Ver" is the version of compression method used.  UNARC supports versions 1-9:
unpacked files,  versions 1 or 2;  packed files,  version 3;  squeezed  files, 
version 4; crunched files, versions 5-8; and squashed files, version 9.
 Functions:                                 Listing an Archive Directory - 4/5

"Stored" is the compressed file length,  that is, the number of bytes occupied 
by the file in the archive,  not including the directory information overhead, 
which adds an additional 29 bytes to each member file.

"Saved" indicates the percentage of the  original  file length which was saved 
by compression.   Higher values indicate better compression.   The  MS-DOS ARC 
documentation refers to this as the "stowage factor".   The value shown in the 
totals applies to the archive as a whole, excluding directory overhead.

"Date" and "Time" are for the last file modification  at the time it was added 
to the archive.
 Functions:                                 Listing an Archive Directory - 5/5

"CRC" is an internal 16-bit cyclic redundancy check value computed when a file
is added to an archive, expressed in hexadecimal.  UNARCZ checks file validity 
by recomputing this value when it extracts a file.  The value is calculated by
a different method than that used  by either of  the two popular public domain 
programs, CRCK and CHEK, but it is  a quite valid and reliable error-detection 
mechanism.  The value is given for completeness only.   The total in  the last 
line is the 16-bit sum of the displayed CRC values and is useful for comparing 
entire  archives.   Since the CRC values are computed before compression,  the 
total should be the same for all  archives created from the  same set of input 
files, without regard for variations in file order or compression methods.

The "Total" line is  displayed  only  if  more  than  one  file appears in the
listing.
 Functions:                             Extracting Files from an Archive - 1/4

   If the second command line  parameter contains  a  DU or  DIR specification 
UNARCZ will extract the selected member file or files to to the indicated disk
directory.   If the directory specification is  given without a filename,  all 
member files will be extracted to the indicated directory.  If only a colon is 
given, the current drive/user will be assumed.

Following is a directory listing as might be generated during file extraction, 
along with some possible warning messages:
 Functions:                             Extracting Files from an Archive - 2/4

A0>UNARCZ CODES B1:

Archive File = A0:CODES.ARK
Output Drive = B1:

Name           Length  Disk   Method  Ver  Stored Saved    Date    Time   CRC
============  =======  ====  ======== === ======= ===== ========= ======  ====
ABLE    .DOC    24320   24k  Crunched  8    11777  52%  30 Apr 86 10:50a  42C0
Replace existing output file (y/n)? Y
BRAVO   .COM    17152   18k  Squeezed  4    14740  14%   2 May 86  4:11p  8CBD
Warning: Extracted file has incorrect CRC
Warning: Extracted file has incorrect length
Warning: Bad archive file header, bytes skipped = 10
CHARLIE .TXT      234    2k   Packed   3       99  58%   2 May 86  4:11p  8927
        ====  =======  ====               =======  ===                    ====
Total      3    41706   44k                 26616  36%                    58A4
 Functions:                             Extracting Files from an Archive - 3/4

"Replace existing  output  file (y/n)?"  appears  if  a  file of the same name
exists in the output directory, requiring a "Y" or "N" response.  Any response 
other than "Y" will be consided to be the same as "N".

The first two of the "Warning:" messages above indicate that either the cyclic 
redundancy check (CRC) value or the  extracted file length  does not match the 
value recorded in the archive header when  the  original file was added.   The 
third warning message is displayed if the proper format for the beginning of a 
new member is not detected,  but UNARCZ recovered by skipping a certain number 
of bytes in the archive file.   If  a recovery attempt fails, UNARC aborts and 
issues a different message, "Invalid archive file format".   The appearance of 
any of these messages probably means  the file data has been corrupted in some 
way.
 Functions:                             Extracting Files from an Archive - 4/4

If the original MS-DOS file length was not an exact multiple of 128 bytes, the 
final record of the extracted file will be  padded with 1Ah  characters (ASCII 
^Z).

Disk space in the listing will be  correct for the specified output directory.  
In the two examples above,  drive A has 1K allocation blocks while drive B has 
a 2K  blocks,  which accounts for  the differences in  the  two listings.   To 
determine the exact disk space requirements before extracting files,  log into 
the desired output drive and take an UNARCZ directory listing of the ARK file.

If a file extraction is aborted with ^C,  any partial output file will have to 
be deleted manually.
 Functions:                                          Typing Member Files - 1/2

   Typing the contents of  a member file in  an  archive to the console may be 
requested by giving a non-ambiguous filename and no output  disk directory  as 
the second command line parameter.  For example:

A0>UNARCZ CODES ABLE.DOC

Archive File = A0:CODES.ARK

Name           Length  Disk   Method  Ver  Stored Saved    Date    Time   CRC
============  =======  ====  ======== === ======= ===== ========= ======  ====
ABLE    .DOC    24320   24k  Crunched  8    11777  52%  30 Apr 86 10:50a  42C0
------------------------------------------------------------------------------
 This is file ABLE.DOC, contained within the archive CODES.ARK.   Typeout will
 proceed until the end of this file, so you'd better be patient.  For somebody
 who has nothing to say,  I've written an awfully big file here.  If you don't
 want to read all 24K of it, you can type ^C ....
 Functions:                                          Typing Member Files - 2/2

The specified file is assumed to contain valid ASCII text data.  All bytes are 
masked to seven bits and all control characters  are ignored except horizontal 
tabs, which is expanded to blanks with stops at every eighth column), and line 
feeds, vertical tabs,  and form feeds,  all of which generate a new line.  SUB 
(^Z) is interpreted and the end of the file.   Backspaces and carriage returns 
are ignored, so text will not be obscured.

UNARCZ will refuse  to type files  whose filetype indicates are not ASCII text 
files, including COM, EXE, OBJ, REL, LBR, and ?Z?.   If one  of these or other 
restricted types is given, directory information only is listed.

CRC  and file length checking  are not performed when  a file is  typed to the 
screen.
 Functions:                                              Printing Member Files

   A single member file may be sent to the printer  (CP/M LST device) with the 
"P" option  as  the third  parameter on  the command line with  or  without  a 
preceding slash.   In addition, the member name must be non-ambiguous and must 
not be preceded by a drive or user specification.  For example:

     A0>UNARCZ CODES CHARLIE.TXT P
or
     A0>UNARCZ CODES CHARLIE.TXT /P

The contents of the specified file is passed  directly to  the printer without 
alteration, additional formatting, or even paging.   The user should make sure 
it  contains data suitable  for printer output.   This unfiltered operation is 
particularly well-suited for the  output of  binary  graphics  images to  dot-
matrix printers.  These files can be extremely large, but compress quite well, 
often to less than 5%  of  their  original size.   The same filetypes excluded 
from typing  are  also excluded from printing.   Printing  may  be  paused  or 
aborted with ^S and ^C respectively.
 Functions:                                              Checking Member Files

   With the  "C" option  UNARCZ can  be directed to extract one or more member
files from an archive,  without  actually storing these  as disk files.   This 
operation performs file CRC and length checking, so it is useful for verifying 
correct modem data transmission of an archive.   As with all options,  the "C" 
must be the third command line parameter.   The  member name may be ambiguous, 
but it cannot be preceded by a disk directory specification.  For example:

     A0>UNARCZ CODES *.* C
:4
 Configuration 

   Several configuration patch points may  be  used  to tailor the program for
specific requirements,  particularly  to  guarantee security on  RCP/M (Remote 
CP/M) systems.  The secure version of UNARCZ can be used by remote callers for 
archive directory listing or for member file typeout, but not for file extrac-
tion.

Other patch points are provided for specialized non-standard systems  and need 
not concern the majority of users running ZCPR3, NZ-COM, or Z3PLUS.

Additional patch options allow adjustment of  a few user preferences,  such as 
the number  of screen lines  between  console  output  pauses  or  the list of 
restricted filetypes for typing and printing.

Patching options are thoroughly described in UNARCZOV.ASM, an assembler source 
file that can  be edited,  assembled,  and then layed  over  UNARCZ.COM.   The 
default options in the  distributed  program files, however,  are suitable for 
most users.
:5
 Examples of Use 

  B0>UNARCZ A3:SAVE.ARK *.*  -->  List all files in CP/M archive SAVE in A3
  B0>UNARCZ A0:SAVE.ARC *.*  -->  List all files in MS-DOS archive SAVE in A0
  A0>UNARCZ SAVE             -->  Same as above
  A0>UNARCZ SAVE *.* N       -->  Same as above (no screen pauses)
  A0>UNARCZ SAVE *.DOC       -->  List just .DOC files
  A0>UNARCZ SAVE READ.ME     -->  Typeout the file READ.ME
  A0>UNARCZ SAVE READ.ME /N  -->  Typeout the file READ.ME (no screen pauses)
  A0>UNARCZ SAVE C3:         -->  Extract all files to directory C3
  A3>UNARCZ SAVE B:*.DOC     -->  Extract .DOC files to directory B3
  A0>UNARCZ SAVE 1:READ.ME   -->  Extract file READ.ME to directory A1
  A0>UNARCZ SAVE PRN.DAT P   -->  Print the file PRN.DAT (no formatting)
  A0>UNARCZ SAVE *.* C       -->  Check validity of all files in archive
