rtsi.com/2014.01.www.rtsi.com.tar/www.rtsi.com/OS9/OS9_6X09/ARCHIVERS/lha211c.lzh/notes.doc

Text File | 1994-05-14 | 17KB | 341 lines

/*
 * notes.doc file:
 */
/*
 * LHA v2.11 Copyright (c) Haruyasu Yoshizaki, 1988-91
 *
 * Modified for CoCo OS9.
 * Modifications for LHA OS9 v2.11c (c) 1993-94 by E. M. Krenciglowa
 *
 *
 *   Gene Krenciglowa
 *   April, l994
 */


-------------------------------------------------------------------------
NOTES ON OS9 LHA
-------------------------------------------------------------------------

**** First a quick summary of how OS9 LHA differs from the original LHA
     documentation file 'lha211.doc' in 'doc211.lzh'.

     There is no -s command or anything to do with self-extracting archives
     in general.  No tell operator '!', environment variables or
     'authenticity' support either.  Omit the entire section 2: SFX,
     Self-Extracting archives.

     There is no -i option or provision for switching the switch character.
     The switch character is '-' and path delimiter is '/'.  Filenames
     beginning with a leading '-' or '@' cannot be processed.  The range for
     any unique name generation with the -m2 option is 0 - 99.  The suffix
     list used in the -z2 option is:

          .pak, .zip, .zoo, .arc, .lzh, .lzs, .lha, .arj, .ar, .Z

     With OS9 LHA v2.11c if a recursive collection of files is specified,
     then the order of the files as they appear in the archive differs
     from IBM LHA (and OS9 LHA v2.11b).  For a recursive collection with
     a filespec something like,

          lha u -r1x arcfile /d1/ *.c *.h

     then at any given directory level, all *.c and *.h files are archived
     before proceeding to the next directory level.  On IBM LHA, the
     collection is first all *.c files in all directory levels, then the
     same for *.h files.

     The uppercase options are all OS9 specific.

     The -a option is somewhat specific to IBM archives, but does come into
     use.  If the archive is an OS9 archive (OS_ID of '9'), extraction is
     not really dependent on the -a option.  Extraction is made if there is
     no conflict with an existing file (or directory).  The file attributes
     are processed according to the following classes:

                                                       Value on IBM

          FA_DIREC       if directory {                      16
                             {if read and write}
                           else
                             {none}
                         }
                         else {
          FA_RDONLY        if read and not write              1
          FA_ARCH          else if read and write            32
                           else {none}

     The above is how OS9 attributes are mapped for processing.  An obvious
     point, a read attribute must be present.  The OS9 file attribute used
     is an image of the attribute in the file descriptor.  Any directories
     created have the standard attributes (d-ewrewr), so any single user 's'
     attribute or other attribute specification in the original directory is
     lost.  If the archive is an IBM archive, then -a option should behave
     as described in the original documentation.

     The IBM LHA uses -lh5- compression which is superior to the -lh1-
     compression used in OS9 LHA.  The -o option on IBM, sets up -h0 and
     -lh1- compression.  There are some typos in lha211.doc: -o sets up -h0,
     the default header is -h1 and -m1 gives the newest file.

     File and path name conventions, including case, are as appropriate for
     OS9, so this differs from IBM LHA.

**** OS9 LHA can be used on any valid .lzh archive.  For example, archives
     produced by IBM LHA can be update also (not just extracted), but
     check out the old style -o option for generic level-0 headers and
     -Y option for lev-0, lev-1 and lev-2 headers.

**** Being a computer program, OS9 LHA has checks on the validity of the
     archive data.  If invalid data is detected, there is an immediate exit
     with a 'Broken archive' message.  That's assuming, of course, that the
     invalid data does not cause a crash.  There is one exception to this.
     If the broken archive is thought to be an LZH10 'extended' header
     archive, only the list and test commands are enabled.  For any other
     command, there is an exit along with a message informing the user of an
     option to fix the archive.  OS9 LHA will not automatically fix it,
     rather this being left completely at the user's option.

**** In the update family of commands, if you want path information stored
     in the arcfile then use the -x option.  Also, note that the base
     directory path is not stored, so that

          lha u arcfile testdir/  -x
     and, lha u arcfile testdir/* -x

     are different.  Generally, absolute paths should not be used so that
     form

          lha u arcfile /d1/   testdir/* -x

     is better form than

          lha u arcfile /d1/testdir/*  -x

     The latter form should be avoided, although OS9 LHA does filter
     absolute path parts out.

**** Files can be collected recursively from directories with two different
     kinds of recursion, -r1 and -r2.  Use:

          lha u -xr2 arcfile   /d1/

     to duplicate the directory tree structure of the disk in /d1.  Note
     that having filespec with -r2 does not behave as expected, so use only
     the form shown above.  Actually, a filespec goes over to a 'dirspec'
     and -r2 gives all files built from bdir/dirspec.

**** File collection is based on the file time stamp (OS9 last modified time).
     If your system does not maintain meaningful file time stamps, then
     explore the -c option to turn this off.  Bad file time stamps are mapped
     to Jan 1, l980 for MSDOS time and Jan 1, 1970 for UNIX time.

**** The old style -o option generates a generic level-0 header with no OS9
     specific information included.  A level-1 header (-h1) is the default.
     The level-0, level-1 and level-2 headers generated with the -h0, -h1
     (default), -h2 options all contain OS9 specific information, namely
     the CoCo/OS9 extended header termed 'ccxhdr'.  The -o and -h0 options
     are different.  The -h0 additionally contains an OS9 specific
     simplified header extention.

**** For the list command, if the archive is made by OS9 LHA, the P column
     indicates the pack level 1 to 9 or 0 for stored.  The file attributes
     column shows OS9 attributes, MSDOS or generic attributes, as appropiate.
     Except for possible case conversions and directory delimiter mapping,
     the list command shows filenames as they appear in the arcfile, and
     before the filenames are mapped into OS9 filenames.  In processing
     commands however, OS9 LHA uses the mapped names.  So, to process a file
     which appears with the filename '!', say, in a list command, use the
     filename '_' which likely is what '!' is mapped into.

**** A shortform for single file archives is introduced as a special case of
     the '@filelist' feature of LHA.  For the full form,

         lha u path/filename filename

     the shortform,

          lha u path/filename @

     may be used instead.  The '@' would normally be used in the form
     '@cmdfile' to get the command line from the 'cmdfile'.  The '@' used
     alone specifies that the filespec is to be taken as the filename part
     of the arcfile name.   This seeming oddity reflects back to the design
     in the Unix 'compress' file compressor.  Here, the form

          lha m filename @

     replaces the uncompressed file 'filename' with the compressed image
     'filename.lzh'.

**** On dearchiving, with v2.11c processing ends when the filespec list is
     known to be exhausted, which applies only if the filespec list does not
     contain wildcards and the -x option is not specified.  The -x option is
     implicit with the x and v commands.  This is generally desirable as the
     whole archive is not forced to be scanned, for example, when extracting
     one small 'readme' file at the beginning of an archive containing a
     hundred, say, member files .  On extract, specifying a bogus -r option
     is used to override this forcing the entire arcfile to be scanned.

**** Below is a simple shell script to convert en masse a given file archive
     type to .lzh archives.

          * Convert .zip to .lzh:  all .zip in data dir to /d1/...lzh
          * The directory TT must already exist on ramdisk /rd.

          dr -p *.zip ! call -x "tfr /rd $.zip; (chd /rd/TT; unzip -d /rd/$;
           lha m -h0P9Ytmz2xr2 /d1/$ </w; del /rd/$.zip ! shell t)" ! shell t

     Note that the entire command 'dr -p *.zip ... ! shell t' must be on a
     single line.  An extra carriage return is present above for the sake
     of the listing.  Here, /rd is the ramdisk, the 'dr -p' is an 'ls' type
     directory lister producing one filename per line, 'tfr' is a form of
     file copy, and repetative shell commands are generated with the 'call'
     available from CoCo BBSes.

     The above script is meant as a guide and can be tailored to other file
     archive types.  While such a script can get the job done, it is by
     no means particularly elegant or even bullet proof, so if used exercise
     caution.

**** A custom rename command 'rnm_lha' is supplied merged together with
     the 'xlh' module in the 'xlh' file.  For OS9 LHA use, the 'xlh' file
     should not be altered.  However, the 'rnm_lha' may be used on its
     own right.  The 'rnm_lha' is supplied as it is faster than the stock
     'rename' module, does not alter the file time stamp, and allows OS9
     LHA to pre-load and link the needed modules (xlh and a rename) as
     a single file.  The 'rnm_lha' is functionally similar to the stock
     'rename' command, except that the form is

          rnm_lha oldname newname
     or,  rnm_lha path/oldname path/newname

     and the file time stamp is unaltered.  If a path is present, the
     same path must be present in both the old and new name parts.


---------------------------------------------------------------------------
OS9 OPTIONS
---------------------------------------------------------------------------

     The uppercase options are all OS9 specific.

**** The -Pn specifies a pack level criteria for the -lh1- compression
     scheme.  A -P0 is the same as -z1, Store method.  A -P9 is full -lh1-
     compression.  The default pack level is -P6 and represents a middle
     ground compromise between speed and compression efficiency.  From
     limited testing and between -P1 (fastest) and -P9 (best compression),
     there is a 5% to 15% difference in the compressed size and a factor of
     two difference in compression speed.  The default -P6 is half way
     between in terms of speed and -P6 gives about a 1% difference in
     compressed size compared with -P9.  This is based on limited testing
     and the timing and compression performance is for raw compression (xlh
     executing), which does not include the actual size of headers, file
     information gathering time etc.

**** The text conversion option -A is fully functional.  MSDOS (CR LF) and
     Unix (LF) end-of-line marks are converted to OS9's (CR).  The tab
     character is expanded to spaces according to the tab stop option
     -Tnn (default nn=4).  The CR character and ascii characters (decimal
     values >= 32 and < 128) are passed unaltered.  All other character
     are converted to a space (decimal 32).

     Of course, the -A option should ONLY be used with TEXT files.

**** File names are mapped into lower case characters and directory names
     are mapped to upper case, if the arcfile OS_ID is of the MSDOS family.
     That is, if the arcfile is made on MSDOS, then case conversion takes
     place.  Use the -U option to suppress the case conversion in file
     names.  If the arcfile is made on Unix, OSK, OS9, for example, then
     there is no case conversion.  This is for lev-1 and lev-2 where an
     OS_ID is present.  For lev-0, lower case conversion takes place except
     for OS9 LHA archives.

**** The default filename mapping is done through an f$prsnam system call
     algorithm.  Note that the stock rename command may be used to change a
     filename.  If a replacement (but otherwise Microware compatible)
     f$prsnam module is installed, then non-standard OS9 (but acceptable by
     f$prsnam) filenames may be generated.  The -L option forces the
     generation of legal OS9 filenames.  The -L algorithm is as follows.  If
     the first character is not alphabetic, prefix the filename with the
     character 'x'.  Then, any character which is not alphanumeric, '.' or
     '_' is replaced by '_'.  The default f$prsnam algorithm is similiar,
     except that replacement by an '_' takes place only if the character is
     not acceptable to the f$prsnam installed.  The f$prsnam algorithm
     duplicates the -L option for legal OS9 filename mapping when the
     original Microware f$prsnam is installed.

     In any case, the total length of the pathname recorded in the arcfile
     never increases in the mapped pathname.  If the mapping should lead
     to an increase in the total length, the mapped pathname is truncated
     to the original total length.

---------------------------------------------------------------------------
ADDITIONAL OS9 OPTIONS
---------------------------------------------------------------------------

     There are additional OS9 options that are not shown on the usage screen.

**** Except for -o (old style) option, the default is that a ccxhdr extended
     header is used.  The -Y option disables the ccxhdr on both read and
     write.  With -h0, OS9 specific information is still left in the lev-0
     header in simplified way.  This is to allow other OS9 lzh processors to
     pick up OS9 information from OS9 LHA produced archives without the
     complexity of the ccxhdr extended header.  This should also allow
     greater compatibility with older, non-OS9, lzh processors.  The -h0
     option is strongly recommended, atleast at the present time, for any
     archives intended for general distribution to the OS9 community.  At
     present, neither UNLZH nor LZH10 process this OS9 specific information,
     principally the file attribute and owner id.

**** The timezone option -Znn is for conversion of local time, what the
     clock on the wall says, and Greenwich mean time (GMT), what a clock
     reads in Greenwich (London, England).  The GMT is the reference used
     in UNIX time which is the time used in lev-2 headers.  The timezone
     factor only is important for lev-2 headers and only if the archive
     is processed on another system, like IBM.  All that happens is that
     the file time stamp may be a few hours off when processed on another
     system.  The default timezone is Eastern Standard Time (EST) which
     has a timezone value of 5 (ie -Z5).  The timezone value increases
     by 1 for each timezone crossed as you travel west.  I am not sure
     what happens at the International Dateline.

**** The use of the -F option for fixing broken LZH10 'extended' header
     archives is completely at the user's option.  If not otherwise specified,
     an attempt is made to generate the default OS9 LHA level-1 archive, so
     be forwarned that LZH10 cannot process these at present.  OS9 LHA
     level-1 archives, being compliant, are processed just fine by UNLZH7.
     However, if the -o or -h0 option is used, then an attempt is made to
     generate a level-0 which should be okay to both LZH10 and UNLZH7.

---------------------------------------------------------------------------
HEADERS
---------------------------------------------------------------------------

**** Headers?  What's a header?  What's the difference?  The .lzh file
     format is somewhat complicated by it's amorphous nature.  For some
     reason, the LHA author, H. Yoshizaki, has not moved over to one
     and only one header format for new archives.  Backward compatibility
     generally involves support for extraction of old archives with their
     various headers and compression methods.

     The main difference is that the lev-0 header is restricted in size
     to 255 bytes and a 8 bit header check sum is used as a basic check
     on the data.  For lev-1 and lev-2, the header sizes larger than
     255 bytes are possible and a 16 bit CRC is used to check header
     integrity.  The lev-2 header, it turns out, is the simplest and
     has the most security for detection of bad data.

     In practical terms, unless pathnames get over 200 characters or so,
     the 255 byte restiction on lev-0 is not so serious.  However, the
     16 bit header CRC is very important from the point of view of an
     internal data integrity check and that alone makes lev-1 and lev-2
     headers much preferred over lev-0.  In addition, the flexible format
     of lev-1 and lev-2 atleast leaves open the door for ready means of
     future expandibility.

/*
 * end notes.doc file:
 */