@database "RingDetect.guide" @author "Tomi Blinnikka" @(c) "Copyright Tomi Blinnikka 1991-96" @$VER: RingDetect.guide 1.15 (02.05.96) (C) Copyright Tomi Blinnikka 1996 @wordwrap @node Main "RingDetect table of contents" @next Doc_Version 02.05.96 @{b}RingDetect V1.15@{ub} @{u}Table of contents@{uu} @{"Document versions " link Doc_Version} @{"Copyright " link Copyright} @{"What does RingDetect do? " link Basics} @{"Compatibility " link Compatibility} @{"Starting from CLI/Shell " link CLIStart} @{"Starting from Workbench " link WBStart} @{"Main window " link Main_Window} @{"Menus " link Menus} @{"Gadgets " link Gadgets} @{"Preferences " link Prefs} @{"Examples " link Examples} @{"Problems " link Problems} @{"Error messages " link Errors} @{"Bugs " link Bugs} @{"Versions " link Versions} @{"Future versions " link Future} @{"Shareware fee " link Shareware} @{"Contacting the author " link Author} @endnode @node Doc_Version "Document version" @prev Main @next Copyright @{u}DOCUMENT VERSIONS@{uu} Updated: 01.01.92 - for version 1.00 (The new year version) - Preliminary docs Updated: 01.01.92 - for version 1.01 (The new year version, part II) Updated: 12.01.92 - for version 1.02 Updated: 31.05.92 - for version 1.04 Updated: 07.06.92 - for version 1.05 Updated: 10.06.92 - for version 1.06 Updated: 09.08.92 - for version 1.07 Updated: 01.01.93 - for version 1.08 (The new year version II) Updated: 01.01.93 - for version 1.09 (The new year version II, part II) Updated: 10.01.93 - for version 1.10 Updated: 07.02.93 - for version 1.11 Updated: 01.05.96 - for version 1.14 Updated: 02.05.96 - for version 1.15 @endnode @node Copyright "Copyright information" @prev Doc_Version @next Basics @{u}COPYRIGHT INFORMATION@{uu} Copyright (C) @{"Tomi Blinnikka" link "Author"} 1996, @{u}All Rights Reserved.@{uu} This program is @{"SHAREWARE" link "Shareware"}. This means that you can copy it and give it to all your friends, upload it to a BBS or include it in a PD-library (FISH, Aminet CDROMS etc.). BUT (!!!) if you use this program frequently you must pay $5 - $10. The other restrictions are: this archive can only be spread in its original form without additions, deletions, or modifications of any kind and it IS NOT TO BE SOLD FOR PROFIT. THIS INCLUDES GERMAN PD DEALERS. If you wish to use this program for commercial purposes, you need written permission from the author. @{b}RingDetect@{ub} IS PROVIDED "AS-IS" AND SUBJECT TO CHANGE; NO WARRANTIES ARE MADE. ALL USE IS AT YOUR OWN RISK. NO LIABILITY OR RESPONSIBILITY IS ASSUMED. @endnode @node Basics "Basics about RingDetect" @prev Copyright @next Compatibility @{u}WHAT DOES IT DO?@{uu} This program tells you when your phone is ringing. You may specify a program for it to run when the phone rings. As extra options, it can bring the screen it was opened on to the front, display a beep and of course all options can be disabled. @endnode @node Compatibility "What is RingDetect compatible with?" @prev Basics @next CLIStart @{u}COMPATIBILITY@{uu} @{b}RingDetect@{ub} will work on any Commodore-Amiga, running on Kickstart 2.04 or higher. This includes the following: A500(+), A600, A1000, A1200, A2000, A2500/20, A2500/30, A3000 (16 MHz or 25 Mhz model), A4000/30/40. The program SHOULD work on any upgrades (based on the Amiga Development Guidelines, see Amiga ROM Kernel Reference Manual (Kickstart 1.3 version): Libraries and Devices, introduction). RD works with internal modems (I had a Supra 2400zi years ago) and extra serial boards (I also had the A2232 :) that support the normal device commands (CMD_READ mainly). Workbench compatibility is available with any version over 1.02. @endnode @node CLIStart "Starting RingDetect from a CLI/Shell" @prev Compatibility @next WBStart @{u}STARTING FROM CLI/SHELL@{uu} You can start the program from a CLI/SHELL/etc. and @{"Workbench" link "WBStart"}. To run the program, enter the following into your CLI/SHELL/etc. 1> RingDetect I=ICONIFY/S,DEV=DEVICE/K,UNIT/N/K,SPEED/N/K PUBSCREEN/K. Where: ICONIFY iconifies program when run. The window won't be activated. Abbreviation: I. DEVICE specifies the name of the desired serial device. Abbreviation: DEV. Keyword required. UNIT specifies the unit number of the desired serial device. Keyword required. SPEED specifies the speed to use on the device. Keyword required. PUBSCREEN specifies the screen where the main window should be opened. Keyword required. Along with the GUI, you can also use the Break command or CTRL-C to quit the program. You can also add this line into your S:User-StartUp to run the program when the machine is booted. RUN >NIL: RingDetect You may want to add the ICONIFY option ... RUN >NIL: RingDetect ICONIFY ... to iconify the window, when the program starts. I used to have ... RUN >NIL: RingDetect ICONIFY DEVICE=modem0.device UNIT=0 SPEED=2400 @endnode @node WBStart "Starting from the Workbench" @prev CLIStart @next Main_Window @{u}STARTING FROM WORKBENCH@{uu} From Workbench, start the program like any other by double-clicking on its icon. If, however, you would like to specify a public screen, use the tool types. This is done by clicking once on the icon and selecting 'Information...' from the 'Icons' menu in the Workbench. Then change the tool types accordingly (please refer to your User Manual, if necessary). Please take care with upper- and lowercase letters! The inputs ARE case- sensitive. If a public screen name isn't given, @{b}RingDetect@{ub} will use the default public screen. Below is a list of available tool types and there usage: TOOL TYPE VALUE ----------------------------------------------------------------------- DEVICE UNIT SPEED ICONIFY PUBSCREEN DONOTWAIT (add only if program is in the 'WBStartUp' drawer) Examples: DEVICE=serial.device UNIT=0 SPEED=9600 ICONIFY or DEVICE=modem0.device UNIT=0 SPEED=2400 ICONFIY PUBSCREEN=My_Screen.1 @endnode @node Main_Window "Description of main window" @prev WBStart @next Menus @{u}MAIN WINDOW@{uu} The main window has several @{"gadgets" link "Gadgets"}, four checkboxes, two string gadgets and two boolean (click on) gadgets. From the checkboxes (On/Off, ScreenToFront, DisplayBeep and Command), you can choose what happens when the phone rings. 'On/Off' specifies whether or not to take any action, 'ScreenToFront' will bring RD's screen and window to front and un-iconify if possible, 'DisplayBeep' will display a beep (how's that possible? Display a BEEP? :), and 'Command' specifies whether or not to execute the command in the string gadget 'Command'. The string gadget 'Init string' holds the text string that is sent to the device every time RingDetect is started. It is normally 'ATZ' or something else to reset the modem and to set its baud/bps rate accordingly. Both Carrier Feed and Line Feed will be appended (ASCII 13 and 10). The string gadget 'Command' holds the command to execute. The 'Command-string' is the program and its arguments (CLI-based) to be run. This can be, say, a program that plays a sample or a script that adds an entry into a log, telling you how many times and when the phone rang while you were away etc. The two boolean gadgets either 'Save' the preferences (window place, gadget settings etc.) or 'Quit' the program. These may also be selected from the menus. The window has a Kickstart 2.04 Zoom gadget. When you click on this the window will go into its iconified state. Clicking on it again will open it up. If the window is iconified and the 'ScreenToFront' option is set when the phone rings, RingDetect will unzoom the window into its bigger size. The window in versions 1.06 and up have a counter that shows how many times a ring has been detected. Every time the phone rings the counter will increase by one. It can be reset from the menus. I decided to put it in the drag bar, since that is the only thing visible all the time. Thus you can quickly check the amount without having to unzoom the window. @endnode @node Menus @prev Main_Window @next Gadgets @{u}MENUS@{uu} Project: Load - Loads the @{"preferences" link "Prefs"} (ENVARC:RingDetect.PREFS). Save - Save the @{"preferences" link "Prefs"}. ~~~~ Quit - Quit program (@{B}NOTE!@{ub} The @{"preferences" link "Prefs"} are not saved!). Counter: Reset - Resets the counter that tells how many times the phone has rung. @endnode @node Gadgets @prev Menus @next Prefs @{u}GADGETS@{uu} - Checkboxes On/Off - Take any action when the phone rings? ScreenToFront - Bring the screen on which RingDetect is on, to the front? It will also bring the window itself to front and unzoom if necessary. DisplayBeep - Display beep? Command - Run the program specified in the 'Command' string gadget? - String gadgets Init string - The text string to send to the device upon startup. A carrier feed and line feed will be added (ASCII 13 and 10). Command - Command to run, including arguments. - Slider gadgets Run on Nth ring - Allows you change how often the command is run. For example, if you set the value to 2, the command will only be run every third time the phone rings (@{b}NOTE!@{ub} Your modem sends the RING text everytime you can hear the phone ring). - Boolean (click on) gadgets Save - Save the @{"preferences" link "Prefs"}. Quit - Quit program (@{b}NOTE!@{ub} The @{"preferences" link "Prefs"} are not saved!). @endnode @node Prefs @prev Gadgets @next Examples @{u}PREFERENCES@{uu} When you select 'Save', either from the @{"menus" link "Menus"} or by clicking on the @{"gadget" link "Gadgets"}, RD will save all settings into a file called RingDetect.PREFS. It will be saved onto the assigned device ENVARC: where other system preferences are stored. It however, is not an IFF file. This is to save space, in both code size and disk space. The window place will also be saved. If the Window was zoomed when 'Save' was chosen, the program will however, not zoom the window when the preferences are loaded or the program is started. On startup you must specify the ICONIFY option. @endnode @node Examples "A few examples" @prev Prefs @next Problems @{u}EXAMPLES:@{uu} Here we have some example scripts to use with RingDetect. The first one quits RD when your terminal program is run and reloads it when you quit the terminal program. In order for this to work, you must use this script to load your terminal program. You'll also need to change the paths and name of the terminal program accordingly. You can, of course, use this with any other program, for example a BBS program. NOTE! This first one DOES NOT WORK when loaded from Workbench. ;---CUT--- FailAt 21 ;prevent Break from terminating Break `Status COM=RingDetect` ;script if RD not run TERM:Term ;Change to your terminal program RUN >NIL: RingDetect ICONIFY ;---CUT--- This second one adds an entry into a log when the phone rings. Again you'll need to change the path to suit your own needs. In the 'Command'-string (in RingDetect) add the string 'Execute Ringer", where Ringer is the name of this script. Once again, change the path and filename correctly. ;---CUT--- echo >>TEXTS:Rings "RING" date >>TEXTS:Rings echo >>TEXTS:Rings "~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~" ;---CUT--- @endnode @node Problems "Possible problems that You might encounter" @prev Examples @next Errors @{u}PROBLEMS@{uu} The program reads characters from the selected serial device. If however you have a terminal program (or BBS software, or any other program that uses the same device) running at the same time, some characters will go to that program and RINGing can not be detected. When changing from one version to another you might receive a file error. This is due to the preferences file changing. Just resave your prefs to overcome this problem. @endnode @node Errors "Error messages displayed by RingDetect" @prev Problems @next Bugs @{u}ERROR MESSAGES@{uu} The @{b}RingDetect@{ub} program will display necessary error messages. If a library can't be opened, the user will be informed. I HATE PROGRAMS THAT DON'T TELL WHAT-THE-HELL IS GOING ON! That clear? If @{b}RingDetect@{ub} doesn't give any output something has gone terribly wrong or you're running with an old Kickstart. Even in this case the return code will be set to -20 (FAIL). @endnode @node Bugs "Known bugs" @prev Errors @next Versions @{u}BUGS@{uu} No known bugs at the moment. @{b}RingDetect@{ub} has been tested with Enforcer & Mungwall. @endnode @node Versions "List of versions and changes" @prev Bugs @next Future @{u}VERSIONS@{uu} Version Size Date Description ------------------------------------------------------------------------ 1.15 8156 02.05.96 You may now specify how many RINGs to wait before running the command. Fixed a bug with the reset function (and other intuition stuff too). 1.14 7800 01.05.96 Small optimization done. Added PUBSCREEN option. Now prints error messages when run from WB. Changed Workbench option ICONIFY. It doesn't need a parameter any more. Just the keyword is sufficient. Locale support added. Now prints unit number too if device open fails. Added Finnish locale. 1.13 8508 15.04.95 Added window refresh code that was missing. Removed some leftover code. 1.12 ???? 20.07.93 Made some parts safer and added a few bugs. Cleaned out some GadTools stuff. 1.11 8484 07.02.93 Changed a few library calls... 1.10 ???? 10.01.93 Removed some extra stuff left in code. 1.09 8484 01.01.93 Added an initstring (Damn you Radix! :) 1.08 8232 01.01.93 Changed the parser to use dos.library. It now conforms to Commodores guidelines. Lost some weight here when I updated the iorequests and messages ports. Changed a few things from the About-window. Added speed options. Tested under Kickstart 3.0/39.110. Updated documents. The new year version II. 1.07 9368 09.08.92 Fixed bug with device unit number. It was opened with an incorrect unit if above 0. NOTE! RingDetect is now SHAREWARE. 1.06 9220 10.06.92 Added a counter to follow how many times the phone has rung. 1.05 8816 07.06.92 Version string now follows Commodores guide- lines. You can now have a comment after the command and options, but no spaces in the device name. 1.04 8828 31.05.92 Major changes: Program now waits ONLY for 'RING', no other string can be given.Now brings the window to front when the screen is brought to front. Added a keyboard shortcut to activate string gadget. Program now resets modem with "ATZ" on startup. Updated documents. 1.03 8908 ??.??.92 Minor changes, so-called bug fixes. 1.02 8360 13.01.92 Fixed enforcer hit. Fixed bug with load. It didn't put gadgets back. Added WB-startup. Updated documents. 1.01 7584 01.01.92 The new year version I, part II. Fixed some bugs. Changed the year to 1992. Window now unzooms only when ScreenToFront is activated. Removed debugging stuff accidently left in code. No opening errors anymore. Forgot to have TRUE with WA_AutoAdjust. 1.00 7636 01.01.92 The new year version. Added lots of goodies. Distributed for testing. Upload to: MITS 0.00a- N/A ??.??.91 Wrote the program basics and main routines. 0.99a @endnode @node Future "Future versions and ideas for them" @prev Versions @next Shareware @{u}FUTURE VERSIONS@{uu} Future version will have the bug fixes for the bugs I haven't found. Maybe an AREXX-interface, who knows? I might even change the program into a commodity. But then again I might let it rot on my HD for another few years... BTW. Don't you just love utilities which have docs that are longer than the program itself? @endnode @node Shareware "RingDetect shareware fee" @prev Future @next Author @{u}SHAREWARE FEE@{uu} If you use this program on a regular basis, be kind enough to thank me with a few bucks. The suggested fee is 5 to 10 USD. Finns can send me 20 to 50 FIM or buy me Coke if they drop by some time. @endnode @node Author "Contacting the author" @prev Shareware @{u}CONTACTING THE AUTHOR@{uu} Please send donations, @{"bug" link "Bugs"} reports, and list of features you would like to have included in @{"future versions" link "Future"} to Tomi Blinnikka Syystie 10 00780 Helsinki FINLAND Contact me at the address above or you can also contact me on the following BBS and net address: MITS +358-0-348 205 docbliny@walrus.megabaud.fi "...trademark of Xerox Corporations. Reading legal mush can turn your brain to guacamole! Epson is registered trademark of Epson America ..." -Amiga RKRM Includes & AutoDocs, fourth page. Tomi Blinnikka docbliny@walrus.megabaud.fi @endnode