TimeMaster IIgs v2.1                          13 August 1992
------------------------------------------------------------

TimeMaster IIgs is an Apple IIgs time correction utility.  It calls atomic time standard services using the system modem and adjusts the time of the Apple IIgs internal clock to within 1 second.  TimeMaster IIgs maintains a log of time corrections in an ASCII text file and provides a graph plot of long term clock drift trend analysis.  TimeMaster IIgs uses this drift analysis to allow you to predict an update of your IIgs clock without calling the time service!  Two time services you can call are the U. S. Naval Observatory in Washington, D.C., (202) 653-0721, and one in Toronto, Canada, (416) 445-9408.  The call lasts about 25 seconds.  This only costs $0.15, calling Washington from St. Louis after 6pm.

Installation
------------------------------------------------------------

TimeMaster IIgs consists of the following files:

1. TimeMaster.IIgs  The executable TimeMaster IIgs utility.
                    Launch this file from the GS/OS
                    Finder desktop, or another program
                    launcher.

2. TimeMaster.Pref  This contains Setup Preferences in
                    text format. It is created in the
                    same directory as 1 above when you
                    select the Save Preferences menu.

3. TimeMaster.Log   This is a text file log that is
                    created the first time you call a
                    time service. It contains results
                    of each time correction (whether by
                    an actual call, or due to a predicted
                    correction) with the date, time and
                    seconds adjusted.

4. TM.read.me       This documentation file as an ASCII
                    text file.

5. TM.read.me.awp   This documentation file as an
                    AppleWorks word processing file.

The TimeMaster.IIgs (file 1 above) executable file is the only one you need to run this application.  It can be placed in any directory on your disk.  Be sure to have some extra space on this disk, because the TimeMaster.Pref and TimeMaster.Log files (2 and 3 above) are created in this same directory.

TimeMaster IIgs Startup
------------------------------------------------------------

TimeMaster IIgs requires specific Apple IIgs Control Panel settings to assure proper communications with your external modem.  Enter the Control Panel by pressing the Open-Apple, Control and ESC keys simultaneously.  You must set the Apple IIgs Control Panel for "Slots" so that Slot 2 is set to "Modem".  You must power down and restart your Apple IIgs for these to take effect.  You should be able to keep these settings for most other applications, unless you have some special card in slot 2.

Be sure to turn on power to your modem.

TimeMaster IIgs execution is initiated by launching the application file named "TimeMaster.IIgs" from the GS/OS Finder by double-clicking the "TimeMaster.IIgs" file's icon, or by using another GS/OS program launcher.

TimeMaster IIgs is now active on the desktop.  All menus may be used.  The display at the bottom of the screen shows the current date and time being maintained by your Apple IIgs.  The center bottom shows the current setting for the time zone difference in hours.  This can be changed, along with several other parameters, using the Setup menu.

Menu Descriptions
------------------------------------------------------------

Apple Menu     ---

About TimeMaster IIgs...

               Displays revision & shareware information.

Help...        Generates an online help display.  This
               covers 5 pages, so click the 'OK' button
               to turn the pages.

Credits...     Displays copyright credits for ORCA/C, the
               Serial I/O and Dialog routines used by
               TimeMaster IIgs.

File Menu      ---

Setup          Use the Setup Menu dialog to alter the modem
               initialization string. It is set for an
               external, Hayes-compatible modem by default.

               Phone number may be changed to accommodate
               calling any prefix, phone number and suffix
               that may be needed to dial the time service.

               Change the time zone difference to adjust
               for your time zone. This number must be
               -23 to +23 hours. For St. Louis during
               winter time, this is -6 when calling a 
               Greenwich Mean Time service, such as 
               the U.S. Naval Observatory.

               Select Touch-Tone or Pulse Dialing.

               Select Disable Timeouts if you are in an area
               that has slow phone service.  This makes
               TimeMaster IIgs wait forever for calls to
               connect and the time service modem to
               respond.

               Any changes are temporary for this call,
               unless you use the Save Preferences Menu.
               Use Cancel to ignore changes made in the
               dialog box. Use Undo to reset changes made.
               Use OK to accept changes.

Save Preferences 
               
               This Menu saves all items in the Setup
               Menu dialog to a file named 'TimeMaster.Pref'
               on your disk. This is read on startup, if
               present. You may delete this file to
               restore the original TimeMaster IIgs
               settings.

Delete Preferences

               This Menu deletes the file named 
               'TimeMaster.Pref' from your disk, restoring
               the original TimeMaster IIgs settings.
               You are asked if this deletion is okay
               before the file is deleted.

Delete Time Log

               This Menu deletes the file named
               'TimeMaster.Log' from your disk, which
               eliminates all record of previous calls
               to time services.  You are asked if this
               deletion is okay before the file is deleted.

Quit           Exits TimeMaster IIgs to the calling system
               (e.g. Finder, or other program launcher).

Edit Menu      ---

Cut            All Edit functions may be used for entry or
Copy           change of text information (e.g. in the
Paste          Setup dialog), using keyboard equivalents.

                    open-apple-X = cut
                    open-apple-C = copy
                    open-apple-V = paste

TimeMaster Menu ---

Dial           The Dial Menu causes TimeMaster IIgs to call
               the time service, set the Apple IIgs clock,
               hang up the phone, and append the time
               correction to the text file 'TimeMaster.Log'.
               If Busy or No Answer, you will be notified.

Hangup         The Hangup Menu simply tells your modem to
               hang up the phone. It is useful only in
               rare instances to force a disconnect.

Plot Clock Drift

               This Menu displays a graph of your IIgs
               clock drift history and characteristics.
               Up to two years of recorded clock corrections
               are plotted.

               Blue '+' symbols indicate clock corrections
               in seconds that were recorded in the
               TimeMaster.Log file based on actual calls to
               the time service (via the Dial Menu).

               Light Blue '+' symbols show corrections to
               the IIgs clock recorded based on TimeMaster
               IIgs predictions (via the Predict Time Menu).

               A Green line shows the running average clock
               drift per month (in seconds per month).  Over
               time, this should be fairly constant for your
               Apple IIgs, however each computer is unique.

               Red '+' symbols show the future monthly
               projection of clock drift (in seconds) if you
               do not correct the clock by Dialing the time
               service or use the Predict Time Menu.

Predict Time   This Menu uses the analysis of the Plot Drift
               function to predict how far your Apple IIgs
               clock has probably drifted since your last
               actual call to a time service.  It then
               predicts a correction to the IIgs clock,
               sets the IIgs clock to this updated time,
               displays this information on the screen,
               and logs this prediction to the time log
               file 'TimeMaster.Log'.

               Predict Time can be used in between time
               service calls to keep your IIgs clock as
               up to date as possible.  While this is
               certainly not as accurate as a time service
               correction, it does update your clock
               fairly accurately without a phone call.

TimeMaster IIgs Operation
------------------------------------------------------------

Select all three menu items under the desktop Apple in the menu bar and review the information displayed for About TimeMaster IIgs..., Help..., and Credits.  This gives vital information on this application, and provides an address to send your $1 contribution for this shareware utility.  Please do so now!

Select the "Setup" item under the File Menu.  This displays the current settings for the modem initialization string, phone number, time zone difference, tone/pulse dialing and disable timeout selections.  Use the mouse to position the cursor to make any changes to this information with the keyboard.  The modem initialization string is set for an EXTERNAL, Hayes-compatible modem, connected through the IIgs modem port.  (Internal modems, or modems connected to serial cards just will not work properly.)  Refer to your modem documentation to determine if you need to change this.  If you don't know what any of this means, then don't mess with this string.  Please note, TimeMaster IIgs does need to have the "Q0" and "V1" parameters included in this string.  These parameters tell your modem to return results codes to TimeMaster IIgs so it can monitor the call's progress, and to send these results in words, not codes.

The phone number can be changed since your needs for dialing may differ.  You may add prefixes like "9-" if going through an office PBX phone system.  You can also add suffixes to accommodate telephone service access codes, and the like.

Be sure to update the Time Zone Difference for your time zone.  This is the number of hours to be subtracted from the time service to set your Apple IIgs clock.  It is initially set at -6 since I live in St. Louis, its not Daylight Savings Time yet, and I call the Greenwich Mean Time service maintained at the U.S. Naval Observatory in Washington, D.C.  This entry must be from -23 to +23.

Select the radio button for Touch-tone or Pulse dialing, depending on your local phone service.

Finally, use the checkbox to select, or not, the Disable Timeout function.  Selecting this checkbox disables all timeouts during call processing.  It is useful for areas that have very slow telephone service.

Exit the Setup dialog by selecting the "OK" button.

Now, to call the time service, use the "Dial" item under the TimeMaster Menu.  TimeMaster IIgs will display calling progress information as it Initializes the Apple IIgs serial port to 300 baud, initializes the modem, dials the time service, connects with it, and receives the correct time.  If the service is busy or not answering, you will be notified.  The call lasts about 25 seconds after connection.  This only costs 15 cents for me to call the Washington service from St. Louis after 6pm.

If you forget to power on your modem, TimeMaster IIgs could appear to freeze at this point.  If Timeouts are enabled, control will be returned with an appropriate message in a few seconds.  If Timeouts are disabled, just press the ESC key, and control will return to you.

After TimeMaster IIgs has received the correct time from the service, it hangs up the phone, and provides statistics on the screen for the Apple IIgs time, correct time and the difference in seconds.  It then displays a continuously running clock in the lower left screen area of the Time Service's time and date.  It updates your Apple IIgs internal clock in accordance with the Time Zone Difference.

TimeMaster IIgs will create an ASCII text file called 'TimeMaster.Log' in the same directory as the application is located.  It is created the first time your clock is corrected.  It contains a log entry of the date and time called, and the difference in seconds.  This file is then added to each time you call the service or use the Predict Time Menu to update the IIgs clock.  This file can be deleted using the Delete Time Log item, under the File Menu.

Use the Plot Clock Drift Menu to display a graphic plot of the drift in your Apple IIgs clock over time.  This shows all clock updates for a two year period, calculates and plots an average drift per month, and a projection of monthly drift.

After you have called a time service with TimeMaster IIgs a few times, this should set a trend for clock drift in your Apple IIgs clock.  Since this drift should remain fairly constant, TimeMaster IIgs can use this information history to Predict updates needed to keep your Apple IIgs clock accurate.  Use the Predict Time Menu to take advantage of this capability.  You will see TimeMaster IIgs initially Plot Clock Drift to determine the average drift, and your IIgs clock will be updated to correct for clock drift that has occurred since your last actual call to a time service.

You can preserve the Setup settings you used by selecting the Save Preferences item under the File Menu.  This saves those settings in the ASCII text file 'TimeMaster.Pref' in the same directory as the application is located.  The next time you start up TimeMaster IIgs, it will read these preference settings and use them.  You can delete this file using the Delete Preferences item, under the File Menu, to restore the original TimeMaster IIgs settings.

Select the Quit item under the File Menu, press the open-apple and Q keys, or click the mouse cursor in the window close box to exit TimeMaster IIgs.

TimeMaster IIgs Revision History
------------------------------------------------------------

Version 1.0 ------------------

TimeMaster IIgs was initially released as version 1.0
on 15 March 1992.

Version 1.1 ------------------

Version 1.1 adjusts several factors that made TimeMaster IIgs time-out on some calling areas and really time-out if you had an accelerator (like TranswarpGS or ZipGS).  All time-outs have been changed to use the IIgs clock ticks rather than processor timing.  Also, all time-outs have been lengthened to allow plenty of time (hopefully) for the anticipated action, such as a connection, to complete.

Version 1.1 also removes the requirement for setting the control panel modem baud rate.  TimeMaster IIgs now will automatically set the baud rate to the required 300 baud when you select the "Dial" menu item.  TimeMaster IIgs does nothing with your control panel modem baud rate setting.

Version 1.2 ------------------

Added Disable Timeouts to allow for slow phone services.

Version 2.0 ------------------

Added Delete Preferences function.

Added Delete Time Log function.

Rearranged Menus to put file and setup functions under the File Menu.

Added the Plot Drift function for clock drift analysis.

Added the Predict Time function.

Version 2.1 ------------------

Added hot keys for all menu items.

Disabled Edit Menu items when they are not available. They are available only while in the Setup dialog.

Displayed the wait cursor (watch hands) during call processing and other processing delays.  This looks neat if you have the Animated Watch Init installed.

The Developer Requests Your Support For Shareware
------------------------------------------------------------

Mike Gooding is the developer of TimeMaster IIgs.  I welcome any constructive comments you may have about TimeMaster IIgs, or any Apple II programming.  I can be reached on several on-line telecommunication services:

     GEnie               M.Gooding
     Compuserve          72627,1365
     America Online      ArchMike
     Proline             pro.applejacks;Atlas

I am pleased to offer TimeMaster IIgs as a Shareware product for the Apple IIgs.  I have extensive background with Apple II computers since acquiring a II plus in 1980.  I founded The Software Mill in 1983 for the development and marketing of several Apple II products, including: "SDM: Screen Data Manager", a data base management system; and a commercially distributed Apple II re-hosting of "Monkey See - Monkey Spell", originally programmed for Atari computers.

Look for one of my recent Apple IIgs Shareware games, called Shuffle Mouse, on the same services TimeMaster IIgs is distributed.

I hope you enjoy using TimeMaster IIgs.  Please support this Shareware effort by contributing $1 to encourage me to develop more Apple IIgs Shareware products.  

I'm only asking for a $1 contribution, so please support Shareware by grabbing a buck out of your wallet, shove it in an envelope and mail it to me now!  Hey, if you are not in the U.S.A., send me some of your local currency!

Thank you for your support of Shareware.

Thanks to those who sent their shareware contributions, or more, for previous versions of TimeMaster IIgs:

Gant, Soffian, Hart, Bettinelli, Lockart, Smith, Williams, Santore, Weldon, Mosier, Chevier, Lyon, Eddings, McDowell, Mackey, Baskwill, Rayback, Merlin, Galbraith, Lewis, Pedeltry, Reedy, Hardies, Traynor, Weithofer, Buback and Bruun.

Acknowledgement
------------------------------------------------------------

Special thanks go to Tom Gooding for his assistance in beta-testing and programming advice.

Shareware & Copyright Notice
------------------------------------------------------------

TimeMaster IIgs is Shareware and may be distributed freely, but users are requested to send a mere $1 contribution to the developer:

     Mike Gooding
     14319 Cypress Hill Drive
     Chesterfield, MO 63017-2838  U.S.A.

TimeMaster IIgs is copyrighted 1992 by Mike Gooding, who reserves all commercial rights.

You may provide copies of TimeMaster IIgs to your friends for evaluation.  TimeMaster IIgs may be placed on computer bulletin boards (BBSs) and online telecommunication services (e.g. GEnie, Compuserve and America Online) provided that the TimeMaster IIgs package is down-loadable without charge, beyond normal connect charges.  TimeMaster IIgs may be placed on diskettes distributed by user groups at a nominal fee.

When distributing TimeMaster IIgs, please provide the entire contents of the TimeMaster IIgs package, as contained in the compacted file named "TimeMaster.shk" or "TimeMaster.bxy", making sure to include all documentation files.

Vendors wishing to put TimeMaster IIgs into their catalogs must contact the developer, at the address above, to secure permission to distribute TimeMaster IIgs, and describe their fee and shareware policy.  A suitable shareware contribution from such vendors would be appropriate, and appreciated.

Whenever TimeMaster IIgs is included on a diskette, catalog or online service, it must be identified as shareware.  Operators and vendors must make it clear that online charges or disk fees do not qualify as payment for the use of this shareware program, and that the requested shareware contribution should be sent to the developer.

TimeMaster IIgs is implemented in the ORCA/C, ANSI Standard C Language.  As such, this program contains material from the ORCA/C Run-Time Libraries, copyright 1987-1991, by Byte Works, Inc.  Used with permission.

TimeMaster IIgs uses serial I/O routines, copyright 1988-1989 by Snow Software. Used with permission.

TimeMaster IIgs uses dialog routines, copyright 1992, by Tom Gooding. Used with permission.

------------------------------------------------------------
End of TimeMaster IIgs Documentation
