Club Amiga de Montreal

home *** CD-ROM | disk | FTP | other *** search

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 447.lha / DClock_v1.29 / DClock.doc < prev next >

Wrap

Text File | 1990-12-08 | 30.0 KB | 582 lines

============================ DClock v1.29 ============================ ======================== A Dumb Clock Utility ======================== ====================================================================== ========================= IMPORTANT NOTICE =========================== ====================================================================== Due to an important change in the handler <-> main process communication structure 'DClock' revisions older than 1.7 are incompatible with this release. Delete the older files and terminate the clock process before you install the 1.29 update first! Programmers: starting with v1.12 the DSeg port structure has changed. To make future expansion easier and to avoid collisions with custom 'DClock' versions ten longwords have been reserved at the bottom of the structure. ============================ BACKGROUND ============================== ====================================================================== Who cares for clock utilities, really, who does? Well, I do. I needed one, but couldn't find anything suitable. The standard Workbench clock was a bit too big, Mclk slowed down system performance, TUC had far too many features (including occasional disk-trashing), RSLClock was too large, so was MachII and DMouse intentionally didn't have any clock display. So, what was I up to do? Right, I programmed my very special creation, short, sweet and functional. ============================= FEATURES =============================== ====================================================================== Since I have already cooked out my custom version of DMouse I didn't need any additional Mouse accelerator, so this one didn't get into it. What I needed were Date (including weekday) and Time. The most important question was: where to place the display? Since I have already tested mouse pointer clocks and my home brewn MouseClock program which features two sprites hovering at the right hand side of the mouse pointer, the answer could only be: put it on the Workbench screen. Remembering my experiences with ReadySoft's A-Max Apple MacIntosh Emulator the time display found its way to the right hand side of the Workbench title bar. The time string is updated each second. 'DClock' and 'DClock-Handler' need arp.library v39.1 and can be made resident via the 'ARes' command. If you wish to use the 'DClock' ARexx interface, rexxhost.library v34.9 or above is required. Mclk uses about 10% of CPU time and about 16000 bytes of memory (that's almost as much as the standard Workbench clock consumes), MachII uses 4% of CPU time and 32000 bytes. 'DClock' only consumes between 1% and 5% of CPU time and requires about 36000 bytes of memory. =========================== INSTALLATION ============================= ====================================================================== Place 'DClock-Handler' in L:, 'DClock' in C: or SYS:, arp.library in LIBS:, type "DClock" to install, "DClock quit" to remove. Easy, isn't it? ============================== EXTRAS ================================ ====================================================================== 'DClock' still isn't a pure clock utility. I used to install a program called DisplayBeep in my Startup-Sequence script. This program spawned a process which replaced the DisplayBeep() function with a substitute not only to flash the display but also to beep audibly. To save some memory the code of DisplayBeep.c has been incorporated into 'DClock-Handler.c'. I also added the Click.c code I had written back in October. Somebody asked me to add an alarm-clock function which took me two hours to program. =============================== USAGE ================================ ====================================================================== To start simply type "DClock" (followed by none or more options) and press return. The main process will be "pulled up" almost instantly. Note: if ANYTHING goes wrong at this stage, 'DClock' will stop at the point where "Installing DClock, " appears and nothing else happens (the handler process has probably died). 'DClock' will wait for ever unless CTRL-C is pressed. 'DClock' will shut down and issue an error message. Now for the command line options. 'DClock' knows and handles the following: QUIT .................. Terminates the handler process and removes all loaded data. INFO .................. Gives some information on the current 'DClock' revision. VERSION ............... Displays the current revision number and creation date of 'DClock'. QUIET ................. Suppresses all those neat information messages which are issued each time an option is selected. REFRESH ............... Will reposition the 'DClock' display (vScreen users: after the screen size has been changed use this option to move the display). READCLOCK ............. Similar to the 'SetClock' command, 'DClock' will read the time from the builtin real time clock chip and adjust the system time accordingly. Note: 'DClock' will only read the information and cannot be used to adjust the battery backed up time (such as 'SetClock save'); so do not delete the 'SetClock' command! BEEP ON/OFF ........... 'DClock' uses a modified DisplayBeep() routine which lets the usual display flash (e.g. after the CTRL-G signal) produce a brief beep as well as a flash. The beep can be turned off this way (default is on). CLICK ON/OFF .......... Each time a key is pressed a keyboard click is produced (very similar to the high quality style IBM-PC® keyboards). This feature can be turned off this way (default is off). SPEECH ON/OFF.......... 'DClock' will tell you the time using the builtin narrator.device. This feature can be turned off and on using this switch. (default is off) HOUR ON/OFF ........... The 'hour' feature will give a brief 'beep' signal each full hour. I suppose this could be a lot funnier if the beep would be replaced by the chime of the Clock Tower of The Houses of Parliament ('Big Ben'). Any sampled sound donations are welcome. (default is off) SECONDS ON/OFF ........ 'DClock' displays the current time including minutes and seconds. The second display can be turned off via keyboard or with this option. (default is on) SETENV ON/OFF.......... Will write the day, date & time to Manx-type environment variables (DAY, DATE & TIME). This feature can be turned on and off. (default is off) COUNTDOWN #/SHOW ...... This is how 'DClock' can help you to make tea: set the timeout to, say 300 (= 5 minutes * 60 seconds) while your Earl Grey tea is drawing. 'DClock'will ring the bell after five minutes. 'DClock COUNTDOWN SHOW' will display the number of seconds to elapse before the countdown clock rings. SOUND <Name>/OFF ...... I don't know if this is useful for anyone, but it may be good for a laugh. The default hour chime produces a simple beep signal. This option will load any IFF-8SVX-sound and play it each time it is required. Selecting 'OFF' as the argument to this option will reset to the default beep. (default is - of course - the default beep) TEXTCOLOUR # .......... The colour in which the 'DClock' time and memory display will appear can be adjusted this way. (default is 0) BACKCOLOUR # .......... Same as above, but controls the background colour. (default is 1) CLICKVOLUME # ......... The volume of the keyboard click can be adjusted between 0 and 64. (default is 64) PRIORITY # ............ This determines the handler process priority. Any number between -128 and 127 will do. (default is 5) PAGE # ................ Selects one of the four (five) display pages as the startup page. (default is page 0) ALARM ON/OFF/SHOW ..... The alarm clock function is controlled by this function. It can be turned off and on. SHOW displays the currently selected alarm time. (default is off) ALARMTIME HH:MM:SS .... The alarm time is adjusted via this option, note that the alarm itself must be turned on separately. (default time is 12:00:00) Workbench users: 'DClock' can be started from Workbench! The following tooltype entries correspond to the approriate CLI options and have to appear in capital letters: BEEP, CLICK, CLICKVOLUME, PRIORITY, TEXTCOLOUR, BACKCOLOUR, ALARM, ALARMTIME, SETENV, COUNTDOWN, HOUR, SECONDS, SOUND, PAGE, SPEECH, READTIME The expected arguments are the same as with the CLI options. ========================== DCLOCK AND AREXX ========================== ====================================================================== Important notice: the DClock<->ARexx interface will only work if rexxhost.library v34.9 or above is present in your system! Interfacing to 'DClock' from ARexx is fairly easy. An example script could look like this: /* A simple DClock<->ARexx demonstration. */ /* We want results to be returned from 'DClock'. */ options results /* Take 'DClock' as the host address for the following * commands. */ address dclock /* Do something sensible, first ask 'DClock' to return its * version number. */ status version say 'You are using DClock' result /* We'll turn on the keyboard click. */ click on /* And we'll set the display colours. */ textcolour 3 backcolour 2 /* Ask 'DClock' to tell us the time. */ telltime /* That's all, read on! */ The 'DClock' ARexx interface knows all commands which can be set from CLI using the 'DClock' main program. The only difference is that commands displaying information such as 'DClock ALARM SHOW' will leave a result in the ARexx 'result' variable. These results are obtained through the 'status' command, not through the setting commands themselves. 'status version' will return the current 'DClock' version, 'status alarm' will return 'off' if alarm is disabled, 'on' if alarm is enabled. The 'status' command knows the following keywords: BEEP, CLICK, CLICKVOLUME, PRIORITY, TEXTCOLOUR, BACKCOLOUR, ALARM, ALARMTIME, SETENV, VERSION, COUNTDOWN, HOUR, SECONDS, SOUND, PAGE, SPEECH, LINE Note: 'LINE' will report 'OFF' if your Amiga computer is currently offline and 'ON' if a carrier signal is detected. If 'status' doesn't recognize a keyword or if you don't supply one, it will return a string of the following format: BEEP ON CLICK OFF CLICKVOLUME 64 PRIORITY 5 TEXTCOLOUR 0 BACKCOLOUR 5 ALARM OFF ALARMTIME 12:00:00 SETENV OFF VERSION 20 COUNTDOWN 0 HOUR OFF SECONDS OFF SOUND OFF PAGE 0 SPEECH OFF LINE OFF The ARexx interface itself isn't very powerful yet, since it was designed to simplify the rendezvous with DClockMenu.rexx. It is quite DClock-specific, no other program will profit from interfacing to 'DClock'. It's up to you to decide what 'DClock' will be good for. The ARexx interface will recognize a request to tell the current time. The approriate command is called "TELLTIME". Note that this function will still work if speech is turned off globally. ========================= DCLOCK AND HOTKEYS ========================= ====================================================================== The 'DClock' display is controlled by two hot-keys: LEFT-AMIGA+HELP and LEFT-AMIGA+DEL. The help-key cycles through five and a half (what does he mean by 'a half'?) different displays: time and date, graphical memory display, numerical memory display and online timer. The del-key toggles whether the time display includes seconds or not. If a countdown is currently running it will be displayed on the fifth page (which you know can be flipped with LEFT-AMIGA+HELP). If speech is enabled, 'DClock' will tell you the current time if you press LEFT-ALTERNATE+HELP. Note that if speech has just been disabled, pressing these keys will deallocate the speech task freeing additional memory. If speech is turned on again, or the TELLTIME command comes in from ARexx, the speech server will be reinitialized. ======================== FUTURE ENHANCEMENTS ========================= ====================================================================== Since starting with this revision the hour chime sound can be loaded externally, the next logical step would be to approach keyboard click, displaybeep and alarm clock in a similar way. To be frank: I don't see the sense behind it. If you do, try to add it on your own (I always said that custom 'DClock' versions are generally appreciated) or try to convince me to add this feature in a future revision. In my opinion - which is shared by the majority of 'DClock' users who have contacted me yet - 'DClock' has reached the point where each new feature has to be weighed carefully against size and usefulness. If you want 'DClock' to have new functions (e.g. to start script files at fixed points of time or to use multiple alarm times) think twice before requesting them. ============================== PROBLEMS ============================== ====================================================================== Selecting CLICK ON together with BEEP ON can cause problems if ConMan output has been halted with ^S. It is quite likely that click and beep will lock each other and the Amiga crashes. I haven't found a solution to this yet. ============================== CREDITS =============================== ====================================================================== Credits go to ARP Programmers for the most recent version of ARP, to Matt Dillon for DMouse, to Mike Oldfield & Peter Norman for the keyboard click, to Mason/Waters/Wright/Gilmour/Parsons for the alarm clock sound, to John Hodgson for the beep, to Thad Floryan for his date conversion routines and to Justin V. McCormick for the very basic string formatting code. A special mention must also go to Bill Hawes, author of ARexx, and to the authors of CygnusEd Professional 2 (Bruce Dawson & Colin Fox) whose programs both controlled the compiler runs. The DClockMenu.rexx code was created by Stefan Sticht who also is responsible for a good lot of ideas which have been incorporated into 'DClock' over the last few months. ================== COPY FEE, AUTHORS REQUEST, ETC. =================== ====================================================================== If you like 'DClock' and wish to contribute any money I urge you to send at least 10 US$ to... Amnesty International P.O. Box 37137 Washington D.C. 20013 I suppose Amnesty International can make better use of the money than I can. Even the smallest contribution makes sense. I don't care what happens to 'DClock' and 'DClock-Handler', copy them, sell them, delete them, they are meant to be PUBLIC-DOMAIN. But don't 'fleece' other users for them. Permission to redistribute the documentation, the source code and executable files granted as long as the body of this document is left intact. - I have tried to make 'DClock' as flexible as possible. The rendezvous data is easily to be extended. I encourage you to add whatever feature you want. I only ask you to send me a copy of your custom version of 'DClock'. The future of this tool depends on you, spread the word and also the disk! My address is: Olaf Barthel, MXM Brabeckstrasse 35 D-3000 Hannover 71 Federal Republic of Germany ============ REVISION HISTORY (most recent change first) ============= ====================================================================== V1.29 Small bug fixed in the speech/rexx server. If the speech server was started by the rexx server it could accidentally freeze the rexx server and flag the handler process to exit (some kind of chain reaction). The speech server would - as usual - prefer to crash if told to quit. The display beep would not work correctly. The beep sound has changed (plays a sine wave instead of a square wave). V1.28 Finally - the 'TurboBackup v1.0' <-> 'DClock' crash has been fixed! I cannot ascertain how it came to pass, but the programs do not lock each other out any more. All files have been recompiled using Aztec 'C' 5.0b. 'DClock-Handler' now also uses arp.library (which reduced the size of the executable file by about 4000 bytes). V1.27 This release introduces a new useful feature: your startup-sequence script can be sped up greatly by removing the 'SetClock load' call and by adding the 'Readclock' keyword to the 'DClock' command line. Starting with this release 'DClock' is able to read and set the system time by taking a look at the battery backed up clock chip (information on the registers contained in the chip were lifted from Ralph Babel's Amiga-Guru Book). The code size went down by almost 2000 bytes for both 'DClock' and 'DClock-Handler'. A small bug was fixed in the LoadChimeSound routine (the replay rate was miscalculated). Please note that this revision does not use any inline library calls. Careful analysis revealed that parts of my Aztec 5.0a Arp wrapper were broken which could eventually knock out the the DClock main program. This has been fixed. The speech server had the unnerving habit of crashing when flagged to shut down; needless to say, this has fixed, too. V1.26 This revision includes some major, major changes; a new date conversion routine has been incorporated into the handler. Sometimes the old one miscalculated the date, resulting in negative date values (blessed are those who were born on the -1st of January 1978). More important, DClock will adjust itself *automagically* to the current font used on the Workbench screen. This is another benefit for A3000 users (if you don't have an A3000, SetFont by Dave Haynie will do). The images once displayed in the Full/Empty bar are gone and will probably never return. Peter Fischer contributed the sampled sound of 'Big Ben', thanks Peter! V1.25 For the benefit of A3000 owners 'DClock' will adjust to the new Kickstart environment. Images are 'remapped' and colours are swapped to fit the new standard colour palette. The display is shifted a bit to the right to take advantage of the additional space available in the Workbench screen title bar. Minor changes have been made to various parts of the code. V1.24 Made small changes to support code to cut down code size and to speed up special code passages. Due to a semicolon behind an if() check RexxHostBase was always closed regardless if it was valid or not causing crashes on systems in which rexxhost.library was not present. The original DisplayBeep ROM code could accidentally crash the system. To avoid such collisions I have added back the old VideoBeep/AudioBeep code. Starting with this release, the keyboard click is by default disabled. V1.23 I was asked to add an online timer which took me some time to create. At first I started playing with hot-keys to start/stop the timer. After a while I discovered that some CIA or Custom chip register contains a flag indicating if the serial port is currently busy. The online timer will start as soon as a carrier signal is detected, and will stop if the carrier signal is lost. As a result, the countdown display has been moved to the fifth display page (the online timer currently resides on the fourth page). Note that the online timer will only work with the standard serial.device, the Supra modem (internal A2000 modem) or the ASDG extra modem are definitely not supported. I haven't checked how the online timer keeps up with multiplexed serial signals (I don't have any multiplexing hardware connected to my serial port). Starting with this release the DisplayBeep video beep will be handled by the original ROM code. V1.22 Discovered that even the Ring() routine used to hang when terminating the sound using AbortIO. I suppose that there is something badly wrong with audio.device which should be fixed as soon as possible (e.g. in Kick2.0). This routine - as some others do - now rather calls WaitIO than AbortIO. I also added the speech feature I found missing. If working with different custom screens you can't always take a look at the clock display. This feature uses less memory than you might think, the speech server even gets deallocated if speech is turned off. And anyway, if they build cuckoo clocks with tea machines and put together copy programs with builtin Tetris games, why shouldn't there be a clock utility to tell you the time? V1.21 Added PAGE option, rewrote the display beep code (used to do a Forbid after LockIBase which could result in a deadly embrace), rewrote the time display routine (used to hang if seconds were turned off externally). There also was a problem with the keyboard click/display beep code which caused one routine stealing the other one's audio channel. As a result DClock-Handler would lock-up trying to vacate the keyboard click channel on exit. This has been fixed. There was another problem with the sound: under certain circumstances an IORequest would never terminate (as you may know there are similar problems with serial.device). This has been fixed using AbortIO followed by a series of GetMsg/ReplyMsg calls. V1.20 DClock-Handler was extensively rewritten for size and speed. Andreas Gehrke suggested an option to turn off the seconds in the time display which I finally added. Added the SOUND option. V1.19 The ARexx interface has been partly rewritten to deal with the result codes correctly. Furthermore I've added an option to make 'DClock' beep briefly each full hour (this option was suggested by Stefan Sticht, thanks Stefan!). The command line option 'DClock ALARM INFO' has changed to 'DClock ALARM SHOW'. The ringing alarm clock can be cancelled via keyboard now. V1.18 The countdown option was introduced whilst playing Battle Squadron and drinking lots of cups of Earl Grey tea. Credits go to Holger P. Krekel who thought it to be a nice idea to have a reliable timer for making tea. V1.17 Finally - it has an ARexx interface and it even makes tea! Can't say that the ARexx interface has any peculiar function yet, it really doesn't do very much. But as usual, it's up to you to expand it. Important: you need rexxhost.library 34.9 or above to use the ARexx feature. V1.16 General cleanups for Aztec 5.0 release. Most functions have been ANSIfied, illegal calling procedures were fixed, as well as unused variables were removed. V1.15 Some minor bug fixes, this distribution now also includes the DClockMenu.rexx macro file written by Stefan Sticht. V1.14 Fixed some bugs in the alarm clock routine (thanks to Peter Fischer the clock will break after thirty seconds of constant ringing), the beep routine (thanks to Stefan Sticht who discovered that disabling the beep function also killed the visual beep) and the PopRequest function which could crash if former front screen/active window had been closed during the request. V1.13 Tried to port 'DClock' to Lattice 'C'; well,the attempt didn't last very long, I will wait for the Aztec 'C' 5.0 compiler update. Some calling mistakes were traced. V1.12 I 'ripped' the PopRequest routine from my programmers' library (mxm.library) and integrated it into the DClock.c code. This will display real error messages ever so often the Workbench tool info parsing routine stumbles upon an error. Note also: I've quit the Electronic Design Hannover team and the copyright changes to MXM. A note on the code (whoops, it rhymes!): the pop-up requester part may be incorporated into any program which has any need of it. If the CED Professional update had reached us earlier the req.library pop-ups would have been employed instead of my requesters. It's too late now, I don't want to change the code any more and anyway: some of you might think that 30 libraries (that's as much as there are in my LIBS: drawer) are enough and will prefer to use the non-library code instead. V1.11 Wow! The display found its way back to the Workbench title bar -> with the fastest refresh scheme possible. This is done via rendering into an invisible RastPort; this image is transferred to the Workbench bar layer. Now also included: display will move to the left hand of the screen depth arrangement gadgets after the REFRESH option is selected. V1.10 Better Workbench support added (older revision preferred to crash too often and didn't notice if Workbench was re-opened after closing the last custom screen). 'DClock' window will auto-adjust its position to appear at the left hand side of the screen depth arrangement gadgets (a special gift for overscanned Workbench screens - merry Christmas, it's the 22nd of December 1989!). V1.9 Full Workbench support added (oh boy, I am tired!). I will try to supply a neat icon to get it working. V1.8 CloseWBench()/OpenWBench() support available now! 'DClock' will close its window just in time to allow the Workbench screen to be closed. It will re-open its window as soon as the Workbench screen has successfully been re-opened. New for single-bitplane Workbench (soon to come in Kickstart 1.4): memory gauge will display a shaded bar instead of an orange one. V1.7 Some cosmetical changes, no spectacular work done; well, except for the small bug fix in the alarm routine (alarm only worked if time display was active). Docs partly rewritten, cleaned up some code. Important: added new DSeg entry: RingBack -> no downward compatibility with older 'DClock' revisions guaranteed anymore (sorry, but this was absolutely necessary). V1.6 Not released. V1.5 Added a most unnerving alarm clock function: the display vibrates, a bell is ringing ... what can it be? Probably 'DClock' trying to wake you up. V1.4 Fixed bug in time signal routine (didn't update if time was set backwards), added status line information, corrected exit() calls in 'DClock'. V1.3 Played around with a taller custom font (saw Kickstart 1.4 alpha 15 and noticed that the Workbench status line became longer overriding the 'DClock' display). The font didn't get into it. Added a numerical memory display. V1.2 Thought of incorporating the code of Click and DisplayBeep into 'DClock' and added them. Also stumbled upon my old MemGauge program and added a memory gauge display. V1.1 Added ARP interface, replaced standard DOS calls with ARP calls, removed the clock display from the barlayer (always crashed after a call to CloseWorkBench()), added weekday conversion and command line options. V1.0 Simple ('dumb') backdrop clock with date and time display to be rendered directly into the Workbench bar layer. * Do only its possibilities make it an Amiga? WHERE IS THE MAGIC ???