


                                '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

+++
