Club Amiga de Montreal

home *** CD-ROM | disk | FTP | other *** search

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 300.lha / LHarc_v1.0 / lharc.doc < prev next >

Wrap

Text File | 1980-12-06 | 18.1 KB | 462 lines

________________________________________________________________________ ------------------------------------------------------------------------ LHARC vers. 1.0 for the Commodore AMIGA Compatible with version 1.13 of Lharc for MSDOS systems by Paolo Zibetti (FidoNet 2:331/101.6) ------------------------------------------------------------------------ IMPORTANT NOTICE: This program is copyrighted by Paolo Zibetti, but can be freely distributed, providing that the following rules are respected. - No change is made to the program nor to the accompaning documentation - The package is always distributed in its complete form consisting of 3 files: "Lharc", "Lharc.doc" and "Changes". - Every form of distribution is allowed and encouraged, but no fee can be charged for this program exept for, possibly, the cost of magnetic media. - It cannot be distributed in any commercial product without the written consent of the author. By copying, distributing and/or using the program you indicate your acceptance of the above rules. Also remember that this program is supplied 'as is': the entire risk as to the quality of the program is to the user. In no event will the author be liable for direct or indirect damage or loss resulting from the use of this program. ------------------------------------------------------------------------ ________________________________________________________________________ ------------------------------------------------------------------------ Lharc is an archive program such as Arc and Zoo. It can store several files in one archive in a compressed form which is generally more efficent than that used by Arc and Zoo. It also supplies all of the archive handling capabilities that an archive program should have. Its only weakness is compression speed: Zoo 2.0, for example, is much faster, but if compression efficency is more important for you than compression time you'll surely appreciate this progam. (anyway decompression is much faster than compression) Lharc is run from CLI with the following command line: Lharc [<switches>] <Command> <Archive> [<dest path>] [<file patterns>] items in square brackets are optional. <Command> can be any of the following (case is not significant): e,x extract files from archive Extracts files from archives. If you specify some file names or patterns only those files satisfying the patterns are extracted, otherwise all the files in the archive are extracted. While extracting files, Lharc checks if a file by the same name already exsists in the destination directory and prompts you before overwriting the old file with the extracted one (unless you specified the -m switch) See below under '<dest path>' for a discussion on where the extracted files are put. l,v show archives contents Displays the names of the files in an archive along with their date, time, CRC, compression type, original lenght and compressed lenght. If the -x switch is specified file names are listed complete with their path (if present in the archive), otherwise only the name of the files is listed. p extract and print files to screen same as 'e' and 'x', but extracted files are sent to stdout t test archive integrity Checks CRCs and checksums to ensure that the archive is not corrupted a create archives or add to existing archives If you try to archive a file and a file by the same name already exists in the archive the file will not be added and a message will be printed on the screen to inform you. By default only file names are stored in the archive, use the -x switch to store file names complete with their paths. Also, by default file attributes are not stored, use the '-a' switch to obtain this. m move files into archivs Same as add, but deletes original files after archiving them [ Please, see below 'Bugs'] d delete files from archives You can delete from an archive a maximum of 150 files at a time, if you find that they are too little, please let me know! u update files in archives Same as with the 'a' command. However, if a file already exists in the archive, LHarc will check its time stamp and will keep the newer one and ignore the older one. f freshen files in archives Replaces a file in the archive with the newer one only if a file with the same name already exists in the archive. Otherwise, no action is taken. <Archive> is the name (eventually preceded by a path) of the archive you want to work on. If no extension is specified the default extension .LZH is used. With the 'l' (or 'v'), 'e' (or 'x'), 'p', 't' and 'a' commands you can work on multiple archives by using wildcards (see 'file patterns' below for a list of accepted wildcards). For example "lharc v *.LZH" will show the contents of all the archives in the current directory, while "lharc x *.LZH *.c" will extract all the C source files contained in all the archives in the current directory. [<dest path>] This parameter is significant only with the 'x' (or 'e') command and is ignored otherwise. It tells where to put the extracted files; if not specified, extracted files will go to the current directory. Similarly, if you specify the -x switch, files will be extracted to the path specified in the archive with respect to <dest path> or with respect to the current directory if <dest path> is omitted. Please note that this paramenter must always end with '/' or ':' otherwise it will not be recognized as such and will be considered as one of the file patterns. If the path specified by <dest path> (or equivalently the path stored in the archive if you are using the -x switch) deos not already exist, you will be prompted if you want new directories to be automatically created (unless you specified the -m switch, in which case directories will be created without any prompt). [<file patterns>] rappresents an optional number of file names or file patterns. They indicate which files to extract/compress/list/delete, ecc. Accepted wild cards are the standard AmigaDOS '#' and '?' plus the '*' which is a synonim of '#?'. Since however the asterisk is a valid caracter in AmigaDOS file names I provided the '**' sequence as an escape. So if you want to refer to a file name containing an asterisk just double the asterisk in the file name. Example: '*.c' is equivalent to '#?.c' and refers to all the files ending with '.c', while 'my**file' refers to the file 'my*file'. [<switches>] rappresents an optional number of switches that are used to change the behaviour of the program. A switch is composed by a leading '-' followed by one letter; unlike commands which are case insensitive, switches are case sensitive. An important point is that if you want to specify more than one switch, every switch must be preceded by its own dash, i.e. to activate the 'x' and 'm' switches you must enter "-x -m" and NOT "-xm". Here is a summary of the available switches: -p Pause after loading [note that this is lowercase 'p'] Causes Lharc to wait for the user to press RETURN before executing a command. This allows floppy disk users to swap disks after loading Lharc. -m no Message for query Suppresses all the queries Lharc normally issues before overwriting existing files or before creating new directories If you specify this switch Lharc will behave as if you typed 'Y' in response to all the prompts. -x use eXtended file names By default, LHarc stores only the file names of files and disregards the names of the directories in which they reside. This switch, used with the 'a' command, tells LHarc to extend all file names with directory names; used with the 'e' command tells Lharc to extract archived files together with their stored directory names, eventually creating the needed directories if they don't already exist; used with the 'l' command tells Lharc to list files with their full path name. So it should be clear that to preserve the directory structure you must use this switch both during compression and during extraction. -n No progress indicator Suppresses the display of the number of bytes beeing processed during compression or decompression. May be useful if you redirect to a file the output of Lharc. Note: this version of Lharc allows the -N switch as a synonim of -n : but this might change in future versions, so preferibly use the lowercase letter. -w set Work directory Use this switch to choose your own directory for temporary files. The directory name must immediatly follow the letter 'w' without any leading space, i.e. to set the 'temp' directory on your hard-disk as the working directory you must write "-wdh0:temp". See below "Temporary files" for a discussion on where temporary files are stored in the absence of this switch. -P set Priority [note that this is uppercase 'P'] Use this switch to set the priority with which Lharc will be executed. Priority must be in the range -5..+5 and must immediately follow the 'P' letter without blanks in between. By default Lharc is excuted with the same priority of the task that invoked it; using this switch will set the new priority immediatley after loading and will set back the priority to the original value immediately after terminating. If you want to do something else with your Amiga, for example editing a letter, while Lharc is compressing a long file, I suggest that you set Lharc's priority to one less than that of the other program, i.e. if you started your editor with the usual priority of zero then invoke Lharc with the '-P-1' switch to set its priority to -1 -a consider file Attributes By default Lharc will ignore file attributes (i.e. the flags indicating protection from deletion, and so on) for maximum compatibility with the MSDOS version: in other words it will store files with an attribute bit pattern which is suitable for MSDOS machines while during extraction it will ignore the attributes stored in the archives, setting the attributes of the extracted files to the usual '----rwed'. If you use this switch, on the contrary, files will be stored with their original attributes and during extraction the stored attributed will be restored. Remember that, to effectively preserve file attributes, you must use this switch both during compression and during extraction. Of course AmigaDOS file attributes are meaningless to MSDOS and vice-versa; so extract files with the -a switch only if you are sure that they contain AmigaDOS file attributes and similarly compress files with the -a switch only if you are sure that the archive will be unpacked only by Amigas and not by MSDOS machines. (Anyway no harm is done if this rule is not respected: extracted files will simply have strange attributes) -u convert file names to Uppercase By default Lharc stores file names/paths with thier original case, if you use this switch they will be converted to uppercase. See below 'Compatibility' for a possible use of this switch. -r Recursively collect files This switch instructs Lharc to search for files matching the specified patterns not only in the specified directories, but also in all the subdirectories that may be found in the specified directories. For example: "Lharc -r a archive.lzh df1:source/*.c" will search for files whose name ends with ".c" in "df1:source/" and in all the subdirectories that may be contained in the "df1:source" directory. Another example: "Lharc -r a archive.lzh df1:*" will archive the entire disk in drive df1:, including all its subdirectories. Very powerfull, isn't it ? When you specify the -r switch, files are always stored with their path name, i.e. the -r switch automatically turns on the -x switch, too. -Temporary files. While compressing files Lharc creates a temporary file called 'Lharc.TMP_XXXXXX' where XXXXXX is a hex digit representing the address of its own Task structure as returned by Exec's FindTask(NULL). The reason for the XXXXXX part of the name is that if you run multiple copies of Lharc at the same time each copy will create its own temporary file with a different name (usefull for multiline BBSes for example). Here is how Lharc decides where to store temporary files. If you specify a path with the -w switch temporary files are stored there, otherwise if the T: logical device is assigned they will be stored in that directory, otherwise they will go to the current directory. If you are not using the -w switch, in order to increase compression speed, I raccomand that you assign T: to a directory in the ram-disk. Note however that T: is usually automatically assigned to 'ram:t' in the startup-sequence of the standard Workbench, so, unless you have modified the startup-sequence, you don't have to worry about this. -Corrupted archives This version al Lharc for the Amiga has the capability of automatically handle corrupted archives. A Lharc archive is made up of several compressed files each precedeed by a header containing information about file name, date, lenght,... To ensure that the archive is not corrupted the header also contains a 16 bit CRC of the file and an 8 bit checksum of the header itself. If during extraction Lharc finds a corrupted file (i.e. one whose CRC does not match with the one stored in the header) the file is extracted anyway, but a warning is printed on the screen. The worst case comes when the header of a file is corrupted: in this case the file cannot be extracted even if the file itself is not corrupted. In this case Lharc will automatically skip the corrupted entry by starting a search for the next valid entry in the archive and will print a message like "WARNING: skipping extraneous/corrupted data" The reason for which it says "extraneous/corrupted" is that an Lharc archive might happen to contain parts that Lharc cannot recognize as valid archive entries even it's not corrupted. This happens when you are extracting files from a self-extracting archive produced by the MSDOS version of Lharc, since a self-extracting archive contains 8086 extraction code which the Amiga-Lharc sees as extraneous data. The only extraneous data which is passed without warnings is additional bytes at the end of an archive: since they are likely to consist of zero padding due to XMODEM transfer they are totally ignored. -Bugs The only relevant bug remaining in this version is that the 'move' command doesn't always work with wildcards (often Lharc stops after succesfully moving the first file, even if there are other files that should be moved). I have found the source of the problem, but since I plan to rewrite almost entirely the offending part of code in next version (I want to give users an option to alphabetically sort files beeing added), I decided not to correct the bug in this version. Anyway the move command is seldom used. -Compatibility. This program is aimed at full compatibility with the MSDOS version 1.13 of Lharc. A few little problems might arise from some file names that are legal under AmigaDOS, but illegal under MSDOS. As a matter of facts AmigaDOS allows a wider range of file names (almost every caracter in the ASCII set is allowed and file names can be longer than 8 characters). For the greatest convenience of Amiga users, I choose not to restrict the file name range to accomplish the MSDOS rules, but if you expect that your archives will be unpacked on an MSDOS machine you'd better rispect the MSDOS limits. Also note that, although MSODS Lharc version 1.13 CAN extract files whose names contain lowercase letters, its pattern matching functions don't work properly with lowercase file names. So if you want to extract an Amiga-created archive on an MSDOS machine by using pattern matching functions (for example to extract only some files instead of the whole archive) you have to create the archive on the Amiga with the -u switch. Finally, to attain 100% compatibility you shuold not use the '-a' switch (see above in the switch descriptions) Also note that the MSDOS version of Lharc has the additional capability of extracting files from archives produced by Larc (a pupular Giapanise archive program): this feature will not be implemented in the Amiga version. -Acknowledgements: First of all I give credit to Haruyasu Yoshizaki for devising such an efficent compression algorythm as LZHUF. Second, since the source to the MSDOS version of Lharc is scarcely portable (lots of 8086 assembler ruotines and MSDOS-dependent C functions), I had to rewrite the program from scratch. Note howerer that for LZHUF compression/decompression I have used with few modifications a 'C' source for an example of single file compression which I found on a BBS. For sake of correctness I quote here the the header of this source: /* * LZHUF.C English version 1.0 * Based on Japanese version 29-NOV-1988 * LZSS coded by Haruhiko OKUMURA * Adaptive Huffman Coding coded by Haruyasu YOSHIZAKI * Edited and translated to English by Kenji RIKITAKE */ I whish to thank the above people whose work has been of foundamental importance for this project. Many thanks also go to all the people who contributed with suggestions and bug reports and particularly to Luca Spada for his invaluable beta testing work. Please send suggestions, comments and bug reports to: Paolo Zibetti Fidonet 2:331/101.6 node 2:331/101 (AmnesiA) is also the official distribution node for Amiga-lharc: you'll always find the latest version available on this board. If you are an officially listed FidoNet node you can f'request the latest version of Lharc with the magic file name AMILHARC. Amnesia (2:331/101) phone +39-331-263425 (v32/HST, upto 14400 bps)