========================================================================== = = = DoTil Revision 3.7 August 18, 1988 = = = = Copyright (c) 1987,1988 Dan Franki = = = ========================================================================== Directory utilities are popular items, if for no other reason than that they can be rewritten endlessly. I should know. This is not the last version of DoTil, I intend to make this one program my life's work. It is the best version thus far, and one I hope you will find a place for on your SYS: disk. If you wish, you may refer to the program as 'Dootle', but please don't mention my name in the same breath. It should only be referred to as "Do 'Til" which cleverly rhymes with "Util". DoTil will list, in alphabetical order, all files on any two directories. It will show the file size, creation date or time, and the amount of free disk space. It will copy, rename and delete files, create or delete directories and move one or more files from one directory to another. It will format and copy disks, edit FileNotes, and maintain files in an archive. Text files may be viewed in ASCII or hexadecimal and IFF picture files may be displayed. Once DoTil is running you may remove your system disk, no external files are required. By experimenting with the menus, selecting a few gadgets and trashing a few disks, you can learn most of DoTil's features on your own. What remains you will probably discover only by reading the following. GETTING STARTED... ======================================================= DoTil requires 512K of memory and WorkBench 1.2. The program supports up to three disk drives and one fixed disk. Be sure you have 80 column mode selected in Preferences. Any font may be used as long as it is the same size as Topaz_Eighty. No special installation is required, just put the program and it's Icon on a disk, somewhere. Start DoTil from WorkBench or CLI. The RAM: disk is displayed in both 'windows'. The left window is the source, the right window is the destination. The copy gadget >>>-COPY->> is a not so subtle reminder of this relationship. Immediately below each window are the drive gadgets. Select one to display the root directory of a disk. Files are displayed in 'white' letters, directories in 'orange'. These colors may vary depending on your Preferences. The total size of all files in the source directory is displayed above the source window. The destination window shows the space available. Select a directory in the source window by clicking on it. The directory will be loaded and displayed. Notice that the Total is updated to reflect the contents of the source directory. Also notice the path name displayed in the Source string gadget located immediately below the drive gadgets. The GP (GetParent) gadget may be used to return to the parent directory. Now select a single file in the source directory. The file is highlighted, the name appears in the Source string gadget, and the size of the file is now the Total. Total will show the total size of all selected files in the source directory. The Source string gadget will show the path AND name if only one file is selected, otherwise it shows the path only. If the file you selected has a FileNote associated with it, it will have a '<<' character next to it's name. When the file is selected, the contents of the FileNote may be displayed and edited. See the EDIT NOTE menu item for details. Select some more files and note the Total size. This value may be compared to the Space Available to see if there is enough room on the destination. It does NOT take into account any files on the destination which have the same name and will be written over. Select the Copy gadget (or use the COPY menu item) to copy the files. The Message area will display each file as it is copied, and the total number copied when the command is complete. So much for getting started. MENUS ==================================================================== The menus support most of the additional features of DoTil. The PROJECT menu contains an ICON selection that closes DoTil's main window. Select this item to get DoTil out of your way temporarily. You also save about 5K of memory by not having the window open. The WINDOWS menu allows the CONTENTS of the source and destination windows to be swapped. The contents of both windows may be made identical using the S -> D and D -> S menu items. The ACTIONS menu items do most of the work. In general, you select source and destination directories, select one or more files in the source window, and then take some ACTION. Some of the ACTION items, such as DELETE, do not require a destination. Others, such as MAKE DIR, require a name to be entered in the source string gadget before the ACTION is selected. The SELECT item may be used to select all files in the directory which match a pattern. By default, the pattern is '*', which will match any file. The following characters may be used to specify a pattern: ? Matches any single character c* Matches zero or more occurrences of character c c+ Matches one or more occurrences of character c \? Matches a question mark \* Matches an asterisk \+ Matches a plus sign While it is true that '*' will match anything, and '*.c' will match all C source files, you must use 'dotil?*.c' to match all C source files that start with the string 'dotil'. The pattern 'dotil*.c' will match 'dotil.c' and 'dotill.c' and 'dotilll.c' but not 'dotil_src.c'. See the OPTIONS menu for instructions on how to set the pattern string. The CLEAR menu item deselects all files in either the source or destination window. Selecting the COPY gadget (>>>-COPY->>) will cause all selected files in the source window to be copied to the destination. The SELECTED menu item does the same thing. The NEW FILES item however will only copy selected files that either do not exist in the destination directory, or are have a more recent creation date. This is great for maintaining backups, which is why it was implemented. RENAME is intended to change the name of a single file. The source and destination windows must display the same directory. Select the file to RENAME, then select the destination string gadget and type in the new name. If the directory is not the root, be sure and add the '/' character first. The MOVE menu item will move all selected files from the source directory to the destination directory. Both directories must be on the same device. A sub directory may be created with the MAKE DIR menu item. Select the source string gadget, type in the directory name, and select MAKE DIR. If the GET DIR ON SELECT option is enabled (see section below) the new directory will be loaded into the source window as soon as it is created. A FileNote may be added to any file in the source window by selecting the EDIT NOTE menu item. A small window will be opened immediately below DoTil and will display the contents of the FileNote. If a FileNote is being added, the string 'New Note' will be displayed. Select the string gadget in this window and edit the FileNote as necessary. When you press RETURN, the note will be added to the file. If the string is empty, the note will be deleted. Any file that has a FileNote associated with it will be displayed with a '<<' character next to it in the directory window. See the OPTIONS section below for more FileNote options. You may delete files or empty directories with DoTil using the DELETE menu item. Files and directories are selected using separate menu items in order to reduce the change of unfortunate accidents. You must enable the SELECT DIRECTORY option (see section below) in order to select the directory you wish to delete. The OPTIONS menu items allow various program options to be changed. The pattern used for selecting files may be entered using the SET PATTERN item. Two patterns, one each for source and destination may be entered. If you exit DoTil, the current patterns will be lost. You may specify a default pattern when the program starts (see DEFAULTS section below). Directories may be selected rather than loaded using SELECT DIRECTORY. Normally, when you select a directory name, that directory is loaded and it's contents displayed. If you want to select the directory itself, to delete it for example, you must use the SELECT DIRECTORY menu item. Files are normally deselected after a command. Sometimes it is useful to leave the files selected. This is handy with COPY for example to insure that only the copied files are subsequently deleted. Select this option using the AFTER COMMAND menu item. The date or time of all files in the source or destination may be displayed, instead of the file size, using the INFO menu item. Select the COPY item in the FILENOTE menu if you want all FileNotes to be copied along with the file itself. If the SHOW item is enbled, the FileNote edit window will be opened and the FileNote displayed each time a single file with a FileNote is selected in the source window. Select IGNORE to disable both options. Set the directory to be used for temporary files using SET ARC TEMP DIR. If this string is empty, the current directory will be used. See the section on Archive REMOVE and UPDATE below. DISKCOPY and FORMAT are activated using the SYSTEM menu. Either selection opens a small window with a few gadgets. Selecting the drive gadget will cause it to advance to the next available drive. A string gadget is supplied for entering a volume name. By default, DoTil starts DISKCOPY with source and destination (from and to) set to DF0: The number of times you will have to swap disks is displayed any time you select a single drive for DISKCOPY. At best, four swaps are required but this value may increase if you don't have enough CHIP memory. FORMAT starts with the drive set to DF0:, and Verify is disabled. You may change both of these defaults at startup. See the DEFAULT section below. The COMMAND menu contains the more exotic features. The VIEW item allows ASCII or binary files to be displayed. A single file must be selected in the source window prior to using the VIEW command. A vertical and horizontal scroll bar is provided to control the display. Tab characters are expanded in ASCII files, but other unprintable characters will be displayed as a small retangular box. SHOWILBM will display the IFF file selected in the source window. This implementation will handle all the common IFF picture formats. Low, medium and high resolution pictures with up to 6 bit planes may be displayed. IFF HAM pictures are supported as well. The display is built in a screen behind the WorkBench and then brought to the front when ready. The Close and Depth gadgets are in the usual places but ARE NOT VISIBLE. Click on the Close gadget (upper left corner) to return to DoTil. The ARCHIVE menu allows ARC format files to be maintained. Those of you familiar with ARC will recognize the EXTRACT, and UPDATE commands. The REMOVE command will delete files from an archive and is similar to ARC delete. To use EXTRACT, select a single ARC file in the source directory. When EXTRACT is selected, DoTil reads the archive file and displays it's contents in a separate window. The window display is similar to the one provided for disk files, but includes additional information. The date and time the file was created, the file's compressed size and it's unarced length are all displayed. Initially, all the files in the archive are selected. Clicking on the file name will cause that file to be deselected. The number of files selected, and the total unarced length of all selected files are displayed at the bottom of the window. Gadgets are provided to select or deselect all files at once. When the DoIt gadget is selected, all selected files will be unarced to the destination directory. Select Cancel! if you decide not to EXTRACT anything. The REMOVE function is similar, but does not require a destination directory. A window is opened and all files in the archive are displayed. Initially, none of the files are selected. If you select DoIt, all selected files will be removed from the archive, permanently. DoTil must copy the archive to a temporary file in order to remove selected entries. By default, this file is created in the destination directory. Consequently, you should make sure you have enough disk space before you select REMOVE. You will need enough space for a second copy of the archive file less any files you will remove from it. You may change the directory where the temporary file will be created using the SET ARC TEMP DIR option. Using the RAM: disk as a temp directory will speed things up, but DoTil must then copy the resulting temp file back where it belongs. You can realize an improvement of about 10% using the RAM: disk. See the DEFAULT section for instructions on setting the location of the temp directory at startup. The UPDATE function may be used to create archive files, or to update files in an existing archive. The resulting archive is fully ARC compatible and may be used with many available utilities such as UNARC. To create an archive, select the files to add in the source window. Select the destination string gadget and type in the name of the archive file to be created. DoTil will automatically add '.ARC' to the end of the file name. Now select UPDATE, and all selected files will be packed into the new archive. A message will report DoTil's progress as each file is packed. File names longer than 12 characters will be truncated. This is ARC's biggest problem, and one of the attractions of competing formats such as ZOO. I hope to eventually support ZOO files as well. Updating an existing archive is similar except that you may select the archive file with the mouse. DoTil must create a temp file in order to UPDATE an existing archive, as discussed previously under REMOVE. ARC was originally developed by System Enhancement Associates, and ported to the Amiga by Raymond S. Brand. I obtained the original MSDOS source from a public bulletin board, and proceeded to pound it into it's current condition. If you don't have ARC, the Amiga version is supported by: Raymond S. Brand ( from Amiga ARC Ver 0.23 3/14/87 ) 503 Rowland Road Fairfield Ct. 06430 and should be available on better BBS's in your area. This implementation does not handle all the packing methods supported by the original ARC. When an archive file is created, ARC determines the packing method which will yield the greatest reduction in size. What qualifies as 'best' has changed over the years as new packing techniques are developed. ARC supports ALL of it's original packing methods, even the ones that are no longer used on new files. DoTil is not so forgiving. If an unsupported packing method is encountered by EXTRACT, DoTil will display the file in 'orange' letters, and you will not be able to select this file. If you are using ARC, you will notice that these files will be displayed in the Verbose (V option) listing as 'crunched' (lower case c). All the other types are supported and worked well when tested with ARC 0.23. The UPDATE function ALWAYS uses Lempel-Zev compression, even if the result will be larger than the original. This should only happen on very small files. Common courtesy (if not legal obligation) requires me to include the following note about ARC: (C) COPYRIGHT 1986,87 by Raymond S. Brand; ALL RIGHTS RESERVED (C) COPYRIGHT 1985,86 by System Enhancement Associates; ALL RIGHTS RESERVED DEFAULTS ================================================================= Many of DoTil's options may be set to a default value when the program starts. If you are using the CLI, command line arguments may be used to set the defaults. Alternately, the defaults may be set in the ToolTypes portion of DoTil's Icon. The command line options are difficult to remember and cumbersome to type, but if you use an alternative shell program such as WSHELL, you may use an alias to select the same options every time. All options must be separated on the command line by at least one space. To set options in ToolTypes, select the DoTil Icon and then select the WorkBench Info menu item. Add each option as described in the section below. You may omit options if you desire the default setting. In an effort to be at least a little less provincial, the format used for printing dates can be set to: Using ToolTypes Using CLI Comment DATES=MDY -dMDY 'mmddyy' the default DATES=DMY -dDMY 'ddmmyy' DATES=YMD -dYMD 'yymmdd' FORMAT and DISKCOPY assume the worst about how many disk drives are available on your system. If you have external drives you can set the drive that will be selected when a FORMAT or DISKCOPY operation is requested. FORMAT performs a Verify operation on each track. You may disable this if like living quickly and dangerously. Using ToolTypes Using CLI Comment FIRSTDRV=1 -f1 Sets first drive to DF1: FVERIFY=OFF -v Turn FORMAT Verify off You may set the default source and destination pattern matching string. Using ToolTypes Using CLI Comment SSPATT=*.o -ps*.o Match all object files DSPATT=*.c -pd*.c Match all C source files The FileNote options may be set to a default value. Using ToolTypes Using CLI Comment FNCOPY=ON -c Copy all FileNotes FNSHOW=ON -s Show FileNote of a selected file The location of the Archive temporary file directory: Using ToolTypes Using CLI Comment ARCTEMP=RAM:t -aRAM:t The default is an empty string which is the destination directory. Finally, the action of the mouse pointer may be controlled. Originally, DoTil's mouse pointer was always active, even when the program was busy doing something else. It was possible to select gadgets even though no action would be taken until the current task was completed. To me, this was confusing, and not consistent with the way most Amiga programs work. As of Revision 2.2, the mouse pointer changes when the program is busy and all input is ignored. I was never sure if this was a real 'improvement', and sure enough, someone recently suggested that I should have left well enough alone. Fair enough, you can now set: Using ToolTypes Using CLI Comment MOUSE=NOSLEEP -m Mouse pointer is always active. See what can happen when you send in a contribution? TIPS, TRICKS and CAVEATS ================================================= Menu Command Key Sequences: Some of the menu selections may be activated using command key sequences. For example, to swap the source and destination windows, hold down the right Amiga key and press 'W'. You can enter a pattern string, select the files that match the pattern and start a copy operation without using the mouse. The command key sequences are shown on the menus and summarized below: Right Amiga plus Action W Swap source and destination. S Select files. D Clear (deselect) files. C Copy selected files. N Copy new files. P Change source pattern. G Get selected directory option. H Select directory option. The other menu items are not supported as there seems to be little motive to take your hands off the mouse and use the keyboard. I am however, open to suggestions. Copying to a New Name: Select a source and destination directory and then select a SINGLE file in the source. Select the destination string gadget and type in the new name. Select the Copy gadget and it's done. This is really useful for changing Icons. Want to use a fancy new Drawer gadget? Select it in the source window, and then select the .info file for a directory in the destination window. No editing is necessary since the new file name will already be in the destination string gadget. Do the copy and select the .info file for another directory. If the LEAVE FILES SELECTED option is on you can do this again and again until all the directories have new drawer gadgets. Refreshing the Display: Clicking on the Total or Space Available labels will refresh the directory window. This is useful if another program such as CLI is used while DoTil is running. Sometimes (rarely but sometimes) I click on the CLI window and COPY a few files using wild cards. It's nice to get an updated directory without having to select everything again. Manual Input: The Source and Destination string gadgets may be used to manually enter the path and file name. Do this ONLY if you are using RENAME, coping a SINGLE file, or using VIEW, SHOWILBM or Archive UPDATE. Program variables are used to maintain the 'current' device and path when performing other tasks and anything you have typed into the string gadgets will be ignored. DoTil always assumes that the directory path displayed in the string gadgets is valid. This is generally true since it created the path string itself. Certain commands, as listed above, simply take whatever is in the string gadget and run with it. DoTil is NEVER aware that you have edited the contents of the string gadgets. If all this seems confusing, just remember: If you can select it with the mouse, do so. Otherwise, type it in. It WILL work. Every time. For everybody. The RAM: Disk: The Space Available displayed for the RAM: disk is a dubious quantity that should be viewed with suspicion. This value is the sum of all available FAST, CHIP, and PUBLIC memory, at the time the display is updated. On a multi-tasking machine, available memory is subject to change without notice, so caution is advised. As of Revision 3.4, the directory information is stored in allocated, rather than static memory. Consequently, the size of the RAM: disk will change depending on the number of files in the currently selected directory. Each file takes less than 100 bytes (180 with a FileNote), but if you are walking a tightrope with available memory, you should keep this in mind. Limitations: A directory may only contain 200 files and/or directories. All others do not exist. The VD0: device is not supported. Yet. The VIEW command will not display more than 2048 LINES of text. HISTORY ================================================================== This section is boring but obligatory. If you have an older copy of DoTil you can read this section to quickly determine what has changed. DoTil 1.0 was a different animal. The windows worked differently and the drive gadgets were less intuitive. Revision 2.0 was a major improvement. When distributed, it had not been optimized for users with FAST RAM. This was corrected in Revision 2.1 by running the FixHunk program on the executable. Revision 2.2 contains some minor enhancements. The mouse pointer changes while the program is "busy" and all input is ignored. This prevents mouse events from producing unpredictable results when the current task is completed. The RAM: drive will now display the available memory. Revision 2.3 has one major, and a few minor bug repairs. Some of the error messages would disappear almost as soon as they were displayed. This has been an ongoing problem, and is the result of my refusing to use a timer to control the error display. I think I have fixed ALL such occurrences, but then, I've thought that before. The major improvement in 2.3 is VIEW which finally works as originally intended. A horizontal scroll bar is provided so that lines longer than the display width can be viewed. The vertical scroll bar is now quite accurate, and the end of the file is displayed correctly. This was all a LOT harder than I expected it to be. Revision 3.0 represents a serious step forward. The COMMAND menu used to contain an EXECUTE item. A Command string gadget allowed a CLI command to be EXECUTEd using this menu. Workable as it may have been, EXECUTE was rather cumbersome, and in practice got very little use. It was removed to make room for UNARC and SHOWILBM. The maximum number of files was changed from 150 to 100. The Date Style option was added and the Refresh Window (click on Total or Space Available) was provided. Revision 3.1 was compiled under Lattice 4.0. DoTil instantly became almost 5K bytes smaller. What could I do but add more features? The pattern matching routines supplied by Lattice inspired me to enhance the SELECT menu item. I do wish we could make up our minds about what metacharacters to use on the Amiga. The COPY NEW function was added also. A bug was fixed in UNARC. Now, when the destination drive fills up, the program gives up gracefully and you no longer get an endless supply of system requesters telling you that the disk is full. 3.0 was not heavily distributed so maybe the total amount of suffering is relatively small. Revision 3.2 includes a window for selecting files within an archive. Unfortunately, I do NOT have a single ARC file which contains an unsupported packing method, so I don't really know if this is handled cleanly. Please let me know if you run into a problem. I eventually ran into a couple of files that would not unpack correctly, but this turned out to be size related and has been fixed. Files which are VIEWED, SHOWN or UNARCED are now deselected after the command. The AFTER COMMAND menu item was renamed as a result. Revision 3.3 was probably never distributed. I changed the storage of directory information from static to dynamic in an effort to allow up to 200 files in a directory. This was probably long overdue, but it took some prodding by a user to overcome the inertia. Revision 3.4 contains yet another bug fix to UNARC. The program would not unpack "Packed" files properly. This bug was introduced (I think) in Revision 3.2. The mouse pointer option was added to this revision and I finally got around to making the Source and Destination gadgets hold larger strings. I think the limit is now 80 characters. Revision 3.5 has an extra menu which contains the DISKCOPY and FORMAT items. I have long intended to implement these functions, but reading the appropriate section of the ROM Kernal Manual left some basic questions unanswered. Like where do you get the data for the track buffer that FORMAT needs? The answer was found in the source to DFC by Radical Eye Software to whom I am profoundly grateful for distributing the source. Revision 3.6 contains some bug fixes. DISKCOPY and FORMAT failed to work properly for users with extended (FAST) RAM. The actual copy or format operation appeared to work fine, but the resulting disk would not be recognized by DOS. The problem turned out to be yet another case of programmer error. The ROM Kernel Manual clearly states that track buffers must be allocated from CHIP (not PUBLIC) memory. In the process of trying to fix this bug, Verify was added to FORMAT. It is enabled by default, but may be turned off at startup. Errors resulting from a FORMAT or DISKCOPY operation (such as WRITE PROTECT) are now reported in English. File names longer than 16 characters would cause SHOW to seek transcendental guidance. Now the message just says "Building Display..." if the file name won't fit. Many thanks to Rob Sudbury, of Connect II (705-745-7165) in Ontario, for his help with these bugs. Revision 3.7 contains too many small changes to mention. Most important, UNARC was replaced with Archive EXTRACT, UPDATE and REMOVE. FileNote support was added. The COMMAND and SYSTEM menus were moved to make it harder to accidently select FORMAT. The command line options were expanded to cover all the options available using ToolTypes. The sleeping mouse pointer image was changed. Command key sequences were added to the most often used menus. This documentation file was reorganized. In the Works: I have already written most of the code to make DoTil ARCre compatible. When complete, any attempt to archive or update a file with a name longer than 12 characters will cause all files to be renamed "ARCfile.n". An appropriate EXECUTE.ME file will be added to the archive and will be used to rename the files as they are EXTRACTED by DoTil. Alternately, the archive may be unpacked using UNARC or ARC, and the EXECUTE.ME 'Executed' to rename the files. The EXTRACT and REMOVE file requesters will show the display the files real name and allow it to be selected. Expect this to be completed in my lifetime. One or more of the devices "DF1: DF2: DH0:" may be replaced with a device name of your choice. This should be straight forward, but in fact I expect it to be a can of worms. You should be able to copy a file to the printer and if Commodore every decides to stop teasing us with 1.3, the RAD: device will be supported. What happens if someone wants a directory of CON: though? CONTRIBUTIONS ============================================================ Please send your cash, check, money order, food stamps, sleazy pictures, comments, suggestions, praise and or hate mail to: Dan Franki 12306 Tomanet Trail Austin, Texas 78758 U.S.A. Please report any bugs you find in DoTil. If you contribute I will send you a new version with the bug repaired. Please state which revision of DoTil you are using and your Amiga's hardware configuration. Last but not least, this important announcement: DoTil may be freely copied and used by anyone provided that: The party providing the copy receives no fee or other compensation excluding club membership dues or media charges. This documentation file is included in its original form. The author makes no claims as to the suitability or accuracy of this program. Any damage resulting from the use of DoTil is the sole responsibility of the user.