SHRINKIT FOR THE APPLE II Program by Andy Nicholas Documentation by Karl Bunker Send comments/suggestions on ShrinkIt to: Andy Nicholas 8415 Thornberry Drive East Upper Marlboro, MD 20772 Electronic Addresses: GEnie or America-Online: shrinkit InterNET: shrinkit@moravian.edu CIS: 70771,2615 Send comments/suggestions on this documentation to: Karl Bunker GEnie: k.bunker What is ShrinkIt? ----------------- ShrinkIt is a utility program for archiving files and disks. "Archiving", in this usage, refers to the process of placing files or disks "within" another file -- the archive file. Archiving is usually done to prepare the files/disks for transmission via modem, or for storage purposes. Thus, an archive file, whether created with ShrinkIt or another archiving utility, will be a file which serves as an envelope, containing one or more other files, or complete disks. There are a number of reasons for archiving files before transmitting them with a modem. The principal reason is that an archive provides a means of sending the "attributes" of a file -- its filetype and other information -- along with the file itself. An archive also allows several related files (or an entire disk) to be packed together into a single file. True archiving utilities will also have the capability of compressing the files they contain to minimize the transmission time and disk space the archive requires. ShrinkIt uses a highly efficient compression algorithm known as dynamic LZW, and creates archive files with a format called NuFX. For technical documentation of the format of NuFX archives, refer to the File Type Note for filetype $E0, auxtype $8002. (File Type Notes are available from Apple Programmers and Developers Association.) ShrinkIt and ShrinkIt-GS are currently the standard archiving utilities for Apple II telecommunications. ShrinkIt can unpack files which have been archived with ShrinkIt, as well as those which have been packed with certain other file-packing utilities, such as BLU and ACU. About These Instructions ------------------------ Most users of ShrinkIt will be interested in unpacking files they have downloaded from a Bulletin Board Service or Information Service. Others will also be using it to pack files that they want to upload to such a service. In these instructions I will first describe how one uses ShrinkIt to unpack archives, and then how to create a new archive file. Finally I will give an explanation of each of the options available in ShrinkIt's Main Menu, and fill in certain other details about ShrinkIt's functioning. If you are ONLY interested in how to unpack a file which you have downloaded, you can just read the section entitled "Unpacking an Archive", and skip the rest of this file. I will attempt to make these instructions understandable to the relatively new computer-user; if you are unfamiliar with any of the terms used, or become generally confused, you may want to consult the instruction manual to your telecommunications software, or a magazine article on telecommunicating with the Apple II. System Requirements ------------------- ShrinkIt requires a 128K enhanced IIe, a IIc, IIc+ or IIgs. Versions of ShrinkIt for the Apple II+ and unenhanced IIe are also available. Shrinking and UnShrinking functions have been split into two different programs for these older machines. These programs are called IIPLUS.SHRINKIT and IIPLUS.UNSHRINK, and they will run on any 64K Apple II, using the 40-column screen. More information on these alternate versions of ShrinkIt will be given towards the end of these instructions. ShrinkIt-GS ----------- These instructions are for the 8 bit version of ShrinkIt. A IIgs version of ShrinkIt may also be available by the time you read this. Archives that have been created with ShrinkIt-GS can be unpacked with version 3.0 or later of the 8 bit ShrinkIt, providing that none of the files being extracted from the archive is an "extended" GS/OS file (also know as files with resource forks). Since ProDOS-8 can't handle extended GS/OS files, someone who doesn't own a IIgs would have no reason to extract such a file. NOTE: As of this writing (March, 1990), ShrinkIt-GS has not yet been released. Distribution and Copyright Info ------------------------------- ShrinkIt is a Freeware program. This means that you are under no obligation to pay the author anything for it, but the copyright is retained by him. You are encouraged to distribute this program to whomever you please, but you may not sell it, or include it in any package which is sold, without the author's permission. Special licensing is required for ShrinkIt to be commercially distributed. "ShrinkIt" is a registered trademark of L&L Productions, Inc. If you find ShrinkIt useful, please show your appreciation by sending Andy Nicholas a donation of some sort. This program represents a tremendous investment of time and effort, and the entire Apple II community is greatly indebted to Andy for his work. His address is given above, and in the "About ShrinkIt..." screen. Launching ShrinkIt ------------------ ShrinkIt can be launched using standard program selectors such as Bird's Better Bye, Squirt, ProSel, or the IIgs Finder. (Some versions of ProSel 16 can't launch ShrinkIt; an update to the latest version of ProSel fixes this.) ShrinkIt is too large to be directly launched from the BASIC prompt ("]"). However, a small SYS file called SHRINKIT.SYSTEM is distributed with ShrinkIt. SHRINKIT.SYSTEM can be launched from BASIC, and it, in turn, will launch ShrinkIt. Some Terms Defined ------------------ In the Apple II telecommunications community, there are a number of different file- and disk-packing formats which have been used over the years. Most of these formats have been superseded by ShrinkIt and its NuFX format; others are still used. These various formats are usually denoted with a three-letter suffix appended to the file's name (as in "MY.FILE.BNY"). Here are some of the suffixes you are likely to encounter, with brief descriptions of their related file formats: .BNY: Binary II format. Though not a true archive format, a Binary II "envelope" will preserve a file's attributes through a download or upload. ShrinkIt can unpack .BNY files, and they can also be automatically unpacked during downloading by many telecommunications programs. .BQY: "Squeezed" (i.e., compressed with a different algorithm than the one used by ShrinkIt) files within a Binary II envelope. Created with the utility BLU, these files can be unpacked with ShrinkIt. .QQ: If you remove the Binary II envelope from a .BQY file, the squeezed files it contains will have the suffix .QQ. These files can be unsqueezed with ShrinkIt. .ACU: The archive format used by America Online (formerly AppleLink Personal Edition); these files can be unpacked with ShrinkIt. (America Online currently uses .SHK format for new uploads.) .SHK: NuFX format; can be created and unpacked with ShrinkIt. .BXY: A NuFX archive within a Binary II envelope. This is the format currently required for new uploads to the Apple II libraries of GEnie and Compuserve. .BXY files can be created and unpacked with ShrinkIt. Although this "envelope within an envelope" format may seem redundant, it has several advantages. Ideally, the Binary II envelope will be entirely "transparent" to end users -- it will be automatically added by telecommunications software during uploading, and automatically removed during downloading. As more telecommunications programs come to support automatic Binary II packing and unpacking, this ideal will be increasingly realized. Thus, if your telecommunications software supports automatic Binary II unpacking during downloading, you can turn this option on when downloading a .BXY file. Doing this will give you a downloaded file which is a "bare" NuFX archive. Thanks to the Binary II envelope, this file will automatically be given the correct name and filetype. Unpacking an Archive -------------------- ShrinkIt starts up with a display of its Main Menu. The options in this menu are selected by using the arrow keys to highlight an option and pressing , or by pressing the letter associated with the option you want. When you have downloaded a file with one of the suffixes given above, you will want to process this file through ShrinkIt to unpack it and get at the files or disks it contains. It doesn't matter which of the packing formats your download is in; ShrinkIt will automatically recognize the format and handle the file accordingly. To unpack an archive, you select "O-Open Archive" from the Main Menu. This will send you to a display called the File Dialog. Similar File Dialog displays are used for many of ShrinkIt's functions; the one you see after selecting Open Archive will show the title "Open Which Archive?" across the upper screen. The File Dialog is used in this case to select which archive file to "open", or unpack. Most of the File Dialog screen is used to display a list of the files in the currently open folder. On the right of the screen are a list of the key-commands you can use at this point: TAB to change disk drives. RETURN to open a highlighted folder, or open a highlighted file. ESC to close the current folder. OA-. (Open Apple-period) to cancel this operation. SPACE to select a file for opening. Below this list of key-commands you will see this notation: OA-G or RETURN does function ? does tree search Thus, if you only want to select a single file in the File Dialog, you can just press with the file highlighted. If you want to select several files to be opened in sequence, you can select the files you want with , and then press either or OA-G (Open Apple-G). The "tree search" function is a very powerful feature which will be especially useful to hard disk owners. By pressing "?", you will be sent to a "directory tree display" -- a display of all the folders within the currently open folder. You can then select the folder you would like to open simply by pressing the arrow keys to highlight that folder. Press and you will be back at the File Dialog screen with your selected folder open. The tree search will not function on volumes which are on an AppleShare network. At the bottom of the "Open Which Archive?" File Dialog, there is the prompt "Showing ARCHIVES (OA-S)". This indicates that ShrinkIt is currently displaying only folders and files that it has identified as archive files. ShrinkIt uses two methods to decide whether a file is an archive: It checks the attributes of the file (its filetype and auxtype), and it checks to see if the filename has an appropriate suffix. When a file is downloaded, its attributes may not be preserved through the download. If your archive doesn't have EITHER the appropriate attributes, OR one of the suffixes listed above, ShrinkIt won't be able to recognize that file as an archive. If you don't see your archive file listed (after you've opened the appropriate folder), try pressing OA-S. The prompt will change to "Showing ALL FILES (OA-S)", and indeed, the File Dialog will now show all of the files in the current folder. Press to open the archive file you have selected, and ShrinkIt will display a list of the "items" -- the packed files or disks -- within that archive. At this point you have to select which items you want to extract. Usually you will want to extract all of them, but you have the option of extracting only one or a few. You can select individual items by pressing , or all of them with OA-A. When the items you want are selected, press . Another File Dialog screen will be displayed, this one entitled "Destination Folder?" You use this to choose which disk and folder you want to put the new, unpacked files in. With this variation of the File Dialog, only folder (DIR) files will be displayed, and the words " highlighted. The archived files will now be unpacked and saved to your disk. Occasionally, you may want to have different files within an archive unpacked into different destination disks or folders. If you press OA- to select an item, that item will be unpacked "with prompting"; before the item is extracted, you will be prompted again to select a new destination folder for it. You can select ALL of an archive's items to be extracted with prompting by pressing OA-P. If the archive file contains a packed disk (or disks), ShrinkIt will prompt you to select a "device" (disk drive) for the archived disk to be unpacked to. Creating an Archive ------------------- As you might expect, creating an archive is somewhat more involved than unpacking one. However, in many ways the procedure is similar to unpacking. First you will select "N-New Archive" from ShrinkIt's main menu. You will be prompted with: Archive What? Files Disk Cancel Archiving files will be examined first. Press with "Files" highlighted, and you will be sent to the File Dialog display described above. This File Dialog screen is entitled "Archive Which Files?" and naturally, is used to select what files you want to archive. Again, you use to select the files you want, and when done, press or OA-G to go to the next step in creating the archive. If you press with a folder (directory) highlighted, then that folder and all of its contents will be archived. When you press or OA-G, yet another File Dialog screen will appear, this one entitled "Name of Archive to Create?" At the bottom of this File Dialog screen you will see a prompt for "Filename:_______________". Using the key-commands described above, you can first open the disk and folder you want your new archive to be saved to. Then type a filename for the archive file you are about to create. To avoid confusion, be SURE to add the correct suffix to your filename: Straight NuFX archive should have the suffix ".SHK", and NuFX-within-Binary-II archives should be suffixed ".BXY". After entering the filename, press , and the archive will be created. There is one very important point to note at this stage: If you want the new archive to be a .BXY (NuFX-within-Binary-II) archive, you must press OA- (Open Apple-), rather than simply after typing in the filename. There is a brief notation to the right of the "Filename:" prompt to remind you of this. The best way to create a .BXY file is to use ShrinkIt to make a .SHK file, and then let your telecommunications program add the outer Binary II envelope during uploading. However, not all telecommunications programs can do this. ShrinkIt does not allow you to add new items to a .BXY archive after it has been created. This can only be done with "bare" NuFX archives. For this reason, if you are using ShrinkIt to make a .BXY file, you must start out with all of the files you want to archive in the same folder, so you can select and pack them all at once. If the archive is simple NuFX, you can add a packed file or disk to it after it has been created. This is done by selecting "A-Add to Archive" from ShrinkIt's main menu. You will first be prompted to select the files (or disk) you want to add, and then to select which archive you want the new items added to. To create a new archive from an entire disk, select "N-New Archive" from the main menu, and then select "Disk" from the "Archive What?" prompt. Disks to be archived may be either 800k 3.5" or 140k 5.25" disks, and may be ProDOS, DOS 3.3, CP/M or Pascal. Some non-standard, "customized" operating systems can also be handled. For most purposes, creating archives from individual files will be more efficient, and preferable. Disk packing is intended primarily as a means of handling data on the older operating systems. ShrinkIt's Main Menu -------------------- The above instructions describe ShrinkIt's two main functions: creating and unpacking archives. ShrinkIt can perform a number of other functions, however. This section reviews each of the options available in ShrinkIt's main menu, in the order in which they are listed. Q-Quit: Exits you from ShrinkIt and returns you to your program selector. N-New Archive: Create a new archive. O-Open Archive: Open an existing archive to unpack it, or simply to see a list of its contents. A-Add to Archive: Add new items -- either packed files or a packed disk -- to an existing archive. C-Catalog: Display a catalog of a disk or folder. The folder or disk to be cataloged is selected using the File Dialog screen described above. F-Format Device: Format (initialize) a 5.25 or 3.5 disk. If you are using a IIgs and an Apple 3.5 drive, you will be prompted for an option called "Fast-Format and Skew 2:1". This is a high-speed disk formatter which forgoes a little error checking for the sake of rapidity. If you'd rather do a slower, safer formatting, select "Cancel" at this prompt. E-Erase Device: Erase the contents of a ProDOS disk. X-Copy Files: Copy files from one disk or folder to another. After selecting this function, two File Dialog screens will appear. The first will ask "Copy Which Files?", and the second "Destination Folder?" D-Delete Files: Delete files from ProDOS disks. T-Type Files: This option allows you to read TXT (ASCII text), AWP (AppleWorks Word Processor), and WPF (WordPerfect Word Processor) files. A File Dialog is used to select the file or files to be "Typed", and then the contents of the file are displayed on-screen. Pressing moves you through the file a page at a time; will exit you from the current file and display the next one you selected (if any). Either or OA-. (Open Apple- period) will return you to the main menu. /-Create Folder: Allows you to create a new folder. A File Dialog is used to choose where to put the new folder and what to name it. Z-Zero ProDOS Disk: If you are planning to create an archive from a ProDOS disk, you should perform this operation on the disk first. It will "zero out" all the unused blocks on the disk, making the disk archive smaller. ?-About ShrinkIt: Displays information about the programmer, gives distribution and copyright information, credits those who helped out, and displays a list of "short cut keys". Key-Commands and Short Cut Keys ------------------------------- This section describes the key-commands which are available within many of ShrinkIt's functions. Some of them have been referred to before. A few of these commands are needed to perform certain of ShrinkIt's operations, while others are just short cuts or alternate ways of doing things. This list does not include those key-commands whose function is explained by on-screen prompts in the File Dialog displays. OA-up arrow and OA-down arrow: In the File Dialog, the arrow keys together with Open Apple will move you through the file list quickly. OA-A: Select all files in the open folder, or all items in the open archive. OA-: Select an archive item to be extracted (unpacked) with separate prompting for a destination folder. OA-P: Select all items in an archive to be extracted with prompting. OA-E: In the File Dialog, eject the current 3.5" disk. OA-O: In the File Dialog, display a list of online volumes. /: In the File Dialog, instead of selecting a pathname by opening the correct disk and folder(s), you can also type it in; just press "/" to start the full pathname. If you type the pathname of a folder, that folder will be opened and displayed in the File Dialog. If you type the full pathname of a file, the operation you have selected (Type, Open Archive, etc.) will be performed on that file. U: If, for some reason, you want to archive a file without compressing it, you can do so by pressing "U" to select it instead of . OA-U: You can select all of the files in the open folder to be archived without compression by pressing OA-U. OA-B: When scrolling through the list of items in an open archive, this will send you to the beginning of the list. When "Typing" a file, OA-B sends you to the beginning of the file. .: At most points in ShrinkIt, you can simply press "." (period) to cancel an operation, rather than OA-. (Open Apple-period). ShrinkIt for the ][+ and unenhanced //e --------------------------------------- As mentioned earlier, if you are using an unenhanced //e or a ][+, you will have to use alternate versions of ShrinkIt. ShrinkIt for these machines is broken up into two programs: IIPLUS.SHRINKIT for creating archives and IIPLUS.UNSHRINK for unpacking archives. To an extent, the above instructions apply to the IIPLUS ShrinkIts, but there are some important differences. In general, the IIPLUS ShrinkIts are simpler than the standard version. The 40 column screen is used, so the on-screen information is minimal. None of the utilities, such as copying files, are available; these programs only create or unpack archives. The Open Apple (OA) key is not used. Some of the OA key commands are replaced with Control key commands, but others, such as OA-A (select all) are not implemented. To select an archived file to be extracted with separate prompting, press "P" (instead of OA-). -------------------------------------------------------------------------------- Shrinkit Version 3.3 Notes: -------------------------------------------------------------------------------- ShrinkIt 3.3 ------------ When decompressing files onto an AppleShare fileserver, files could be corrupted because AppleShare doesn't support sparse files and when the EOF of a file is extended by a set_eof call to prodos, the blocks which get allocated aren't guaranteed to contain zeroes. ShrinkIt 3.2.3 -------------- When I mess something up, I do it right. The previous fix to make BQY and ACU files only made BQY files work. Thus, we have a new version. I hope this fixes this for a long time... argh. ShrinkIt 3.2.2 -------------- Wow. One little change can bring so much grief. I was removing some dead code from the Unsqueeze function inside of shrinkit to free some space to make room for the stuff I added in v3.2.1 -- and managed to completely break the unsqueeze function. Augh, I hate bugs like this. Assuming that everything is working ok, I hope this is the last hiccup version for a while. ShrinkIt 3.2.1 -------------- I somehow managed to break the file copying function from being able to copy entire folders. I don't know how this escaped detection, but it's been fixed. Long pathnames are now properly flagged as errors when archiving files. v3.2 used to just skip files that had bad pathnames. I originally did this to skip files that had weird names on AppleShare file servers, but accidently made shrinkit always skip files with long (longer than 64 characters) names. When archiving something which has a bad file or pathname, you'll have the option of skipping that file and continuing with what you were doing (archiving or copying, etc) or stopping. The Universal Disk Controller (UDC) will really, honestly, work correctly with ShrinkIt 3.2.1 -- special thanks to Gary Gilmore who sent me his UDC card to get ShrinkIt working right. ShrinkIt 3.2 ------------ A RENAME function is now available from the main menu. A plus sign ("+") is shown beside the filetype of files which have resource forks in both the catalog function and file selection dialogs. Lowercase filenames will be displayed for those files on a disk which were created with GSOS on System 5.0 or later. If you intend to use files with lowercase in the name, I suggest using ProDOS-8 Version 1.8 or later. When extracting, filenames will still be in UPPERCASE because ProDOS-8 does not support creating files with lowercase characters. Unless ProDOS-8 changes, it is doubtful that ShrinkIt will ever create filenames with lowercase. When a function is required of only a single directory, that directory will be the destination directory. Catalog, Rename, Delete, Type, and Create will use the destination directory for doing their thing. ShrinkIt will no longer attempt to archive the archive that it is creating. If ShrinkIt finds that a file is already open, it will skip that file and not put it into the archive which it is creating. For instance, if I were to archive every file in /A/STUFF/ and my destination pathname was /A/STUFF/MY.ARCHIVE.SHK, older versions of ShrinkIt would gag ever so nicely when trying to put the archive file which it is making INTO the archive file which it is making! This is also fixed for adding to an archive. When archiving, adding to an archive, or copying files ShrinkIt will stop when it encounters a file with a resource fork and displays a dialog. You can choose whether to continue doing what you were doing and merely skip the forked file or cancel the operation. If you cancel while making an archive or adding files to an archive the destination archive will contain what was archived to the point before the dialog was shown. When archiving, adding to an archive, or copying files ShrinkIt will skip any files which it can't access -- these include drop boxes or any folder which you don't have access to on AppleShare fileservers. Shrinkit will also skip any files which have illegal filenames. The following archives are now handled by ShrinkIt: NuFX (ShrinkIt) NuFX (ShrinkIt) inside Binary II NuFX (ShrinkIt) inside MacBinary NuFX (ShrinkIt) from Macintosh America-Online Binary II Binary II inside Binary II Binary II inside MacBinary ACU ACU inside Binary II ACU inside MacBinary SQ When any of the previous archives are opened, only the type of the innermost archive will be shown. For instance, a Binary II file inside a MacBinary file will show up as being only a Binary II file. If you need an 8-bit program which has the ability to identify archives, I suggest using AUTO-UnShrinkIt, which has a scavenge mode for damaged archives built-in as a bonus. 500 files at a time can now be extracted from an archive. Previously, only 450 at a time could be handled. 8-bit ShrinkIt still has an upper limit of dealing with archives that have up to 60,000 items. There is now an "Overwrite All" option in the rename dialog which appears if you are extracting and a duplicate file already exists. If you choose then from that point onwards while extracting ShrinkIt will automatically delete duplicate files. This saves the monotony of having to sit and hit the overwrite "button" over and over again if you usually extract the same set of files. There is now a "Skip Duplicates" option in the rename dialog which appears if you are extracting and a duplicate file already exists. If you choose then from that point onwards while extracting ShrinkIt will automatically skip duplicate files. This saves the monotony of having to sit and hit the skip "button" over and over again if you usually skip files that already exist. This also applies to copying files. If you would TAB to a drive from a disk, the first file of which was a folder, and the second drive didn't have any files on it, then if you'd press return, shrinkit would place you in the disk selection dialog. This doesn't happen any more. Unpacking is slightly faster. When unpacking the IIGS Finder, it used to take me 28 seconds. Now it takes 26. The same optimization will be incorporated into GS-ShrinkIt. Packing is marginally faster. I clocked it at about 3-5% faster. It might save someone a few seconds. Forked files in archives now show up as type "Forked" instead of "File" 800k drives no longer disappear on ROM 03 machines if a disk is removed or is in the drive, but just not formatted. 5.25" drives should appear properly if you have a multikache or a UDC card. If a lowercase period (".") appeared in a filename, the following characters would be uppercased. This no longer happens. Previously, only .QQ squeezed files would be matched in the archive selection dialog -- .SQ files will also now be matched. When copying files, the first file would have its creation date set to the current date, the second file would have the creation date of the first file copied, and so on. This no longer happens. The fast-format option that was previously only available on ROM 01 machines has been removed due primarily to space constraints and the fact that many people didn't know what it was. Disabling the ability to verify a disk is a bad thing to do in the first place in that you could format a disk, it could have bad blocks, and you would never know until you attempted to write to it. Also, it was kind of a "guru feature" that more people asked me to explain than ended up saying "that's neat, keep it."