Path: utzoo!utgpu!jarvis.csri.toronto.edu!mailrus!iuvax!bsu-cs!ibmbin
From: dhesi@bsu-cs.bsu.edu (Rahul Dhesi)
Newsgroups: comp.binaries.ibm.pc
Subject: v02i035: user manual for lharc 1.0
Summary: lharc10.txt, user manual for lharc 1.0
Message-ID: <6507@bsu-cs.UUCP>
Date: 4 Apr 89 19:00:31 GMT
Sender: ibmbin@bsu-cs.UUCP
Followup-To: comp.binaries.ibm.pc.d
Lines: 690
Approved: dhesi@bsu-cs.bsu.edu
X-Submissions-to: ibmpc-binaries@bsu-cs.bsu.edu
X-Questions-to: ibmpc-binaries-request@bsu-cs.bsu.edu

Checksum: 1047552142  (Verify with "brik -cv")
Posting-number: Volume 02, Issue 035
Originally-from: Haruyasu Yoshizaki, K.Okubo, & Paul Homchick <no email addr>
Submitted-by: Rahul Dhesi <dhesi@bsu-cs.bsu.edu>
Archive-name: lharc/lharc10.txt

Here is a user manual for the archiving program lharc 1.0e that was
posted here recently.  It is by Haruyasu Yoshizaki (Yoshi), the author
of lharc, who wrote the manual in Japanese.  It has been translated
into English by K.Okubo and revised by Paul Homchick.

There are really two files here:  "lharc10.man", the manual, and
"readme", a revision history.  Cut at the cut lines to separate the
two, or optionally just keep them as one file.  The manual was
originally called "lharc.man" but I renamed it so there won't be
confusion when further versions of the software or the manual appear.

-- cut here for "lharc10.man" --
         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

------------------------------------------------------ 1989 - 3 - 4 ----

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 Review and Deview.  The next shock came when I saw Mr.
Okumura's LZARI which has even better compaction 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 public domain. 

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
sequence of switches can be specified.

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 'file1.ext' is already in the archive, then LHarc replaces it
       with the new file.

    u (Update)

     LHarc u Archive.LZH file1.ext
       'file1.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 is created.  You must delete this
       file later.  Or, you may redirect the output to the "more"
       command of DOS.


    d (Delete)

      LHarc d Archive.lzh filed.ext  

        Deletes filed.ext from the archive Archive.LZH.


    l (List)

      LHarc l Archive.LZH 
        List to standard output [+] filename in Archive.LZH in two
        columns. '+' indicates a pathname exists with filename.

      LHarc l /x Archive.LZH
        List filenames in Archive.LZH in full detail standard output.
        Each line consists of [pathname] '+' filename. Similar to -l
        switch in UNIX ls command.


    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.


*    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: /rxwa or /cxve.  When the switches r and v
    are used with another switch, they must be specified at the end of
    the sequence as above.

      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.
               '++' means '-'.  That is, both '+' and '-' are toggles.

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

*   You have to use small letters for switches. Capital letters are
*   reserved for future use.


    /x[-|+] (eXtend)

      Extend file_names with directory names.
  
    LHarc a Archive.LZH stat.h
       will archive two files with the same name in two different
       directories.

       Suppose if you are in the root directory \, and you have 2 files
       \tc\include\sys\stat.h and
       \stat.h in the same directory.
     
     LHarc a Archive.LZH stat.h
       will archive stat.h only.

     LHarc a /x Archive.LZH stat.h
      will eXtend the search to the depth of \tc\include\sys\ and archive
      the other stat.h with the name \tc\include\sys\stat.h.

     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.

*    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 just stores files with archive bit set, this
       switch forces it to add all files regardless of the attribute.


    /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. When you specify /r or /r+ switch.

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


      (c) directory mode. /r2 

          LHarc a /r2 Documents.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 working directory.  All the temporary files
        created in the process of archiving reside in this directory
        and will be deleted later.
      SET LHarc.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 > more
       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.
      
       LHarc create an un-archived file LHARC.TMP and invokes the
       utility.  Temporary files will normally be deleted after you
       review the output.
    
     LHarc p /v2 [ <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.


Definition:  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
    extension for the path_name, LHarc will prompt you with that
    extension.

    Wildcards are valid in e,x,p,l,v,s commands.
   
   LHarc e Archive.LZH *.c
    un-archive all the files with the extension .c.


Definition: 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 /rx ex Archive.LZH tc\include\ stat.h

          to have \tc\include\sys\stat.h archived in Archive.LZH with
          name SYS\STAT.H .


Definition:  File Name (a Path_name) to be archived.

*     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 delimiter from function call 37h, SET VECTOR, you have
    to place your delimiter, say '-', in front of our '/' like -/cx.
    You may use '/' for a directory delimiter, using the Unix convention.
    You can always use '-' as a switch character 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 totally recursive mode.

    It is, also possible to specify the working directory with environmental
    variable 'TMP', like
    set LHarc.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.

      Dos returns the following results codes after batch files.

    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 renaming 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 make a list of archived files inside cabinet.

    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. 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.

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.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.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.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.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 sometime.
       Possibility eliminated.

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.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.07a

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

Ver. 0.07c

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

Ver. 1.00 

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


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 experiment shows 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 of "lharc10.man" --

-- cut here for "readme" --
The accompanying document is a preliminary draft of my personal
interpretation of the LHarc User Manual in Japanese contained in
LHarc10d.com.

I have tested command lines in this English version with
LHarc10e.com extracted LHarc.exe 1.00 except for the switching character.

The machine I used for the test is Toshiba T5100 with MSDOS 3.30 from
Toshiba.  The machine is one of those PC-Compatibles.

I have had no authorization or checking done on this translation,
either from an English speaking native nor from the author of LHarc.
I do welcome comments on faults in this document in any respect,
language, usage or style.

I am willing to revise, and am actually planning to revise this document.
For the people in U.S. unfamiliar with Japanese archivers, I think I have
to upload the twin archive tool Larc by K.MIKI, very soon.
 
Please notify to the address K.Okubo on GEnie for any comments or questions.

[Some further editing of the lharc manual (without the benefit of the
Japanese original, which wouldn't have helped anyway) was performed by
Paul Homchick, one of the SysOps on GEnie's IBMPC RoundTable].

March 26, 1989
-- end of "readme" --