@database TimeKeeper.guide @$VER: TimeKeeper.guide 1.06 (2019-02-08) @(c) 2017-2019 Carsten Sonne Larsen @author Carsten Sonne Larsen @rem Copyright (c) 2017-2019 Carsten Sonne Larsen @rem All rights reserved. @rem @rem Redistribution and use in source and binary forms, with or without @rem modification, are permitted provided that the following conditions @rem are met: @rem 1. Redistributions of source code must retain the above copyright @rem notice, this list of conditions and the following disclaimer. @rem 2. Redistributions in binary form must reproduce the above copyright @rem notice, this list of conditions and the following disclaimer in the @rem documentation and/or other materials provided with the distribution. @rem @rem THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR @rem IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES @rem OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. @rem IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, @rem INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT @rem NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, @rem DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY @rem THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT @rem (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF @rem THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. @Width 74 @Node Main "TimeKeeper.guide" @Next "Configuring the client" AmiTimeKeeper is a small program which keeps the time right on your machine. No installation is required. AmiTimeKeeper is operated as a commodity and is controlled by AmigaOS. An AmiTCP compatible TCP/IP stack is required for AmiTimeKeeper to work. AmiTimeKeeper can be configured through several settings. This can be done either directly from the command line or by using the tooltypes of an icon. Preferences can also be saved between reboots. @{"Configuring the client" Link "Configuring the client"} @{"Using tooltypes of an icon" Link "Using tooltypes of an icon"} @{"Saving preferences" Link "Saving preferences"} @{"Change Log / Change History" Link "Change Log"} @{"Software License" Link "Software License"} @{"Contacting the author" Link "Contacting the author"} @EndNode @Node "Configuring the client" "TimeKeeper.guide/Configuring the client" @Toc "Main" @Prev "Main" @Next "Using tooltypes of an icon" @{b}Server Address@{ub} NTP servers are managed by several organizations. The pool.ntp.org project and Network Time Foundation are probably the two most famous. The pool.ntp.org project organize servers into pools whereas Network Time Foundation maintains a list of valid NTP servers. The servers are divided into two categories: Stratum 1 and Stratum 2. The NTP pool servers are divided into zones. If you want to use a server in Europe you can use set the server address to europe.pool.ntp.org. For North America the server address is north-america.pool.ntp.org. Zones also exists for countries. To use a server in for example Germany the server address should be set to de.pool.ntp.org. For Switzerland the address should be ch.pool.ntp.org. Network Time Foundation has a website on http://support.ntp.org/ The pool.ntp.org project website is located at https://www.ntppool.org/ @{b}Server Port@{ub} NTP servers use port 123 as default. Only under special circumstances are the NTP server port different from 123. @{b}Interval between requests@{ub} The Amiga hardware clock will slowly drift away from true time. The drift is determined by several factors and is small, but the drift is not insignificant. Request are repeatedly sent to the NTP server in order to keep the Amiga hardware clock as close to true time as possible. The requests are sent in certain intervals defined by the interval parameter. The interval should be specified using milliseconds. One thousand (1.000) milliseconds are equal to one second. @{b}Threshold@{ub} Due to the accuracy of NTP servers and the nature of Amiga CPUs it does not make sense to adjust the Amiga clock on every response from the NTP server. Processing the response could take longer time than anticipated. The amount of accepted inaccuracy is set using the threshold parameter. The threshold should be specified using microsecond. One million microseconds (1.000.000) are equal to one second. @{b}Read Only@{ub} It is possible to send request to the NTP server without setting the Amiga hardware clock. This option can be handy when debugging time zone setup and other time related parameters. @{b}Connection Timeout@{ub} In some cases, a connection to the NTP server cannot be established or the NTP server simply does respond. To avoid an infinitive wait for a response the connection will instead make a time out. The timeout interval should be specified using milliseconds. One thousand (1.000) milliseconds are equal to one second. @{b}Verbosity@{ub} The level of logging can be adjusted from none to all. Expressed as a numeric value verbose can be 0, 1, 2 or 3, where 0 is equal to none and 3 is equal to maximum verbosity. @{b}Log file@{ub} It is possible to send log messages to a file instead of sending them to a console window. @EndNode @Node "Using tooltypes of an icon" "TimeKeeper.guide/Using tooltypes of an icon" @Toc "Main" @Prev "Configuring the client" @Next "Saving preferences" Settings can be changes by setting tooltypes in the TimeKeeper icon. Add the following line to the icon tooltypes in order to set the server to an European pool server: SERVER=europe.pool.ntp.org The available tooltypes are the same as the available command line parameters. @{b}Parameter@{ub} | @{b}Short description@{ub} ----------------------------------------- SERVER | Server Address PORT | Server Port THRESHOLD | Adjustment threshold INTERVAL | Interval between requests CX_PRIORITY | Commodity priority READONLY | Read only option TIMEOUT | Connection Timeout VERBOSE | Log verbosity LOGFILE | Log file location @{b}Caveats@{ub} Settings can be overridden and are set in the following order: 1. Preference file 2. Icon tooltypes 3. CLI parameters CLI parameters has highest precedence and will always override settings from icon tooltypes and from the preference file. @EndNode @Node "Saving preferences" "TimeKeeper.guide/Saving preferences" @Toc "Main" @Prev "Using tooltypes of an icon" @Next "Change Log" Preferences from the setting window are saved in the file ENV:timekeeper.prefs Preferences are also persisted between reboots in the file ENVARC:timekeeper.prefs Depending on the setup the content of timekeeper.prefs could be: CX_PRIORITY=25 THRESHOLD=1000000 SERVER=de.pool.ntp.org PORT=123 TIMEOUT=5000 INTERVAL=17500 VERBOSE=3 READONLY=0 LOGFILE=RAM:log The preference file should not be edited under normal circumstances. @{b}Caveats@{ub} If LOGFILE is set in the preference file, no messages will be emitted to screen (unless overridden by CLI or Icon tooltype with LOGFILE=NO). @EndNode @Node "Change Log" "TimeKeeper.guide/Change Log" @Toc "Main" @Prev "Saving preferences" @Next "Software License" @{b}v1.06 08.02.2019@{ub} - Adjust layout in settings window @{b}v1.05 06.08.2018@{ub} - Preferences can now be saved from settings window - Time zone is shown as UTC offset in settings window - Running multiple instances no longer create zombie processes - Low water option renamed to threshold and high water option removed - New option for sending log messages to file instead of to screen - Some incorrect NTP log messages no longer appears - Read-only option is now applied consistently - Potential race condition in memory allocation fixed - Other minor enhancements @{b}v1.04 15.12.2017@{ub} - Default settings adjusted to comply better with AmigaOS - Bugs in threshold settings (high/low water) fixed - Bugs in opening and closing of libraries fixed - New and more accurate error and log messages @{b}v1.03 09.12.2017@{ub} - Settings window @{b}v1.02 29.11.2017@{ub} - AROS code compliance @{b}v1.01 28.11.2017@{ub} - Handle network disconnection - Fix infinity timeout problem - Support hardware clock - Improved error messages @{b}v1.00 26.11.2017@{ub} - First public release @EndNode @Node "Software License" "TimeKeeper.guide/Software License" @Prev "Change Log" @Next "Contacting the author" @Toc "Main" @{b}Simplified BSD License / 2-clause BSD license@{ub} Copyright (c) 2001, 02 Motoyuki Kasahara Copyright (c) 2007 TANDBERG Telecom AS Copyright (c) 2008-2009 Dag-Erling Smørgrav Copyright (c) 2017-2019 Carsten Sonne Larsen All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. @EndNode @Node "Contacting the author" "TimeKeeper.guide/Contacting the author" @Toc "Main" @Prev "Software License" The author of AmiTimeKeeper can be contacted using the following email addresses: or . Please notice is a member of several high volume mailing lists and should not be used under normal circumstances. Feel free to send suggestions, feature request and bug reports. General comment and questions are also welcome. Carsten Sonne Larsen February 2019 @EndNode