diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Arcinfo | 124 | ||||
| -rw-r--r-- | doc/alf14.atr | bin | 0 -> 92176 bytes | |||
| -rw-r--r-- | doc/alf14_doc.txt | 266 | ||||
| -rw-r--r-- | doc/fileformat.txt | 45 | ||||
| -rw-r--r-- | doc/review.txt | 44 |
5 files changed, 479 insertions, 0 deletions
diff --git a/doc/Arcinfo b/doc/Arcinfo new file mode 100644 index 0000000..6c9d500 --- /dev/null +++ b/doc/Arcinfo @@ -0,0 +1,124 @@ + +ARC-FILE.INF, created by Keith Petersen, W8SDZ, 21-Sep-86, extracted +from UNARC.INF by Robert A. Freed. + +From: Robert A. Freed +Subject: Technical Information for ARC files +Date: June 24, 1986 + +Note: In the following discussion, UNARC refers to my CP/M-80 program +for extracting files from MSDOS ARCs. The definitions of the ARC file +format are based on MSDOS ARC512.EXE. + +ARCHIVE FILE FORMAT +------------------- + +Component files are stored sequentially within an archive. Each entry +is preceded by a 29-byte header, which contains the directory +information. There is no wasted space between entries. (This is in +contrast to the centralized directory used by Novosielski libraries. +Although random access to subfiles within an archive can be noticeably +slower than with libraries, archives do have the advantage of not +requiring pre-allocation of directory space.) + +Archive entries are normally maintained in sorted name order. The +format of the 29-byte archive header is as follows: + +Byte 1: 1A Hex. + This marks the start of an archive header. If this byte is not found + when expected, UNARC will scan forward in the file (up to 64K bytes) + in an attempt to find it (followed by a valid compression version). + If a valid header is found in this manner, a warning message is + issued and archive file processing continues. Otherwise, the file is + assumed to be an invalid archive and processing is aborted. (This is + compatible with MS-DOS ARC version 5.12). Note that a special + exception is made at the beginning of an archive file, to accomodate + "self-unpacking" archives (see below). + +Byte 2: Compression version, as follows: + + 0 = end of file marker (remaining bytes not present) + 1 = unpacked (obsolete) + 2 = unpacked + 3 = packed + 4 = squeezed (after packing) + 5 = crunched (obsolete) + 6 = crunched (after packing) (obsolete) + 7 = crunched (after packing, using faster hash algorithm) (obsolete) + 8 = crunched (after packing, using dynamic LZW variations) + +Bytes 3-15: ASCII file name, nul-terminated. + +(All of the following numeric values are stored low-byte first.) + +Bytes 16-19: Compressed file size in bytes. + +Bytes 20-21: File date, in 16-bit MS-DOS format: + Bits 15:9 = year - 1980 + Bits 8:5 = month of year + Bits 4:0 = day of month + (All zero means no date.) + +Bytes 22-23: File time, in 16-bit MS-DOS format: + Bits 15:11 = hour (24-hour clock) + Bits 10:5 = minute + Bits 4:0 = second/2 (not displayed by UNARC) + +Bytes 24-25: Cyclic redundancy check (CRC) value (see below). + +Bytes 26-29: Original (uncompressed) file length in bytes. + (This field is not present for version 1 entries, byte 2 = 1. + I.e., in this case the header is only 25 bytes long. Because + version 1 files are uncompressed, the value normally found in + this field may be obtained from bytes 16-19.) + + +SELF-UNPACKING ARCHIVES +----------------------- + +A "self-unpacking" archive is one which can be renamed to a .COM file +and executed as a program. An example of such a file is the MS-DOS +program ARC512.COM, which is a standard archive file preceded by a +three-byte jump instruction. The first entry in this file is a simple +"bootstrap" program in uncompressed form, which loads the subfile +ARC.EXE (also uncompressed) into memory and passes control to it. In +anticipation of a similar scheme for future distribution of UNARC, the +program permits up to three bytes to precede the first header in an +archive file (with no error message). + + +CRC COMPUTATION +--------------- + +Archive files use a 16-bit cyclic redundancy check (CRC) for error +control. The particular CRC polynomial used is x^16 + x^15 + x^2 + 1, +which is commonly known as "CRC-16" and is used in many data +transmission protocols (e.g. DEC DDCMP and IBM BSC), as well as by +most floppy disk controllers. Note that this differs from the CCITT +polynomial (x^16 + x^12 + x^5 + 1), which is used by the XMODEM-CRC +protocol and the public domain CHEK program (although these do not +adhere strictly to the CCITT standard). The MS-DOS ARC program does +perform a mathematically sound and accurate CRC calculation. (We +mention this because it contrasts with some unfortunately popular +public domain programs we have witnessed, which from time immemorial +have based their calculation on an obscure magazine article which +contained a typographical error!) + +Additional note (while we are on the subject of CRC's): The validity +of using a 16-bit CRC for checking an entire file is somewhat +questionable. Many people quote the statistics related to these +functions (e.g. "all two-bit errors, all single burst errors of 16 or +fewer bits, 99.997% of all single 17-bit burst errors, etc."), without +realizing that these claims are valid only if the total number of bits +checked is less than 32767 (which is why they are used in small-packet +data transmission protocols). I.e., for file sizes in excess of about +4K bytes, a 16-bit CRC is not really as good as what is often claimed. +This is not to say that it is bad, but there are more reliable methods +available (e.g. the 32-bit AUTODIN-II polynomial). (End of lecture!) + + Bob Freed + 62 Miller Road + Newton Centre, MA 02159 + Telephone (617) 332-3533 + + diff --git a/doc/alf14.atr b/doc/alf14.atr Binary files differnew file mode 100644 index 0000000..7fc3021 --- /dev/null +++ b/doc/alf14.atr diff --git a/doc/alf14_doc.txt b/doc/alf14_doc.txt new file mode 100644 index 0000000..832f59d --- /dev/null +++ b/doc/alf14_doc.txt @@ -0,0 +1,266 @@ + AlfCrunch Documentation Revised 7/10/88 + ----------------------- + + AlfCrunch is an implementation of the Lempel-Ziv compression + algorithm. Although it produces files that have the same structure as + those produced by the Arc program, the two are not compatible. Arc + cannot uncrunch AlfCrunch files, nor can AlfUnCrunch unarc normal Arc + files. + + The current version of the LZ/DZ files is 1.4. Versions 1.1 through 1.3 + are compatible, but not with 1.0. If you have 1.0, you should discard it + and use 1.4. The reason for this is that 1.0 used the same header as + normal Arc crunch. Because of possible confusion over this, the header + used by AlfCrunch was changed. Since 1.0 had very limited distribution, + this situation should not often arise. For those who wish to be able to + detect the AlfCrunch format, the first two bytes of the file will always + be $1A $0F. + + This version fixes an annoying bug in both v1.2 and 1.3. If you had a +subdirectory entry amongst the filenames you were crunching, LZ would +stop at the subdir entry. Also the stack errors will now cause a proper +exit to Dos rather than re-execution. + + Enhancements to v1.4 are the addition of time/date support. If you +are running under Sparta 3.2, LZ will store the Sparta date/time from each +file into the header. DZ does not use this information, it's just there to +provide a reference point. + + When running either LZ.COM or DZ.COM, Memlo must be under $3000. This + should not normally be a problem unless you have a lot of handlers +installed. + A cartridge may be present, as it only affects the size of the buffer + available to AlfCrunch. Maximum speed will be achieved without a + cartridge being present. + + A final note + ------------ + + Well I think this is about as far as AlfCrunch is going to get for now. I +don't really believe there are any more features to add without modifying the +command line parameters. So this version (1.4) will be the last for +some time to come. Except for bug fixes (few if any I hope) the 1.x line will +not change. I hope to add command line parameters similar to ARC and maybe +add the ARC compression methods to finally resolve the compatibility issue. + + Alfred + Programmer's Aid BBS + (416) 465-4182 + + Running AlfCrunch + ----------------- + + To crunch files, load LZ.COM. The title will be displayed, along + with the version which should be 1.4. You will then be prompted for + the output filename. This may be up to 80 characters long, + including subdirectory names. + + If the output file already exists, it is checked to see if it is an +AlfCrunch file. If the first header is correct, then the new files will be +appended to it. If the header is wrong the program will print an error +message and exit to Dos. If the file is shorter than the header length +(29 bytes), then it is simply opened for normal output, which erases it. + + Next you will be prompted for the input filemask. This is what will + be used to select the files. This may also be up to 80 characters long, + including any subdirectory names. Wildcards are allowed. If selecting + all files, the mask must end in *.* . + + Finally, you have the option of turning the screen off. Selecting + this option will speed up the program by 15-20%. Once selected, you will + not again be prompted for this option. If you do not elect to turn the + screen off, the program will continue to present this prompt until it is + selected. + + The program will then select files using the mask and compress them, + displaying the filenames as it progresses. When it has finished, it will + prompt you for additional input filemasks. You may either enter another + mask or simply press return to exit back to Dos. + + LZ and SpartaDos 3.2 + -------------------- + + If you are using SpartaDos 3.2, you may invoke LZ.COM and specify + the output file and input filemask on the command line. The format is: + + [Dn:]LZ Dn:[path>]filename[.ext] [Dn:[path>]filename[.ext] ] + + The square brackets denote optional parameters which may be omitted. + The first filename is the output file. The second is the input + filemask. If you do not specify the input filemask, the program will + prompt you for it. The program will automatically turn the screen off. + When it is finished it will prompt you for more input filemasks. + + To invoke LZ as part of a batch file, the format is almost identical. + The lines in the batch file would be: + + [Dn:]LZ Dn:[path>]filename[.ext] [Dn:[path>]filename[.ext] ] + Dn:[path>]filename[.ext] <- Additional + Dn:[path>]filename[.ext] input masks + + The program will read each input filemask, compress the files + selected and continue until all the input masks have been used. You will + then be prompted for more input masks. If this is part of a larger batch + file, leave a single return after the last input mask to force LZ to + return control back to the batch file. Example: + + [Dn:]LZ Dn:[path>]filename[.ext] [Dn:[path>]filename[.ext] ] + Dn:[path>]filename[.ext] + Dn:[path>]filename[.ext] + (single return here) + [Dn:]LZ Dn:[path>]filename[.ext] [Dn:[path>]filename[.ext] ] + Dn:[path>]filename[.ext] + Dn:[path>]filename[.ext] + (single return here) + + At the end of this, you will be left at the Dos prompt. Because of + the way i/o redirection is handled, an alternative form is available: + + [Dn:]LZ + Dn:[path>]filename[.ext] <- The output file + Dn:[path>]filename[.ext] <- The input filemask + Y <- Turn the screen off + Dn:[path>]filename[.ext] <- Additional + Dn:[path>]filename[.ext] <- input filemasks + (single return here) + + Notice that the Y was only supplied once. When LZ is run in this + manner, it behaves exactly as if you were pressing the keys yourself. If + you turn the screen off, then you need only enter the Y once. If you + said N, then you would need an N after every input filemask until you + said Y. Example: + + [Dn:]LZ + Dn:[path>]filename[.ext] <- The output file + Dn:[path>]filename[.ext] <- The input filemask + N <- Leave the screen on + Dn:[path>]filename[.ext] <- Additional mask + N <- Leave the screen on + Dn:[path>]filename[.ext] <- Additional mask + Y <- Screen off now + Dn:[path>]filename[.ext] <- Additional masks, but no Y + Dn:[path>]filename[.ext] <- is necessary + (single return here) + + Getting Them Back + ----------------- + + To extract the files from an Alfcrunch file, load DZ.COM The title + will be displayed, along with the version number. + + The first prompt is for the name of the file to uncrunch. This + filename may be up to 80 characters long, including subdirectory names. + Wildcards are not allowed. + + The next prompt is the output directory. This is the directory where + the files will be placed when extracted from the crunch file. If the + directory does not exist, an attempt will be made to create the + directory. This may involve creating a number of subdirectories to get + to the last one, so care should exercised with this feature. If + errors occur during the directory build stage, an error message will be + displayed, and the program will return to DOS. You may specify a wildcard to +only extract certain files or use '*.*' to extract them all. *.* is the default. + + Auto directory creation is only available under SpartaDos. Under + any other Dos, if you specify a subdirectory, you will probably get +a single file with the name of the first pathname. + + Assuming all is well, you again have the option of turning the screen + off while files are being extracted. + + The program will then extract each file and place it in the output + directory specified. If any errors occur, an error message is printed + and the program returns to Dos. When all files have been extracted, you + will be prompted for another input file. You may enter another filename + or press Return to exit to Dos. + + The situation may arise where the crunch file has been corrupted. + This may occur due to errors during download, or failure of the disk on + which the file resides. There are several error messages which are + associated with bit errors. + + Msg: Not An AlfCrunch File! + --------------------------- + If this message is issued before any files were extracted, then + either the first two bytes of the file are corrupt, or else the file was + not created by AlfCrunch. If the message is issued after several files + were extracted, then the file has been damaged somewhere in the last + file extracted. You may also get the message which is described next. + + Msg: File Checksum In Error + --------------------------- + DZ has detected that the checksum calculated for the filename just + extracted does not agree with the checksum in the header block. Either + the header block has been damaged or more likely, the file itself has + been corrupted. If the file is a text file, it may be partially correct. + Object file types should be discarded, as it must be assumed they are + corrupt. + + Msg: Stack Overrun + ------------------ + This is an internal DZ error. The file being processed has been + corrupted, and DZ has exhausted all free memory in attempting to extract + the data. The output file produced is incomplete, corrupt, and should be + discarded. + + Msg: Extra Bytes At Eof, Don't Add To File + ------------------------------------------ + This means that the file has extra data at the end which is not valid. +This may arise from downloading where the last block is padded. Do not add +new files to it with LZ as you will not be able to get them back when you run +DZ again. You will get the 'Not An AlfCrunch File!' message at that time. + + DZ and SpartaDos 3.2 + -------------------- + If you are using SpartaDos 3.2, you may invoke DZ.COM and specify + the input file and output directory on the command line. The format is: + + [Dn:]DZ Dn:[path>]filename[.ext] [Dn:[path>][*.*] + + The square brackets denote optional parameters which may be omiited + if you wish. The first filename is the file to be processed. The second + filename is the directory in which the output files are to be placed. + Remember, if any of the directories in the output path do not exist, an + attempt will be made to create them. Remember, you can use a wildcard to +limit the files or take the default +which is '*.*'. + + The program will automatically turn the screen off, and extract + the files. If any errors occur, the appropriate error message will + be printed and control will return to Dos. + + When DZ is finished with the current input file, it will again prompt + you for another input file. You may continue uncrunching files, or + simply press return to exit back to Dos. + + As part of a batch file, the form for DZ is almost identical to the + LZ form. Accordingly, only brief examples will be shown: + + [Dn:]DZ Dn:[path>]filename[.ext] [Dn:[path>][*.*] + Dn:[path>]filename[.ext] <- Second input file + Dn:[path>][*.*] <- Second output path + Dn:[path>]filename[.ext] <- Third input file + Dn:[path>][*.*] <- Third output path + (single return) <- Return to Dos + + The second format is: + + [Dn:]DZ Dn:[path>]filename[.ext] <- First input file + Dn:[path>][*.*] <- First output path + Dn:[path>]filename[.ext] <- Second input file + Dn:[path>][*.*] <- Second output path + Dn:[path>]filename[.ext] <- Third input file + Dn:[path>][*.*] <- Third output path + (single return) <- Return to Dos + + The third format is: + + [Dn:]DZ + Dn:[path>]filename[.ext] <- First input file + Dn:[path>][*.*] <- First output path + Y <- Screen off + Dn:[path>]filename[.ext] <- Second input file + Dn:[path>][*.*] <- Second output path + Dn:[path>]filename[.ext] <- Third input file + Dn:[path>][*.*] <- Third output path + (single return) <- Exit to Dos diff --git a/doc/fileformat.txt b/doc/fileformat.txt new file mode 100644 index 0000000..eb08d13 --- /dev/null +++ b/doc/fileformat.txt @@ -0,0 +1,45 @@ +An ALF archive is laid out exactly like an ARC version 2 or greater +archive, with a 29-byte header for each file, followed by the +compressed data, followed by either EOF or the next file's header. + +See the file Arcinfo for the original ARC file format. For ALF files, +"Byte 2: Compression version" will always be $0F. + +The differences are: + +- ALF files use $0F for the 'compression type' (Byte 1), whereas + ARC files use compression types 2 through 8 (or 1, for ARC v1). + +- The actual compressed data is incompatible with any of the + compression types supported by ARC. Although ALF uses an + implementation of Lempel-Zev, it's not the same implementation + as any of the ones that ARC uses. + +- For ARC, the last file's compressed data is followed by a 0 byte + (in place of the $1A header), to signal "end of archive". For + ALF, there's no data after the last byte of the last compressed + file; + +Other things caused by the limitations of the Atari: + +- Not really a file format difference, but the dates stored inside + ALF files might be wrong or gibberish, if they were created on + an Atari OS other than SpartaDOS (or, on SpartaDOS, but without + the time set correctly). + +- Atari filenames are generally limited to 12 characters, e.g. + PROGRAM1.BAS, so the filename field (Bytes 3-15, 13 bytes long) + will never be completely filled. ALF uses a null (0) byte for + the filename terminator, and any remaining bytes in the field + will be set to $20 (ASCII spaces, *not* more nulls). + +- ALF files are never embedded inside a self-extracting executable, + so the first file's header always starts at the first byte of + the file. + +- ARC and ALF both store the compressed and uncompressed file lengths + as 32-bit unsigned integers... but for ALF, the maximum file size + that can be compressed is probably under 64KB, so both the lengths + should have their last 2 bytes set fo 0. I haven't yet attempted + to compress a file larger than 64KB with ALF on the Atari, so I + may be wrong... diff --git a/doc/review.txt b/doc/review.txt new file mode 100644 index 0000000..f56e4c3 --- /dev/null +++ b/doc/review.txt @@ -0,0 +1,44 @@ +The following review was published in the Atari H.A.C.K. magazine, +in the August 1988 issue (Volume II, Issue IIX) [1]: + +--------------------------------------------------------------------- +Those of us who are experienced telecommunicators are quite familiar +with the ARC family of disk file compression programs. The most +widely used of the 8-bit versions of the ARC program has been, +and remains to be, ARC version 1.2 (the archiver) and ARCX version +1.2 (the dearchiver). Two very excellent programs written in C by +Ralph Walden of the Atari Computer Enthusiasts of Eugene, aka ACE. +Almost every BBS worth its salt uses this program to compress its +files not only to make them take up less space, but also to save time +on file transfers. A smaller program simply takes less time to send +or receive. Of course, since the file is compressed, or archived, it +isn't runnable until it's dearced with the ARCX program. + +ARC and ARCX are great programs but they have their small problems. +They are slow and sometimes show unexplainable CRC errors when +dearcing. This frustrates and detracts from what is otherwise a great +program. There was none better, that is, until now. + +ALFCRUNCH is here. Despite its cute name it has nothing to do with +the furry wise guy from the planet Melmac. ALFCRUNCH consists of two +programs, LZ.COM, the archiver, and DZ.COM, the dearchiver. Files are +manipulated the same way as the ARC programs do it but they are not +compatible. The LZ program compresses programs slightly more than does +ARC.COM, or anywhere from a few percent to almost 70%, all depending +on file type and save method used. The DZ program works as claimed- +there isn't much to say except that it works. All of this sounds good +but so what? Why change for a few percent? + +The reason to change is speed. ALF programs are at least 10 times +faster than the ARC programs. Sometimes they are even quicker! +Programs which may have taken several minutes to process are done +in seconds with ALF. In fact the first time I tried ALF I thought it +didn't work... but it does! Reason enough to change? Not yet? Well, +ALF is free. Get it from your club PD library or download it from +SLOWPOKE! [2] +--------------------------------------------------------------------- + +[1] The full issue of HACK can be found here: + https://archive.org/details/AtariHACKNewsAugust1988 + +[2] SLOWPOKE was an Atari BBS in the Salem/Portland, Oregon area. |