April 5, 1989


          USER's MANUAL for highly effective Archiving Program

                           LHarc version 1.00

            Copyright(c) Haruyasu Yoshizaki (Yoshi), 1988-89

                                                  Nifty Serve PFF00253
                                                  ASCII pcs   pcs02846


0. It came to pass one day..

   After reading "Harddisk Cookbook" from Shouei-Press, I had an strong
   desire to write my own archiving utility.  In the Nifty Serve
   network, I was first exposed to Mr.  Miki's Larc which surpassed the
   well-known pkware in compression rates, as reported in the Forum
   Software Debut and Review.  The next shock came when I saw Mr.
   Okumura's LZARI which has even better compaction rate performance.  I
   started to rewrite LZARI in MASM trying to make it run faster, but I
   could find no way of speeding up the process of de-archiving.

   So, as an alternative, I used adaptive Huffman coding with an LZSS
   encoder to achieve a similar rate of compression with a faster
   decompression process.  This is the idea used in LHarc.

   No one can be sure of eradicating all possible bugs, yet if SPACE is
   more valuable than TIME for you, please give this program a try.  It
   may be slower in execution but it achieves the tightest compression
   rate of any archiver in the present freeware market.  (Copyright
   reserverd).

1. How to use it:

   [ Synopsis ]

        LHarc [command][/<switch>[-|+|2|<option>]]<archive>
              <file_name> [ <Home directory_name>\|<Drive_Name>: ]
              [<path_name> ]

   You may place switch(es) at any place following the command(s).  A
   group of switches can be specified on a consecutive line.

   Just type LHarc to see the help menu.


Commands:
========

    a  (Add)

            LHarc a ARCHIVE.LZH FILE1.EXT

       FILE1.EXT is archived and added to the ARCHIVE.LZH.  If the
       file 'ARCHIVE.LZH' does not exists, then LHarc creates it.  If
       'FILE.EXT' is already in the archive, then LHarc replaces it
       with the new file.


    u  (Update)

            LHarc u Archive.LZH file1.ext

       'FILE.EXT' is archived into 'Archive.LZH' the same as the 'a'
       command.  But now, lharc checks the date of 'file1.ext' when
       'file1.ext' already exists in the archive.  LHarc keeps the newer
       one and ignores the other.  With the /c switch on, the action
       is the same as with the 'a' command.


    m  (Move)

            LHarc m ARCHIVE.LZH FILE1.EXT

        is equivalent to

            LHarc u ARCHIVE.LZH FILE1.EXT
            DEL FILE1.EXT

       Beware of the fact that the second line is always active.  You
       might lose the older 'FILE1.EXT' for eternity.


    f (Freshen)

            LHarc f ARCHIVE.LZH FILE1.EXT

      If FILE1.EXT was archived then the file is replaced by new one.
      The option will not do anything if FILE1.EXT does not exist in
      the archive.

            LHarc f /c ARCHIVE.LZH FILE1.EXT

       will replace FILE1.EXT in the archive without checking, /c
       is to suppress checking.


    e  (Extract) or x (eXtract)

            LHarc e ARCHIVE.LZH

       extracts all the files from ARCHIVE.LZH.

            LHarc e ARCHIVE.LZH FILE2.EXT

       extracts FILE2.EXT from the archive.  If there is a file with
       the name FILE2.EXT in the target directory, then LHarc
       refrains from extraction if the existing file has the same
       time stamp or is newer.  The /c switch will force LHarc to
       ignore this time stamp checking.

            LHarc e ARCHIVE.LZS* [FILE.EXT]

       will extract [FILE.EXT] from .LZS* files archived with LARC
       3.xx.

       Note:  Larc is another popular archiver in Japanese PDS's.


    p  (Print)

            LHarc p ARCHIVE.LZH [FILE2.EXT]

       will output un-archived file(s) to standard output.

            LHarc p /v ARCHIVE.LZH [FILE1.EXT FILE2.EXT ....]

       will usually activate the utility 'less' and will prompt for
       the output.  A temporary file LHarc.TMP is created and will
       be deleted later.

            LHarc p /vsee ARCHIVE.LZH [FILE1.EXT]

       will invoke "see" page formatter, and redirect output to
       stdout in a paged format.  Refer to PC-LESS.ARC, LIST64A.ARC
       and SEE15.ARC.  (These should be available in most BBS
       libraries).


    d  (Delete)

            LHarc d ARCHIVE.LZH FILED.EXT

       Deletes FILED.EXT from the archive ARCHIVE.LZH.


    l  (List)

            LHarc l ARCHIVE.LZH [*.c *.h README.DOC]

       List information about archived files in ARCHIVE.LZH to
       standard output.  Each file takes one line of output.  A '+'
       indicates a directory name is stored with filename.  If you
       specify file extensions, then you will see only files with
       the matched extensions.

       In the above command line, you get informations of all the

                .c FILE(s)
                .h FILE(s)
            and README.DOC FILE(s).

            LHarc l /x ARCHIVE.LZH [FILE.C FILE.H...]

       Similar to the above except that the listing takes two lines
       per file; the first with full pathname and the next
       containing the other information.


    v  (View)

            LHarc l /x Archive.LZH

       is equivalent to LHarc v ARCHIVE.LZH.


    s  (Self-extract)

            LHarc s ARCHIVE.LZH

       Create self-extracting file "ARCHIVE.COM" from ARCHIVE.LZH.
       If a home directory is specified, this file will be created
       in the home directory.

       There exists a definite maximum size for a self-extracting
       .COM file.  Theoretically, it is as large as 640 free memory
       area, but normally please make a check if your self-
       extracting file exceeds 400 KiloBytes.

            LHarc ARCHIVE.LZH FILE1.EXT ....no command specified.

       Lharc acts exactly as with l command.  This optional action is
       temporary.  Don't count on it in the coming version.

Switches:
========

   Specify switch(es) following the switch character /.  If you want to
   specify more than one switch, type characters continuously without
   any space between, like: /rxwe\work or /cxvless.  When the switches w
   and v are used with other switches, they must be specified at the end
   of a sequence as above examples show.

   You may place a '+' or '-' sign after switches with the following
   meanings: '+' sets the switch on, and '-' sets the switch off.

            '2' option will be explained later.
            If you just specify a /<switch> without '+' or '-'
                then <switch> will toggle from 'on' to 'off' or
                vice versa.

   Note: '2' creates a special attribute to /r and /v switches.
             (See below).

   You have to use small letters for switches.  Capital letters are re-
   served for future use.

            /x[-|+] (eXtend)

   Extend file_names with directory names.  This switch determines
   whether to store only the file name or the full path name.

   Suppose if you are in the root directory \, and you have 2 files:

            \TC\include\SYS\STAT.H, and
            \STAT.H

            LHarc a ARCHIVE.LZH STAT.H

   will archive file STAT.H from the current (root) directory only.

            LHarc a ARCHIVE.LZH STAT.H \TC\include\SYS\STAT.H

   will fail with the message 'Same name in another path', because
   eXtended directory names are not specified.

            LHarc a /x ARCHIVE.LZH STAT.H \TC\include\SYS\STAT.H

   will eXtend the stored path_names to STAT.H and \TC\include\SYS\
   STAT.H and include both files in archive.

            LHarc e ARCHIVE.LZH STAT.H

   extracts only one STAT.H file to the root directory.

            LHarc e /x ARCHIVE.LZH STAT.H

   extracts two STAT.H files, one on the root directory, and the other
   in the directory \TC\include\SYS.

   Use of the /r switch will allow storage of all files with the same
   name by recursively searching directories.

            LHarc a /r ARCHIVE.LZH STAT.H

   archives two STAT.H files, one on the root directory, and the other
   in the directory \TC\include\SYS, with pathnames.

   The /r switch always sets /x simultaneously.  If you want to do
   without /x then please set /x- after specifying the /r switch.

            /p[-|+] (Precise)

   Give a precise distinction between filenames.  Suppose your archive
   TC.LZH has both STAT.H and SYS\STAT.H

            LHarc e TC STAT.H

   will extract both files and one with older date will be overwritten
   by the other.

            LHarc e /p TC.LZH STAT.H

   will give you only STAT.H

            LHarc e TC.LZH SYS\STAT.H

   gives you SYS\STAT.H only.

            /c[-|+] (ignore Comparison of time stamp)

            LHarc [efux] /c ARCHIVE.LZH [FILE1.EXT FILE2.EXT...]

   If a file with the same name is to be created, the default is to
   compare the time stamp of two files and some are overwritten and some
   are just ignored.  This switch forces overwriting of existing files
   with the extracted one.

            /m[-|+] (no Message)

            LHarc [commands] /m ARCHIVE.LZH [FILE1.EXT FILE2.EXT...]

   by default LHarc ask questions like "Overwrite y/n ?".  This switch
   will suppress these prompts and processing continues as if "y" is
   typed in.

            /a[-|+] (any Attribute)

            LHarc a /a ARCHIVE.LZH FILE1.ARC

   adds FILE1.ARC to archive with compression.

   Normally, LHarc will not store files with hidden, read_only and/ or
   system attributes.  This switch forces LHarc to archives files with
   these attributes.

            /r[-|+|2] (Recursive)

            LHarc a /r ARCHIVE.LZH *.c

   Adds to ARCHIVE.LZH all the files with the extension .c under the
   specified directory.

   There are 3 modes in collecting files to be archived:

      (a)  default or /r-.

           Archive files with specified names only.

      (b)  File_name specified mode across directories.
           (When you specify /r or /r+ switch).

           Disregards directory names, and adds all the files with
           the specified file_name under the current working
           directory.  Normally, this is used to archive all the
           versions or all files of similar nature.

      (c) directory mode.  /r2

              LHarc a /r2 DOCUMENT.LZH \DOC

           This is like unix -r switch.  All the files in a
           directory specified by path_name \doc are archived into
           Documents.LZH.  Normally used to archive a complete
           directory.

   Switches /r and /r2 will invoke the /x switch simultaneously.  You
   may have to toggle /x switch off after /r or /r2 specification, with
   /x-.  The switch /x- is to disregard directories.


            /w[-|+|<working directory name>]

            LHarc a /w[ d:\tmp ] Archive.LZH [ File1.EXT File2.EXT....]

   All the temporary files are created on the drive d:\tmp.  In case no
   directory name is specified, the current directory becomes the work-
   ing directory.  All the temporary files created in the process of
   archiving reside in this directory and will be deleted later.

            SET TMP = d:\

   does exactly the same, but may be overridden by /w switch.

   Normally the switch is necessary when:

      1) you have no room in the directory where the .LZH file is,

   or

      2) you want your work done silently and swiftly on a Ram Disk.


            /v[-|+|2|< utility command redirection >] (View by page)

            LHarc p /v ARCHIVE.LZH

   when you want to read formatted output from print command of
   LHarc.  The default utility is less.com.

   Note:  LESS.COM is a tool similar to the DOS MORE.COM and
          something more, but it is less than the "less" in
          American Unix Networks.  PC-LESS.ARC or LIST64A.ARC
          (available from many BBS sources in the U.S.A.) works
          as well as Japanese tool.

   LHarc create an un-archived file LHARC.TMP and invokes the utility,
   usually a page formatter like see.exe or list.exe.  Temporary files
   will normally be deleted after you have read the output.


            LHarc p /v2 [ /v<utility name> ] ARCHIVE.LZH

   LHarc suppress the output of path_name or file_name.  The switch is
   supplied for viewing binary files with a dump command.


Archive Name(Path_name).
=======================

   All the archived files have the same format as Larc* except for the
   extension .LZH while Larc uses .LZS.  When you use a different ex-
   tension for the path_name, LHarc will prompt you with that extension.

   Wildcards are valid in e,x,p,l,v,s commands.

            LHarc e *.LZH *.c

   un-archive all the files with the extension .c from all archive(s).


Home_directory.
==============

   If you specify a home_directory then everything happens on this
   directory as if it is the current directory.  Specify a
   directory_name ending with either '\' or ':'.  In archived files,
   there will be no record of this home directory name.

   Example.  In the following directory tree:

                           |-- BIN --
                           |
          |-- \ --|-- TC --|-- LIB --
                           |
                           |-- INCLUDE --|-- SYS --|-- STAT.H

   Type from your root directory \

            LHarc a /r Archive.LZH tc\include\ stat.h

   to have \TC\include\SYS\STAT.H archived in ARCHIVE.LZH with name
   SYS\STAT.H in your home directory \TC\include.


File Name (a Path_name):
========================

   File_names or Path_names of files to be archived must be specified or
   LHarc will automatically assume *.* with no directory names.  The
   wildcards behaves exactly as in MS-DOS.  You can not use them in
   specifying directories except in the mode / r2, as UNIX -r option for
   cp, mv or rm.


Terminology:
============

   Path name, Directory Name, File_name:

            a:\tc\include\stdio.h
            |<---- path_name --->|
            |<---------->||<--->|
           directory_name  file_name


   SWITCH character:

   If you are using some other letter like '-' for the forward slash '/'
   as switch delimitter from function call 37h, SET VECTOR, you have to
   place your delimitter, say '-', instead of our '/' like -cx.  Then
   you may use '/' for a directory delimiter, as in Unix convention.
   You can use '-' as a switch charcter anyway.

   The above comment may not be true if you are not using MS-DOS 3.xx.


2. Set switches in environmental variable.

   You may set switches by using the Environmental variable 'LHARC'.

   Example.
   A>set LHarc=/we: /r2        Set work directory in drive e: and
                                archive files in directory mode.

   It is, also possible to specify the working directory with environ-
   mental variable 'TMP', like set TMP=e: but the /w switch override the
   setting.


3. Self-Extracting Files.

   If a self-extracting file is executed, then it will try to extract
   all of the archived files into the current directory.  Every
   extracted file has the attribute 20h.  If a file with a name of
   AUTOLARC.BAT exists, this batch file is activated immediately.

   It is possible to embed some jokes or even so-called viruses in this
   autolarc.bat file.  The possibility exits even with other SFX files
   from ARC or PKware.  So I have chosen to keep the batch file option
   active in the present version because the world is now well-prepared
   for those tricks.


4. Archive file header.

   Our header is compatible with that of Larc*.  Methods of archiving
   are two:

            -lh0-    stored as it was,
            -lh1-    compressed by LZHuf coding.

   LArc archived files with extension .LZS may be un-archived by LHarc,
   if they belong to type 4 and 5.

   Note:  Larc is another Japanese archiver with source code
          published on a Journal.  [It will be uploaded to the
          American GEnie network soon].

5. Result Codes.

   LHarc returns following results codes to parent process.

    0   normally finished.

    1   Process finished with ignoring the nonexistent filenames in
        archiving.  Or, CRC error occurred during un-archiving.

    2   Process terminated by a fatal error.  No archives created nor
   moved.

    3   Unable to write in the temporary files into archive.  Work file
        renamed as LHARC.)2(. Original archive was deleted. Try re-
        naming LHARC.)2( as your archive, although it could be damaged.


6. Temporary Files.

        LHARC.)1( Old archive file renamed
        LHARC.)2( Working file to create new archive file
        LHARC.TMP Work file to be reviewed by some page formatter

   If a file with these names already exists, then the normal action of
   LHarc is not guaranteed.


7. My Distribution Policy.

   Under conditions which follow, you may freely copy and distribute
   this software.

   1.  Under all circumstances, 'Copyright by Haruyasu Yoshizaki'
       must be attached to the copy.

   2.  This manual or its hardcopy should go together with the
       software.

   3.  You may modify the program, but in that case, you must
       distribute the complete source code for the program,
       including your contribution, and you must make it clear that
       you have made such modifications.

   4.  You must try to distribute the newest version available.

   5.  I assume no warranty for the claim of any damage you may
       sustain by using this software.

   6.  I have no obligation to revise the program to correct any
       fault in this software.

   7.  For the commercial use of this software, I add the following:

      a.  The entire software made incorporating this program
          should not be copy protected in the sense that
          DISKCOPY command of MS-DOS makes a perfect copy.

      b.  Every part of the package should print the name LHarc
          and the copyright banner.

      c.  The distribution policy of this software should be
          printed either in the manual, in the package or on the
          disk-label.


8. Acknowledgments.

   Special gratitude for H.Okumura who uploaded the code for LZARI in
   PCVAN on which this LZHuf coding is based.  To K.Miki, who re-posted
   LZARI to Nifty Serve, and who is the author of Larc I, also, express
   my gratitude.  For those who contributed reports and comments and
   information on bugs, I thank you very much.

   The "exe" file for LHarc is nearly 2 KiloBytes smaller due to use of
   pcs27162 by S.Takanami.  I honor the utility and thank him for
   letting me use it in LHarc.

   I have made so many revisions to LHarc, yet I do not think I can
   ever expel all the bugs dwelling inside.  I would appreciate your
   comments and bug reports.  Please route them to me via the SDR Forum
   of Nifty or salon.pds of ASCII Net.  [American users of GEnie can
   send messages to the author via K.OKUBO].


9. References.

   1) AP-Labo :A Harddisk Cook Book Shouei Press,(1987).

   2) Kurita,T:Jewlry Box of Computing 43, Huffman Coding, bit,
      Vol.20, No.7, pp.100-101 (1988).

   3) Miki K, Document for Larc : Larc.man (to appear on GEnie).


10. History of Revisions.

    Ver. 1.00
         1.  Mode without working file added
         2.  /r switch forces /x switch simultaneously


    Ver. 0.07c
         1.  Remove bug in detecting memory shortage
         2.  Compacted self-extracting program


    Ver. 0.07a
         1.  Ver. 0.05 ` 0.07 break down Heap areas, corrected
         2.  Accept any directory names with any attributes

    Ver. 0.07
         1.  Prohibition of actions to a write-protected archive
         2.  'm' command now removes files made by older versions
         3.  Error handling routine revised in dealing with wild
             card names for archive files
         4.  No commands specified is now interpreted as l command
             specified
         5.  Error level 1 return when CRC checking detect an error
             in un-archiving
         6.  Program now halts when self-extracting process meets an
             error.
         7.  Bug in CRC checking when a directory name is met in un-
             archiving process.

    Ver. 0.06b
         1.  Removed possibility of a damaged cluster appearing in
             failing to re-create(=freshen) an archive file
         2.  Remove the "+" bug in redirecting with p command

    Ver. 0.06
         1.  If a file transaction fails with u, m, or f commands,
             LHarc will leave the archive file as it is.
         2.  File attributes were misunderstood by f commands some-
             time, possibility eliminated.

    Ver. 0.05
         1.  CRC checks extend to self-extracting files
         2.  Completely recursive modes are made possible for
             a, u, m commands
         3.  Meet append.exe of MS-DOS version 3.3
         4.  You don't have to add \ anymore to the end of working
             directory name

    Ver. 0.04
         1.  Support environmental string 'TMP'
         2.  "LHarc p  /v  a.LZH a_file"
             used to delete 'a_file' in case of an error, bug fixed
         3.  Checks whether there exists a file with same name in
             making a self-extracting file
         4.  In a self-extracting archive file, if a file with the
             same name with larger size exists, then LHarc kept
             difference when overwritten by a smaller file, this bug
             removed

    Ver. 0.03
         1.  The environmental variable 'LHARC' sets some of the
             switches
         2.  Made it possible to specify '+', '-' by switches
         3.  /v switch included
         4.  Now wild cards can be used for archive names for
             explvs commands
         5.  Home directory names had some interactions with Kanji-
             code, fixed
         6.  Fixed header file bugs of self-extracting .EXE files

    Ver. 0.02
         1. Support of m command
         2. LArc 3.xx compatibility - type 4, 5 .lzs files are un-
            archived
         3. Accept systems with different switch characters
         4. Minor bugs fixed with e command
         5. Revised format for l command

    Ver. 0.01
         1. Support of Self-extracting Files
         2. p command added
         3. /c switch applies for more combinations of commands
            and switches.
         4. Error handling revised
         5. Bug fixed in l command
         6. New algorithm introduced in sorting path-names


11.Comments:

a. Some other algorithms I have in mind.

   For some specific files, the compression rates are not as good as
   PKware's PKZIP.  For such files, I may use LZSS compression with
   correlated arithmetic compression.  This is an effective method and
   my experiments show that the rates are no less than PK's.  Yet, it
   takes too much time in both archiving and de-archiving processes,
   with much higher memory consumption.  Consequently, I intend to keep
   on working on this LZHuf algorithm.

   Naturally, I am ready to accept any comments and I continue to
   experiment.


b. Naming of LH(arc)

   Some people expressed concerns that the string 'arc' is contained in
   the name LHarc.  I make the following statements for them.

   The crucial point in the case where Sea sued PK, is the way PK
   advertised and sold Pk(x)arc with an emphasis on arc-compatibility,
   with a certain amount of profits from shareware contributions.

   This is not the case with LHarc.  I used a different archiving
   method and made it a freeware program with a format not compatible
   with arc.  I hope I will not be bothered by similar accusations.

                                - end -