                 Documentation for SUPER ARC and SUPER UN-ARC versions 2.4                            By: Robert Puff  01/31/89                                       WHAT IS ARC?                 Arc is short for Archive. It is a program (actually in this     case, two programs) that allows you to "Archive" or compress one or     more files into a single .ARC file for later retrieval.  Arc is     available for many computer types; a file created on one will be able     to be unarced on another.  The only exception to this that I am aware     of is the CP/M version of Arc for the Commodore.  Super Arc uses     several mathematical compression techniques to reduce the size of the     data to be compacted by as much as possible.  "Why would you do     that", you ask?  For number of reasons, but primarily to save time -     Time is money.  This can be realized when downloading a file from a     long-distance BBS, or from a pay service such as CompuServe or GEnie.     Super Arc will compact your file(s) as much as it possibly can, which     averages around 30%.  As a bonus, Super UnArc will uncrunch files     created with AlfCrunch (a program similar to Super Arc), so separate     programs are not required!  Also included in Super UnArc is the code     necessary to un-squash files.  Squashed files are created by Phil     Katz's PKPAK utility for the PC.  This makes Super UnArc THE most     compatible unarchiver for the 8-bit!  You must, however, have more     than 64K of memory for this unsquash feature.                 Arc is not the same thing as Diskcomm (Disk Communicator, a     program I wrote back in '87.).  Diskcomm is designed to compact     entire floppy disks sector-by-sector, making an exact copy of the     disk; while Arc is file-oriented.  What this all means is if you have     a disk that is self-booting, or looks for data in specific sectors,     you should use Diskcomm to turn that disk into a file for easy     transfer.  If, however, you wish to transfer only a few of the files     on the disk, or the files on the disk are not dependent on being     specifically located at a certain sector, then Arc is the program to     use.  Please remember that Disk Operating Systems (DOS) look for     specific sectors, so they should NOT be compacted by Arc.  Diskcomm,     while it does have compaction techniques, is not as sophisticated as     Arc; so if you REALLY want to make the smallest file of a boot disk,     you could Arc the Diskcommed file.  Be sure, however, that the person     receiving your file knows he must go through two processes to recover     the disk: UnArcing the file, then unDiskcomming the resulting file!                                 SETTING UP SUPER ARC & SUPER UN-ARC                 Both of the files, ARC.COM and UNARC.COM are binary, command     files.  This means they should be loaded from your DOS menu by     selecting the LOAD BINARY FILE option.  If you are using a command     processor DOS (such as DOS XL or SpartaDOS), simply type the first     part of the filename at the command prompt.                 You may wish to set up Super Arc & UnArc on a separate disk     with a menu program.  There are many public domain menu programs that     will fit the bill; just be sure the loader program is capable of     loading Binary files, not (just) BASIC programs.  Super Arc & UnArc     will automatically disable the internal BASIC on XL/XE machines, so     there is no NEED to hold the OPTION key when booting.  (SpartaDOS is     the only exception to this rule: because of a bug, BASIC will not be     turned off.)                                           USING SUPER ARC                 Once the program has loaded, you will be presented with a     number of parameters on the top of the screen, and a menu.  (If you     are using a command processor DOS, you may specify commands on the     command line as an alternative of using the menu.  Please see the     section below entitled 'USING SUPER ARC WITH CP DOSES'.)  First, the     parameters will be discussed.  To modify them, press [P], then use     the arrow keys to move to the desired parameter. Now hit [RETURN] to     toggle between YES and NO.  Press [ESC] when finished.                 Screen Off:  If this option is enabled, the screen will narrow     to a single status line in the middle of your screen during the     compaction process.  This will increase processing time by 30%.  If     there is a need for more user-input, or if any errors occur, the     screen will be restored.  If this option is set to NO, the screen     will remain unchanged.                 Disk Swaps:  This option is for single-drive users.  If this     option is enabled, you may use a different disk as your destination     (using the same drive).  This is helpful when the source and     destination will not all fit on one disk.  Make sure that your source     and destination disks are formatted in the same density!  Also,     follow the prompts VERY carefully.  If this option is set to NO, or     if you specify different source and destination drives, you will not     be prompted.                 Compact with Query:  If this option is set to YES, as Super     Arc finds each file, you will be asked if you wish to compact it.     This is useful for selecting exactly which files on a disk you want     to include in the archive.  At the prompt, you may answer [Y]es to     compact the file, [N]o to skip it, [P] to change the source     drive/mask, [1-9] for disk directories, or [ESC] to finish arcing.     If this option is set to NO, all files found will be compacted.                 Crunch Only:  A brief explanation of the arcing process is in     order here.  When you compress a file with Super Arc when this option     is set to NO (it defaults to NO), the program first analyzes the data     in the first pass to determine which of the three types of     compression would create the smallest file.  The three types are:     Storing, where no compaction is done; Packing, where repeated bytes     are "packed", and Crunched, where the data is run through a     sophisticated compressing routine.  It then reads the source a second     time, actually compacting the data this time.  The "Crunching" method     of compaction is usually the method used most often (perhaps 90%).     If this option is set to YES, Super Unarc will not analyze the file;     it will only Crunch it.  This takes only 1/2 the time, since the     compaction process is done only once instead of twice.  The     disadvantage is that on those files that will not benefit from     Crunching, you will not have the smallest possible file.     High-resolution picture files usually fall into this category.          Special note for SpartaDOS users: If you set the Crunch Only option     to YES, Super Arc will initially crunch the data, but if it     determines that Crunching is not the best, it will re-write the file     using the best method.  This may seem to be the best of both worlds;     however, since a file written to the disk cannot become smaller, the     file will still be the same length.  If you add more files to the     archive, this unused space will disappear.  What this all means is     that if you want the smallest file possible, leave this option set to     NO.  For most purposes, I recommend using this option (when using     SpartaDOS).                 Password Encrypt:  Setting this option to YES will cause the     arced file to be encrypted with a special password you supply.  The     only way to recover the file created will be if the person unarcing     your file enters the exact same password you used.  I STRONGLY     recommend you not use this feature often, because it is HIGHLY     unlikely you will be able to recover the file without it.  The     password is not hidden anywhere in the file, so you can't look for     it.  When this option is set to YES, Super Arc will ask for the     password after you have entered the destination filename.  Pressing     [RETURN] will cancel the password, and continue as normal.  The     password is not case or inverse sensitive, but should not contain any     spaces if you wish to use an IBM or ST to unarc the file.  Setting     this Password Encrypt option to NO (as it is by default) will not use     any password data, and will compact as normal.                 Those are the parameters that are on the top of the screen.     On the main menu, there are more options.  You may format a floppy or     RAMdisk in either single or double density by typing [F].  Selecting     [D] will allow you to delete file(s).  You may use these two options     to prepare your destination disk for the destination file.                 Selecting [G] will cause your computer to reboot (act as if it     had been turned off, then back on).  This is helpful for preserving     the contents of RAMdisks when switching programs.  For XL/XE users:     remember to hold [OPTION] down while pressing [G] if you want to     reboot without internal BASIC.                 Pressing [H] will return you to your DOS menu, or to the     command processor if you are using a command processor DOS.                 Disk directories may be done by pressing the drive number     (1-9), then entering the subdirectory pathname to view.  Simply hit     [RETURN] here to view the main directory.  Disk directories may be     also done at the "Enter Source Filemask" prompt, and the Compact with     Query prompts.                                          HOW TO ARC A FILE                 Change any parameters you wish in the top box, then type [A]     to Arc file(s).  Super Arc will now ask you for the destination     filename.  ".ARC" will be added to the filename specified, so you do     not need to specify the extender.  Type the drive identifier and     filename. (Examples: D2:TESTER, D6:FILES>SAMPLE)  Drive 1 (D:) will     be assumed if no "Dx:" is specified.  The program will now open that     destination file.                 Now you will be prompted for the "Source Filemask".  Super Arc     is now asking you which file(s) you want to put into this single     destination file.  If you wanted to arc all files on drive 1, you     would enter "D1:*.*" [RETURN]. To arc only the file "TEST.BAS" on     drive 2, you would enter "D2:TEST.BAS" [RETURN].  This is basically     the same as entering the source when using the copy file feature of     your DOS.  Subdirectories ARE supported!  To arc all files ending     with .COM on drive 3 in subdirectory MOD, use "D3:MOD>*.COM"     [RETURN].                 If you set the Compact with Query option to YES, the program     will display each filename it finds, and ask you if you want to arc     it.                 The compacting process will now begin.  If the Crunch Only     option is set to YES, the number of bytes saved will be displayed     after the file was compacted.  Otherwise, the resulting size of each     compacting process would occupy will be displayed, along with which     of the three types Super Arc chose.  If the Screen Off option is set     to YES (as it is by default), you will just see the message     "Compacting xxx".  Your screen will be restored after it is done.                 Note for SpartaDOS users:  Super Arc will save the time and     date of each file automatically.  If the source is not in Sparta     format, or if using any other DOS, the date of 09/01/88 and time of     12:00 PM will be saved.                 After the file(s) have been compacted, you will be prompted     for the source filemask again.  If you have any more files to add,     enter them now.  Otherwise, press [RETURN], and your archive will be     complete!  If you ever get a disk error while arcing, the destination     file should be deleted.  It will not have meaningful data.                 If you have an arced file, but want to add some more files to     it, you may use the [B] function from the menu, Add to an Archive.     This functions identically to arcing a file from scratch, except the     data will be ADDED to the destination file you specify.  Be sure your     destination disk has as many sectors free as the length of the Arc     file to which you are adding, because Super Arc must copy the     contents of that file into another temporary file to properly append.     The temporary file is then deleted.  If there are any problems adding     to an arced file (such as if the file you are adding to is not in Arc     format), the message "Cannot add to file" will be displayed.                                    USING SUPER ARC WITH CP DOSES                 You may invoke Super Arc to perform certain functions without     having to use the menu when using Command Processor DOSes such as DOS     XL and SpartaDOS.  Super Arc will return to the CP after it is done,     or upon an error.  The following is the proper syntax:          [Dn:]ARC [Dn:][path>]filename[.ext] Dn:[path>]source [/ACPQSX]     [password]                 The first parameter is the destination filename.  Remember     .ARC will be added to it if you do not specify an extender.  The     second parameter is the source filemask, and the third optional field     is the options desired:     A = Add to the existing source archive     C = Use Crunch only (with SpartaDOS, this isn't really what it         means: re-read the section on Crunch Only for explanation)     P = Use the fourth parameter as an encryption password     Q = Compact with query     S = Have screen remain fully on     X = Enable Disk Swaps                 The default (without a third parameter field) is: Screen     Off-YES, Disk Swaps-NO, Compact with Query-NO, Crunch Only-NO,     Password-NO.  The fourth parameter is only used if the password [/P]     is specified.  Here are some examples:          [Dn:]ARC D2:TEST D3:*.BAS /QSC                 Will ask you if you want to arc each file on drive 3 ending     with .BAS, leaving the screen on, and enabling the Crunch Only     option.  It will write the result to D2:TEST.ARC.          [Dn:]ARC TEST MYFILE.OBJ /P DATA                 Will compact file MYFILE.OBJ on the current drive, and write     the destination to the file TEST.ARC on the current drive.  It will     use the word "DATA" as a password.          [Dn:]ARC D1:TEST2 D3:*.* /AC                 Will arc all files on drive 3, and add them to the already     existing file TEST2.ARC on drive 1.  It will enable the Crunch Only     option.                                         USING SUPER UN-ARC                 Super UnArc operates much like Super Arc, except it is doing     the opposite - Taking a single source, and writing out one or more     destination files.  The following is a list of the parameters in the     top box of Super UnArc.  To save space, refer back to the parameter     section of Super Arc for some of these.                 Screen Off:  (same as in Super Arc).                 Disk Swaps:  (same as in Super Arc).                 Over-Write:  This is a safety feature.  If a file already     exists in the directory you have specified with the same name as the     file being uncompacted, Super Arc will ask you if you want to     overwrite your existing file.  Typing [Y] will overwrite it; pressing     [N] or [RETURN] will skip the file and proceed to the next entry.     Pressing [ESC] will abort the unarcing process.  All the above will     take place if the Over-Write option is set to NO.  Setting it to YES     will not prompt you, and will overwrite any files having the same     name.                 Extract with Query:  If this option is set to YES, the program     will display each entry in the arced file, and ask you if you wish to     uncompact it.  This is handy for viewing just the text files in an     archive.  Setting this option to NO will extract all files.  This     feature can also be used to extract a very large source, if you do     not have enough room on one disk for all the files to be unarced.                 Time/Date Stamp:  This option is valid only under SpartaDOS.     Setting this option to YES will cause the destination files to be     written out with the original time and date of the file when it was     first Archived.  Some arc programs do not save the time and date, so     if you get a bogus value, this is why.  If this option is set to NO     (as it is by default), the current time and date will be used.                 Password Encrypt:  This option is to be used when the source     file has been encrypted with a password.  If this option is set to     YES, you will be asked for the password after entering the     destination pathname.  Pressing [RETURN] will disable the password     (incase you inadvertently turned it on).  The password can be 1-20     characters long, and is not inverse or case sensitive.  If you use     the wrong password, you may or may not get a "File is Corrupted"     message depending on the method of compaction, but the destination     file WILL be corrupted.                 As with Super Arc, the [D]elete, [F]ormat, [G] Reboot, [H]     Return to DOS, and [1-9] directories function just as in Super Arc.     See the section entitled 'Using Super UnArc with CP DOSes' for     information concerning passing parameters to Super UnArc.                 You may view the contents of an arced file by typing [V].     Enter the source filename.  ".A??" is added to the end of the source     filename you enter, so if the extender is .ARC or .ALF (for Arc and     AlfCrunch, respectively), the file will be read.          ** PLEASE NOTE!!! IF THE SOURCE FILE HAS NO EXTENDER, ADD A [.]     PERIOD AFTER THE SOURCE FILENAME! **          This means if you have a file on drive 3 named TEST (no extender),     you should enter "D3:TEST." (note the period after the filename).  If     the file was named TEST.ARC, then you would only have to enter     "D3:TEST".  When viewing a file, each filename, compaction method,     and expanded sector size (in single-density sectors) will be shown.     The total number of single or enhanced density free sectors needed to     uncompact all the files will be displayed at the end.  When using     double-density, divide the counts by 2 (approximately).                                         HOW TO UNARC A FILE                 To un-arc or un-alfcrunch a file, first change any parameters     you wish in the top box; then type [A].  Enter the source filename     (and extender if it is not .ARC or .ALF - see the paragraph on     [V]iewing files for information on the source filename).  If the file     is not found, an "Error 170" will result.  You may then use the     directory functions to locate the correct name, and try again.     Again, remember: IF YOUR SOURCE FILE HAS NO EXTENDER, ADD A PERIOD     AFTER THE NAME!                 You will now be prompted for "The destination pathname or     drive # (& mask)".  Entering data at this prompt will do two things:     it will tell Super UnArc where to put the destination file(s), and it     will also tell which files you wish to recover.  If you wanted to     extract all files and place them on drive 2, you would simply press     [2] and [RETURN].  If you wanted to place them in a subdirectory     called "SUBDIR" on drive 3, you would use "D3:SUBDIR>".  You may also     use "E:" to make the output go to the screen (for viewing text files:     use Control 1 to start and stop), or P: to route the output to your     printer.  Using "N:" will extract each file, but throw away the data     (N for Null device).  The use for this feature is to test the     integrity of the source file (to see if there might be some bad bytes     in it).                 Also with this prompt, you may select which files to extract     from the archive file.  For example, if you viewed a sample arc file     and found two .DOC files, you could print them out by unarcing to     "P:*.DOC".  The same thing applies to disk files; to extract all     files ending with .BAS in an archive to drive 1, use "D1:*.BAS".     (Just "D1:" by itself will extract all files.)  Wild cards are not     necessary; if you wanted to extract a single file, you could just     type in that filename after the destination drive identifier.  So     there are two ways to extract certain files: enable the Extract with     Query option, and/or specify the filespec when entering the     destination filemask.                 The uncompressing process will now begin.  Each filename,     compression type, uncompacted length in single-density sectors, and     the number of bytes saved by the compaction will be displayed.  If     you specified a subdirectory for the destination and it is not found,     Super UnArc will ask you if you wish to create the directory.     Subdirectories are supported for MYDOS and SpartaDOS.  If a file     exists on your destination with the same name as the one you are     about to uncompact, the program will ask you if you wish to overwrite     the file ONLY IF the Over-write option is set to NO.                 If you have turned on the "Extract with Query" option, the     program will prompt you if you wish to extract the file displayed.     Pressing [Y] will extract it, [N] will skip and go to the next entry,     [P] will allow you to change the destination drive number/path/mask,     [1-9] will allow you disk directories, and [ESC] will terminate the     un-arcing process.                 If Super UnArc has a problem opening up the destination file,     you will be given an error recovery menu.  This will allow you to     change the destination drive number/path/mask, and do directories.     If you gave the wrong drive number, or your destination was     write-protected, you can fix it here, then press [RETURN] to     continue.  If you wish to bail out, press [ESC].                 If you have the "Screen Off" set to yes (as it is by default),     you will only see each filename as it uncompacts.  If you have the     "Disk Swaps" set to yes, the screen will remain on, so that you can     see when to insert the proper disk.  If the screen is "off" and you     wish to turn it on, Press [SPACE].  When Super UnArc extracts the     next file, the screen will be restored.                 The uncompressing process will continue until completion or a     major error.  If you get the message "File fails CRC check", that     file is corrupted and should probably be discarded.  The version 1.2     of Arc program written by Ralph Walden had a bug that caused this to     occur quite often, sometimes because it DID put bad bytes in the     file, other times not.  If you see a file that was "Squeezed" with a     CRC error, it was probably caused by this 1.2 Arc program - Use the     file at your own risk.  If you get CRC errors on any other type of     compacted file, the file DOES have bad bytes is it.  If the CRC error     is followed by the messages "Not an ARC or ALFCRUNCH file" or "File     is corrupted", the source file is DEFINITELY corrupted.  You may     occasionally get the message "Not an ARC or ALFCRUNCH file" at the     end of uncompacting an AlfCrunch file.  This is due to extra bytes at     the end of the file caused by improper X-modem routines; but all the     file(s) will be intact.                 Super UnArc supports un-squashing, a method do compaction     recently introduced by IBM, ST, and Commodore computers.  This new     method of compaction requires 16K of additional memory; memory that     is really not available on the standard 8-bit Atari.  However, if you     have a 130XE, upgraded 800XL, or an Axlon-compatible upgraded 800,     the last bank of extra memory in these machines will be used.     Un-squashing is totally automatic - it is used just like the other     methods.  If you do not have any extra memory, and you try to unarc a     file that was squashed, the program will give you the message "You     need >=128K to unsquash", and will end.                 When viewing or uncompressing a file, Super UnArc verifies     that the file was indeed created by Arc or AlfCrunch.  If it is not,     it checks to see if the source file was compacted with Diskcomm, or     is a binary file.  It will report what it finds, or "Not an Arc or     AlfCrunch file" is it cannot determine.  If there are any garbage     bytes at the beginning of the file (caused by older terminal     programs), the program will search ahead to find the true start.                                  USING SUPER UN-ARC WITH CP DOSES                 As in Super Arc, the program supports parameter passing with     command processor DOSes such as DOS XL and SpartaDOS.  If there are     no parameters specified, or if they are in an improper syntax, the     program will ignore them, and display the menu.  This is the proper     syntax for Super Unarc:          [Dn:]UNARC [Dn:][path>]filename[.ext] Dn:[path>][mask] [/OPQSTX]     [password]                 The first parameter is the source file (remember ".A??" will     be added to the name, so specify the extender if it does not begin     with .A), the second is the destination drive number, or path (and     mask), and the third optional parameter is the options desired:     O = Over-Write set to YES, will overwrite any file with the         same name as the destination     P = Use a encryption password (the fourth parameter, which is         only used with this option)     Q = Extract files with Query set to YES     S = Have screen remain full during uncompaction     T = Use time/date stamp from source file when writing         destination files     X = Disk Swaps set to YES, for single drive users                 You may specify none, any, or all (in any order).  The default     without any options is: Screen Off:YES, Disk Swaps:NO, Over-Write:NO,     Extract with Query:NO, Time/Date stamp:NO, Password encrypt:NO.  The     fourth parameter is only used if the password [/P] is enabled.  Here     are some examples:          [Dn:]UNARC D2:TEST 3 /QS                 Will uncompact the file D2:TEST.A?? to drive 3, extract with     query, and have the screen remain on.          [Dn:]UNARC TEST.JNK P:*.DOC /P DATA                 Will uncompact all .DOC files to the printer from the file     TEST.JNK on the current drive.  It will use the word "DATA" as the     password to unencrypt the archive.          [Dn:]UNARC D7:MOD>MYFILE N:                 Will verify the integrity of the file MYFILE.A?? in the     subdirectory MOD of drive 7.                                          CLOSING COMMENTS                 I had originally desired to put both Arc and Unarc programs     into one, but due to memory constrictions, this was not possible.     Both programs require tables over 16K in length, which leaves little     for the program itself.  In fact, if you use Super Arc or UnArc with     a cartridge installed, you will have VERY small I/O buffers.                 I would like to take the time to thank all the people who have     helped by debugging, giving hints, etc, but this file would be 10K     longer! :-)  However, a special thanks goes out to all GEnie users,     who helped beta-test these two programs, and to Frank Walters, for     his intensive de-bugging efforts!  Also a special thanks to Glenn     Garman, who makes sure everyone can understand my documentation!                 A good deal of time has been spent on these programs - much     longer than I intended.  The public domain, however, needed a good     Arc and Unarc program.  So I have released this program as Shareware.     What this means is that you may use it as you like, and give it to     your friends, clubs, etc, without cost.  However, I would ask that     you consider the time and effort involved in creating a program such     as this.  Making it compatible with all DOSes was no small feat!  If     you enjoy the program, consider sending a token of your appreciation.     This will provide incentives for me to keep updating and writing     other quality utilities for the Atari 8-bit.  If you have any     suggestions, donations, comments, etc, please send them to:                         Robert Puff                    Suite 222                    2117 Buffalo Rd                    Rochester, N.Y. 14624                 I may also be reached on GEnie (mail address is BOB.PUFF),     CompuServe (72377,2045), and on these local BBS's:          The Moose BBS      (716) 381-5139     The Lakeside Manor (716) 338-2453                                           TECHNICAL NOTES                 Super Arc & UnArc both use the vectors provided at HATABS for     screen and keyboard I/O, so re-direction should present no problems.     Both programs load in at $6F00, then relocate to LOMEM.  If there is     not enough room between LOMEM and HIMEM, the programs will display an     out-of-memory message, end exit.  The remainder of memory from the     end of the program to HIMEM is used by input/output buffers; the     bigger the buffer the faster the program will run.  (Super Arc will     just fit when a cartridge is present.)  Built-in BASIC will be     disabled automatically, unless SpartaDOS is detected.  The programs     detect Sparta by looking for a "S" in location $0700.                 A graphics 0 call is made when the program exits, to maintain     compatibility with programs that play with the display list such as     TDLINE.  Screen memory is saved, so the data on the screen is     preserved.  If you wish to include Super Arc & UnArc in specific     application software (such as a graphical Operating System), please     get in touch with me, as small modifications to the program could be     easily done.                 If you are using MYDOS version 4.0 thru 4.3C, you may wish to     upgrade to version 4.5.  Super Arc & UnArc will work correctly with     the older versions, but certain functions will be much slower. The     new version 4.5 of the DOS is in the Public domain, and may be     downloaded from the online services.  Note: I have not tested Super     Arc with the new DOS XE.  If you do have any problems, I suggest     downloading MYDOS 4.5.  It will handle any type of system     configuration, and is COMPATIBLE.                 Both Super Arc & UnArc support three delimiters for separating     subdirectory names: The colon [:], the greater-than sign [>], and the     backslash [\].          Bob Puff  01/31/89          P.S. This version 2.4 corrected all known bugs that have been     reported to me.  Please delete any old versions of either Super Arc     or UnArc.                