home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 2 / goldfish_vol2_cd1.bin / files / dev / asm / tbsource / ringdetect / final / ringdetect.doc < prev    next >
Encoding:
Text File  |  1993-12-21  |  13.4 KB  |  386 lines
  1.  
  2. 07/02-93                    RingDetect V1.11
  3.  
  4. Updated: 01/01-92 - for version 1.00 (The new year version)
  5.                     - Preliminary docs
  6. Updated: 01/01-92 - for version 1.01 (The new year version, part II)
  7. Updated: 12/01-92 - for version 1.02
  8. Updated: 31/05-92 - for version 1.04
  9. Updated: 07/06-92 - for version 1.05
  10. Updated: 10/06-92 - for version 1.06
  11. Updated: 09/08-92 - for version 1.07
  12. Updated: 01/01-93 - for version 1.08 (The new year version II)
  13. Updated: 01/01-93 - for version 1.09 (The new year version II, part II)
  14. Updated: 10/01-93 - for version 1.10
  15. Updated: 07/02-93 - for version 1.11
  16.                         
  17.  Copyright (C) Tomi Blinnikka 1993, All Rights Reserved.
  18.                     ^^^^^^^^^^^^^^^^^^^^
  19. This program is SHAREWARE. This means that you can copy it and give it
  20. to all your friends, upload it to a BBS or include it in a PD-library
  21. (FISH etc.). BUT (!!!) if you use this program frequently you must 
  22. pay $5 - $10. The other restrictions are: all of the files must be 
  23. included in their original form without additions, deletions, or 
  24. modifications of any kind and it IS NOT TO BE SOLD. THIS INCLUDES 
  25. GERMAN PD DEALERS. If you wish to use this program for commercial 
  26. purposes, you need written permission. The RingDetect program is 
  27. provided "AS IS" without warranty of any kind, and the author is not 
  28. responsible for any damage this software may or may not do.
  29.  
  30. WHAT DOES IT DO?
  31. ~~~~~~~~~~~~~~~~
  32. This program tells you when your phone is ringing. You may specify a
  33. program for it to run when the phone rings. As extra options, it can bring
  34. the screen it was opened on to the front, display a beep and of course
  35. all options can be disabled.
  36.  
  37. WHAT DO YOU NEED?
  38. ~~~~~~~~~~~~~~~~~
  39. You'll need an Amiga computer (see compatibility list), with Kickstart
  40. 2.04 (intuition.library and gadtools.library version 37 or higher). You'll
  41. also need a HAYES compatible modem.
  42.  
  43. COMPATIBILITY
  44. ~~~~~~~~~~~~~
  45. RD (RingDetect) will work on any Commodore-Amiga, running on Kickstart
  46. 2.04 or higher. This includes the following: A500(+), A600, A1000, A1200,
  47. A2000, A2500/20, A2500/30, A3000 (16 MHz or 25 Mhz model), A4000/40.
  48. The program SHOULD work on any upgrades (based on the Amiga Development
  49. Guidelines, see Amiga ROM Kernel Reference Manual (Kickstart 1.3 version):
  50. Libraries and Devices, introduction). RD works with all internal modems
  51. (I have a Supra 2400zi) and extra serial boards (I also have the A2232 :)
  52. that support the normal device commands (CMD_READ mainly). Workbench 
  53. compatibility is available with any version over 1.02.
  54.  
  55. HOW TO USE IT
  56. ~~~~~~~~~~~~~
  57. You can start the program from both CLI/SHELL/etc. and Workbench. 
  58.  
  59.     CLI USAGE
  60.     ---------
  61.  
  62. To run the program, enter the following into your CLI/SHELL/etc.
  63.  
  64.     1> RingDetect I=ICONIFY/S,DEV=DEVICE/K,UNIT/N/K,SPEED/N/K
  65.  
  66.     Where:  ICONIFY iconifies program when run. The window won't
  67.         be activated. Use 'I' as an abbreviation.
  68.  
  69.         DEVICE specifies the name of the desired serial device.
  70.         Use 'DEV' as an abbreviation.
  71.  
  72.         UNIT specifies the unit number of the desired serial
  73.         device.
  74.  
  75.         SPEED specifies the speed to use on the device.
  76.  
  77. Along with the GUI, you can also use the Break command or CTRL-C to quit
  78. the program.
  79.  
  80. You can also add this line into your S:User-StartUp to run the program when
  81. the machine is booted.
  82.  
  83. RUN >NIL: RingDetect
  84.  
  85. You may want to add the ICONIFY option ...
  86.  
  87. RUN >NIL: RingDetect ICONIFY
  88.  
  89.  ... to iconify the window, when the program starts.
  90.  
  91. I have ...
  92.  
  93. RUN >NIL: RingDetect ICONIFY DEVICE=modem0.device UNIT=0 SPEED=2400
  94.  
  95.  
  96.     WORKBENCH USAGE
  97.     ---------------
  98.  
  99. From the Workbench, start the program like any other, by double-clicking on
  100. its icon. If, however, you would like to specify the device, unit, speed or
  101. iconification, use the tool types. This is done by clicking once on the icon
  102. and selecting 'Information...' from the 'Icons' menu in the Workbench. Then
  103. change the tool types accordingly (please refer to user manual, if needed).
  104. Please take care with upper- and lowercase letters! The inputs ARE case-
  105. sensitive. If you would like the program to run on every boot, move
  106. RingDetect into the 'WBStartUp' drawer. If you do this, don't forget to add
  107. the tool type 'DONOTWAIT' (this applies to almost every program...). Below
  108. is a list of available tool types and there usage:
  109.  
  110. TOOL TYPE    VALUE
  111. -----------------------------------------------------------------------
  112. DEVICE        device name
  113. UNIT        device unit
  114. SPEED        device speed
  115. ICONIFY        YES
  116. DONOTWAIT    <NONE> (add only if program is in the 'WBStartUp' drawer)
  117.  
  118. Examples:
  119.  
  120.     DEVICE=serial.device
  121.     UNIT=0
  122.     SPEED=9600
  123.     ICONIFY=NO
  124.  
  125. or
  126.  
  127.     DEVICE=modem0.device
  128.     UNIT=0
  129.     SPEED=2400
  130.     ICONFIY=YES
  131.  
  132.  
  133. MAIN WINDOW
  134. ~~~~~~~~~~~
  135. The main window has several gadgets, four checkboxes, two string 
  136. gadgets and two boolean (click on) gadgets. From the checkboxes
  137. (On/Off, ScreenToFront, DisplayBeep and Command), you can choose what
  138. happens when the phone rings. 'On/Off' specifies whether or not to
  139. take any action, 'ScreenToFront' will bring RD's screen and window to
  140. front and un-iconify if possible, 'DisplayBeep' will display a beep
  141. (how's that possible? Display a BEEP? :), and 'Command' specifies whether
  142. or not to execute the command in the string gadget 'Command'.
  143.  The string gadget 'Init string' holds the text string that is sent to the
  144. device every time RingDetect is started. It is normally 'ATZ' or something
  145. else to reset the modem and to set its baud/bps rate accordingly. Both
  146. Carrier Feed and Line Feed will be appended (ASCII 13 and 10).
  147.  The string gadget 'Command' holds the command to execute. The
  148. 'Command-string' is the program and its arguments (CLI-based) to be
  149. run. This can be, say, a program that plays a sample or a script that
  150. adds an entry into a log, telling you how many times and when the phone
  151. rang while you were away etc.
  152.  The two boolean gadgets either 'Save' the preferences (window place,
  153. gadget settings etc.) or 'Quit' the program. These may also be selected
  154. from the menus.
  155.  The window has a Kickstart 2.04 Zoom gadget. When you click on this the
  156. window will go into its iconified state. Clicking on it again will open it
  157. up. If the window is iconified and the 'ScreenToFront' option is set when
  158. the phone rings, RingDetect will unzoom the window into its bigger size.
  159.  The window in versions 1.06 and up have a counter that shows how many
  160. times a ring has been detected. Every time the phone rings the counter 
  161. will increase by one. It can be reset from the menus. I decided to put it
  162. in the drag bar, since that is the only thing visible all the time. Thus 
  163. you can quickly check the amount without having to unzoom the window.
  164.  
  165. LIST OF OPTIONS
  166. ~~~~~~~~~~~~~~~
  167.  
  168.   MENUS
  169.   -----
  170.  
  171. Project:
  172.  
  173.     Load        - Loads the preferences (ENVARC:RingDetect.PREFS).
  174.  
  175.     Save        - Save the preferences.
  176.     ~~~~
  177.     Quit        - Quit program (NOTE! The preferences are not
  178.               saved!).
  179.  
  180. Counter:
  181.  
  182.     Reset        - Resets the counter that tells how many times
  183.               the phone has rung.
  184.  
  185.   GADGETS
  186.   -------
  187.  
  188. - Checkboxes
  189.  
  190.     On/Off        - Take any action when the phone rings?
  191.  
  192.     ScreenToFront    - Bring the screen on which RingDetect is on, to
  193.               the front? It will also bring the window itself
  194.               to front and unzoom if necessary.
  195.  
  196.     DisplayBeep    - Display beep?
  197.  
  198.     Command        - Run the program specified in the 'Command' string 
  199.               gadget?
  200.  
  201.  
  202. - String gadgets
  203.  
  204.     Init string    - The text string to send to the device upon
  205.               startup. A carrier feed and line feed will be
  206.               added (ASCII 13 and 10).
  207.  
  208.     Command        - Command to run, including arguments.
  209.  
  210.  
  211. - Boolean (click on) gadgets
  212.  
  213.     Save        - Save the preferences.
  214.  
  215.     Quit        - Quit program (NOTE! The preferences are not
  216.               saved!).
  217.  
  218. PREFERENCES
  219. ~~~~~~~~~~~
  220. When you select 'Save', either from the menus or by clicking on the gadget,
  221. RD will save all settings into a file called RingDetect.PREFS. It will
  222. be saved onto the assigned device ENVARC: where other system preferences 
  223. are stored. It however, is not an IFF file. This is to save space, in both 
  224. code size and disk space.
  225.  The window place will also be saved. If the Window was zoomed when 'Save'
  226. was chosen, the program will however, not zoom the window when the
  227. preferences are loaded or the program is started. On startup you must 
  228. specify the ICONIFY option.
  229.  
  230. EXAMPLES
  231. ~~~~~~~~
  232. Here we have some example scripts to use with RingDetect. The first one
  233. quits RD when your terminal program is run and reloads it when you quit the
  234. terminal program. In order for this to work, you must use this script to
  235. load your terminal program. You'll also need to change the paths and name
  236. of the terminal program accordingly. You can, of course, use this with any
  237. other program, for example a BBS program. NOTE! This first one DOES NOT
  238. WORK when loaded from Workbench.
  239.  
  240. ;---CUT---
  241. FailAt 21                ;prevent Break from terminating
  242. Break `Status COM=RingDetect`        ;script if RD not run
  243. JRCOMM:JR-Comm                ;Change to your terminal program
  244. RUN >NIL: RingDetect ICONIFY
  245. ;---CUT---
  246.  
  247. This second one adds an entry into a log when the phone rings. Again you'll
  248. need to change the path to suit your own needs. In the 'Command'-string (in
  249. RingDetect) add the string 'Execute Ringer", where Ringer is the name of
  250. this script. Once again, change the path and filename correctly.
  251.  
  252. ;---CUT---
  253. echo >>TEXTS:Rings "RING"
  254. date >>TEXTS:Rings
  255. echo >>TEXTS:Rings "~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"
  256. ;---CUT---
  257.  
  258. PROBLEMS
  259. ~~~~~~~~
  260. The program reads characters from the selected serial device. If however
  261. you have a terminal program (or BBS software, or any other program that
  262. uses the same device) running at the same time, some characters will go 
  263. to that program and RINGing can not be detected.
  264.  When changing from one version to another you might receive a file error.
  265. This is due to the preferences file changing. Just resave your prefs to
  266. overcome this problem.
  267.  
  268. ERROR MESSAGES
  269. ~~~~~~~~~~~~~~
  270. The RingDetect program will display necessary error messages. If a window
  271. can't be opened, the user will be informed. If a PublicScreen cannot be
  272. locked, the user will informed etc. I HATE PROGRAMS THAT DON'T TELL
  273. WHAT-THE-HELL IS GOING ON! That clear? If RD doesn't give any output,
  274. output has been redirected to NIL: etc.
  275.  
  276. VERSIONS
  277. ~~~~~~~~
  278. Version Size    Date     Description
  279. ---------------------------------------------------------------------
  280. 1.11    8484    07/02/93 Changed a few library calls...
  281.  
  282. 1.10    ????    10/01/93 Removed some extra stuff left in code.
  283.  
  284. 1.09    8484    01/01/93 Added an initstring (Damn you Radix! :)
  285.  
  286. 1.08    8232    01/01/93 Changed the parser to use dos.library. It
  287.              now conforms to Commodores guidelines.
  288.              Lost some weight here when I updated the
  289.              iorequests and messages ports.
  290.              Changed a few things from the About-window.
  291.              Added speed options.
  292.              Tested under Kickstart 3.0/39.110.
  293.              Updated documents.
  294.              The new year version II.
  295.  
  296. 1.07    9368    09/08/92 Fixed bug with device unit number. It was
  297.              opened with an incorrect unit if above 0.
  298.              NOTE! RingDetect is now SHAREWARE.
  299.  
  300. 1.06    9220    10/06/92 Added a counter to follow how many times
  301.              the phone has rung. 
  302.  
  303. 1.05    8816    07/06/92 Version string now follows Commodores guide-
  304.              lines. You can now have a comment after the
  305.              command and options, but no spaces in the
  306.              device name.
  307.  
  308. 1.04    8828    31/05/92 Major changes: Program now waits ONLY for
  309.              'RING', no other string can be given.Now 
  310.              brings the window to front when the screen 
  311.              is brought to front.
  312.              Added a keyboard shortcut to activate string
  313.              gadget. Program now resets modem with "ATZ"
  314.              on startup.
  315.              Updated documents.
  316.  
  317. 1.03    8908    ??/??/92 Minor changes, so-called bug fixes.
  318.  
  319. 1.02    8360    13/01/92 Fixed enforcer hit. Fixed bug with load. It
  320.              didn't put gadgets back. Added WB-startup.
  321.              Updated documents.
  322.  
  323. 1.01    7584    01/01/92 The new year version I, part II. Fixed some
  324.              bugs. Changed the year to 1992. Window now
  325.              unzooms only when ScreenToFront is activated.
  326.              Removed debugging stuff accidently left in
  327.              code. No opening errors anymore. Forgot to
  328.              have TRUE with WA_AutoAdjust.
  329.  
  330. 1.00    7636    01/01/92 The new year version. Added lots of goodies.
  331.              Distributed for testing. Upload to: MITS
  332.  
  333. 0.00a-    ????    ??/??/91 Wrote the program basics and main routines.
  334. 0.99a
  335.  
  336. FUTURE VERSIONS
  337. ~~~~~~~~~~~~~~~
  338. Future version will have the bug fixes for the bugs I haven't found. Maybe
  339. an AREXX-interface, who knows? BTW. Don't you just love utilities which
  340. have docs that are longer than the program itself?
  341.  
  342. BUGS
  343. ~~~~
  344. No known bugs at the moment, execpt one "feature" mentioned in problems.
  345. RingDetect has been run with enforcer & mungwall and nothing was found.
  346.  
  347. SHAREWARE FEE
  348. ~~~~~~~~~~~~~
  349. As of version 1.07 RingDetect is ShareWare. I am not asking for a huge
  350. amount of money, so I hope I will get some response. The fee is only $5 to
  351. $10 (USD), or whatever that happens to make at the moment you're reading
  352. this, in german marks (DM). If you're from Finland a sum of 20 FIM to 50
  353. FIM is great (Yeah, so what if I changed the $10 to $12 ? You Finnish guys
  354. don't have to pay so much for postage :)
  355.  
  356. BUG REPORTS ETC...
  357. ~~~~~~~~~~~~~~~~~~
  358. Please send donations, bug reports, and list of features you would like to
  359. have included in future versions to
  360.  
  361. Tomi Blinnikka
  362. Syystie 10
  363. 00780 Helsinki
  364. FINLAND
  365.  
  366. If you want the source code (it has some examples how to take care of
  367. command line inputs, PublicScreen stuff, libraries with special 2.04
  368. things), contact me at the address above or you can also contact me on the
  369. following BBS and net(s):
  370.  
  371. MITS +358-0-458 2066
  372. MITS +358-0-458 2077
  373. MITS +358-0-458 2088 (Sec. level 40 or higher ONLY) 
  374.  
  375. docbliny@mits.mdata.fi
  376.  
  377.  
  378. "...trademark of Xerox Corporations. Reading legal mush can turn your
  379. brain to guacamole! Epson is registered trademark of Epson America
  380. ..." -Amiga RKRM Includes & AutoDocs, fourth page.
  381.  
  382.  
  383.                         Tomi Blinnikka
  384.  
  385.                         docbliny@mits.mdata.fi
  386.