'Die Uhr' a digital-clock accessory dokumentation Dec 24, 1992 Program by Thomas Birke & Hinnerk Rmenapf (C) 1987 - 1992 T.B. & HWR *Pentagramm Software Braunschweig Thomas Birke Hinnerk Rmenapf Billrothstr. 31 Ottweilerstr. 18 W-3300 Braunschweig W-3300 Braunschweig ------------------- GERMANY 'Die Uhr' may be used by everyone who gives a (FREE) copy to anyone who might want to use it. 'Die Uhr' may be copied ONLY if ALL the following files are included and unchanged: - DIE_UHR.ACC the accessory - D_UHR11E.TXT this file - UHRCONF.PRG configuration-program for 'Die Uhr' - UHRCONF.RSC resource-file needed by UHRCONF.PRG ALL RIGHTS belong to the authors, we're only letting you use it. There is NO WARRANTY whatsoever. (What do you expect for free ?) History 'Die Uhr' startet off as a test 'how to write an Accessory'. Over the years it has seen many changes and new features. The first Version put on an FTP- server was labeled 1.0. 'Die Uhr' is another clock-accessory, with the following features: Version 1.0 june/july 1992 - pure GEM-program, no vektors changed, no interrupt-routines - a short but well-known melody on the hour (can be switched off). - should work with any screen-resolution (we hope - we couldn't try them all). - a change of the screen-resolution without reset ( AS-Overscan, PixelWonder, ...) should cause no problems. - an alarm with a 'time-window'. If 'Die Uhr' is blocked at alarm-time (e.g. by TOS-programs) it will sound the alarm up to half an hour after the alarm-time (if it gets a chance). - 'Die Uhr' is configurable. the default settings can be changed with UHRCONF.PRG. - we recommend to "Let 'em fly" with software by Oliver Scheel. version 1.1 Nov/Dez 1992 major changes : - first version with english documentation: 1.1E (german version: 1.1) - display can be configured (X-position, ... ) - a 12-hour (AM/PM) mode - the running accessory can be reconfigured without reset - (a few little bug fixes) And now for the documentation : 0. GEM-accessories ------------------ Accessories are utilitiy-programs which are loaded at system-start and remain in memory until a restart. Accessories are running 'almost' parallel to GEM-programs (if those are written correctly). If 'Die Uhr' should stop it could have different reasons : a GEM - program is running (ending .PRG or .APP) Whoever wrote that programm didn't do his job properly. a TOS - program is running (ending .TOS or .TTP) These porgrams usually block ALL accessories. If you leave the programm 'Die Uhr' should work again - if it doesn't, its either a TOS-fault, or ours. If you click the menu entry 'Die Uhr' in the leftmost menu (e.g. title 'DESK') the accessory will display a dialog (explained below). If your computer does not have a hardware-clock you'll have to set the time yourself ussing the control-acc., our D_T_E.PRG (D_T.PRG) or any similar utility. 1. Display ---------- The time is displayed in the top right corner. If the screen resolution changes (e.g. AS-Overscan) the distance time-display / right edge is kept constant. This distance can be configured. You can select (configure) either a 24- or a 12-hour (AM/PM) display . If time-display AND alarm are switched on, a bell symbol is displayed as well. Some GEM-programs use the whole screen width for their menu. In this case the time-display may replace some of the last menu title. It doesn't look too good, but the menu will work. You can switch the time-display on or off in the accessory-dialog. Use the two buttons right of the clock-symbol (AN = ON, AUS = OFF). The default-setting is configurable. 2. melody on the hour --------------------- Listen and enjoy, or turn if off. Every time the hour changes 'Die Uhr' can play a (very) short melody. You can switch the 'melody on the hour' on or off in the accessory-dialog. Use the two buttons beside the musical note symbol (AN = ON, AUS = OFF). The default-setting is configurable. 3. Alarm -------- To set the alarm ... - Click the menu-entry 'Die Uhr', the dialog will be displayed. - Use the buttons beside the bell symbol to switch on the alarm (AN = ON). - Enter the desired alarm time in the field below the bell symbol according to the selected mode (12/24 hour display): 24-hour mode ============ ALWAYS enter 4 digits. Examples : Alarm time enter this -------------------------------------------- 12 past 1 am 01:12 3 past 9 am 09:03 5 past 2 pm 14:05 10 past midnight 00:10 12-hour mode ============ In this mode two extra buttons AM and PM are displayed. ALWAYS enter 4 digits, and select either AM or PM. Examples : Alarm time enter this and select ------------------------------------------------------- 12 past 1 am 01:12 AM 3 past 9 am 09:03 AM 5 past 2 pm 02:05 PM 10 past midnight 12:10 PM Now click the button OK, the dialog disappeares. If 'Die Uhr' detects an error in the alarm-time, it will display an alert box and then re-open the dialog. If alarm AND time-display are switched on, a Bell symbol will be displayed as well. To switch off the alarm before it goes off: - open the acc. dialog (menu entry 'Die Uhr') - select the button 'AUS' beside the bell-symbol. As mentioned above, you cannot always be sure that 'Die Uhr' gets a chance to sound the alarm right on time. If it misses the exact time, the alarm can go off up to half an hour after the exact alarm time. If 'Die Uhr' is blocked for more then half an hour (starting with the alarm time) - I'm sorry, you missed it ! 4. where to get the time from ----------------------------- There are several possibilities to determine the time-of-day. Each of them has advantages and disadvantages (for configuration see 5.) : TIMER When the accessory is started, the GEMDOS-time is used ONCE for initialisation. After that the time passed since then is calculated using the 200 Hz system timer. Works pretty well, just one snag: if you change the system-time (e.g. using the control acc.) 'Die Uhr' won't notice on it's own. So just help it by opening the accessory-dialog once to update the time. ( Rumor sais there are programs that set this timer, but I doubt that. If you set that timer the system crashes, and why should anyone want to set it ? ) XBIOS fine, only ... there is a problem if your computer doesn't have a build-in hardware clock (e.g. the old 260 ST, 520 ST[+], 1040 STF[M], ...) . In this case the XBIOS asks the 'intelligent' keyboard what time it is. This confuses the screen saver of ATARI's MACCEL3 program. MACCEL3 will -NOT- crash, but the screen saver won't work. Recommended for the ATARIs WITH build-in hardware clock (MEGA ST[E], ...). GEMDOS PROBLEM : The event-critic-handler (No disk in drive A ?) calls the AES, which allows the accessories to continue. If one of the accessories calls the GEMDOS while the event-critic-handler is active the system will crash (sooner or later). To prevent this kind of crash the screen is locked for the AES before the GEMDOS-call using WindowUpdate ( 1 ), and afterwards released with WindowUpdate ( 0 ). This prevents the crash, but it also blocks 'Die Uhr' every time another program locks the screen with WindowUpdate ( e.g. window redraw, dialog-boxes, ...). None of these methods is ideal, just try out which you consider best. You can select one of them in the configuration program. 5. configuration ---------------- If you don't like the default settings you can change them with UHRCONF.PRG. Since version 1.1 the running accessory can be reconfigured without reset. We wrote a seperate configuration program to keep the accessory short. Once started, UHRCONF.PRG looks for a running DIE_UHR.ACC. If the acc. is running, UHRCONF.PRG displays the settings of the RUNNING accessory; else some internal default-settings are displayed. Now you can change the settings. If 'Die Uhr' is active, the running accessory will be notified of the changes (just look at the time-display). other functions: LOAD All settings will be loaded from a file DIE_UHR.ACC. If the accessory is active, it will be notified of any changes. SAVE Write all settings to a file DIE_UHR.ACC (the accessory). The saved settings are the new default. OK Quit the configuration program. If accessory- and UHRCONF.PRG- version don't match an according message is displayed. In that case nothing should crash, but I'd advise you to get an update soon. APPENDIX A: The accessory's patch area (only for the ever curious) -------------------------- Exemple and explanation: &Die_Uhr_Vars:TZM2k1pS& |||||||| |||||||+- S : seven-segment figures ||||||| s : normal figures ||||||| ||||||+- P : 12-hour mode |||||| p : 24-hour mode |||||| |||||+- "1" to "9" : distance from right screen edge ||||| (in character-width) ||||| ||||+-- K : display italic (slanted) |||| k : normal display |||| |||+--- "1" to "9" : Update-time in seconds ||| ||| ||+---- M : melody every full hour ON || m : -------- " --------- OFF || |+----- Z : display ON | z : -- " -- OFF | | Get time from ... +------ T : 200 Hz - Timer X : XBIOS G : GEMDOS [ see 4. ] Dokumentation by Hinnerk Rmenapf. >> broken english spoken perfectly >> to err is human, to forgive divine +++