ARCUTIL version 2.0
                                         ARCUTIL version 2.0
                                         ARCUTIL version 2.0
                                         ARCUTIL version 2.0
 
 
 
 
 
                                                 07 May 1991
 
 
 
                                              John S. Fisher
 
 
                                         ARCUTIL Version 2.0
                                         ARCUTIL Version 2.0
                                         ARCUTIL Version 2.0
                                         ARCUTIL Version 2.0
 
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
 
PREFACE
PREFACE
PREFACE
PREFACE
_______
 
The  ARCUTIL  program provides a collection of functions for
the manipulation of distribution files  from  public  domain
software  archive  systems  on  a  main-frame host computer.
This document describes the version  of  ARCUTIL  designated
Version  2.0.    ARCUTIL  executes  on IBM systems using the
VM/SP operating system.   It provides  the  following  func-
tions.
 
.   Recover  the  original data for a file that has been en-
    coded using either the uuencoding or xxencoding method.
 
.   Render a file  in  encoded  form,  either  uuencoded  or
    xxencoded.
 
.   Recover  the  original  data  for  a  file that has been
    "squeezed."
 
.   Recover the original data  for  a  file  that  has  been
    "crunched" using version 2 of the GEL Crunch program.
 
.   Extract  and  decompress all members from a .ARC or .ARK
    library file.
 
.   Extract and decompress all members from a  .LBR  library
    file.
 
.   Extract  and  decompress all members from a .ZIP library
    file.
 
.   Translate files of ASCII text to EBCDIC, with or without
    ASA carriage control generation.
 
Users are encouraged to correct bugs and enhance  the  prod-
uct.  Such modifications should be sent to the address below
for inclusion in subsequent releases.
 
Questions, comments, contributions may be sent to
 
BITNET    FISHER@RPIECS
 
INTERNET  FISHER@VM.ECS.RPI.EDU
 
USPS      John S. Fisher
          Engineering Computing Services
          Rensselaer Polytechnic Institute
          Troy, NY  12180 3590
 
Copyright (c) 1986-1991, John S. Fisher, Troy, NY.
 
 
Preface                                                   ii
 
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
 
Permission is granted to copy and distribute this documenta-
tion  in  any  form to any one as long as (1) this notice of
copyright and distribution policy  remain  intact,  (2)  the
distribution  is  made  without  charge above and beyond any
reasonable  fee  to  copy costs in making and delivering the
copy, and (3) no additional restrictions are imposed, either
as to use or distribution.
 
Changes in this release.
Changes in this release.
Changes in this release.
Changes in this release.
________________________
 
The following enhancements and changes  have  been  made  to
ARCUTIL version 2.0.
 
.   Support  for .ZIP files has been added.  ARCUTIL handles
    all of the .ZIP file storage methods known at  the  time
    of this writing.
 
.   Cyclic  redundancy  checking is performed for .ARC, .LBR
    and .ZIP files.
 
.   Support for xxencoding  and  xxdecoding  functions  have
    been added.  Uuencoding has been updated to support cur-
    rent  practice, but the older version is still available
    for  compatibility.    An  option  is   available   with
    uuencoding  to use a character sequence that is believed
    to be compatible with the JANET network gateway.
 
.   The length for output records may be specified as an op-
    tion.
 
.   The number of lines per page may be specified.
 
Except as noted below, ARCUTIL version 2.0 is fully  compat-
ible with earlier versions.
 
.   The  MEMBER  option  has been discontinued.   Equivalent
    functionality is provided by the pattern matching  oper-
    and after the input file identifier.
 
.   The  default  fileid  for  the  output  from COPY is the
    fileid of the input file with a dollar-sign prepended to
    the input filename.  In the prior  version  of  ARCUTIL,
    the  output file had the same filename as the input, and
    LISTING for the filetype.
 
.   The UUENCODE, UUDECODE, and  UNLIB  commands  have  been
    superceded  by  the  ENCODE, DECODE, and UNLBR commands.
    They are accepted still by ARCUTIL version 2.0, but they
    may be discontinued in future versions.
 
 
Preface                                                  iii
 
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
 
.   A few programming errors have been corrected that caused
    extraneous bytes sometimes to appear at the end of  out-
    put  files.    The  EBCDIC translator no longer discards
    blank lines.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
Preface                                                   iv
 
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
 
INTRODUCTION TO ARCUTIL
INTRODUCTION TO ARCUTIL
INTRODUCTION TO ARCUTIL
INTRODUCTION TO ARCUTIL
_______________________
 
A  great  wealth  of public-domain and shareware software is
available through various academic  and  research  networks.
For  the  MS-DOS an CP/M communities, such software is often
packaged together with documentation  and  supporting  files
into a single archive file so that the entire package may be
              _______
shipped as a unit over the network.
 
For MS-DOS systems archives are built often in the so-called
ZIP  format or in the older ARC format.  Archives files usu-
___                         ___
ally have either .ZIP or .ARC as their file name  extension.
In  CP/M  systems  .LBR  (for library) and .ARK (exactly the
                              _______
same as MS-DOS .ARC) files are commonly found.
 
ARCUTIL is a utility command you can use on  your  VM/SP  or
VM/XA  system.    It  will help you manipulate archive files
that you might have obtained over one of the  computer  net-
works.    ARCUTIL  can extract the individual files from ar-
chives of any of the three types mentioned above (.ZIP, .ARC
or .ARK, and .LBR).  It can translate from ASCII to  EBCDIC,
and it can even generate FORTRAN-style carriage control (ASA
carriage control) if you ask it.
 
For  the  sake  of  an  example, assume there is a person in
Potsylvania with  whom  you  frequently  correspond.    Your
friend,  Boris,  claims to have what might be conservatively
called the absolute greatest public-domain software  product
for  the IBM PC ever written, and he agrees to forward you a
copy.
 
A rather large electronic mail message for you shows  up  on
your VM/SP host.  It is from Boris.
 
In  the  message  Boris explains that he has enclosed an ar-
chive file for the fabulous GETMOOSE program.   Since he  is
sending  it  in  as part of a mail message, he has xxencoded
                                                   _________
the archive.  Archives contain mostly binary data, and  mail
systems   generally   handle   only   textual   information.
Xxencoding is a method for encoding binary data as text that
can be decoded later.
 
A good first step would be for you to decode  the  xxencoded
file.  Having saved Boris' message in a file called GETMOOSE
XXE, you enter the command
 
  ARCUTIL DECODE GETMOOSE XXE A ( XXENCODE
 
DECODE is one of ARCUTIL's many functions.  ARCUTIL can han-
dle  a  couple  of  encoding methods, so you need to tell it
which method was used.
 
Introduction to ARCUTIL                                    1
 
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
 
After only a brief pause,  ARCUTIL  reports  that  the  file
GETMOOSE  ZIP  has  been created.   You wonder what it might
contain:
 
  ARCUTIL UNZIP GETMOOSE ZIP A ( LIST
 
UNZIP is another of ARCUTIL's many functions.  Since you in-
terested  in  what  the  ZIP  archive  has  in it, you asked
ARCUTIL to list the directory of the archive and not extract
anything.  ARCUTIL responses something like this:
 
  Member name    SizeIn SizeOut   Method   Filename Filetype  Comment...
  ============  ======= =======  ========  ======== ========  ====================
  GETMOOSE.C       1911    6300  Implode   GETMOOSE C
  GETMOOSE.DOC    45177  182524  Implode   GETMOOSE DOC
  GETMOOSE.EXE     1976    7713  Implode   GETMOOSE EXE
  SUBS.C            887    2352  Shrink    SUBS     C
  SQUIRREL.DOC     2880   10500  Implode   SQUIRREL DOC
 
You are not a source code freak, so the program source files
excite you not at all, but the two documentation files might
be of interest.   One  of  them  is  rather  large  (182,524
bytes);  perhaps  more  than  you really want to put through
your poor PC printer.  You ask ARCUTIL to extract the  docu-
ment  files from the archive and translate the ASCII text to
EBCDIC (complete with printer carriage control).
 
  ARCUTIL UNZIP GETMOOSE ZIP A * DOC A ( CCEBCDIC
 
After examining both the GETMOOSE and SQUIRREL DOC files you
erase the latter and print the former  on  the  system  page
printer.    The  GETMOOSE.DOC file leads you to believe that
maybe Boris was right.  This could well be the most  wonder-
ful public-domain program around.  You cannot wait to try it
out on your PC.
 
You  could  download  the full archive to your PC, but it is
rather large.  Seeing how you have already printed a copy of
the documentation on your host, and you do not  really  care
about  the  source  code,  it  seems a shame to wait for the
whole .ZIP file to transfer when all you really need is  the
executable.  ARCUTIL to the rescue one final time.
 
  ARCUTIL UNZIP GETMOOSE ZIP A GETMOOSE EXE A
 
You then start the download of just the executable file that
ARCUTIL  so  kindly  extracted.   Six thousand three hundred
bytes later you new-found panacea is running on you PC....
 
 
 
Introduction to ARCUTIL                                    2
 
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
 
ARCHIVE EXTRACTION FUNCTIONS
ARCHIVE EXTRACTION FUNCTIONS
ARCHIVE EXTRACTION FUNCTIONS
ARCHIVE EXTRACTION FUNCTIONS
____________________________
 
ARCUTIL  has functions to let you extract and decompact mem-
bers from file archives.   The three  most  popular  archive
formats  used  in  the  MS-DOS and CP/M communities are sup-
ported; .ARC, .LBR, and .ZIP files are all handled.    (.ARK
files  found  among  CP/M systems are identical in format to
.ARC files.)
 
ARCUTIL also has functions to let you decompact  files  that
were  compacted  using  either  the  squeeze  or  the crunch
                                     _______          ______
method.  Both methods are still occasionally used among CP/M
users.  Squeezed files typically have the letter  Q  as  the
second  character  in the filetype field (or file extension,
in microcomputer terminology).  Crunched files have the let-
ter Z.
 
ARCUTIL may be invoked with the command
 
  ARCUTIL  cmd  infileid  outfileid  ( options...
 
where
 
cmd       specifies which function you want ARCUTIL to  per-
___
          form.  Select one of the following.
 
          UNARC     process a .ARC or .ARK file.
 
          UNLBR     process a .LBR file.
 
          UNZIP     process a .ZIP file.
 
          UNSQ      process a squeezed (.?Q?) file.
 
          UNCR      process a crunched (.?Z?) file.
 
infileid  specifies which CMS file you want ARCUTIL to proc-
________
          ess.      You  must  provide  the  full  filename,
          filetype, and filemode for your input file.
 
outfileid specifies which members of the  archive  you  want
_________
          ARCUTIL  to extract and where they should be writ-
          ten.  The filename and filetype fields may contain
          wild card symbols to be used in pattern  matching.
          _________
          An  asterisk  matches  any string of characters; a
          percent matches any single character; other  char-
          acters  match only themselves.  The filemode tells
          ARCUTIL where to write the output files.    If  an
          outfileid  is  not  included  on the command line,
          ARCUTIL will use * * A1.
 
 
Archive Extraction Functions                               3
 
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
 
options... specify processing options for the function.  The
__________
          more commonly used options include
 
          REPLACE   tells ARCUTIL that a file extracted from
                    the  archive may replace an existing CMS
                    file by the same name.   If  REPLACE  is
                    not  specified, ARCUTIL skips any member
                    that would  conflict  with  an  existing
                    file.
          EBCDIC    tells  ARCUTIL  to  translate the member
                    data from ASCII to EBCDIC.  Carriage re-
                    turns,  linefeeds,  and  formfeeds   are
                    treated  as  end  of record indications;
                    tabs are expanded to spaces.
          CCEBCDIC  tells ARCUTIL to  translate  the  member
                    data  from ASCII to EBCDIC and to gener-
                    ate ASA carriage control characters  for
                    each line.  Carriage returns, linefeeds,
                    and  formfeeds  are converted to the ap-
                    propriate carriage control; tabs are ex-
                    panded to spaces.
          NL        tells  ARCUTIL  that  linefeed   symbols
                    should  be treated as a newline.  The NL
                    option  is  meaningful  only  with   the
                    EBCDIC and CCEBCDIC options.
          LIST      tells  ARCUTIL  that  only the directory
                    information should be produced.  No data
                    should be extracted.
 
 
 
 
 
 
 
 
 
 
Archive Extraction Functions                               4
 
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
 
ENCODING AND DECODING FILES
ENCODING AND DECODING FILES
ENCODING AND DECODING FILES
ENCODING AND DECODING FILES
___________________________
 
For  many  netorks  it  may  not be possible to conveniently
transmit binary data.   The various types  of  archives  and
compacted  file  formats  used for software packages all use
binary data, so to have such files sent  through  a  network
may require that the data be encoded by some scheme that re-
presents  binary  information  using only plain-text charac-
ters.
 
Two very closely related encoding methods in common use  are
uuencoding  and xxencoding.  Both methods represent each six
__________      __________
bits of binary data with an eight-bit character (and so  en-
coded files are roughly one-third larger than the original).
Uuencoding  is  the older of the two, but it has limitations
when both ASCII and EBCDIC systems are involved in the  net-
work  transfer.    Xxencoding avoids this problem by using a
character   sequence   for   its   encoding   that    avoids
discrepencies between the ASCII and EBCDIC character sets.
 
ARCUTIL  has  functions to encode and decode files using ei-
ther the uuencode or xxencode methods.  ARCUTIL may  be  in-
voked with the command
 
  ARCUTIL  cmd  infileid  outfileid  ( options...
 
where
 
cmd       specifies  which function you want ARCUTIL to per-
___
          form.  Select one of the following.
 
          ENCODE    encode a file.
 
          DECODE    decode a file.
 
infileid  specifies which CMS file you want ARCUTIL to proc-
________
          ess.    You  must  provide  the   full   filename,
          filetype, and filemode for your input file.
 
outfileid for  the  ENCODE function, this specifies the name
_________
          of the file ARCUTIL should create.  A complete CMS
          fileid (filename, filetype, and  filemode)  should
          be entered.  For the DECODE function, the filename
          and  filetype parts of the outfileid specify which
          files ARCUTIL should decode.  The input  file  may
          contain  multiple  encoded  files concatenated one
          after the other. You may use wild card symbols  to
                                       _________
          be  used in pattern matching.  An asterisk matches
          any string of characters; a  percent  matches  any
          single  character;  other  characters  match  only
          themselves.  The filemode tells ARCUTIL  where  to
          write the output files.
 
Encoding and Decoding Files                                5
 
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
 
options... specify processing options for the function.  The
__________
          more commonly used options include
 
          XXENCODE  tells   ARCUTIL   that   the  rules  for
                    xxencoding are to be used.
          UUENCODE  tells  ARCUTIL  that   the   rules   for
                    uuencoding  are  to be used.  If neither
                    XXENCODE nor UUENCODE  are  included  on
                    the   command   line,   ARCUTIL  assumes
                    UUENCODE.
          MGUARD    tells ARCUTIL that it should use an now-
                    obsolete variant of uuencoding.  A guard
                                                       _____
                    character is added to the  end  of  each
                    uuencoded  line  (typically  the  letter
                    "M"), and that the  space  character  is
                    used  instead  of  agrave  accent.   The
                    MGUARD is meaningful only in combination
                    with  the  ENCODE   function   and   the
                    UUENCODE option.
          JANET     tells  ARCUTIL that it should use a spe-
                    cial character sequence for  uuencoding.
                    The  character sequence used is believed
                    to be compatible with the network  gate-
                    way between BITNET and JANET.  The JANET
                    is  meaningful only combination with the
                    ENCODE function and the UUENCODE option.
          REPLACE   tells ARCUTIL that a file extracted from
                    the archive may replace an existing  CMS
                    file  by  the same name.   If REPLACE is
                    not specified, ARCUTIL skips any  member
                    that  would  conflict  with  an existing
                    file.
 
 
 
 
 
 
 
 
Encoding and Decoding Files                                6
 
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
 
SIMPLE FILE COPYING
SIMPLE FILE COPYING
SIMPLE FILE COPYING
SIMPLE FILE COPYING
___________________
 
The  COPY  function  of  ARCUTIL copies the input file to an
output file.  This function is useful  with  specified  with
the  EBCDIC  option  to  convert  an ASCII file to printable
EBCDIC.  It is also useful for converting a file with  vari-
able  length records into one where all the records have the
same length.  The command to invoke  the  COPY  function  of
ARCUTIL has the following form.
 
  ARCUTIL  COPY  infileid  outfilid  (  options...
 
where
 
infileid  specifies which CMS file you want ARCUTIL to proc-
          ess.      You  must  provide  the  full  filename,
          filetype, and filemode for your input file.
 
outfileid specifies the full name for the CMS  file  ARCUTIL
          should create.
 
options... specify processing options for the function.  The
          more commonly used options include
 
          REPLACE   specifies  that  the  output  files from
                    ARCUTIL may replace  existing  files  by
                    the same name.
          CCEBCDIC  specifies  that  the  output  is  to  be
                    translated from ASCII to EBCDIC.    Car-
                    riage  returns, linefeeds, and formfeeds
                    are converted to ASA  carriage  control;
                    tabs are expanded to spaces.
          EBCDIC    specifies  that  the  output  is  to  be
                    translated from ASCII to EBCDIC.    Car-
                    riage  returns, linefeeds, and formfeeds
                    are treated as record breaks;  tabs  are
                    expanded to spaces.
 
 
 
 
 
 
Simple File Copying                                        7
 
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
 
COMMAND SUMMARY
COMMAND SUMMARY
COMMAND SUMMARY
COMMAND SUMMARY
_______________
 
The syntax for the ARCUTIL command is as follows.
 
  ARCUTIL  command  infileid  outfilid  (  options...
 
The command parameter indicates which of ARCUTIL's functions
    _______
is to be performed.  It may be any of these commands.
 
UNARC          process a .ARC or .ARK file.
 
UNLBR          process a .LBR file.
 
UNZIP          process a .ZIP file.
 
UNSQ           process a squeezed (.?Q?) file.
 
UNCR           process a crunched (.?Z?) file.
 
ENCODE         encode a file.
 
DECODE         decode a file.
 
COPY           copy a file.
 
The  infileid  parameter parameter specifies the name of the
     ________
input file ARCUTIL should process.   It should be  the  com-
plete  CMS  file  identifier; that is, it should include the
filename, filetype, and the filemode.
 
For the ENCODE and COPY  commands,  the  outfilid  parameter
                                         ________
gives  the complete CMS file identifier (filename, filetype,
and filemode) for the output file.  For the other  commands,
the  filename and filetype fields specify which archive mem-
bers should be extracted.   Asterisks and  percents  may  be
used  as  "wild card" symbols:  a percent matches any single
character, and the asterisk matches  any  character  string.
The  filemode  field  specifies  where  the output should be
written.
 
The command-line options  specify  any  special  processing.
                 _______
Here is a complete list of supported ARCUTIL options.
 
REplace        If an output file would overwrite an existing
               file of the same name, ARCUTIL normally skips
               processing  that output.   Specifying REPLACE
               tells ARCUTIL it may erase the existing file.
 
EBcdic         Data in the output file  is  translated  from
               ASCII to EBCDIC.  Carriage return, line feed,
               and  form feed characters are treated as end-
 
Command Summary                                            8
 
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
                    ARCUTIL Version 2.0
 
               of-line signals.  Tab characters are expanded
               to blanks.
 
CCEBcdic       Data  in  the  output file is translated from
               ASCII to EBCDIC.  Carriage return, line feed,
               and form feed characters are converted to the
               appropriate printer carriage control  charac-
               ters.  Tab characters are expanded to blanks.
 
NL             ARCUTIL is to interpret a line feed character
               as  a  new line character (that is, as a car-
               riage return, line feed sequence).    The  NL
               option  is  meaningful only with the CCEBCDIC
               option.
 
LIST           ARCUTIL constructs the contents directory  of
               the  input file, but it suppresses the gener-
               ation of any output files.
 
Block nn       This option specifies the size of the  output
               records  generated  by ARCUTIL.   If omitted,
               the program assumes 128 byte records for most
               cases.  If the CCEBCDIC option is  specified,
               then  the default record length is set to 133
               bytes.
 
LINEcoun nn    This option specifies the number of lines per
               output  page.     The  LINECOUN   option   is
               meaninful   only   in  combination  with  the
               CCEBCDIC option.   ARCUTIL assumes  60  lines
               per page if LINECOUN is not provided.
 
UUencode, XXencode   These   options  indicate  whether  the
               uuencoding or xxencoding rules are used.  The
               option may be used with the DECODE and ENCODE
               functions of  ARCUTIL.    If  not  specified,
               ARCUTIL assumes uuencoding.
 
MGuard         This  option  enables  the  old-style form of
               uuencoding in which the length  character  is
               appended  to  each output line.   (The length
               character is usually the letter M.)  This op-
               tion is meaningful only with the UUENCODE op-
               tion and the ENCODE function.
 
JANET          This option enables a special  character  se-
               quence  for uuencoding believed to be compat-
               ible with the  JANET  network  mail  gateway.
               This  option  is  meaningful  only  with  the
               UUENCODE option and the ENCODE function.
 
 
Command Summary                                            9