@DATABASE "YamTools v1.6 Documentation" @NODE MAIN "YamTools v1.6 Documentation" @$VER: YamTools v1.6 Copyright ©1997 by Dick Whiting YamTools v1.6 Documentation Copyright ©1997 by Dick Whiting Standard Disclaimer: I wrote it, it works for me, I don't guarantee that it will do anything productive for anyone else, etc. etc. ;-) HOWEVER, if you do find a use for it: I homeschool my kids and they would love a postcard from where EVER you live. Instant Geography Lesson;) Postcards: Dick Whiting 28590 S. Beavercreek Rd. Mulino, Oregon 97042 USA Email: Dick Whiting @{" Table Of Contents " Link Table_Of_Contents} @{" Requirements " Link 1.} @{" Basics " Link 2.} @{" How To Get Started " Link 3.} @{" Folder Page " Link 4.} @{" Mail List Page " Link 5.} @{" Config Pages " Link 6.} @{" Miscellaneous " Link 7.} @{" History " Link 8.} @{" Thanks " Link 9.} @{" Postcards - I REALLY love getting these!! " Link 10.} @ENDNODE @NODE Table_Of_Contents " Table Of Contents " MAIN@{" YamTools v1.6 Documentation " Link MAIN} 1.@{" Requirements " Link 1.} 2.@{" Basics " Link 2.} 2.1.@{" Notes and Warnings " Link 2.1.} 3.@{" How To Get Started " Link 3.} 3.1.@{" Running from a CLI " Link 3.1.} 4.@{" Folder Page " Link 4.} 4.1.@{" Folder List " Link 4.1.} 4.2.@{" Searching YAM mails " Link 4.2.} 4.3.@{" Search Options " Link 4.3.} 5.@{" Mail List Page " Link 5.} 5.1.@{" Mail List " Link 5.1.} 6.@{" Config Pages " Link 6.} 6.1.@{" System " Link 6.1.} 6.2.@{" ARexx Buttons " Link 6.2.} 7.@{" Miscellaneous " Link 7.} 7.1.@{" Menus " Link 7.1.} 7.2.@{" Aborting Processing " Link 7.2.} 7.3.@{" Extra Scripts " Link 7.3.} 7.4.@{" Setups for other scripts " Link 7.4.} 8.@{" History " Link 8.} 8.1.@{" Bugs " Link 8.1.} 9.@{" Thanks " Link 9.} 10.@{" Postcards - I REALLY love getting these!! " Link 10.} @ENDNODE @NODE 1. "Requirements" You will need several programs from Aminet: FlashFind by Frank Würkner - util/cli/FlashFind1.2.lha MuiRexx by Russell Leighton - dev/mui/MUIRexx_2_2.lha And, of course, Marcel Beck's wonderful YAM mail software FILES INCLUDED IN THIS ARCHIVE: YamTools.rexx - the REAL program. YamTools.info - for running from an icon YamTools.guide - this documentation YamTools.guide.info - multiview guide StartYamTools.rexx - starts YamTools from YAM ARexx menu item. StopYamTools.rexx - stops YamTools from YAM ARexx menu item. ReadMe - short starter version arexxqsort.lha - handles sorting of stem variables. by Willy Langeveld - originally found on Aminet Extras: ReDate.rexx - change date of mail to received date YAM2IB.rexx - display text/html using IBROWSE YTArchive.rexx - archive selected incoming mail YTArcMove.rexx - archive/move from ANY folder to archives YTArc2Sent.rexx - move SENT mail back to SENT folder YTDelete.rexx - delete selected mail YTDeDup.rexx - locate & delete duplicate mail YTDeSim.rexx - locate & delete similar mails YTReWrap.rexx - fixes badly word wrapped lines in mail @ENDNODE @NODE 2. "Basics" This program adds a SEARCH function to YAM. It also allows you to run ARexx scripts against selected folders, selected mail, or all mail in selected folders. There is bubble help available for all gadgets, lists, etc. Place the pointer above the item and wait;) There is also context sensitive help to this guide by pressing help with the pointer over a gadget. @{" Notes and Warnings " Link 2.1.} @ENDNODE @NODE 2.1. "Notes and Warnings" Be very careful to thoroughly test any scripts prior to placing them on a YamTools button. I write temporary files to T: including the output of FlashFind. Do NOT search a 100M of mail files for the letter 'a'. You will run out of RAM if that is where T: is assigned. I have no 'real' way of telling if you have changed YAM configurations or stopped and restarted YAM with a new Mail Directory. I try to trap these, but it is up to you to reload the folder list if you do this. @ENDNODE @NODE 3. "How To Get Started" Unload all of the YamTools pieces to YAM:rexx/ Get MuiRexx and FlashFind from Aminet and install according to their documentation. For MuiRexx this boils down to: Copy MUIRexx2.2/MuiRexx somewhere Copy MUIRexx2.2/MCC_Icon/Libs/MUI/Icon.mcc to MUI:Libs/MUI/ Assign MUIREXX: to wherever you put MuiRexx For FlashFind: Put it wherever you want (C: is a good place) Unpack and install QuickSort. Put QuickSort in Sys:Rexxc YamTools can be started from the icon, a tool bar (I use ToolDaemon and it works fine), or by placing the StartYamTools.rexx script in your YAM Arexx menu. The first time you start YamTools, it will complain either that one of the programs cannot be found or that the configuration cannot be found. Update the information on the @{"Config Page" Link Config Page} and do a SAVE. YamTools is ready to use (first start YAM). The default locations are: FlashFind in C: QuickSort in SYS:rexxc @{" Running from a CLI " Link 3.1.} @ENDNODE @NODE 3.1. "Running from a CLI" It is actually MuiRexx that is executed. Here are the commands necessary for running from a CLI or adding to a toolbar as CLI commands: CD YAM:rexx run muirexx:muirexx YamTools.rexx PORT YAMTOOLS HELP YamTools.guide Explanation: ------------ CD YAM:rexx - look for Yamtools stuff in Yam:rexx muirexx:muirexx - where to find MuiRexx Program YamTools.rexx - where to find YamTools.rexx PORT YAMTOOLS - port name to communicate with YamTools (don't change this) HELP YamTools.guide - where to find the YamTools Help file @ENDNODE @NODE 4. "Folder Page" This page includes the @{"Folder List" Link 4.1.}, the @{"Searching YAM mails" Link 4.2.} options, and allows you to run ARexx programs against selected folders using @{"ARexx Buttons" Link 6.2.}. @{" Folder List " Link 4.1.} @{" Searching YAM mails " Link 4.2.} @{" Search Options " Link 4.3.} @ENDNODE @NODE 4.1. "Folder List" This shows all of the Folders in the current YAM session. If you add or delete folders during the session, or stop YAM and restart it with a different configuration and mail directory, then make sure to reload the folder list using the button. The current Mail Directory is shown at the top of the page and can be changed on the @{"Config Page" Link Config Page}. Double-clicking on an entry will create a list of all of the mail in that folder in the @{"Mail List" Link 5.1.} page. Shift-clicking or drag-selecting can be done to select which folders are to be searched or have an ARexx program run against using the @{"ARexx Buttons" Link 6.2.} @ENDNODE @NODE 4.2. "Searching YAM mails" Highlight the folders you want to search. Choose which types of lines you want to search. Selecting 'ALL' turns off the other selections. Specify the character strings you wish to search for. Each string is considered as a separate complete argument. Select whether you want to locate mail with 'ANY' of the strings or only mail that has 'ALL' of them. More info about @{"Search Options" Link 4.3.} is available. Press SEARCH After a time that varies with the size and number of folders, you will be presented with all of the mail that matches. Double clicking on one of them will display it using the viewer specified in the @{"System" Link 6.1.} configuration. @ENDNODE @NODE 4.3. "Search Options" Search Subject Lines: looks in the subject line of the mail;) Search From Lines: checks From: Reply-To: and Sender: lines. Search To Lines: examines To: and CC: lines. Search text lines: considers any line that does NOT start with a word with a colon after it a text line. Simple to fool, but will work most of the time. Search All lines: considers all lines, header and text, as valid. Match Any: says to select files that contain any of the strings specified. (OR logic) Match All: says to select files that have ALL of the strings specified. (AND logic) Search strings: Each entry area is considered a separate and complete argument. Specifying 'search' (without quotes) will look for any line that contains the characters 'search' in it. Specifying ' search ' should find only lines that contain the word 'search'. Specifying 'search throu' would find lines such as 'search through the mail folder'. The Search button starts the search. The resulting matches are shown on the @{"Mail List" Link 5.1.} page, @ENDNODE @NODE 5. "Mail List Page" This page contains the @{"Mail List" Link 5.1.} and buttons for running ARexx programs against selected mail. The list is created by either a search or by reading an entire folder from the @{"Folder List" Link 4.1.} @{" Mail List " Link 5.1.} @ENDNODE @NODE 5.1. "Mail List" Double-clicking a mail list entry will display the mail using the viewer specified in the @{"System" Link 6.1.} configuration. Shift-select or drag-select to chose mail to run ARexx programs against using the @{"ARexx Buttons" Link 6.2.} @ENDNODE @NODE 6. "Config Pages" These pages are where you tell YamTools where to find FlashFind, QuickSort, what the current Mail Directory is, and which @{"ARexx Buttons" Link 6.2.} you want. There are also a few startup options available. @{" System " Link 6.1.} @{" ARexx Buttons " Link 6.2.} @ENDNODE @NODE 6.1. "System" These are the file/program requirements. Either enter or use the popups to specify the current Mail Directory Yam is using, where FlashFind is located, and where QuickSort is. The VIEWER is what YamTools uses to display mail. The default value is sys:Utilities/multiview %f PUBSCREEN=%s Any viewer that can be specified similarly should work. Note that %f is replaced with the filename of the mail file and that %s is replaced with the screen that YAM is using. An alternate option is to specify the viewer as YAMTOOLS in which case an MUI window will be created with a short header at the top and a scrollable section with the text of the mail. The EDITOR string determines what program to call with the EDIT button on the ARexx page. It should be something like: Utils:CED %f The DELAY ARCHIVE LOAD checkmark determines whether YamTools automatically loads the the Archive List at startup or not. The SHOW YAMTOOLS PAGES checkmark determines whether all of the YamTools pages are shown at startup or just the ARexx portion. After starting, you can toggle this using the menu items or Amiga-P for show pages and Amiga-H for hide pages. Press USE to use but not save the configuration. Press SAVE to use AND save. Press RELOAD to reload the LAST saved or loaded configuration. @ENDNODE @NODE 6.2. "ARexx Buttons" There are up to 800 buttons available to place ARexx scripts on. You do this by selecting an entry in the list on the config page and entering values for the button LABEL, the TYPE of processing (see below), and the AREXX program to run. The button area is now a VIRTUAL group. This means that it is able to be scrolled. Use the scroll bar;) Press USE to use but not save the configuration. Press SAVE to use AND save. Press RELOAD to reload the LAST saved or loaded configuration. Press CLEAR to reset an entry to empty. The one highlighted in the list will be the one cleared-so be careful. Press UNDO to remove the last change you did. It only works on the most recent change. Undo depth=1;) Press EDIT to call the configured editor for the selected ARexx program. The list can be sorted by dragging and dropping entries to where you want them. Press USE to see the new button layout. Processing TYPES: Specifying 'MAIL' will result in the ARexx program being run once for each mail in a selected folder when invoked from the Folder List page. If invoked from the Mail List page, then the program will be invoked for each selected mail. Specifying 'FOLDER' will result in the ARexx program being run once for each folder selected on the Folder List page. You can't run one of these from the Mail List page. Specifying 'ONCE' will result in the ARexx program being called once;) Nothing is passed to the routine and the routine is responsible for all of it's own activity. I added this so that programs that process all folders, etc. could be placed on a button. Whenever an ARexx program is run from a button, YAM is set to the selected folder and appropriate mail (or to the first mail in the folder). The ARexx program is also passed the directory name as an argument if TYPE=FOLDER or the filename if TYPE=MAIL. This allows the ARexx program to access either YAM information or AmigaDos information. TYPE=ONCE passes NO information. COLS allows you to set how many columns of buttons are to appear. Valid range is 1 to 20. ROWS allows you to set how many rows of buttons are to appear. Valid range is 1 to 40. Warning: If you change the TOTAL number of buttons to a LOWER value than a previous configuration, you may LOSE some button definitions. Check your math before saving a new configuration;) @ENDNODE @NODE 7. "Miscellaneous" @{" Menus " Link 7.1.} @{" Aborting Processing " Link 7.2.} @{" Extra Scripts " Link 7.3.} @{" Setups for other scripts " Link 7.4.} @ENDNODE @NODE 7.1. "Menus" Menus are: Project: About - Tells abit about the various products involved or used. Save - Save the current configuration to the default or last loaded SaveAs - Save the current configuration to a specified name. Open - Open and use a new configuration Quit - Quit YamTools Settings: Show Pages - shows the Archive list, Mail list, and Config pages of YamTools if they are not already displayed. Hide Pages - hides the above pages. Only the ARexx buttons will show. MUI - calls the MUI settings functions @ENDNODE @NODE 7.2. "Aborting Processing" During most potentially long processing a small information window is displayed that allows you to abort or interrupt processing. The abort will take place AFTER the current action is complete. Be patient-it will stop. In some places INTERRUPT can be used to continue further processing with the data accumulated so far (INTERRUPTING the 'scanning folder..' will go ahead and process any matches found to that point. @ENDNODE @NODE 7.3. "Extra Scripts" Note: The scripts named 'YT*.rexx' require YamTools. The others do not. Set these on buttons according to the @{"ARexx Buttons" Link 6.2.} directions. See below for the correct TYPE to use for each. YTDelete.rexx will delete mail selected on the mail list. My suggested use is to use the SEARCH function to find all the ones you want to delete. Highlight them on the mail list. Press the button. YTDelete should be TYPE=ONCE YTArchive.rexx acts the same but will archive mail from your INCOMING folder to the selected target folder. A requester list is displayed for you to make your target choice. If Marcel adds a 'mailmove' command then I will update this to handle archiving and moving in one piece. This one is entirely YAM 'legal'. See next one. YTArchive should be TYPE=ONCE YTArcMove.rexx can archive/move mail FROM ANY folder to any folders other than Incoming,Outgoing, and Sent. For the MOVES it uses DOS copy and delete commands and calculates what I think Marcel does. Please note that this is doing things OUTSIDE of the normal Yam environment and I will not guarantee that everything will continue to work when Marcel updates Yam. Be Careful!! As of right now, I have encountered no problems using it, but.... YTArcMove should be TYPE=ONCE YTArc2Sent.rexx moves SENT mail back to the SENT folder so that it can be Forwarded or ReSent. Same warnings for this one as for YTArcMove. YTArc2Sent should be TYPE=ONCE YTDeDup.rexx locates and DELETES duplicate mail in a folder. I HIGHLY recommend that you have 'Delete on Close' as your default if you are going to use this program. That will allow you to validate the actions prior to any actual deletes being performed. YTDeDup should be TYPE=FOLDER YTDeSim.rexx locates and DELETES similar mails in a folder. This one only checks the From, Date, and Subject lines. It IS possible that some non-duplicates could be identified and deleted. I HIGHLY recommend that you have 'Delete on Close' as your default if you are going to use this program. That will allow you to validate the actions prior to any actual deletes being performed. YTDeSim should be TYPE=FOLDER YTReWrap.rexx fixes badly wrapped lines in a mail file. To use this select a mail and adjust the outer and inner quoting when prompted. The outer quoting should be the character(s) or possibly none that prefix the piece of lines that got wrapped badly. The inner quoting should be the remainder (or none) necessary to make the lines uniform. Sorry, if that is unclear. Play with it using the UNDO/REDO to figure out how to make it work. YTReWrap can be TYPE=ONCE for use from a YAM list YTReWrap can be TYPE=ONCE or TYPE=MAIL from a YamTools list ReDate.rexx changes the Date: header in a mail to the date/time that it was received. Most useful for handling mail sent by people without a valid clock. Not sure what happens if YOU don't have one. I decided to NOT use the date/timestamp of the file itself, since so many of the scripts that I have seen update it. Instead, I use the filename to determine the date and use the timestamp from the original Date: header to build the new one. This seems to be the best compromise ReDate can be TYPE=ONCE for use from a YAM list ReDate can be TYPE=ONCE or TYPE=MAIL from a YamTools list YAM2IB.rexx displays text/html using IBROWSE. You must set some values in the script prior to using. See the comments at the top of the script. YAM2IB.rexx should be TYPE=ONCE @ENDNODE @NODE 7.4. "Setups for other scripts" There are quite a number of scripts available from Aminet and on the YAM mail list. Also check Kai Nikulainen's Web Page: http://www.utu.fi/~knikulai/ARexx.html Here are the TYPE settings for a few that I have tried: ShowSubjects.rexx by Kai Nikulainen TYPE=FOLDER To strip attachments for ALL selected mail or ALL mail in a FOLDER using the YamTools lists use: StripAttachment.rexx by Marcel Beck TYPE=MAIL To strip the current mail on a YAM list use: StripAttachment.rexx by Marcel Beck TYPE=ONCE @ENDNODE @NODE 8. "History" v1.6 Fixes and Changes: Made ARexx buttons NOT a scrolled area, IF there is only one row defined. Added CONFIG option for entering an editor for ARexx programs and a button to EDIT the selected program on the ARexx page. Thanks to Terry Hover for this suggestion. Fixed problem with viewer when VIEWER=YAMTOOLS. Now clears the list before displaying the new mail. Thanks to Stefan Akerblom. Fixed 'wonky' layout on requestor, garbage info for OuterQuote, and missing value for wordwrap in YTReWrap. Stefan Akerblom,again;) Fixed potential problem if a word was longer than the wrap length in YTReWrap. Also forced wrap length to be numeric. Found THESE BEFORE Stefan did;) v1.5 Fixes and Changes: Added option to display only the ARexx buttons on startup. This also required adding HIDE/SHOW options to the menus. To allow for a wide bar of buttons I also increased the maximum columns of ARexx buttons to 20 and the maximum rows of buttons to 40. Added option to DELAY loading the archive list on startup. As part of this I split the CONFIG page into two pages. Added option to select your own favorite VIEWER rather than being forced to use Multiview. Added option to use an MUI window for the viewer instead of one such as multiview. Specify YAMTOOLS for viewer to do this. Changed HELP BUBBLES for ARexx buttons so that they display what program is to be executed and what the TYPE for it is. Added @{"Extra Scripts" Link 7.3.} YTReWrap.rexx to distribution YTReWrap.rexx fixes badly wrapped lines in a mail file. Use it on files that have been quoted multiple times or written using one line length and then shortened somewhere during the sending/receiving process. Added @{"Extra Scripts" Link 7.3.} YAM2IB.rexx which uses IBrowse to display HTML attachments. Added @{"Extra Scripts" Link 7.3.} ReDate.rexx which fixes the dates for mail sent by those without clocks or invalid ones. Fixed bug that could result in mail list page disappearing. Sped up some list handling and the checkmark handling. v1.4 Fixes and Changes: Added @{"Extra Scripts" Link 7.3.} YTDeDup.rexx to distribution YTDeDup.rexx locates and deletes duplicates within a folder. Suggest 'Delete on Close' be your default if you use this so that you can validate the correctness of the deletes. Added @{"Extra Scripts" Link 7.3.} YTDeSim.rexx to distribution YTDeSim.rexx locates and deletes SIMILAR mail within a folder. Suggest 'Delete on Close' be your default if you use this so that you can validate the correctness of the deletes. Added YAM version checking to YTArcMove.rexx Added YAM version checking to YTArc2Sent.rexx Removed extra, unused code from YamTools.rexx v1.3 Fixes and Changes: Changed Folder Page search options to shrink vertical dimensions Thanx to 'The Duke of Prunes' (?) for the prod on this one. Changed Buttons to a scrollable group for same reason and to enable making button layout and number user configurable. The button area is scrollable. See @{"ARexx Buttons" Link 6.2.} for more information. Added Column and Row options to Config page to allow number of buttons (up to 96) to be user configurable -- takes effect after SAVING config and RESTARTING YamTools. The 6x16 limit is purely arbitrary, if you want it changed--email me. Fixed stupid error if mail directory was specified WITH the '/' Thanx Stefan Akerblom - sorry for the frustration;) Fixed error handling folders if some have been deleted, leaving a Folder list in the configuration with gaps in number sequence. Thanx Stefan Akerblom - again;) Added @{"Extra Scripts" Link 7.3.} YTArcMove.rexx to distribution YTArcMove.rexx archives/moves mail from ANY folder to any of the normal archive folders. Does not allow moving TO Incoming, Outgoing, or Sent. See warnings in @{"Extra Scripts" Link 7.3.} Added @{"Extra Scripts" Link 7.3.} YTArc2Sent.rexx to distribution YTArc2Sent.rexx moves SENT mail back to SENT folder so that it can be Forwarded or ReSent v1.2 Fixes and Changes: Added 'ONCE' option for @{"ARexx Buttons" Link 6.2.} Fixed problem if YAM was using WB screen - thanx Thorsten Ernst Getting Folder mail list now includes new mail since last rescan Fixed problem with 'deferred' and 'non-binding' assignments for the Mail Directory - thanx Duncan Gow Finally (?) fixed LAST and ONLY match condition;) Added @{"Extra Scripts" Link 7.3.} YTArchive.rexx to distribution Added @{"Extra Scripts" Link 7.3.} YTDelete.rexx to distribution Added documentation about @{"Setups for other scripts" Link 7.4.} v1.1 Fixes and Changes: Shortcuts for Menu items now displayed and work Fixed EXTRA processing on LAST match record condition Fixed MISSING processing on ONLY match record condition that fixing LAST match record condition introduced;) Added option to interrupt/abort after double-clicking on a folder. Changed 'showlist' function to 'show' for ports/libs, OOPS!! Removed debug scripts from distribution - too confusing for now Added Failat 21 to suppress return code messages to CLI Added instructions for @{"Running from a CLI" Link 3.1.} v1.0 First release. Not old enough to have a history yet;) @{" Bugs " Link 8.1.} @ENDNODE @NODE 8.1. "Bugs" As of the date of uploading this program, I have stopped being able to break it. This does not mean it is bug free. If you find any, please email me so that I can correct it for others. Thanks. @ENDNODE @NODE 9. "Thanks" Thank you's to: Willy Langeveld for RexxArpLib, VLT, QuickSort, et. al. Frank Würkner for FlashFind Stefan Stuntz for MUI. Russell Leighton for MuiRexx (without which this would not have been done at all) Stephan Sürken for Text2Guide (without it I would not have done a Guide format documentation) Marcel Beck for YAM - the BEST way to contact anyone. Holger Kruse for MIAMI - the BEST way to hook YAM to the net;) AND ... all of the other shareware, freeware, etc. programmers for the AMIGA who make it possible for US to still use our favorite machine;) Dick Whiting May 25, 1997 @ENDNODE @NODE 10. "Postcards - I REALLY love getting these!!" Thanks for the postcards to: Stefan Akerblom Melbourne, Australia Terrence Chun Philadelphia, Pennsylvania, USA Shane Cracknell Perth, Australia Todd Ehlers Madison, Wisconsin, USA Duncan Gow Helensburgh, Scotland Les Hellawell White Rose County, Britain Richard Starr White River Junction, Vermont, USA Kirk Strauser Springfield, Missouri, USA @ENDNODE